# 账户财务 (/account)



<ProductDirectory title="账户财务" description="账户财务文档，提供账号、访问管理、订单、账单、资源包、发票、审计日志、企业账号和常见问题等说明。" navLabel="账户财务文档分类" showCategoryNav="false" topSegment="account" />


# FAQ (/faq)



<ProductDirectory navLabel="FAQ 分类" topSegment="faq" />


# 七牛文档 (/products)



<ProductDirectory />


# SDK & 工具 (/sdk-tools)



<span id="8" />

<ProductDirectory title="SDK & 工具" description="常用 SDK、命令行工具、图形工具和社区生态入口。" navLabel="SDK 与工具分类" topSegment="sdk-tools" />


# 账号注册 (/account/0-account-registration)



最近更新时间: 2026-05-07 09:51:30

# 中国大陆账号手机号码注册 [#中国大陆账号手机号码注册]

## 第一步 [#第一步]

进入[七牛云官网首页](https://www.qiniu.com/)，点击“免费注册”
![image.png](/docs-assets/account/%280-manual%29/0-account-registration/Fs2I715dwpJidckm2lDSF9HfRhbK-c12e8694e2fe.webp)

## 第二步 [#第二步]

填写账号信息，使用手机接收验证码短信。查看[七牛云服务用户协议](https://www.qiniu.com/agreements/user-agreement)和 [隐私权政策](https://www.qiniu.com/agreements/privacy-right)后，点击“免费注册”完成注册。

<img src="/docs-assets/account/%280-manual%29/0-account-registration/FvpZ1uLahccpogDv0oNfzgaAVLkO-91686c26bffe.webp" width="50%" />

# 中国大陆账号微信扫码注册 [#中国大陆账号微信扫码注册]

## 第一步 [#第一步-1]

进入[七牛云官网首页](https://www.qiniu.com/)，点击“免费注册”
![image.png](/docs-assets/account/%280-manual%29/0-account-registration/Fs2I715dwpJidckm2lDSF9HfRhbK-c12e8694e2fe.webp)

## 第二步 [#第二步-1]

点击“微信快速注册”

<img src="/docs-assets/account/%280-manual%29/0-account-registration/FrUgbFQjq8SiGuCbiswqrW8DGKvh-3a42bf6c42ae.webp" width="50%" />

## 第三步 [#第三步]

微信扫码，填写信息，完成注册

<img src="/docs-assets/account/%280-manual%29/0-account-registration/Fg4VJfslZzN1BIvvWTiJp34g9alj-c2e8075464f8.webp" width="50%" />

# 海外账号注册 [#海外账号注册]

## 第一步 [#第一步-2]

进入[七牛云官网首页](https://www.qiniu.com/)，点击“免费注册”
![image.png](/docs-assets/account/%280-manual%29/0-account-registration/Fs2I715dwpJidckm2lDSF9HfRhbK-c12e8694e2fe.webp)

## 第二步 [#第二步-2]

进入中国大陆注册页面，点击“[七牛海外用户注册](https://portal.qiniu.com/intl/signup)”

<img src="/docs-assets/account/%280-manual%29/0-account-registration/Fm3K2xlWnRPRhwdJ-ZpFfysMvC3J-4e1b7dbe5df0.webp" width="50%" />

## 第三步 [#第三步-1]

填写账号信息，查看[七牛云服务用户协议](https://www.qiniu.com/agreements/user-agreement)和 [隐私权政策](https://www.qiniu.com/agreements/privacy-right)后，点击“免费注册”完成注册。

<img src="/docs-assets/account/%280-manual%29/0-account-registration/Fn9kpYMCRJfEIll5Y3q26BPQzd7B-ee463297228b.webp" width="50%" />


# 审计日志 (/account/0-audit-log)



最近更新时间: 2026-01-15 18:18:52

审计日志（Audit Log）是一项支持对七牛云账号进行监管、合规性检查、操作审核和风险审核的服务。借助 Audit Log，可以记录日志、持续监控并保留与整个七牛云的云基础设施中操作相关的账号活动。

访问地址：[https://portal.qiniu.com/audit/log-query](https://portal.qiniu.com/audit/log-query)
![image.png](/docs-assets/account/%280-manual%29/0-audit-log/FtA1AErC62PAn7TJKIQ49yHp3ZA0-4e1d36aa3927.webp)


# 设置可用额度预警 (/account/0-available-credit-warning)



最近更新时间: 2026-05-06 16:22:28

# 一、设置入口 [#一设置入口]

登录账号后，进入管理控制台>财务中心>[财务概况](https://portal.qiniu.com/financial/overview)，点击开启「可用额度预警」。

![image.png](/docs-assets/account/%280-manual%29/0-available-credit-warning/FgS0Xl4rfhS4SWRxr-wkNN19YuWB-99a42ccecd69.webp)

# 二、设置阈值 [#二设置阈值]

请输入大于0的数值，最多精确到小数点后2位。

![image.png](/docs-assets/account/%280-manual%29/0-available-credit-warning/FkjdJNijCZU0CWPavYvi0BRHmnjm-9220bd3d658e.webp)

# 三、预警规则 [#三预警规则]

**1.通知条件。**

当您账户的可用额度低于预警阈值时，系统会每天为您发送短信和邮件预警通知。

**2.通知对象。**

七牛云会通知到您账户绑定的邮箱和手机号。如需修改可以前往 个人中心>[安全设置](https://portal.qiniu.com/developer/user/security)，更换邮箱和手机号。

**3.通知频率。**

每天发送一次。

# 四、关闭通知 [#四关闭通知]

1.点击开关，将预警设为关闭。
![image.png](/docs-assets/account/%280-manual%29/0-available-credit-warning/FgS0Xl4rfhS4SWRxr-wkNN19YuWB-99a42ccecd69.webp)


# 费用分析说明 (/account/0-cost-analysis-shows-that)



最近更新时间: 2026-05-06 18:24:43

# 概述 [#概述]

费用分析，为客户提供了多维度、可视化查看费用变化趋势、各产品费用占比、资金流入渠道占比等多种费用相关信息，提供比较全面的组合分析能力。该页面主要包含费用总览、费用详情、购买推荐三个模块。

# 费用总览 [#费用总览]

## 查询周期选择：近六个月、近一年 [#查询周期选择近六个月近一年]

> 注：由于本月账单需在下月月初出账，所以费用总览的查询周期不包含本月。

## 可视化形式：折线图、柱状图 [#可视化形式折线图柱状图]

> 注：费用大于统计周期内平均费用的20%线段（柱状图）颜色呈紫色，小于统计周期内平均费用的20%线段（柱状图）呈浅蓝色。

## 汇总维度：全部计费模式、按量计费、包年包月 [#汇总维度全部计费模式按量计费包年包月]

> 注：
> 全部计费模式：包含按量计费和包年包月的全部费用。
> 按量计费：按量计费产品费用，当月账单费用在下月月初出账。
> 包年包月：预付费产品（包含预付费/后付费订单）。

![image.png](/docs-assets/account/%280-manual%29/0-cost-analysis-shows-that/FgtqMn_bh6N-Izvzxlnj28c9aSfA-6523b79f633a.webp)

# 费用详情 [#费用详情]

## 汇总维度：产品、计费模式、支付币种、资金流入、资金流出 [#汇总维度产品计费模式支付币种资金流入资金流出]

> 注：
> 产品：按统计周期内所消费产品类别汇总。
> 计费模式：按量计费、包年包月
> 支付币种：现金、抵用券、赠送金
> 资金流入：包含所有通过不同渠道流入账户的资金，如充值、转账、退款、赠送等。这里的时间是资金流入/流出实际发生的时间和月结算单/账单所在月份不一一对应，例如2月份充值支付1月份账单，账单时间是1月份，充值时间是2月份。
> 资金流出：包含所有通过不同渠道流出账户的资金，如消费、转账等。

## 时间选择：上个月、近三个月、近六个月 [#时间选择上个月近三个月近六个月]

> 注：
> 上个月：按不同汇总维度统计上月各种金额占比。
> 近三个月：按不同汇总维度统计近三个月（不包含本月）各类金额占比。
> 近六个月：按不同汇总维度统计近六个月（不包含本月）各类金额占比。

## 查询周期：近六个月、近一年 [#查询周期近六个月近一年]

> 注：
> 近六个月：展示近六个月（不包含本月）按不同维度汇总的堆叠图。
> 近一年：展示近十二个月（不包含本月）按不同维度汇总的堆叠图。

![image.png](/docs-assets/account/%280-manual%29/0-cost-analysis-shows-that/FsKg_bgfEshh-yGtTaJREubwuCyV-a3bfbc6c41b2.webp)

# 购买推荐 [#购买推荐]

## 近六个月（不包含本月）的消费情况总结： [#近六个月不包含本月的消费情况总结]

费用最高月份及金额
费用环比增长率最高月份及金额
月平均消费排名前三位产品及消费金额

## 资源包购买： [#资源包购买]

可以点击资源包上「立即抢购」进入相应产品购买页面，也可以点击「云商城」进入云商城选购。
![image.png](/docs-assets/account/%280-manual%29/0-cost-analysis-shows-that/FnuNLdiBNaRVb_UnU0_CNyfpJjYS-a68651257618.webp)


# 电子合同说明及操作手册 (/account/0-electronic-contract-documentation-and-operation-manuals)



最近更新时间: 2026-05-08 17:28:23

# 适用范围 [#适用范围]

电子合同适用于请款、报销等预付费场景。

# 操作手册 [#操作手册]

操作位置：控制台-财务中心-发票与合同-合同管理 （[点击前往](https://portal.qiniu.com/financial/invoice-contract/contract)）

1）点击【申请合同】按钮
![image.png](/docs-assets/account/%280-manual%29/0-electronic-contract-documentation-and-operation-manuals/Fv26pFdPsmUKre4BBEXEQYGDXDa0-a74ca6763eca.webp)

2）填写合同信息

* 甲方名称：实名认证名称不可更改。
* 地址：根据公司所在地，可自助填写。
* 联系人：公司业务联系人。
* 联系电话：联系人的有效联系电话。
* 服务内容：订单和按量付费产品至少填一个。
* 填写承诺付款金额：该项适用于请款合同，公司若无要求可不填写。
  ![image.png](/docs-assets/account/%280-manual%29/0-electronic-contract-documentation-and-operation-manuals/FnLWpTlq8eDtuJq8kSnXpcUHy49q-66a3723d21c1.webp)

3）直接创建正式合同

创建正式合同后不能再修改，如有特殊需求请联系商务或提交工单。
![image.png](/docs-assets/account/%280-manual%29/0-electronic-contract-documentation-and-operation-manuals/FpkwuvGPZyuJrAsQE62I98FaMbKi-724813066326.webp)

4）先保存草稿再转为正式合同

若有信息尚未确定，可先保存草稿后续再转为正式合同。草稿状态下的合同允许修改/删除。
![image.png](/docs-assets/account/%280-manual%29/0-electronic-contract-documentation-and-operation-manuals/Fkp6qw7yhMAVlPc4Jhi9xwr2XqBR-c1a1247fcbf5.webp)
![image.png](/docs-assets/account/%280-manual%29/0-electronic-contract-documentation-and-operation-manuals/FlCDbnqUNyCe51TbxAiprqnlbd9u-cd97d64cf3ff.webp)

5）下载正式电子合同
![image.png](/docs-assets/account/%280-manual%29/0-electronic-contract-documentation-and-operation-manuals/Fqw3WKDuOGrek8yKj-l5x0H-QxoO-e9c11b281792.webp)

# 特别提示 [#特别提示]

1）本【合同管理】页面仅针对电子合同，若需纸质合同请联系商务或提交工单。
2）电子合同仅针对标准预付费场景，合同金额不代表最终付款金额，每月应付款金额请以月结算单为准。
3）若签订合同后业务上有任何变更以实际业务规则为准。
4）每个订单只允许关联一个合同，未生成正式合同前您可自助修改，正式合同不可修改，若有需求请联系商务或提交工单。


# 财务对外 API 文档 (/account/0-financial-external-api-documentation)



最近更新时间: 2025-09-10 19:35:37

# 七牛云对外账单API文档 [#七牛云对外账单api文档]

### 更新日志 [#更新日志]

* 2021/12/22 v0.1 内部文档
* 2022/01/04 v1.0 对外文档
* 2022/02/24 v1.1 增加detail接口
* 2022/08/04 v1.2 增加订单、资源包管理接口
* 2023/03/03 v2.0 增加按量计费预估每日快照详情接口、月结算单详情接口v2
* 2023/08/11 v2.1 增加获取账户余额接口
* 2024/02/29 v2.2 增加获取分账账单详情接口

### 概述 [#概述]

财务对外 API 为七牛用户提供更加灵活的财务管理方式。作为对[财务中心](https://portal.qiniu.com/)管理系统的补充，可查看用户在某个账期内各产品的消费情况。

### 注意事项 [#注意事项]

按量计费的账单每月4号出账，为保数据的完整性，请在5号后查看上月账单。如2021年6月账单应在7月5号后查看。
接口支持查询近24个月的数据。

### 接口域名 [#接口域名]

[https://api.qiniu.com/](https://api.qiniu.com/)

### 接口列表 [#接口列表]

* [月结算单概览](#月结算单概览接口)
* [月结算单详情](#月结算单详情接口)
* [订单列表](#订单列表接口)
* [订单详情](#订单详情接口)
* [订单取消](#订单取消接口)
* [资源包当月概览](#资源包当月概览接口)
* [资源包列表](#资源包列表接口)
* [资源包详情](#资源包详情接口)
* [资源包历史抵扣明细](#资源包历史抵扣明细接口)
* [按量计费预估每日快照详情接口](#实时消费每日快照详情接口)
* [账户余额接口](#账户余额接口)
* [分账账单详情接口](#分账账单详情接口)

### API签名 [#api签名]

[文档地址](/products/kodo/development-guidelines/security/access-token)

<span id="error-code" />

### 错误码 [#错误码]

| 错误码  | 错误消息                        | 错误说明        |
| ---- | --------------------------- | ----------- |
| 1000 | InvalidParameter            | 请求参数不正确     |
| 1001 | BaseBillGetFailed           | 账单数据获取失败    |
| 1002 | CustomBillGetFailed         | 自定义账单数据获取失败 |
| 1003 | OrderGetFailed              | 订单数据获取失败    |
| 1004 | MonthStatementGetFailed     | 月结算单获取失败    |
| 1005 | QueryTimeExceeded           | 请求的时间不正确    |
| 1006 | TransactionGetFailed        | 流水数据获取失败    |
| 1007 | CouponUsageGetFailed        | 优惠券使用量获取失败  |
| 1008 | CancelOrderByUnionOrderHash | 取消订单失败      |
| 1009 | MonthOverviewGetFailed      | 资源包当月概览获取失败 |
| 1010 | RespackOverviewGetFailed    | 资源包列表获取失败   |
| 1011 | RespackDetailGetFailed      | 资源包详情获取失败   |
| 1012 | HistoryUsageGetFailed       | 资源包历史抵扣获取失败 |
| 1013 | GetBalanceOverviewFailed    | 账户余额获取失败    |
| 1014 | FindSABillDetailsFailed     | 获取分账账单详情失败  |

<span id="order-seller" />

### 订单产品归属 [#订单产品归属]

以下列举了目前订单系统内商品的产品归属对应常量值，即订单相关接口中的 seller\_id

| seller\_id | 名称            |
| ---------- | ------------- |
| 33         | SSL 证书        |
| 39         | 存储            |
| 45         | CDN           |
| 51         | 内容安全          |
| 54         | 云主机           |
| 60         | 直播            |
| 72         | 云短信           |
| 75         | 短视频 SDK       |
| 78         | 智能多媒体         |
| 79         | 实时音视频         |
| 82         | 视频监控          |
| 94         | 企业直播aPaaS-P01 |
| 98         | 企业直播aPaaS-P02 |
| 99         | SDK           |

<span id="%E6%9C%88%E7%BB%93%E7%AE%97%E5%8D%95%E6%A6%82%E8%A7%88%E6%8E%A5%E5%8F%A3" />

### **月结算单概览接口** [#月结算单概览接口]

#### 描述 [#描述]

本接口作GET请求用来获取请求拥有的所有月结算单的概览列表。该接口需要您使用带Authorization签名认证的请求，如果使用匿名请求无法获取账单概览。

#### 请求 [#请求]

##### 请求语法 [#请求语法]

```
GET /billing-api/v1/bill/overview?start=<StartTime>&end=<EndTime> HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>
```

##### 请求参数 [#请求参数]

| 字段名称  | 类型     | 是否必须 | 示例                  | 说明                     |
| ----- | ------ | ---- | ------------------- | ---------------------- |
| start | string | 是    | 2021-09-01T00:00:00 | 开始时间(东八区时间)，目前只支持按月查询  |
| end   | string | 是    | 2021-10-01T00:00:00 | 结束时间(东八区时间)，时间范围支持左闭右开 |

##### 请求头 [#请求头]

该请求操作的实现使用了所有操作的公共请求头。有着详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

##### 请求内容 [#请求内容]

该请求操作的的请求体为空

#### 响应 [#响应]

##### 响应语法 [#响应语法]

```
HTTP/1.1 200 OK
ContentType: application/json
{
        "code": <ErrorCode>,
        "data": <Data>,
        "message": <Message>
}
```

##### 响应头 [#响应头]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

##### 响应内容 [#响应内容]

| 字段名称       | 类型      | 示例                               | 描述                                                         |
| ---------- | ------- | -------------------------------- | ---------------------------------------------------------- |
| start      | string  | 2021-09-01T00:00:00              | 账单开始时间(东八区时间)                                              |
| end        | string  | 2021-10-01T00:00:00              | 账单结束时间(东八区时间)，左闭右开                                         |
| billID     | string  | 3489e21b4a1240d61d45c38e40f376a8 | 账单或者订单编号                                                   |
| type       | string  | bill                             | 账单类型有：bill、order，分别表示：账单、订单                                |
| payStatus  | string  | paid                             | 支付状态有：unpaid、paid、refunded、postpaid，分别表示：未支付、已支付、已退款、转为后付费 |
| product    | string  | SSL证书                            | 产品名称                                                       |
| itemDesc   | string  | Geotrust 企业型SSL证书                | 订单显示商品名，账单显示计费项名                                           |
| fee        | integer | 1995000000                       | 支付总金额，精确到小数点后8位，示例值为19.95元                                 |
| couponFee  | integer | 0                                | 优惠券金额，精确到小数点后8位                                            |
| presentFee | integer | 0                                | 赠送金支付金额，精确到小数点后8位                                          |
| cashFee    | integer | 0                                | 现金支付金额，精确到小数点后8位                                           |
| currency   | string  | CNY                              | 币种：CNY=人民币，USD=美元                                          |

##### 响应状态码 [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误码](#error-code)。

#### 示例 [#示例]

##### 请求示例 [#请求示例]

```
GET /billing-api/v1/bill/overview?start=2021-11-01T00:00:00&end=2021-12-01T00:00:00
Host: api.qiniu.com
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
```

注：要在 Authorization 头部的 \<AccessToken> 前添加 Qiniu 和半角空格。

###### 响应示例 [#响应示例]

```
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Tue, 04 Jan 2022 09:13:06 GMT
X-Reqid: kXAAAACiAypdBscW


{
    "code":0,
    "message":"Success",
    "data":[
        {
            "start":"2021-12-01T00:00:00",
            "end":"2022-01-01T00:00:00",
            "billID":"61d085825e65d175d97c8efb",
            "type":"bill",
            "payStatus":"paid",
            "product":"对象存储",
            "itemDesc":"存储空间-华北",
            "fee":0,
            "couponFee":0,
            "presentFee":0,
            "cashFee":0,
            "currency":"CNY"
        },
        {
            "start":"2021-12-01T00:00:00",
            "end":"2022-01-01T00:00:00",
            "billID":"61d08582722bbb5ef2fb22f7",
            "type":"bill",
            "payStatus":"unpaid",
            "product":"对象存储",
            "itemDesc":"存储空间-华东",
            "fee":7329416000000,
            "couponFee":0,
            "presentFee":0,
            "cashFee":0,
            "currency":"CNY"
        }
    ]
}
```

<span id="%E6%9C%88%E7%BB%93%E7%AE%97%E5%8D%95%E8%AF%A6%E6%83%85%E6%8E%A5%E5%8F%A3" />

### **月结算单详情接口** [#月结算单详情接口]

#### 描述 [#描述-1]

本接口使用GET请求用来获取请求拥有的所有月结算单详情的列表。该接口需要您使用带Authorization签名认证的请求，如果使用匿名请求无法获取账单概览。

#### 请求 [#请求-1]

##### 请求语法 [#请求语法-1]

```
GET /billing-api/v1/bill/detail?start=<StartTime>&end=<EndTime> HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>


注：第一版本的 /billing-api/v1/bill/detail，当您查询日计费的月结算单详情时，响应体里面的 start 和 end 不
会精确到天，若您需要日计费的时间精确到天，请使用第二版 /billing-api/v2/bill/detail 接口，该接口与第一版本的
行为完全一致，唯一的差别是响应体里面的日计费 start 和 end 值会精确到天。
```

##### 请求参数 [#请求参数-1]

| 字段名称  | 类型     | 是否必须 | 示例                  | 说明                     |
| ----- | ------ | ---- | ------------------- | ---------------------- |
| start | string | 是    | 2021-09-01T00:00:00 | 开始时间(东八区时间)，目前只支持按月查询  |
| end   | string | 是    | 2021-10-01T00:00:00 | 结束时间(东八区时间)，时间范围支持左闭右开 |

##### 请求头 [#请求头-1]

该请求操作的实现使用了所有操作的公共请求头。有着详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

##### 请求内容 [#请求内容-1]

该请求操作的的请求体为空

#### 响应 [#响应-1]

##### 响应语法 [#响应语法-1]

```
HTTP/1.1 200 OK
ContentType: application/json
{
        "code": <ErrorCode>,
        "data": <Data>,
        "message": <Message>
}
```

##### 响应头 [#响应头-1]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

##### 响应内容 [#响应内容-1]

| 字段名称         | 类型          | 示例           | 描述                |
| ------------ | ----------- | ------------ | ----------------- |
| currency     | string      | CNY          | 币种：CNY=人民币，USD=美元 |
| total\_money | int64       | 538323000000 | 总费用，精确到小数点后面8位    |
| list         | List\<List> |              | 详情列表              |

List

| 字段名称               | 类型               | 示例                       | 描述                                                                                                                                                                                                                                                    |
| ------------------ | ---------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start              | string           | 2021-09-01T00:00:00      | 账单开始时间(东八区时间)                                                                                                                                                                                                                                         |
| end                | string           | 2021-10-01T00:00:00      | 账单结束时间(东八区时间)，左闭右开                                                                                                                                                                                                                                    |
| bill\_id           | string           | 65bb76a7a8c02e237dda4111 | 账单唯一标识                                                                                                                                                                                                                                                |
| product            | string           | CDN加速                    | 产品线                                                                                                                                                                                                                                                   |
| item               | string           | 动态加速-动态请求次数-华东           | 计费项描述                                                                                                                                                                                                                                                 |
| zone               | string           | 华东                       | 地区                                                                                                                                                                                                                                                    |
| bill\_period       | string           | 月出账单                     | 账单周期                                                                                                                                                                                                                                                  |
| package\_usage     | int64            | 0                        | 免费额度使用量                                                                                                                                                                                                                                               |
| respack\_usage     | int64            | 0                        | 资源包抵扣量                                                                                                                                                                                                                                                |
| total\_usage       | int64            | 7015066                  | 总用量，计量原始量                                                                                                                                                                                                                                             |
| usage\_coefficient | int64            | 1073741824               | 计量转化数，计费的用量 = 计量原始量 ÷ 计量转化数，计量单位为 `usage_unit` 字段中表示的单位。<br />例如：<br /> 计量原始量 total\_usage = 7015066\<br> 计量转化数 usage\_coefficient = 1024 \* 1024 \* 1024 = 1073741824\<br> 计量单位 usage\_unit = GB\<br>则  计费的用量 = 7015066 ÷ 1073741824 = 0.00653329 GB |
| usage\_unit        | string           | GB                       | 计量单位                                                                                                                                                                                                                                                  |
| price\_type        | string           | 各阶梯单价                    | 价格表类型                                                                                                                                                                                                                                                 |
| price\_unit        | string           | CNY/GB                   | 价格单位                                                                                                                                                                                                                                                  |
| item\_money        | int64            | 13233000000              | 计费项费用，精确到小数点后8位，此价格已经计算减免以及抵扣的费用                                                                                                                                                                                                                      |
| discount\_money    | int64            | -13225000000             | 折扣金额，精确到小数点后8位                                                                                                                                                                                                                                        |
| rebate\_money      | int64            | 0                        | 减免金额，精确到小数点后8位                                                                                                                                                                                                                                        |
| currency           | string           | CNY                      | 币种：CNY=人民币，USD=美元                                                                                                                                                                                                                                     |
| usage\_cost        | List\<UsageCost> |                          | 各价格阶梯用量与费用                                                                                                                                                                                                                                            |

UsageCost

| 字段名称                  | 类型      | 示例        | 描述                                 |
| --------------------- | ------- | --------- | ---------------------------------- |
| is\_guaranteed\_price | Boolean | false     | 是否是阶梯保底价格                          |
| money                 | int64   | 0         | 此价格阶梯产生的费用，精确到小数点后8位               |
| price                 | int64   | 112000000 | 价格，精确到小数点后4位，加上price\_unit是单价      |
| usage                 | int64   | 7015066   | 使用量，计量原始值，根据usage\_coefficient进行换算 |
| usage\_from           | int64   | 0         | 价格阶梯起始量，计量原始量                      |
| usage\_to             | int64   | 1024      | 价格阶梯结束量，计量原始量，-1表示无穷大              |

##### 响应状态码 [#响应状态码-1]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误码](#error-code)。

#### 示例 [#示例-1]

##### 请求示例 [#请求示例-1]

```
GET /billing-api/v1/bill/detail?start=2021-11-01T00:00:00&end=2021-12-01T00:00:00
Host: api.qiniu.com
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
```

注：要在 Authorization 头部的 \<AccessToken> 前添加 Qiniu 和半角空格。

###### 响应示例 [#响应示例-1]

```
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Thu, 24 Feb 2022 08:29:17 GMT
X-Reqid: 2ZUBFPIhD-akXtYW

{
 "code": 0,
 "message": "Success",
 "data": {
         "currency": "CNY",
         "total_money": 538323000000,
         "list": [
            {
                "currency": "CNY",
                "discount_money": 0,
                "end": "2022-03-01T00:00:00",
                "bill_id":  "65bb76a7a8c02e237dda4111",
                "item": "CDN-HTTPS 流量-其它地区",
                "item_money": 0,
                "package_usage": 0,
                "price_type": "各阶梯单价",
                "price_unit": "CNY/GB",
                "product": "CDN加速",
                "rebate_money": 0,
                "respack_usage": 0,
                "start": "2022-02-01T00:00:00",
                "total_usage": 7015066,
                "usage_coefficient": 1073741824,
                "usage_cost": [
                    {
                        "is_guaranteed_price": false,
                        "money": 0,
                        "price": 112000000,
                        "usage": 7015066,
                        "usage_from": 0,
                        "usage_to": 10995116277760
                    },
                    {
                        "is_guaranteed_price": false,
                        "money": 0,
                        "price": 98000000,
                        "usage": 0,
                        "usage_from": 10995116277760,
                        "usage_to": 54975581388800
                    },
                    {
                        "is_guaranteed_price": false,
                        "money": 0,
                        "price": 85000000,
                        "usage": 0,
                        "usage_from": 54975581388800,
                        "usage_to": 109951162777600
                    },
                    {
                        "is_guaranteed_price": false,
                        "money": 0,
                        "price": 85000000,
                        "usage": 0,
                        "usage_from": 109951162777600,
                        "usage_to": 109951162777600
                    }
                ],
                "usage_unit": "GB",
                "zone": "其它地区"
            },
        }
}
```

<span id="%E8%AE%A2%E5%8D%95%E5%88%97%E8%A1%A8%E6%8E%A5%E5%8F%A3" />

### **订单列表接口** [#订单列表接口]

#### 描述 [#描述-2]

本接口作 GET 请求用来获取订单列表数据。该接口需要您使用带Authorization签名认证的请求，如果使用匿名请求无法获取订单数据。

#### 请求 [#请求-2]

##### 请求语法 [#请求语法-2]

```
GET /billing-api/v1/order/order-list?seller_id=<SellerID>&create_time_start=<startTime>&create_time_end=<endTime>&status=<status>&page=<page>&page_size=<pageSize> HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>
```

##### 请求参数 [#请求参数-2]

| 字段名称                | 类型      | 是否必须 | 示例                        | 说明                                           |
| ------------------- | ------- | ---- | ------------------------- | -------------------------------------------- |
| seller\_id          | integer | 否    | 45                        | 通过产品归属过滤，产品归属常量值见 [订单产品归属](#order-seller) 章节 |
| status              | array   | 否    | 1                         | 通过订单状态过滤，取值范围：1(新建)、2(已支付)、3(已作废)、5(后付费)     |
| create\_time\_start | string  | 否    | 2021-07-31T23:50:00+08:00 | 通过订单创建时间过滤，默认查询当前时间最近6个月内订单 ( 东八区时间 )        |
| create\_time\_end   | string  | 否    | 2022-07-31T23:50:00+08:00 | 通过订单创建时间过滤，默认查询当前时间最近6个月内订单 ( 东八区时间 )        |
| page                | integer | 否    | 1                         | 页码，从1开始                                      |
| page\_size          | integer | 否    | 20                        | 每页条数，默认20，最大不超过200                           |

##### 请求头 [#请求头-2]

该请求操作的实现使用了所有操作的公共请求头。有着详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

##### 请求内容 [#请求内容-2]

该请求操作的的请求体为空

#### 响应 [#响应-2]

##### 响应语法 [#响应语法-2]

```
HTTP/1.1 200 OK
ContentType: application/json
{
        "code": <ErrorCode>,
        "data": <Data>,
        "message": <Message>
}
```

##### 响应头 [#响应头-2]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

##### 响应内容 [#响应内容-2]

| 字段名称               | 类型      | 示例                               | 描述                                                       |
| ------------------ | ------- | -------------------------------- | -------------------------------------------------------- |
| order\_hash        | string  | 3489e21b4a1240d61d45c38e40f376a8 | 订单唯一编号                                                   |
| union\_order\_hash | string  | QU01G762EJHZY4QS8E82BASDWR0G     | 订单统一编号                                                   |
| create\_time       | string  | 3489e21b4a1240d61d45c38e40f376a8 | 订单创建时间 ( 东八区时间 )                                         |
| pay\_action\_time  | string  | 0001-01-01T00:00:00+08:00        | 订单支付时间 ( 东八区时间 )，未支付订单返回零值时间                             |
| expired\_time      | string  | 2022-07-31T23:50:00+08:00        | 订单支付过期时间 ( 东八区时间 )                                       |
| seller\_id         | integer | 45                               | 订单产品归属，释义见 [订单产品归属](#order-seller) 章节                    |
| status             | integer | 2                                | 订单状态：1(新建)、2(已支付)、3(已作废)、5(后付费)，                         |
| currency\_type     | string  | CNY                              | 订单币种：CNY(人民币)、USD(美元)                                    |
| c\_fee             | integer | 1200000000                       | 订单总金额，实际金额保留2位小数乘以100000000的整数值，如实际金额 1.23，则返回 123000000 |

##### 响应状态码 [#响应状态码-2]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误码](#error-code)。

#### 示例 [#示例-2]

##### 请求示例 [#请求示例-2]

```
GET /billing-api/v1/order/order-list?status=1&status=2&seller_id=45
Host: api.qiniu.com
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
```

注：要在 Authorization 头部的 \<AccessToken> 前添加 Qiniu 和半角空格。

###### 响应示例 [#响应示例-2]

```
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Tue, 04 Jan 2022 09:13:06 GMT
X-Reqid: kXAAAACiAypdBscW

{
    "code": 0,
    "data": [
        {
            "c_fee": 89870000000,
            "create_time": "2022-08-02T18:09:03+08:00",
            "currency_type": "CNY",
            "expired_time": "2022-08-09T18:09:03+08:00",
            "order_hash": "13a54eb19f708bc8b94824bafd143f76",
            "pay_action_time": "2022-08-09T18:19:03+08:00",
            "seller_id": 45,
            "status": 2,
            "union_order_hash": "QU01G9F0FGQK1S1HSAP921WAV4PA"
        },
        {
            "c_fee": 89870000000,
            "create_time": "2022-07-28T15:07:03+08:00",
            "currency_type": "CNY",
            "expired_time": "2022-07-31T23:50:00+08:00",
            "order_hash": "9a05f866685148fae608fd509a19c822",
            "pay_action_time": "0001-01-01T00:00:00+08:00",
            "seller_id": 45,
            "status": 1,
            "union_order_hash": "QU01G91T2P0JE9TQ04M1HEP548Z5"
        }
    ],
    "message": "Success"
}
```

<span id="%E8%AE%A2%E5%8D%95%E8%AF%A6%E6%83%85%E6%8E%A5%E5%8F%A3" />

### **订单详情接口** [#订单详情接口]

#### 描述 [#描述-3]

本接口作 GET 请求用来获取订单详情数据。该接口需要您使用带Authorization签名认证的请求，如果使用匿名请求无法获取订单详情。

#### 请求 [#请求-3]

##### 请求语法 [#请求语法-3]

```
GET /billing-api/v1/order/order-detail?order_hash=<OrderHash> HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>
```

##### 请求参数 [#请求参数-3]

| 字段名称        | 类型     | 是否必须 | 示例                               | 说明     |
| ----------- | ------ | ---- | -------------------------------- | ------ |
| order\_hash | string | 是    | 3489e21b4a1240d61d45c38e40f376a8 | 订单唯一编号 |

##### 请求头 [#请求头-3]

该请求操作的实现使用了所有操作的公共请求头。有着详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)
。

##### 请求内容 [#请求内容-3]

该请求操作的的请求体为空

#### 响应 [#响应-3]

##### 响应语法 [#响应语法-3]

```
HTTP/1.1 200 OK
ContentType: application/json
{
        "code": <ErrorCode>,
        "data": <Data>,
        "message": <Message>
}
```

##### 响应头 [#响应头-3]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)
。

##### 响应内容 [#响应内容-3]

| 字段名称               | 类型      | 示例                               | 描述                                                       |
| ------------------ | ------- | -------------------------------- | -------------------------------------------------------- |
| order\_hash        | string  | 3489e21b4a1240d61d45c38e40f376a8 | 订单唯一编号                                                   |
| union\_order\_hash | string  | QU01G762EJHZY4QS8E82BASDWR0G     | 订单统一编号 (调用订单取消接口时需要传递此参数)                                |
| create\_time       | string  | 3489e21b4a1240d61d45c38e40f376a8 | 订单创建时间 ( 东八区时间 )                                         |
| pay\_action\_time  | string  | 0001-01-01T00:00:00+08:00        | 订单支付时间 ( 东八区时间 )，未支付订单返回零值时间                             |
| expired\_time      | string  | 2022-07-31T23:50:00+08:00        | 订单支付过期时间 ( 东八区时间 )                                       |
| seller\_id         | integer | 45                               | 订单产品归属，释义见 [订单产品归属](#order-seller) 章节                    |
| status             | integer | 2                                | 订单状态: 1(新建)、2(已支付)、3(已作废)、5(后付费)，                        |
| currency\_type     | string  | CNY                              | 订单币种: CNY(人民币)、USD(美元)                                   |
| c\_fee             | integer | 1200000000                       | 订单总金额，实际金额保留2位小数乘以100000000的整数值，如实际金额 1.23，则返回 123000000 |
| product\_orders    | array   | \[\{...}]                        | 商品订单明细，结构见下表                                             |

商品订单明细(product\_orders)结构:

| 字段名称                 | 类型      | 示例                          | 描述                                                                                                                                         |
| -------------------- | ------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| product\_name        | string  | CDN流量                       | 商品名称                                                                                                                                       |
| seller\_name         | string  | CDN                         | 产品归属，释义见 [订单产品归属](#order-seller) 章节                                                                                                        |
| quantity             | integer | 1                           | 数量                                                                                                                                         |
| c\_fee               | integer | 120000000                   | 商品订单金额，实际金额保留2位小数乘以100000000的整数值，如实际金额 1.23，则返回 123000000                                                                                  |
| product\_description | string  | CDN流量100TB                  | 商品描述，可能为空                                                                                                                                  |
| status               | integer | 2                           | 发货状态，取值范围: 1(新建)、2(完成）                                                                                                                     |
| start\_time          | string  | 0001-01-01T00:00:00+08:00   | 初始值为零值时间，仅发货完成后有值 ( 东八区时间 )                                                                                                                |
| end\_time            | string  | 0001-01-01T00:00:00+08:00   | 初始值为零值时间，仅发货完成后有值 ( 东八区时间 )                                                                                                                |
| category\_id         | integer | 0                           | 商品分类，默认为0，资源包类订单值为 3                                                                                                                       |
| carry\_over\_policy  | integer | 2                           | 结转方式，仅对资源包类订单有效，取值范围: 0(按月分配可结转)、1(按月分配不可结转)、2(一次性分配)，释义见[资源包介绍](/account/resource-package-management/0-the-resource-bundle-is-introduced) |
| effect\_time         | string  | 2022-06-01T00:00:00+08:00   | 资源包生效时间，仅对资源包类订单有效 ( 东八区时间 )                                                                                                               |
| extra\_details       | array   | \[\{"label":"","value":""}] | 其他额外细节信息，结构见下表                                            <br /><br />                                                                     |

其他额外细节信息(extra\_details)结构:

| 字段名称  | 类型     | 示例   | 描述 |
| ----- | ------ | ---- | -- |
| label | string | 资源类型 |    |
| value | string | 云主机  |    |

##### 响应状态码 [#响应状态码-3]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误码](#error-code)。

#### 示例 [#示例-3]

##### 请求示例 [#请求示例-3]

```
GET /billing-api/v1/order/order-detail?order_hash=3489e21b4a1240d61d45c38e40f376a8
Host: api.qiniu.com
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
```

注：要在 Authorization 头部的 \<AccessToken> 前添加 Qiniu 和半角空格。

###### 响应示例 [#响应示例-3]

```
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Tue, 04 Jan 2022 09:13:06 GMT
X-Reqid: kXAAAACiAypdBscW

{
    "code":0,
    "data":{
        "c_fee":1350000000,
        "create_time":"2022-05-19T17:18:35+08:00",
        "currency_type":"CNY",
        "expired_time":"2022-05-26T17:18:35+08:00",
        "order_hash":"30e9bcc5762be923aa29bdf3bdd31f5b",
        "pay_action_time":"0001-01-01T00:00:00+08:00",
        "product_orders":[
            {
                "c_fee":1350000000,
                "carry_over_policy":2,
                "category_id":3,
                "effect_time":"2022-06-01T00:00:00+08:00",
                "end_time":"0001-01-01T00:00:00+08:00",
                "extra_details":[
                    {
                        "label":"订单类型",
                        "value":"资源包"
                    }
                ],
                "product_description":"",
                "product_name":"视频监控上行流量100GB包年",
                "quantity":1,
                "seller_name":"视频监控",
                "start_time":"0001-01-01T00:00:00+08:00",
                "status":1
            }
        ],
        "seller_id":82,
        "status":1,
        "union_order_hash":"QU01G3DSS6XJ466ZGVBAKQVFPYGX"
    },
    "message":"Success"
}
```

<span id="%E8%AE%A2%E5%8D%95%E5%8F%96%E6%B6%88%E6%8E%A5%E5%8F%A3" />

### **订单取消接口** [#订单取消接口]

#### 描述 [#描述-4]

本接口作 POST 请求用来取消订单。该接口需要您使用带Authorization签名认证的请求，如果使用匿名请求无法获取订单详情。

#### 请求 [#请求-4]

##### 请求语法 [#请求语法-4]

```
POST /billing-api/v1/order/order-cancel HTTP/1.1
Host: api.qiniu.com
Content-Type: application/json
Authorization: Qiniu <AccessToken>
```

##### 请求参数 [#请求参数-4]

| 字段名称               | 类型     | 是否必须 | 示例                           | 说明                |
| ------------------ | ------ | ---- | ---------------------------- | ----------------- |
| union\_order\_hash | string | 是    | QU01G762EJHZY4QS8E82BASDWR0G | 订单统一编号，注意不是订单唯一编号 |

##### 请求头 [#请求头-4]

该请求操作的实现使用了所有操作的公共请求头。有着详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)
。

##### 请求内容 [#请求内容-4]

```
{"union_order_hash":"string"}
```

#### 响应 [#响应-4]

##### 响应语法 [#响应语法-4]

```
HTTP/1.1 200 OK
ContentType: application/json
{
        "code": <ErrorCode>,
        "data": <Data>,
        "message": <Message>
}
```

##### 响应头 [#响应头-4]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)
。

##### 响应内容 [#响应内容-4]

该请求正常无响应内容

##### 响应状态码 [#响应状态码-4]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误码](#error-code)。

#### 示例 [#示例-4]

##### 请求示例 [#请求示例-4]

```
POST /billing-api/v1/order/order-cancel
Host: api.qiniu.com
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
Content-Type: application/json

{"union_order_hash":"QU01G3DSS6XJ466ZGVBAKQVFPYGX"}
```

注：要在 Authorization 头部的 \<AccessToken> 前添加 Qiniu 和半角空格。

###### 响应示例 [#响应示例-4]

```
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Tue, 04 Jan 2022 09:13:06 GMT
X-Reqid: kXAAAACiAypdBscW

{
    "code":0,
    "message":"Success"
}
```

<span id="%E8%B5%84%E6%BA%90%E5%8C%85%E5%BD%93%E6%9C%88%E6%A6%82%E8%A7%88%E6%8E%A5%E5%8F%A3" />

### **资源包当月概览接口** [#资源包当月概览接口]

#### 描述 [#描述-5]

本接口作 GET 请求用来获取资源包当月概览数据。该接口需要您使用带Authorization签名认证的请求，如果使用匿名请求无法获取数据。

#### 请求 [#请求-5]

##### 请求语法 [#请求语法-5]

```
GET /billing-api/v1/respack/month-overview?page=<Page>&page_size=<PageSize> HTTP/1.1
Host: api.qiniu.com
Authorization: Qiniu <AccessToken>
```

##### 请求参数 [#请求参数-5]

| 字段名称       | 类型      | 是否必须 | 示例 | 说明                 |
| ---------- | ------- | ---- | -- | ------------------ |
| page       | integer | 否    | 1  | 页码，从1开始            |
| page\_size | integer | 否    | 20 | 每页条数，默认20，最大不超过200 |

##### 请求头 [#请求头-5]

该请求操作的实现使用了所有操作的公共请求头。有着详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)
。

##### 请求内容 [#请求内容-5]

该请求操作的的请求体为空

#### 响应 [#响应-5]

##### 响应语法 [#响应语法-5]

```
HTTP/1.1 200 OK
ContentType: application/json
{
        "code": <ErrorCode>,
        "data": <Data>,
        "message": <Message>
}
```

##### 响应头 [#响应头-5]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)
。

##### 响应内容 [#响应内容-5]

| 字段名称            | 类型      | 示例        | 描述     |
| --------------- | ------- | --------- | ------ |
| item\_name      | string  | CDN加速通用流量 | 计费项目   |
| zone\_name      | string  | 中国大陆      | 可用区域   |
| available\_time | string  | 全时段       | 可用时段   |
| total\_surplus  | integer | 1024      | 当月可用总量 |
| month\_used     | integer | 0         | 当月已用量  |
| month\_remain   | integer | 1024      | 当月剩余可用 |
| respack\_unit   | string  | GB        | 用量单位   |

##### 响应状态码 [#响应状态码-5]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误码](#error-code)。

#### 示例 [#示例-5]

##### 请求示例 [#请求示例-5]

```
GET /billing-api/v1/respack/month-overview?page=1&page_size=20
Host: api.qiniu.com
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
```

注：要在 Authorization 头部的 \<AccessToken> 前添加 Qiniu 和半角空格。

###### 响应示例 [#响应示例-5]

```
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Tue, 04 Jan 2022 09:13:06 GMT
X-Reqid: kXAAAACiAypdBscW

{
    "code": 0,
    "data": [
        {
            "available_time": "全时段",
            "item_name": "CDN加速通用计费项",
            "month_remain": 5120,
            "month_used": 0,
            "respack_unit": "GB",
            "total_surplus": 5120,
            "zone_name": "中国大陆"
        }
    ],
    "message": "Success"
}
```

<span id="%E8%B5%84%E6%BA%90%E5%8C%85%E5%88%97%E8%A1%A8%E6%8E%A5%E5%8F%A3" />

### **资源包列表接口** [#资源包列表接口]

#### 描述 [#描述-6]

本接口作 GET 请求用来获取资源包列表数据。该接口需要您使用带Authorization签名认证的请求，如果使用匿名请求无法获取数据。

#### 请求 [#请求-6]

##### 请求语法 [#请求语法-6]

```
GET /billing-api/v1/respack/list?page=<Page>&page_size=<PageSize> HTTP/1.1
Host: api.qiniu.com
Authorization: Qiniu <AccessToken>
```

##### 请求参数 [#请求参数-6]

| 字段名称        | 类型      | 是否必须 | 示例 | 说明                                 |
| ----------- | ------- | ---- | -- | ---------------------------------- |
| order\_hash | string  | 否    | 1  | 订单唯一编号，查询指定订单的资源包                  |
| status      | integer | 否    | 1  | 资源包状态: 1(未使用)、2(使用中)、3(已用完)、4(已过期) |
| page        | integer | 否    | 1  | 页码，从1开始                            |
| page\_size  | integer | 否    | 20 | 每页条数，默认20，最大不超过200                 |

##### 请求头 [#请求头-6]

该请求操作的实现使用了所有操作的公共请求头。有着详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)
。

##### 请求内容 [#请求内容-6]

该请求操作的的请求体为空

#### 响应 [#响应-6]

##### 响应语法 [#响应语法-6]

```
HTTP/1.1 200 OK
ContentType: application/json
{
        "code": <ErrorCode>,
        "data": <Data>,
        "message": <Message>
}
```

##### 响应头 [#响应头-6]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)
。

##### 响应内容 [#响应内容-6]

| 字段名称                | 类型      | 示例                               | 描述                                                                                                                              |
| ------------------- | ------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| respack\_name       | string  | 中国大陆全时段加速流量5TB                   | 资源包名称                                                                                                                           |
| effective\_start    | string  | 2020-08-11T04:05:14+08:00        | 有效时间起始 ( 东八区时间 )                                                                                                                |
| effective\_end      | string  | 2022-08-11T04:05:14+08:00        | 有效时间终止 ( 东八区时间 )                                                                                                                |
| carry\_over\_policy | integer | 1                                | 分配方式，取值范围: 0(按月分配可结转)、1(按月分配不可结转)、2(一次性分配)，释义见[资源包介绍](/account/resource-package-management/0-the-resource-bundle-is-introduced) |
| status              | integer | 2                                | 资源包状态: 1(未使用)、2(使用中)、3(已用完)、4(已过期)                                                                                              |
| total\_amount       | integer | 1024                             | 资源包总量                                                                                                                           |
| used\_amount        | integer | 1024                             | 已用量                                                                                                                             |
| respack\_unit       | string  | GB                               | 用量单位                                                                                                                            |
| data\_update\_time  | string  | 2022-05-11T04:05:14+08:00        | 数据更新时间 ( 东八区时间 )                                                                                                                |
| order\_hash         | string  | f9cefba946e0b547a72abb4a9d4acc3c | 订单唯一编号，用于查询资源包详情                                                                                                                |
| po\_id              | integer | 1                                | 商品订单编号，用于查询资源包详情                                                                                                                |

##### 响应状态码 [#响应状态码-6]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误码](#error-code)。

#### 示例 [#示例-6]

##### 请求示例 [#请求示例-6]

```
GET /billing-api/v1/respack/list?page=1&page_size=20
Host: api.qiniu.com
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
```

注：要在 Authorization 头部的 \<AccessToken> 前添加 Qiniu 和半角空格。

###### 响应示例 [#响应示例-6]

```
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Tue, 04 Jan 2022 09:13:06 GMT
X-Reqid: kXAAAACiAypdBscW

{
    "code": 0,
    "data": [
        {
            "carry_over_policy": 2,
            "data_update_time": "2022-08-11T04:05:14+08:00",
            "effective_end": "2022-08-11T04:05:14+08:00",
            "effective_start": "2020-08-11T04:05:14+08:00",
            "order_hash": "65abb4569ce66c6592571824d8492666",
            "po_id": 524913,
            "respack_name": "国内 HTTPS 10GB 动态加速闲时包年",
            "respack_unit": "GB",
            "status": 4,
            "total_amount": 10,
            "used_amount": 0
        }
    ],
    "message": "Success"
}
```

<span id="%E8%B5%84%E6%BA%90%E5%8C%85%E8%AF%A6%E6%83%85%E6%8E%A5%E5%8F%A3" />

### **资源包详情接口** [#资源包详情接口]

#### 描述 [#描述-7]

本接口作 GET 请求用来获取资源包详情数据。该接口需要您使用带Authorization签名认证的请求，如果使用匿名请求无法获取数据。

#### 请求 [#请求-7]

##### 请求语法 [#请求语法-7]

```
GET /billing-api/v1/respack/detail?order_hash=<OrderHash>&po_id=<PoID> HTTP/1.1
Host: api.qiniu.com
Authorization: Qiniu <AccessToken>
```

##### 请求参数 [#请求参数-7]

| 字段名称        | 类型      | 是否必须 | 示例                               | 说明                                   |
| ----------- | ------- | ---- | -------------------------------- | ------------------------------------ |
| order\_hash | string  | 是    | 65abb4569ce66c6592571824d8492666 | 订单唯一编号                               |
| po\_id      | integer | 是    | 524913                           | 商品订单编号，取自 respack/list 返回结果中的 po\_id |

##### 请求头 [#请求头-7]

该请求操作的实现使用了所有操作的公共请求头。有着详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)
。

##### 请求内容 [#请求内容-7]

该请求操作的的请求体为空

#### 响应 [#响应-7]

##### 响应语法 [#响应语法-7]

```
HTTP/1.1 200 OK
ContentType: application/json
{
        "code": <ErrorCode>,
        "data": <Data>,
        "message": <Message>
}
```

##### 响应头 [#响应头-7]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)
。

##### 响应内容 [#响应内容-7]

| 字段名称                | 类型      | 示例                                             | 描述                                                                                                                              |
| ------------------- | ------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| respack\_name       | string  | 中国大陆全时段加速流量5TB                                 | 资源包名称                                                                                                                           |
| effective\_start    | string  | 2020-06-01T00:00:00+08:00                      | 有效时间起始 ( 东八区时间 )                                                                                                                |
| effective\_end      | string  | 2022-06-01T00:00:00+08:00                      | 有效时间终止 ( 东八区时间 )                                                                                                                |
| carry\_over\_policy | integer | 1                                              | 分配方式，取值范围: 0(按月分配可结转)、1(按月分配不可结转)、2(一次性分配)，释义见[资源包介绍](/account/resource-package-management/0-the-resource-bundle-is-introduced) |
| status              | integer | 2                                              | 资源包状态: 1(未使用)、2(使用中)、3(已用完)、4(已过期)                                                                                              |
| total\_amount       | integer | 1024                                           | 资源包总量                                                                                                                           |
| used\_amount        | integer | 1024                                           | 已用量                                                                                                                             |
| respack\_unit       | string  | GB                                             | 用量单位                                                                                                                            |
| data\_update\_time  | string  | 2021-10-01T00:00:00+08:00                      | 数据更新时间 ( 东八区时间 )                                                                                                                |
| order\_hash         | string  | f9cefba946e0b547a72abb4a9d4acc3c               | 订单唯一编号，用于查询资源包详情                                                                                                                |
| po\_id              | integer | 1                                              | 商品订单编号，用于查询资源包详情                                                                                                                |
| is\_combo\_item     | bool    | false                                          | 是否是融合资源包，true表示融合资源包，false表示普通包                                                                                                 |
| description         | string  | 全站加速DCDN-HTTP 流量、全站加速DCDN-HTTPS 流量，抵扣系数为1:1.15 | 融合计费项抵扣规则说明                                                                                                                     |
| deduct\_details     | array   | \[\{...}]                                      | 资源包抵扣明细，结构见下表                                                                                                                   |

资源包抵扣明细(deduct\_details) 结构:

| 字段名称           | 类型      | 示例                        | 描述                        |
| -------------- | ------- | ------------------------- | ------------------------- |
| deduct\_date   | string  | 2021-10-01T00:00:00+08:00 | 抵扣月份 ( 东八区时间 )            |
| deduct\_status | integer | 2                         | 出账抵扣状态: 1(未出账抵扣)、2(已出账抵扣) |
| deduct\_amount | string  | 1024                      | 抵扣量                       |

##### 响应状态码 [#响应状态码-7]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误码](#error-code)。

#### 示例 [#示例-7]

##### 请求示例 [#请求示例-7]

```
GET /billing-api/v1/respack/detail?order_hash=65abb4569ce66c6592571824d8492666&po_id=524913
Host: api.qiniu.com
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
```

注：要在 Authorization 头部的 \<AccessToken> 前添加 Qiniu 和半角空格。

###### 响应示例 [#响应示例-7]

```
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Tue, 04 Jan 2022 09:13:06 GMT
X-Reqid: kXAAAACiAypdBscW


{
    "code": 0,
    "data": {
        "carry_over_policy": 2,
        "deduct_details": [
            {
                "deduct_date": "2021-10-01T00:00:00+08:00",
                "deduct_status": 2,
                "deduct_amount: 1024
            }
        ],
        "description": "",
        "effective_end": "2022-06-01T00:00:00+08:00",
        "effective_start": "2021-06-01T00:00:00+08:00",
        "is_combo_item": false,
        "item_code": "fusion:dyn:transfer:https",
        "order_hash": "65abb4569ce66c6592571824d8492666",
        "respack_name": "国内 HTTPS 10GB 动态加速闲时包年",
        "respack_unit": "GB",
        "status": 4,
        "total_amount": 10,
        "used_amount": 0
    },
    "message": "Success"
}
```

<span id="%E8%B5%84%E6%BA%90%E5%8C%85%E5%8E%86%E5%8F%B2%E6%8A%B5%E6%89%A3%E6%98%8E%E7%BB%86%E6%8E%A5%E5%8F%A3" />

### **资源包历史抵扣明细接口** [#资源包历史抵扣明细接口]

#### 描述 [#描述-8]

本接口作 GET 请求用来获取资源包历史抵扣数据。该接口需要您使用带Authorization签名认证的请求，如果使用匿名请求无法获取数据。

#### 请求 [#请求-8]

##### 请求语法 [#请求语法-8]

```
GET /billing-api/v1/respack/history-usage?month=<Month> HTTP/1.1
Host: api.qiniu.com
Authorization: Qiniu <AccessToken>
```

##### 请求参数 [#请求参数-8]

| 字段名称  | 类型     | 是否必须 | 示例     | 说明            |
| ----- | ------ | ---- | ------ | ------------- |
| month | string | 是    | 202205 | 月份，格式: YYYYmm |

##### 请求头 [#请求头-8]

该请求操作的实现使用了所有操作的公共请求头。有着详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)
。

##### 请求内容 [#请求内容-8]

该请求操作的的请求体为空

#### 响应 [#响应-8]

##### 响应语法 [#响应语法-8]

```
HTTP/1.1 200 OK
ContentType: application/json
{
        "code": <ErrorCode>,
        "data": <Data>,
        "message": <Message>
}
```

##### 响应头 [#响应头-8]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)
。

##### 响应内容 [#响应内容-8]

| 字段名称                 | 类型      | 示例                               | 描述                                                                                             |
| -------------------- | ------- | -------------------------------- | ---------------------------------------------------------------------------------------------- |
| order\_hash          | string  | 9cf81ce0056dc6df87901c5fe2fcfaaf | 订单唯一编号                                                                                         |
| respack\_name        | string  | 中国大陆全时段加速流量5TB                   | 资源包名称                                                                                          |
| item\_name           | string  | CDN加速通用加速                        | 计费项目                                                                                           |
| is\_combo\_item      | bool    | false                            | 是否是融合计费项目，释义见[资源包介绍](/account/resource-package-management/0-the-resource-bundle-is-introduced) |
| total\_this\_month   | integer | 5120                             | 当月总共可用(含上月结余)                                                                                  |
| used\_this\_month    | integer | 0                                | 当月本包已用                                                                                         |
| usable\_this\_month  | integer | 5120                             | 本月剩余可用                                                                                         |
| respack\_unit        | string  | GB                               | 用量单位                                                                                           |
| data\_update\_time   | string  | 2020-10-31T16:00:00Z             | 数据更新时间 ( 东八区时间 )                                                                               |
| combo\_item\_details | array   | \[\{...}]                        | 融合包的单计费项抵扣明细，结构见下表                                                                             |

融合包的单计费项抵扣明细(combo\_item\_details) 结构:

| 字段名称                   | 类型      | 示例    | 描述      |
| ---------------------- | ------- | ----- | ------- |
| item\_name             | string  | CDN加速 | 计费项项目   |
| used\_raw\_this\_month | integer | 2     | 账单上的抵扣量 |

##### 响应状态码 [#响应状态码-8]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误码](#error-code)。

#### 示例 [#示例-8]

##### 请求示例 [#请求示例-8]

```
GET /billing-api/v1/respack/history-usage?month=202206
Host: api.qiniu.com
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
```

注：要在 Authorization 头部的 \<AccessToken> 前添加 Qiniu 和半角空格。

###### 响应示例 [#响应示例-8]

```
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Tue, 04 Jan 2022 09:13:06 GMT
X-Reqid: kXAAAACiAypdBscW

{
    "code": 0,
    "data": [
        {
            "combo_item_details": [
                {
                    "item_name": "CDN加速 HTTP",
                    "used_raw_this_month": 0
                },
                {
                    "item_name": "CND加速 HTTPS",
                   "used_raw_this_month": 0
                },
            ],
            "data_update_time": "2022-06-01T00:00:00+08:00",
            "is_combo_item": true,
            "item_name": "CDN加速通用计费项-版本2",
            "order_hash": "9cf81ce0056dc6df87901c5fe2fcfaaf",
            "respack_name": "中国大陆全时段加速流量5TB",
            "respack_unit": "GB",
            "total_this_month": 5120,
            "usable_this_month": 5120,
            "used_this_month": 0
        }
    ],
    "message": "Success"
}
```

<span id="%E5%AE%9E%E6%97%B6%E6%B6%88%E8%B4%B9%E6%AF%8F%E6%97%A5%E5%BF%AB%E7%85%A7%E8%AF%A6%E6%83%85%E6%8E%A5%E5%8F%A3" />

### **按量计费预估每日快照详情接口** [#按量计费预估每日快照详情接口]

#### 描述 [#描述-9]

本接口使用 HTTP GET 请求来获取按量计费预估每日快照详情数据。该接口的请求需要使用 Authorization 签名认证；
若您要请求当天的数据，请您在上午 8 点以后调用此接口。

##### 按量计费预估快照说明 [#按量计费预估快照说明]

1，每月 1 号的按量计费预估快照为上月 1 号到本月 1 号（不含）的累计消费
2，每月其他日期的按量计费预估快照为当月 1 号到查询日期（不含）的累计消费

#### 请求 [#请求-9]

##### 请求语法 [#请求语法-9]

```
GET /billing-api/v2/bill/snapshot?date=<SnapshotDate> HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>
```

##### 请求参数 [#请求参数-9]

| 字段名称 | 类型     | 是否必须 | 说明                                                           | 示例（以2023年3月为例）                                                                                                                      |
| ---- | ------ | ---- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| date | string | 是    | 1，日期（东八区时间）格式为 YYYY-mm-ddT00:00:00\<br>2，仅支持传入当前月份 1 号到今天的日期 | 1，当入参是 2023-03-01T00:00:00，返回的是 3 月 1 号的快照，包含的是 2 月整月的累计消费<br />2，当入参是 2023-03-10T00:00:00，返回的是 3 月 10 号的快照，包含的是 1 号到 10 号（不含）的累计消费 |

##### 请求头 [#请求头-9]

该请求操作的实现使用了所有操作的公共请求头。有着详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

##### 请求内容 [#请求内容-9]

该请求操作的的请求体为空

#### 响应 [#响应-9]

##### 响应语法 [#响应语法-9]

```
HTTP/1.1 200 OK
ContentType: application/json
{
        "code": <ErrorCode>,
        "data": <Data>,
        "message": <Message>
}
```

##### 响应头 [#响应头-9]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

##### 响应内容 [#响应内容-9]

| 字段名称         | 类型          | 示例           | 描述                |
| ------------ | ----------- | ------------ | ----------------- |
| currency     | string      | CNY          | 币种：CNY=人民币，USD=美元 |
| total\_money | int64       | 538323000000 | 总费用，精确到小数点后面8位    |
| list         | List\<List> |              | 详情列表              |

List

| 字段名称               | 类型               | 示例                  | 描述                                                                                                                                                                                                                                                    |
| ------------------ | ---------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start              | string           | 2021-09-01T00:00:00 | 账单开始时间(东八区时间)\<br>如果是月计费账单，那么该时间为账单月份的 1 号 0 点<br />如果是日计费账单，该时间是账单日的 0 点                                                                                                                                                                             |
| end                | string           | 2021-10-01T00:00:00 | 账单结束时间(东八区时间)\<br>如果是月计费账单，那么该时间为传入的参数 date <br />如果是日计费账单，那么该时间比 start 大一天                                                                                                                                                                           |
| product            | string           | CDN加速               | 产品线                                                                                                                                                                                                                                                   |
| item               | string           | 动态加速-动态请求次数-华东      | 计费项描述                                                                                                                                                                                                                                                 |
| zone               | string           | 华东                  | 地区                                                                                                                                                                                                                                                    |
| bill\_period       | string           | 月出账单                | 账单周期                                                                                                                                                                                                                                                  |
| package\_usage     | int64            | 0                   | 免费额度使用量                                                                                                                                                                                                                                               |
| respack\_usage     | int64            | 0                   | 资源包抵扣量                                                                                                                                                                                                                                                |
| total\_usage       | int64            | 7015066             | 总用量，计量原始量                                                                                                                                                                                                                                             |
| usage\_coefficient | int64            | 1073741824          | 计量转化数，计费的用量 = 计量原始量 ÷ 计量转化数，计量单位为 `usage_unit` 字段中表示的单位。<br />例如：<br /> 计量原始量 total\_usage = 7015066\<br> 计量转化数 usage\_coefficient = 1024 \* 1024 \* 1024 = 1073741824\<br> 计量单位 usage\_unit = GB\<br>则  计费的用量 = 7015066 ÷ 1073741824 = 0.00653329 GB |
| usage\_unit        | string           | GB                  | 计量单位                                                                                                                                                                                                                                                  |
| price\_type        | string           | 各阶梯单价               | 价格表类型                                                                                                                                                                                                                                                 |
| price\_unit        | string           | CNY/GB              | 价格单位                                                                                                                                                                                                                                                  |
| item\_money        | int64            | 13233000000         | 计费项费用，此价格已经计算减免以及抵扣的费用                                                                                                                                                                                                                                |
| discount\_money    | int64            | -13225000000        | 折扣金额，精确到小数点后8位                                                                                                                                                                                                                                        |
| rebate\_money      | int64            | 0                   | 减免金额，精确到小数点后8位                                                                                                                                                                                                                                        |
| currency           | string           | CNY                 | 币种：CNY=人民币，USD=美元                                                                                                                                                                                                                                     |
| usage\_cost        | List\<UsageCost> |                     | 各价格阶梯用量与费用                                                                                                                                                                                                                                            |

UsageCost

| 字段名称                  | 类型      | 示例        | 描述                                 |
| --------------------- | ------- | --------- | ---------------------------------- |
| is\_guaranteed\_price | Boolean | false     | 是否是阶梯保底价格                          |
| money                 | int64   | 0         | 此价格阶梯产生的费用，精确到小数点后8位               |
| price                 | int64   | 112000000 | 价格，精确到小数点后4位，加上price\_unit是单价      |
| usage                 | int64   | 7015066   | 使用量，计量原始值，根据usage\_coefficient进行换算 |
| usage\_from           | int64   | 0         | 价格阶梯起始量，计量原始量                      |
| usage\_to             | int64   | 1024      | 价格阶梯结束量，计量原始量，-1表示无穷大              |

##### 响应状态码 [#响应状态码-9]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误码](#error-code)。

#### 示例 [#示例-9]

##### 请求示例 [#请求示例-9]

```
GET /billing-api/v2/bill/snapshot?date=2021-11-01T00:00:00
Host: api.qiniu.com
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
```

注：要在 Authorization 头部的 \<AccessToken> 前添加 Qiniu 和半角空格。

###### 响应示例 [#响应示例-9]

```
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Thu, 24 Feb 2022 08:29:17 GMT
X-Reqid: 2ZUBFPIhD-akXtYW

{
  "code": 0,
  "message": "Success",
  "data": {
    "total_money": 0,
    "currency": "CNY",
    "list": [
      {
        "start": "2023-02-07T00:00:00",
        "end": "2023-03-01T00:00:00",
        "product": "对象存储",
        "item": "存储空间-华南",
        "zone": "华南",
        "bill_period": "按月出账",
        "price_type": "各阶梯单价",
        "total_usage": 23530065,
        "package_usage": 23530065,
        "respack_usage": 0,
        "usage_coefficient": 1073741824,
        "usage_unit": "GB",
        "price_unit": "CNY/GB",
        "usage_cost": [
          {
            "usage_from": 0,
            "usage_to": -1,
            "price": 9900000,
            "is_guaranteed_price": false,
            "usage": 0,
            "money": 0
          }
        ],
        "item_money": 0,
        "rebate_money": 0,
        "discount_money": 0,
        "currency": "CNY"
      },
      {
        "start": "2023-02-07T00:00:00",
        "end": "2023-03-01T00:00:00",
        "product": "对象存储",
        "item": "标准存储CDN回源流出流量-华南",
        "zone": "华南",
        "bill_period": "按月出账",
        "price_type": "各阶梯单价",
        "total_usage": 81538534,
        "package_usage": 81538534,
        "respack_usage": 0,
        "usage_coefficient": 1073741824,
        "usage_unit": "GB",
        "price_unit": "CNY/GB",
        "usage_cost": [
          {
            "usage_from": 0,
            "usage_to": -1,
            "price": 15000000,
            "is_guaranteed_price": false,
            "usage": 0,
            "money": 0
          }
        ],
        "item_money": 0,
        "rebate_money": 0,
        "discount_money": 0,
        "currency": "CNY"
      },
      {
        "start": "2023-02-07T00:00:00",
        "end": "2023-03-01T00:00:00",
        "product": "CDN加速",
        "item": "CDN-HTTPS 流量-中国大陆",
        "zone": "中国大陆",
        "bill_period": "按月出账",
        "price_type": "各阶梯单价",
        "total_usage": 189458719719,
        "package_usage": 0,
        "respack_usage": 10240,
        "usage_coefficient": 1073741824,
        "usage_unit": "GB",
        "price_unit": "CNY/GB",
        "usage_cost": [
          {
            "usage_from": 0,
            "usage_to": 109951162777600,
            "price": 28000000,
            "is_guaranteed_price": false,
            "usage": 0,
            "money": 0
          },
          {
            "usage_from": 109951162777600,
            "usage_to": 1125899906842624,
            "price": 23000000,
            "is_guaranteed_price": false,
            "usage": 0,
            "money": 0
          },
          {
            "usage_from": 1125899906842624,
            "usage_to": -1,
            "price": 18000000,
            "is_guaranteed_price": false,
            "usage": 0,
            "money": 0
          }
        ],
        "item_money": 0,
        "rebate_money": 0,
        "discount_money": 0,
        "currency": "CNY"
      },
      {
        "start": "2023-02-07T00:00:00",
        "end": "2023-03-01T00:00:00",
        "product": "对象存储",
        "item": "PUT请求数-华南",
        "zone": "华南",
        "bill_period": "按月出账",
        "price_type": "各阶梯单价",
        "total_usage": 76,
        "package_usage": 76,
        "respack_usage": 0,
        "usage_coefficient": 1000,
        "usage_unit": "千次",
        "price_unit": "CNY/千次",
        "usage_cost": [
          {
            "usage_from": 0,
            "usage_to": -1,
            "price": 100000,
            "is_guaranteed_price": false,
            "usage": 0,
            "money": 0
          }
        ],
        "item_money": 0,
        "rebate_money": 0,
        "discount_money": 0,
        "currency": "CNY"
      }
    ]
  }
}
```

<span id="%E8%B4%A6%E6%88%B7%E4%BD%99%E9%A2%9D%E6%8E%A5%E5%8F%A3" />

### **账户余额接口** [#账户余额接口]

#### 描述 [#描述-10]

本接口使用 HTTP GET 请求来获取账户余额。该接口的请求需要使用 Authorization 签名认证；

#### 请求 [#请求-10]

##### 请求语法 [#请求语法-10]

```
GET /billing-api/v1/account/balance-overview HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>
```

##### 请求头 [#请求头-10]

该请求操作的实现使用了所有操作的公共请求头。有着详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

##### 请求内容 [#请求内容-10]

该请求操作的的请求体为空

#### 响应 [#响应-10]

##### 响应语法 [#响应语法-10]

```
HTTP/1.1 200 OK
ContentType: application/json
{
        "code": <ErrorCode>,
        "data": <Data>,
        "message": <Message>
}
```

##### 响应头 [#响应头-10]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

##### 响应内容 [#响应内容-10]

| 字段名称                    | 类型     | 示例                                    | 描述                                                                                                    |
| ----------------------- | ------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| account\_id             | string | 1002345667                            | 账户唯一标识                                                                                                |
| email                   | string | [abc@gamil.com](mailto:abc@gamil.com) | 用户邮箱                                                                                                  |
| available\_balance      | int64  | 538323000000                          | 可用额度，精确到小数点后面8位                                                                                       |
| cash\_balance           | int64  | 538323000000                          | 现金余额，精确到小数点后面8位                                                                                       |
| present\_balance        | int64  | 538323000000                          | 赠送金余额，精确到小数点后面8位                                                                                      |
| credit\_line            | int64  | 538323000000                          | 信用额度，精确到小数点后面8位                                                                                       |
| unpaid\_money           | int64  | 538323000000                          | 未支付金额，精确到小数点后面8位                                                                                      |
| estimated\_bills\_money | int64  | 538323000000                          | 实时消费金额，精确到小数点后面8位 <br />每月 1 号的实时消费快照为上月 1 号到本月 1 号（不含）的累计消费；<br />每月其他日期的实时消费快照为当月 1 号到查询日期（不含）的累计消费 |
| currency                | string | CNY                                   | 币种：CNY=人民币，USD=美元                                                                                     |

##### 响应状态码 [#响应状态码-10]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误码](#error-code)。

#### 示例 [#示例-10]

##### 请求示例 [#请求示例-10]

```
GET /billing-api/v1/account/balance-overview
Host: api.qiniu.com
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
```

注：要在 Authorization 头部的 \<AccessToken> 前添加 Qiniu 和半角空格。

###### 响应示例 [#响应示例-10]

```
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Thu, 24 Feb 2022 08:29:17 GMT
X-Reqid: 2ZUBFPIhD-akXtYW

{
    "code":0,
    "message":"Success",
    "data":{
        "account_id":"1001176420154",
        "email":"abc@gmail.com",
        "balance":706767000000,
        "cash_balance":706767000000,
        "present_balance":0,
        "credit_line":0,
        "unpaid_money":0,
        "estimated_bills_money":45690830000000,
        "currency":"CNY"
    }
}
```

<span id="%E5%88%86%E8%B4%A6%E8%B4%A6%E5%8D%95%E8%AF%A6%E6%83%85%E6%8E%A5%E5%8F%A3" />

### **分账账单详情接口** [#分账账单详情接口]

#### 描述 [#描述-11]

本接口使用 GET 请求用来获取用户分账账单详情的列表（前提是该用户开通了分账账单功能）。该接口需要您使用带Authorization签名认证的请求，使用匿名请求无法获取数据。

#### 请求 [#请求-11]

##### 请求语法 [#请求语法-11]

```
GET /billing-api/v1/separate-accounting/details?month=<Month>&product=<Product> HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>

```

##### 请求参数 [#请求参数-10]

| 字段名称    | 类型     | 是否必须 | 示例     | 说明                                                    |
| ------- | ------ | ---- | ------ | ----------------------------------------------------- |
| month   | string | 是    | 202401 | 分账账单月份。格式为 yyyyMM                                     |
| product | string | 否    | kodo   | 产品线名称。可取值 \[对象存储,CDN]，若不传值，表示 “对象存储”+“CDN” 两个产品线的分账账单 |

##### 请求头 [#请求头-11]

该请求操作的实现使用了所有操作的公共请求头。有着详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

##### 请求内容 [#请求内容-11]

该请求操作的的请求体为空

#### 响应 [#响应-11]

##### 响应语法 [#响应语法-11]

```
HTTP/1.1 200 OK
ContentType: application/json
{
        "code": <ErrorCode>,
        "data": <Data>,
        "message": <Message>
}
```

##### 响应头 [#响应头-11]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

##### 响应内容 [#响应内容-11]

| 字段名称      | 类型          | 示例          | 描述                   |
| --------- | ----------- | ----------- | -------------------- |
| tag\_keys | \[]string   | 用户标签 key 数组 | 用户在产品线页面打的标签对的 key 值 |
| list      | List\<List> |             | 详情列表                 |

List

| 字段名称                      | 类型        | 示例                                   | 描述                                                                |
| ------------------------- | --------- | ------------------------------------ | ----------------------------------------------------------------- |
| id                        | string    | 65e02a84eb9b8ebe0109263e             | 分账账单账单唯一标识                                                        |
| bill\_id                  | string    | 65e02ad4eb9b8ebe0109263f             | 账单唯一标识                                                            |
| resource\_name            | string    | user-shopping-cart-bucket            | 资源名称，cdn 域名或云存储 bucket                                            |
| resource\_type            | string    | bucket                               | 资源类型，枚举值，取值为\[bucket,domain]，分别表示云存储 bucket 和 CDN 域名              |
| product                   | string    | 对象存储                                 | 枚举值，取值为\[对象存储,CDN]                                                |
| item                      | string    | CDN-HTTP-中国大陆                        | 计费项区域展示                                                           |
| count\_cycle              | string    | 2024-01-01 00:00 \~ 2024-01-31 24:00 | 计费周期                                                              |
| billing\_model            | string    | 月计费95峰值(去余取整)                        | 计费类型，例如 CDN 月 95 峰                                                |
| resource\_usage           | int64     | 41426                                | 本资源用量数                                                            |
| usage\_unit               | string    | GB                                   | 用量单位                                                              |
| resource\_usage\_humanize | string    | 0.0001                               | 渲染过后的 resource\_usage，与 usage\_unit 配合使用                          |
| rate                      | string    | 0.00044                              | 用量占比（精度处理：采用截断，保留 5 位小数）                                          |
| item\_money               | int64     |                                      | 原内部账单总金额，精确到小数点后面8位                                               |
| resource\_money           | int64     |                                      | 本资源金额，精确到小数点后面8位                                                  |
| currency\_type            | string    |                                      | 币种，枚举，取值为\[CNY,USD]                                               |
| tag\_values               | \[]string |                                      | 标签 value 数组，该标签与上一层的 tag\_keys 的排序值相同，如果某个 key 不存在，则其 value 为 "-" |
| created\_at               | string    | 2024-02-03T06:26:19.119Z             | 分账账单创建时间                                                          |

##### 响应状态码 [#响应状态码-11]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误码](#error-code)。

#### 示例 [#示例-11]

##### 请求示例 [#请求示例-11]

```
GET /billing-api/v1/separate-accounting/details?month=202401&product=kodo
Host: api.qiniu.com
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
```

注：要在 Authorization 头部的 \<AccessToken> 前添加 Qiniu 和半角空格。

###### 响应示例 [#响应示例-11]

```
HTTP/1.1 200 OK
Content-Length: chunked
Connection: keep-alive
Content-Type: application/json
Date: Thu, 24 Feb 2022 08:29:17 GMT
X-Reqid: 2ZUBFPIhD-akXtYW

{
          "code":  0,
          "message":  "Success",
          "data":  {
                    "list":  [
                              {
                                        "id":  "65bddc8b794f2844a4f518e3",
                                        "bill_id":  "65bb76a7a8c02e237dda46ba",
                                        "resource_name":  "hikcloucdn.example.com",
                                        "resource_type":  "domain",
                                        "product":  "CDN",
                                        "item":  "CDN-HTTP-中国大陆",
                                        "count_cycle":  "2024-01-01 00:00 ~ 2024-01-31 24:00",
                                        "billing_model":  "",
                                        "resource_usage":  41426,
                                        "usage_unit":  "GB",
                                        "resource_usage_humanize":  "0.0000",
                                        "rate":  "0.00044",
                                        "item_money":  0,
                                        "resource_money":  0,
                                        "currency_type":  "CNY",
                                        "tag_values":  [
                                                  "-",
                                                  "http-chinese-mainland"
                                        ],
                                        "created_at":  "2024-02-03T06:26:19.119Z"
                              },
                              {
                                        "id":  "65bddc8b794f2844a4f518e2",
                                        "bill_id":  "65bb76a7faf4f475da0a2037",
                                        "resource_name":  "qiniu.ex1-example.net",
                                        "resource_type":  "domain",
                                        "product":  "CDN",
                                        "item":  "CDN-HTTP-海外未分区",
                                        "count_cycle":  "2024-01-01 00:00 ~ 2024-01-31 24:00",
                                        "billing_model":  "",
                                        "resource_usage":  7795793,
                                        "usage_unit":  "GB",
                                        "resource_usage_humanize":  "0.0073",
                                        "rate":  "1.00000",
                                        "item_money":  0,
                                        "resource_money":  0,
                                        "currency_type":  "CNY",
                                        "tag_values":  [
                                                  "-",
                                                  "http-overseas"
                                        ],
                                        "created_at":  "2024-02-03T06:26:19.363Z"
                              }
                    ],
                    "tag_keys":  [
                              "user-shopping-cart-bucket",
                              "user-shopping-cart-cdn"
                    ]
          }
}
```


# 免费额度及查看方法 (/account/0-freequota)



最近更新时间: 2026-05-08 17:16:00

# 一、免费额度内容 [#一免费额度内容]

| 产品    | 免费额度                                                                                      |
| ----- | ----------------------------------------------------------------------------------------- |
| 存储    | - 标准存储空间：10GB/月<br />- CDN回源流出流量：10GB/月<br />- PUT/DELETE 请求：10万次/月<br />- GET 请求：100万次/月 |
| 智能多媒体 | - 图片处理服务：10TB/月<br />- 多媒体处理：20元/月                                                        |
| CDN   | - HTTP每个区域：10GB/月<br />- 动态加速请求数：5万次/月                                                    |
| 实时音视频 | - 连麦纯音频：5000分钟<br />- 连麦标清：5000分钟<br />- 连麦高清：5000分钟<br />- 连麦超清：5000分钟                   |
| 容器轻应用 | - C1M1：750小时                                                                              |

**使用规则：**

1. 开通对应服务并完成实名认证即可自动享受免费额度。
2. 每月优先抵扣免费额度，超出部分按量计费。
3. 不同产品的免费额度独立计算，不可跨产品共享。
4. 每月自动发放，当月未用完不可结转到次月。

## 二、如何查看免费额度 [#二如何查看免费额度]

**入口：** [https://portal.qiniu.com/financial/price?product=kodo](https://portal.qiniu.com/financial/price?product=kodo)
&#x2A;*操作步骤：**
进入财务中心 → 点击「价格和优惠」菜单 → 查看各产品免费额度和当月使用情况
![image.png](/docs-assets/account/%280-manual%29/0-freequota/FtwjID-krN2p0PfeVJV21S3Q67ch-18c7c6024c16.webp)


# 有害信息分类 (/account/0-harmful-information-classification)



最近更新时间: 2023-04-20 11:41:43

## 政治类 [#政治类]

* 攻击国家基本制度安排
* 破坏国家主权、领土完整
* 抹黑诋毁英烈等

## 暴恐类 [#暴恐类]

* 暴恐组织其行为、思想
* 暴恐事件
* 其他包括细致展示凶残犯罪过程、血腥画面、传播暴恐音视频、教授制枪制爆技术等

## 诈骗类 [#诈骗类]

* 通过虚拟事件或隐瞒真相的地方，骗取国家、集体或个人财务
* 通过欺诈行为使对方产生错误认识，实现非法目的

## 色情类 [#色情类]

* 直接暴露展现性的信息内容
* 产生性刺激的信息内容
* 淫秽色情相关行业资讯

## 低俗类 [#低俗类]

* 隐晦变现性行为、具有挑逗性或者侮辱性的内容
* 带有侵犯个人隐私性质的走光、偷拍、露点等

### 色情低俗十大表现形式 [#色情低俗十大表现形式]

1. 境外中文色情网站
2. 借即时通讯工具进行的色情违法活动
3. 色情聊天室
4. 色情小游戏，动漫违法网站
5. 利用云存储等工具传播色情有害信息
6. 色情小说、电子书
7. 情感、两性等网站栏目传播低俗、色情有害信息
8. 低俗、色情药品广告
9. 色情手机应用程序
10. 传播低俗、色情有害信息的网站弹窗、广告栏侧边栏

## 赌博类 [#赌博类]

* 细致展示或销售赌博相关器具
* 网络虚拟赌场、网上博彩网址等相关信息
* 涉赌的网络游戏

## 谣言类 [#谣言类]

* 可能影响社会公共秩序、公共安全的虚假群体性事件信息
* 涉及食品药品安全、健康、医疗、急救等领域伪科学的谣言、言论
* 违反社会常识、管理制度、法律法规等的谣言、言论

## 侵权类 [#侵权类]

* 未经同意授权，擅自泄露或公开个人隐私信息
* 未经他人授权，私自使用他人或机构肖像、名称、姓名用于商业目的
* 新闻报道或材料内容失实，致他人名誉受损的
* 直接或间接以辱骂、谩骂、贬损、嘲讽等方式导致对方名誉受损

## 其他类 [#其他类]


# 欠费状态下各产品的限制功能 (/account/0-owe-the-protection-limit-function)



最近更新时间: 2026-04-29 10:56:40

介绍欠费状态下使用各种产品/服务的限制。

**一、欠费保护期状态下限制功能**

| 模块     | 限制功能                                                                                                                                                               |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 财务功能   | 无法使用账户余额支付订单，只能使用支付宝/微信等第三方支付。                                                                                                                                     |
| CDN    | 无法新增域名和修改域名。                                                                                                                                                       |
| 对象存储   | 详情见[账号欠费保护期功能限制](/products/kodo/0-accounts-owe-protection)                                                                                                         |
| 云主机    | 详情见[账户冻结后资源停用删除说明](/products/qvm/2-disable-delete-resources-following-the-account-is-frozen)                                                                       |
| IoT视频云 | 1.我的应用<br />（1）创建应用<br />（2）修改应用的基本信息<br />（3）修改云存配置<br />（4）创建/编辑Topic\<br>（5）编辑日志配置<br />2.设备管理<br />（1）创建设备/批量创建设备<br />（2）批量获取密钥<br />（3）编辑设备信息<br />（4）更新设备影子 |

**二、如何解除欠费**
在财务中心- [账户充值](https://portal.qiniu.com/financial/recharge)，进行充值，充值抹平欠费后将解除欠费状态。
![](/docs-assets/account/%280-manual%29/0-owe-the-protection-limit-function/FnIsE2LzUOhtiyrCqImWl1lym35x-dc4aab2445ff.webp)


# OAuth 2.0 应用对接 (/account/0-qiniu-oauth2)



最近更新时间: 2026-04-09 14:58:25

# OAuth 2.0 介绍 [#oauth-20-介绍]

OAuth 2.0 是一个开放授权标准，用于用户授权第三方应用访问该用户在七牛的资源而不需要提供账号密码信息给第三方应用。

## OAuth 2.0 角色 [#oauth-20-角色]

OAuth 2.0 有以下四个角色：

| 角色                   | 说明                          |
| -------------------- | --------------------------- |
| Resource Owner       | 资源拥有者                       |
| Resource Server      | 资源服务器                       |
| Client               | 第三方应用客户端，指任何可以消费资源服务器的第三方应用 |
| Authorization Server | 授权服务器，管理上述三个角色的中间层          |

## OAuth 2.0 授权流程 [#oauth-20-授权流程]

![oauth2.png](/docs-assets/account/%280-manual%29/0-qiniu-oauth2/FnztQDUQkR6NRasKeWetCOdjUfvx-992a3f6c2d5b.webp)
（A）：客户端请求资源所有者的授权。
（B）：资源所有者同意授权。
（C）：客户端获得了资源所有者的授权之后，向授权服务器申请授权令牌。
（D）：授权服务器验证客户端无误后发放授权令牌。
（E）：客户端拿到授权令牌之后请求资源服务器发送用户信息。
（F）：资源服务器验证令牌无误后将用户信息发放给客户端。

# 使用说明 [#使用说明]

## 第三方应用接入 [#第三方应用接入]

### 创建第三方应用客户端 [#创建第三方应用客户端]

七牛目前暂未对外提供第三方应用客户端管理的入口，如有需要，需提工单或和七牛对接人申请，并提供如下信息：

| 字段                                                            | 描述           | 示例                                                 |
| ------------------------------------------------------------- | ------------ | -------------------------------------------------- |
| name                                                          | 名称           | 极客 AI                                              |
| description                                                   | 描述           | 极客 AI 七牛 OAuth 应用对接                                |
| redirect\_uri                                                 | 重定向地址，用于授权回调 | [https://example.geek.ai](https://example.geek.ai) |
| 完成第三方应用创建后，会得到一组 `client_id` 和 `client_secret`，用于后续获取资源访问授权码。 |              |                                                    |

## 授权服务 [#授权服务]

### 请求资源所有者的授权获取授权码 [#请求资源所有者的授权获取授权码]

**请求**

```http
GET|POST https://portal.qiniu.com/oauth/v2/authorize?response_type=code&client_id=<client_id>[&redirect_uri=<redirect_uri>][&state=<state>]
```

> 该接口同时支持 `GET` 方法和 `POST` 方法，`Query Paramters` 中的参数也可以 `Form` 的形式提交

* `response_type`： 必须为 `code`
* `client_id`：必填，为第三方应用的 `client_id`
* `redirect_uri`：可选，回调地址，默认为第三方应用注册时填写的回调地址。如果提供则必须与第三方应用注册时填入的回调地址相同或是其子路径。如注册时的路径为 `http://example.qiniu.com/a`，则下列的 `redirect_uri` 的合法性为：
  * `https://example.qiniu.com/a`：合法
  * `http://example.qiniu.com/a/b`：合法
  * `http://subdomain.qiniu.com/a`：非法
  * `http://example.qiniu.com/b`：非法
* `state`：可选，但强烈建议提供，用于防范 csrf 攻击

**响应**

```http
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=<code>[&state=<state>]
```

如果授权成功，则授权服务器会携带授权码 `code` 重定向至回调地址。

**注意，授权码仅在十分钟内一次有效。**

**错误**

```http
HTTP/1.1 302 Found
Location: https://client.example.com/cb?error=<error>
```

如果授权过程中发生错误，则授权服务器会携带错误信息 `error` 重定向至回调地址。

可能的错误值为：

* `invalid request`：请求不合法，可能缺少必要的参数，或者是 `client_id` 不合法
* `access denied`：授权被拒绝
* `server error`：服务器错误

### 向授权服务器申请授权令牌 [#向授权服务器申请授权令牌]

**请求**

```http
POST|GET https://portal.qiniu.com/oauth/v2/token
Authorization: Basic <Auth>
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&redirect_uri=<redirect_url>
```

> 该接口同时支持 `GET` 方法和 `POST` 方法，`Query Paramters` 中的参数也可以 `Form` 的形式提交

* `grant_type`：必须为 `authorization_code`
* `code`：必填，从 `/authorize` 接口回调后取得的 `code`，即上一步获取到的授权码
* `redirect_uri`：如果在 `/authorize` 接口中也提供了该参数时必填，且必须一样

第三方应用的凭证 `client_id` 和 `client_secret` 可以以两种形式提供，**一种**是以如上例请求中的 `Basic Auth` 的形式提供，**另一种**则是以表单参数的形式提供。

当使用 `Basic Auth` 的方式时，需要在请求头中附加如下信息：

```http
Authorization: Basic <Auth>
```

其中 `<Auth> `为经过 base64 编码的 `client_id` 和 `client_secret`，即 `base64_encode(client_id:client_secret)`

**响应**

```js
{
  "access_token": "hoCh3nfpNKVRztaYrmq8Cmvu0AHsrDX0BVM5WrpI9YlASBkJ",
  "expires_in": 2591999, // 单位：秒
  "refresh_token": "1k5gVZFRM7TS8ue515s5P8ODJkjvXGgMj2zBjRTxMReJBwAL",
  "token_type": "Bearer"
}
```

可能返回的错误码为：

* `400`：请求不合法，可能缺少必要的参数，或者是 `client_id` 不合法
* `401`：授权被拒绝
* `500`：服务器错误

### 刷新授权令牌 [#刷新授权令牌]

**请求**

```http
POST|GET https://portal.qiniu.com/oauth/v2/token
Authorization: Basic <Auth>
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<refresh_token>
```

> 该接口同时支持 `GET` 方法和 `POST` 方法，`Query Paramters` 中的参数也可以 `Form` 的形式提交

* `grant_type`：必须为 `refresh_token`
* `refresh_token`：必填，用于刷新的 `refresh_token`

**响应**
同`向授权服务器申请授权令牌`接口

## 资源服务 [#资源服务]

第三方应用从授权服务器拿到的 `Access Token` 即可用于访问资源服务器获取与用户相关的资源。

### 鉴权 [#鉴权]

访问的凭证为 `Access Token`，目前支持的携带方式有：

* 在请求头中添加 `Authorization`头，值为 `Bearer <Access Token>`
* `query param` 中携带 `access_token=<access_token>`
* `POST` 请求时，Body 中以 Form 的格式携带 `access_token=<access_token>`

### 接口规格 [#接口规格]

#### 获取用户基本信息 [#获取用户基本信息]

**请求**

```http
GET|POST https://portal.qiniu.com/oauth/v2/api/account/info
```

> 该接口同时支持 `GET` 方法和 `POST` 方法

**响应**

```js
{
	data: {
      "uid": 1380537799
	},
	"msg": "succ",
	"ret": 0,
}
```

可能返回的错误码为：

* `400`：请求不合法，可能缺少必要的参数，如 token 不合法或已过期
* `500`：服务器错误

#### 获取用户可用额度（需申请配置授权） [#获取用户可用额度需申请配置授权]

**请求**

```http
GET https://portal.qiniu.com/oauth/v2/api/finance/available-balance
```

**响应**

```js
{
	data: {
      "balance": 9000 // 单位：万分之一元
	},
	"msg": "succ",
	"ret": 0,
}
```

可能返回的错误码为：

* `400`：请求不合法，可能缺少必要的参数，如 token 不合法或已过期
* `500`：服务器错误


# 七牛云费用账户变更说明 (/account/0-seven-niuyun-expenses-account-changes)



最近更新时间: 2026-05-08 18:10:19

2019年9月12日起，我们将调整财务中心可用额度的计算和展示，将按量计费预估金额作为负值列入可用额度，确保用户能查看实时的可用额度，以便判断具体的充值金额。

具体介绍如下，请您耐心阅读，预计阅读时间3分钟。

<br />

**1.可用额度计算调整**

可用额度=现金余额+赠送金余额-欠费金额-按量计费预估金额

管理页面：财务中心- >[财务概览](https://portal.qiniu.com/financial/overview)
![image.png](/docs-assets/account/%280-manual%29/0-seven-niuyun-expenses-account-changes/FqNzKQ7hFQcZgRN-YGAimF0pcBdZ-12279699e72f.webp)

**2.账户金额说明**

| 名称     | 说明                                                                                               |
| ------ | ------------------------------------------------------------------------------------------------ |
| 可用额度   | 可以用来购买云服务的余额。                                                                                    |
| 现金余额   | 通过线上充值或线下银行转账充值的现金余额。                                                                            |
| 赠送金余额  | 只能支付按量付费产品的费用，不能购买预付费产品，不能提现和开发票。                                                                |
| 欠费金额   | 用户因使用七牛云服务所产生的欠费金额。                                                                              |
| 按量计费预估 | 用户因使用云服务，但未到出账结算的消费金额。立即查看 [按量计费预估](https://portal.qiniu.com/financial/bills/estimated-consume)。 |

<br />

**3.可用额度为负的影响**

可用额度为负后，您的账户将进入欠费流程，会根据您的认证类型授予一定的欠费保护期，保护期内您无法操作新建和变更等功能。保护期内若未按要求充值，您将被冻结。保护期时长如下：

* 未认证：1天保护期
* 个人认证：3天保护期
* 企业认证：5天保护期

关于欠费流程的更多说明请参考文档 [新版欠费流程](/faq/account-finance/account-problem/5996-new-owe-the-process-description) 。

<br />

**4.设置可用额度预警**

您可以设置可用额度预警，来了解可用额度的变化，以便及时充值，避免欠费影响您的服务 [立即设置](https://portal.qiniu.com/financial/overview)。
![image.png](/docs-assets/account/%280-manual%29/0-seven-niuyun-expenses-account-changes/Fnlqs16KSi_IcSG0KOuRXzJ2Qfp3-1e80d0123d17.webp)


# 计费方式变更 (/account/0-switch-charge-method)



最近更新时间: 2026-05-06 17:06:13

本文档主要介绍了针对支持多种计费方式计费的产品，如何变更其计费方式，通过变更计费类型，可以让您选择更合适的计费方式。

### 操作方式 [#操作方式]

1. 登陆七牛云财务中心 - [价格和优惠](https://portal.qiniu.com/financial/price) ，选择需要切换计费方式的产品以及对应计费项，点击【切换计费方式】
   ![image.png](/docs-assets/account/%280-manual%29/0-switch-charge-method/FgrREIbsKNCvg4czhnstXKee-b3x-1e715e224be5.webp)

2. 您可在不同的计费方式之前切换，如从原有带宽日峰值计费变更为流量计费，请您仔细确认调整后的价格，确认无误后点击【确定】保存变更

![image.png](/docs-assets/account/%280-manual%29/0-switch-charge-method/FqkIiufkKxM1Dk8gFBye-Yi68ztp-acc4a0a166cb.webp)

3. 确定变更计费方式后，对应计费项会立即调整为新的计费方式和价格

![image.png](/docs-assets/account/%280-manual%29/0-switch-charge-method/FtHtKl28h0o17ahAt6Owyy0yF4_P-278a6e291690.webp)

### 变更计费方式后，需注意以下说明： [#变更计费方式后需注意以下说明]

* 切换计费方式每日仅可操作一次且无法撤销或再次变更，操作后当日立即生效，请您关注次日更新的实时消费账单。
* 若您在同个账期月份里进行多次变更计费方式，当月账单会根据实际操作分段计费。举例说明比如于某月1日从原有带宽日峰值计费切换到流量计费方式，再于11日从流量计费方式切换回带宽日峰值计费，再于21日从带宽日峰值计费方式切换到流量计费方式，当月后续不再操作，那实际当月出账单分段为1~~10日流量方式计费，11~~20日带宽日峰值方式计费，21\~31日流量方式计费。
* 变更计费方式为带宽计费后，您已购买的资源包将无法抵扣，故若您已购买资源包请切换到流量计费方式以免影响出账抵扣。
* 若您是与七牛云签约合同的大客户，请联系您的七牛云商务经理变更计费方式，此处不提供切换计费方式的选项。


# 新版财务概况 (/account/0-the-new-financial-situation)



最近更新时间: 2026-04-29 10:51:30

# 一、管理界面 [#一管理界面]

登录账号后，进入管理控制台>财务中心>[财务概览](https://portal.qiniu.com/financial/overview)，就可查看新版财务概览。
![](/docs-assets/account/%280-manual%29/0-the-new-financial-situation/Fsx2KYALgVvPR6YcyJBOiKweZQd1-ca52ec1908f5.webp)

# 二、账户金额说明 [#二账户金额说明]

* 可用额度：可以用来购买云服务的余额。
* 可用额度=现金余额+赠送金余额-欠费金额-实时消费金额
* 支付费用时，七牛云将优先扣除抵用券、赠送金余额，再扣除现金余额。
* 现金余额：通过线上充值或线下银行转账充值的现金余额。
* 赠送金余额：只能支付按量付费产品的费用，不能提现和开发票。
* 欠费金额：用户使用七牛云服务产生的欠费金额，但不包括已消费未出账金额和已出账未扣费金额。
* 实时消费金额：七牛云会在账户内暂时冻结实时消费金额，冻结的金额并未实际消耗，更多说明请参考 [按量计费预估](/account/bill-management/0-real-spending-detail)


# 违规信息处罚标准 (/account/0-violation-of-information-standards)



最近更新时间: 2026-05-06 17:16:53

| 产品类别       | 违规级别 | 处罚策略 |
| ---------- | ---- | ---- |
| 对象存储（KODO） | 轻    | 封禁资源 |
|            | 中    | 冻结空间 |
|            | 重    | 冻结账号 |
| CDN        | 轻    | 封禁外链 |
|            | 中    | 冻结域名 |
|            | 重    | 冻结账号 |
| 视频直播（Pili） | 轻    | 封禁房间 |
|            | 中    | 冻结空间 |
|            | 重    | 冻结账号 |
| 快直播（Miku）  | 轻    | 封禁房间 |
|            | 中    | 冻结空间 |
|            | 重    | 冻结账号 |
| 云主机服务（QVM） | 轻    | 阻断网络 |
|            | 中    | 冻结主机 |
|            | 重    | 冻结账号 |

## 注： [#注]

违规级别将根据账号的[违规类型](/account/0-harmful-information-classification)、违规数量、传播程度等情况综合判定。

# 违规信息处理帮助 [#违规信息处理帮助]

请您根据站内信或邮箱中《违规信息处理通知》里面通报的违规内容，尽快完成清理规避风险。

## 注： [#注-1]

监管部门下发要求处置的，不支持解除封禁。


# 抵用券介绍 (/account/0-vouchers-types-and-rules-is-introduced)



最近更新时间: 2026-05-06 17:57:34

# **一、抵用券管理页面** [#一抵用券管理页面]

入口：管理控制台->财务中心

-订单券：[https://portal.qiniu.com/financial/coupon](https://portal.qiniu.com/financial/coupon)

-账单券：[https://portal.qiniu.com/financial/voucher](https://portal.qiniu.com/financial/voucher)

![image.png](/docs-assets/account/%280-manual%29/0-vouchers-types-and-rules-is-introduced/FiwD83p_sQ1zRl3JEwrEbDCtt4aF-8b7189355f79.webp)

# **二、抵用券分类** [#二抵用券分类]

根据抵用券适用的系统/付费类型的不同，分为：

-账单券：适用于按量付费的后付费产品费用。
-订单券：适用于流量包、SSL证书、包年包月的云主机等一次性结算的产品费用。

# **三、抵用券优惠规则** [#三抵用券优惠规则]

## **1、满减类型** [#1满减类型]

根据有无金额门槛，分为：无门槛券和满减券。

## **2、抵用券面额** [#2抵用券面额]

抵用券能抵扣的最大金额。

## **3、抵用券门槛** [#3抵用券门槛]

使用抵用券需要满足的费用门槛。

## **4、生效时间** [#4生效时间]

抵用券的有效时间范围。

# **四、抵用券使用规则** [#四抵用券使用规则]

## **1、使用次数** [#1使用次数]

根据抵用券能够使用的次数，分为：仅一次使用和可多次使用。

## **2、付费类型** [#2付费类型]

-预付费（即订单券）
-后付费（即账单券）

## **3、适用产品/商品** [#3适用产品商品]

抵用券能适用在哪些产品/商品上。

## **4、抵扣规则** [#4抵扣规则]

账单券：账单出账扣费后，系统将自动抵扣多张有效状态、符合时间范围、符合适用范围的账单抵用券，优先抵扣快过期的抵用券。
订单券：订单券不会自动抵扣，需要您选购好商品下单时，主动选择需要使用的抵用券，再进行支付。

# **五、抵用券使用注意事项** [#五抵用券使用注意事项]

## **1、订单抵用券** [#1订单抵用券]

（1）每个订单最多只能使用一张抵用券，抵用券不可叠加使用。
（2）订单退款时，抵用券不支持退回；并且抵用券无法转让、提现，抵用券支付的金额无法开票。
（3）抵用券无法抵扣欠费金额。

## **2、账单抵用券** [#2账单抵用券]

（1）抵用券无法抵扣欠费金额。
（2）若通过活动获得抵用券，请于激活绑定抵用券后再使用，已使用或绑定成功的抵用券将显示在已激活抵用券列表。

# **六、举例说明** [#六举例说明]

抵用券：
![](/docs-assets/account/%280-manual%29/0-vouchers-types-and-rules-is-introduced/FtZXBQd8BGCrUHNsjZlWDJ5PVzxe-3f69dca474bf.webp)

![](/docs-assets/account/%280-manual%29/0-vouchers-types-and-rules-is-introduced/Ftb9gQKPjPyaiaR_udxpRlan8swB-3086b2138e2f.webp)

以上抵用券类型和规则解释如下：
-抵用券类型：订单券
-抵用券满减类型：满减券
-抵用券面额：10元
-抵用券门槛：100元
-抵用券生效时间：2019-12-16 18:10:29 \~ 2020-01-15 18:10:29
-抵用券使用次数：仅一次可用
-抵用券付费类型：预付费
-抵用券使用商品：预付费产品通用
-抵用券抵扣规则：在下单时，选择该抵用券，再进行支付。


# 常见账单问题汇总 (/faq/account-finance/12989-Bill-overview)



最近更新时间: 2026-05-26 18:11:35

* 欠费了如何确定自己的消费明细
* 为什么会产生欠费
* 可用额度预警
* cdn流量说明
* 如何查看充值记录等
* 按量计费预估费用描述，资源包购买、续费
* 为什么自动瘦身费用很高？

***

# 1. 欠费了如何确定自己的消费明细 [#1-欠费了如何确定自己的消费明细]

收到邮件提示欠费，进入[财务中心](https://portal.qiniu.com/financial/overview)，可以通过[按量计费预估](https://portal.qiniu.com/financial/bills/estimated-consume)查看自己当月的消费详情。

# 2. 为什么会产生欠费 [#2-为什么会产生欠费]

按量计费预估，是延迟统计的；例如今天的消费，需要到明天才会完成统计，有一定延迟导致的。

# 3. 可用额度预警 [#3-可用额度预警]

为了避免欠费，可以设置下[可用额度预警](https://portal.qiniu.com/financial/overview)，余额到达您的设定数值会给您提醒。
注意：可用额度预警是基于按量计费预估进行提醒的，也有一天的延迟。
![image.png](/docs-assets/faq/account-finance/12989-Bill-overview/FhOB48GjVTr3nPPG6QhBQwGrTztF-ecbb5b7515e5.webp)

# 4. cdn流量是什么，如何分析自己产生的流量 [#4-cdn流量是什么如何分析自己产生的流量]

cdn流量是访问cdn域名产生的流量费用；可以通过[用量统计](https://portal.qiniu.com/cdn/statistics/usage/flow)来查看自己的流量；[日志分析](https://portal.qiniu.com/cdn/statistics/log/access)可以查看到流量来源地区等信息。
如果需要查看访问量较高的ip或者url，可以通过[TOP 访问统计](https://portal.qiniu.com/cdn/statistics/log/top)查看对应的信息，列举了前100访问量高的ip和url。

# 5. 如何查看充值记录等 [#5-如何查看充值记录等]

[收支明细](https://portal.qiniu.com/financial/cost/income-expenses)，可以查看到您的余额抵扣信息，可以切换时间和流水类型对应查看。
![image.png](/docs-assets/faq/account-finance/12989-Bill-overview/FvTZhZojGj4qy4Z2Vs7_tazYRcL-8d29fad668bc.webp)

# 6. 按量计费预估费用描述，资源包购买、续费 [#6-按量计费预估费用描述资源包购买续费]

如果需要根据您的[按量计费预估](https://portal.qiniu.com/financial/bills/estimated-consume)购买对应的资源包可以参考下如下（资源包主要是kodo和cdn的）：

| 费用描述               | 费用说明                                                                                  | 对应资源包                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| 标准存储-对应存储区域        | 存储空间标准存储类型的文件容量的使用（有10g的免费额度）产生的计费                                                    | [标准存储资源包](https://qmall.qiniu.com/template/MTEy?spec_combo=MzA0Mw\&ref=index)                 |
| 标准存储CDN回源流出流量-对应区域 | 回源流量具体说明可以参考文档[回源流量说明](/faq/cdn/6358-bills-storage-cdn-back-to-the-origin-of-traffic) | [回源流量资源包](https://qmall.qiniu.com/template/MTEy?spec_combo=MzE3NQ\&ref=index)                 |
| 外网流出流量-对应区域        | 通过自定义源站域名、s3域名访问或者使用工具没有指定cdn域名，访问产生的流量                                               | [外网流出流量资源包](https://qmall.qiniu.com/template/MTEy?spec_combo=MzE0Mg\&ref=index)               |
| CDN-HTTP(S)-中国大陆   | 通过cdn域名访问产生的流量（http协议的cdn域名有10G的免费额度）                                                 | [cdn中国大陆资源包](https://qmall.qiniu.com/template/NTI?ref=category\&spec_combo=MTk0OA\&ref=index) |
| CDN-HTTP(S)-海外     | 海外的cdn域名访问产生流量                                                                        | [海外cdn资源包](https://qmall.qiniu.com/template/NTU?ref=category\&spec_combo=MjEzNA)              |

# 7. 为什么自动瘦身费用很高？ [#7-为什么自动瘦身费用很高]

自动瘦身费用是您的CDN域名开启了 [自动瘦身](/products/cdn/configuration-management-fusion/5-image-optimization) 功能后，访问png或jpg图片时产生的。<br /> 费用增加一般是以下原因：<br /> 1、CDN域名配置了不缓存或缓存时间很短，CDN节点没有缓存，频繁回源拉取资源导致。缓存配置参考[文档](/products/cdn/configuration-management-fusion/2-cache-configuration) <br /> 2、存储空间或源站新上传文件很多，且被大量访问产生的。存储空间的文件上传统计数据可以参考 [统计分析](/products/kodo/kodo-console-guide/1-statistical-analysis) 文档查询。


# 按量计费预估详细费用说明 (/faq/account-finance/12990-real-spending-detail-describe)



最近更新时间: 2026-09-03 15:36:32

# 一、KODO [#一kodo]

存储这边的收费文档可以参考：[存储计费说明文档](/products/kodo/1-metering-and-billing)
[存储价格详情](https://www.qiniu.com/prices/kodo)
1.标准存储-（华东/华南/华北/北美/亚太）：存储空间容量的收费。**每个月有10G的免费额度**，超出部分按对应区域的单价收费。
如下费用账单，减去10G的免费额度，剩下的按单价计费：
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/Fmk_Ig1FGznAvkEjkuoBMkus_44M-be1aeaa867a6.webp)

2.低频/归档/深度归档-（华东/华南/华北/北美/亚太）：存储空间容量的收费；**没有免费额度**。
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/FsMbtCztv6FzRyc7lThDNElrWmgx-08d47d6e5c40.webp)

3、智能分层存储：这个存储类型的收费是按访问频率不同，分别计算的；分为智能分层存储频繁访问层/不频繁访问层/归档直读访问层，以及智能分层对象监控和自动化费用。![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/Fu1JoCZZjD_9kTcVRR_FZUPtRR8N-17ca5cc9d325.webp)
具体收费项目如下
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/Fr0CVhgvJUpq_hJhUr4qvct_6SZb-bbf9069edab7.webp)

4. CDN回源流出流量-（华东/华南/华北/北美/亚太）：存储空间绑定cdn域名，访问cdn域名时，cdn节点「没有缓存」时，需要回源站拉取资源并缓存，从空间拉取资源到cdn节点，产生的流量费用就是回源流量。**每个月有10G的免费额度**，全部存储区域通用免费额度，超出部分按对应区域的单价收费。
   ![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/FgNrFJLtd9A_dSApTok364D2ZXaz-34a17374579a.webp)

5.数据取回-（华东/华南/华北/北美/亚太）：除了标准存储，其他类型的存储访问，解冻会产生数据取回的费用
低频存储：访问低频存储数据时，会产生额外的数据取回费。按服务端读取的数据量计算
归档直读存储：访问归档直读存储数据时，会产生额外的数据取回费。按服务端读取的数据量计算
归档存储：访问归档存储数据前，需要先解冻数据。按解冻数据量计算
深度归档存储：访问深度归档存储数据前，需要先解冻数据。按解冻数据量计算
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/FhT1FQFWJ4s54mLeVb-uJs2OTrF3-60ec15cd2dc8.webp)

6.外网流出流量-（华东/华南/华北/北美/亚太）：使用自定源站域名、或者使用工具没有指定cdn域名访问下载产生的流量（各个存储类型都会产生）。**没有免费额度**。
标准存储外网流出流量
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/Fi5HuCelQrFLhkGl1325yQpjnRtC-36a203a6fb5c.webp)
低频存储外网流出流量
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/Fn2nW9cpnvclbzwxBdV01QHIMDy6-769b364fa45a.webp)

7.Put/Delete请求：调用写请求的次数（包括 list 请求在内），比如上传/删除等。各个存储类型共用，**每月10万的免费额度**。
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/Fgw0D-tEWFX_w1OcY6Q3C99R3tPl-7684584dc179.webp)
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/FrgIEcLK6vOEGb32CimPcBgXb1me-698976a960b6.webp)

8、Get请求：调用读请求的次数，比如访问文件。各个存储类型共用，**每个月100万次的免费额度**。
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/FgRJtPwl_mNgVWaPTHQFi43cOA70-6c1d99294f7f.webp)

# 二、CDN [#二cdn]

CDN的收费可以参考：[CDN 产品价格说明](/products/cdn/0-cdn-product-pricing)
[CDN价格详情](https://www.qiniu.com/prices/qcdn)
1.CDN-HTTP(S)-中国大陆：国内线路cdn访问产生的流量费用，**其中CDN-HTTP协议的域名，每个月有10G的免费额度**；当域名使用HTTPS协议时，无论请求是否使用HTTPS，都是**按HTTPS流量收费的，且没有免费额度**。
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/FhhGjoLap1xu4S9_Lq7T0qb4vnR1-9fadd4ab2e5e.webp)

2.CDN-HTTP(S)-海外未分区：使用海外cdn，但是不按分区计费产生的流量，是无法抵扣资源包的，也**没有免费额度**。
注意：海外未分区流量需要联系商务经理进行分区，分区后可正常使用免费额度或资源包进行抵扣
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/FpNSrF_WUfqtFiiSJUTr7458StHo-d6da01345d0d.webp)

3、CDN-HTTP(S)-（亚洲/亚洲其他/欧洲北美/南美洲/大洋洲与其他）:使用海外cdn，按请求节点所在地区分区计费，可以使用对应资源包抵扣；**其中CDN-HTTP协议的域名，每个月有10G的免费额度**；当域名使用HTTPS协议时，无论请求是否使用HTTPS，都是**按HTTPS流量收费的，且没有免费额度**。

# 三、全站加速 [#三全站加速]

全站加速流量收费参考：[全站加速计费说明](/products/dcdn/0-dcdn-billing-instructions)
1.动态请求数计费：全站加速请求收费，**每月5万的免费额度**。
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/Fi0ffHMPBcbA9jurlZ3sQfGoG0BZ-7bde10109567.webp)
2.全站加速-HTTP(S)协议-(中国大陆/亚洲/亚洲其他/欧洲北美/南美洲/大洋洲与其他):全站加速流量收费，**没有免费额度**。
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/FjGxJk6dzu52wqCDzXWm5is5deAi-e6b5edf1f0de.webp)

# 四、QVM [#四qvm]

云主机计费说明参考：[计费说明文档](/products/qvm/0-qvm-billing-contrast)
云主机主要计费模式为：预付费（包年包月）、后付费（按量付费）。下面仅为说明部分
1.QVM磁盘快照：不同区域收费不一样。[快照页面](https://portal.qiniu.com/qvm/vm/snapshot)可以查看您账号下的快照。
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/FvxGJmkQrR59DyN3D6NlmieOdwf5-472302d25f88.webp)

2.镜像收费：您账号下创建的磁盘，[查看您的镜像](https://portal.qiniu.com/qvm/vm/image)。

3、磁盘收费：单独购买磁盘只支持按量付费模式，[磁盘查看页面](https://portal.qiniu.com/qvm/vm/disk)。
![image.png](/docs-assets/faq/account-finance/12990-real-spending-detail-describe/Fj6RodV-vkwUsxfMMUTuuZDoNIxW-8e70e6d86e33.webp)

4、负载均衡，可以在这边页面查看：[负载均衡页面](https://portal.qiniu.com/qvm/slb/instance)。


# 接收对象管理-Webhook：如何获取钉钉机器人 (/faq/account-finance/13427-slugeceptionmanagement-ding)



最近更新时间: 2026-04-09 16:39:48

**1. 在 PC 版钉钉中找到需要接收消息通知的会话群。选中并右键单击群，在弹框中单击【群设置】**。
![image.png](/docs-assets/faq/account-finance/13427-slugeceptionmanagement-ding/Ftk1xio__W-zSahL7mT11F_Sq7NO-f9e47270dff4.webp)

**2. 找到【智能群助手】-【添加更多】-【添加机器人】-【自定义】-【添加】，编辑机器人名称和选择添加的群组。**
**3. 安全设置请选择【自定义关键词】，并输入：七牛云**
![image.png](/docs-assets/faq/account-finance/13427-slugeceptionmanagement-ding/FubvBVSf42PNlfNsNH72uq2lG5aA-c95df0f69746.webp)

**4. 提交后即可获取webhook地址**

![image.png](/docs-assets/faq/account-finance/13427-slugeceptionmanagement-ding/FjzX6dl69bCyvPzBYCWkgkmzHUFD-e1c7e02c50d5.webp)


# 接收对象管理-Webhook：如何获取飞书机器人 (/faq/account-finance/13433-receptionmanagementfeishu)



最近更新时间: 2026-04-09 16:47:12

**1. 在 PC 版飞书中找到需要接收消息通知的会话群。进入后点击右侧的设置并选择【群机器人】。**
![image.png](/docs-assets/faq/account-finance/13433-receptionmanagementfeishu/FiKXiXhN__0u8yrRcL9gD4WdP0-9-959a4c7f11b0.webp)

**2. 点击【添加机器人】-【自定义机器人】，并填写机器人名称和描述**
![image.png](/docs-assets/faq/account-finance/13433-receptionmanagementfeishu/Fun8iqCXFUK7GIsZBE0dBNQM6Vrg-a937660c6b60.webp)

**3. 安全设置请选择【自定义关键词】，并输入：七牛云**
![image.png](/docs-assets/faq/account-finance/13433-receptionmanagementfeishu/Fmqf_C_HJraphDiB2Zav4VgSC96y-518f16f27e5c.webp)

**4. 完成配置，即可获取webhook地址**


# 接收对象管理-Webhook：如何获取企业微信机器人 (/faq/account-finance/13434-wechat)



最近更新时间: 2026-04-09 16:48:54

**1. 在 PC 版企业微信中找到需要接收消息通知的企业微信群。选中并右键单击企业微信群，在弹框中单击【添加群机器人】。**

![image2021-5-14\_16-55-43.png](/docs-assets/faq/account-finance/13434-wechat/Fl-CdAQ8LYb7U0GSjVX4IMVXEYzr-b5b2c2504e37.webp)

**2. 在弹框中单击【新创建一个机器人】，自定义机器人名称，填写完后单击【添加机器人】，即可获取webhook地址。**
![image2021-5-14\_16-58-45.png](/docs-assets/faq/account-finance/13434-wechat/FpE1lmVB9_DRnQYmXo72g_FYcAhG-ecd740faf3e1.webp)


# 如何进行网站公安备案和查询公安备案信息 (/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information)



最近更新时间: 2026-04-30 10:28:53

# 查询公安备案信息 [#查询公安备案信息]

打开 [全国公安机关互联网安全管理服务平台](https://beian.mps.gov.cn/#/)。
对首次登录系统的用户，系统会自动弹出提示信息，提示您先填写开办主体信息。

查询方式：在未登录网站情况下点击页面上方的【公共查询】，如下图所示：
![image.png](/docs-assets/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information/Fhve987fbHNkah-a8fLilFI13dK5-cc3a90f922df.webp)
可分别根据网站名称、网站域名、公安机关备案号来查询是否已经存在备案信息，查到显示如下页面：
![image.png](/docs-assets/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information/FhIXjfS7IeqUMKQGjBlPz-Jsy8G9-4eaf13764465.webp)

# 网站公安备案的操作流程 [#网站公安备案的操作流程]

## 开办主体管理 [#开办主体管理]

注册并登录 [全国公安机关互联网安全管理服务平台](https://beian.mps.gov.cn/#/)。
对首次登录系统的用户，系统会自动弹出提示信息，提示您先填写开办主体信息。
![image.png](/docs-assets/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information/FmIUEhKg7aVdcWVUW1or96O3y5Hg-1688549dda68.webp)
开办主体申请： 对于首次备案的用户，必须首先填写主办单位及负责人的真实有效信息，只有提交了主体信息后，才能在该主体下进行网站备案。
开办主体分为： 个人、单位；单下又细分为：企业单位、国防军队、高等院校、政府机构、事业单位、社会团体、境外组织。
点击左侧菜单【开办主体管理】，您需要根据实际情况选择自己的开办主体性质，并正确填写各项信息\*\*（注：填写主体信息时，请您务必保证所填写的信息完整、真实、准确，这样才能通过审核，顺利完成备案）\*\*填写完成后点击【保存】，公安民警审核后您会收到短信通知，也可在系统消息中查看审核结果，一般审核时间为2-3个工作日。
![image.png](/docs-assets/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information/Fm-tZn6MNOWtKZ_Db9LJOMSAT379-1d4fb793f528.webp)
![image.png](/docs-assets/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information/FuGjhku-nin365ufbksC1DJtsPiW-f1698c7ab319.webp)

* 填写注意事项：

  1. 上传的证件图片要清晰大小在5MB以内，支持png,jpeg,jpg格式;
  2. 单位名称：应完整填写网站主办者全称，如个人应填写个人姓名，企业应填写工商营业执照注册公司名 称。内容应真实准确，不得以数字、字母等符号或以网站名称代替网站主办者信息;
  3. 单位性质：应与主办单位名称等信息对应一致，如主办单位名称为某某公司，则单位性质应为企业;如主办单位为张三，则单位性质应为个人;
  4. 证件号码：应符合相应的格式要求，且与主办单位性质等信息（企业、事业单位、政府机关、军队、社会团体、个人等）对应一致。如主办单位性质为企业，只能填写不应填写军队代号或个人身份证等号码等非工商营业执照号码或非组织机构代码证号码;
  5. 投资或主管单位：网站所属者为企业、事业单位、社会团体、政府机关、军队填写法人姓名或单位最高负责人姓名;
  6. 负责人常住地：内容真实准确，格式标准完整。例如，农村单位应详细填写到村，城镇单位应填写到街道门牌号或信箱号;
  7. 办公电话：务必填写。号码应格式标准、内容真实准确，标准格式为“0086-010-68870788”，不得出现“010-00000000”等明显不真实的联系方式。

## 新办网站备案申请 [#新办网站备案申请]

点击左侧菜单【网站业务-新办网站申请】，根据要求填写真实合法的信息，填写完成后，点击【提交】等待公安民警审核，一般审核时间为3-5个工作日\*\* （注务必按照要求填写，否则将被退回） \*\*

### 第一步：网站开办主体，已经提交申请或审核已经通过，直接点击【下一步】即可； [#第一步网站开办主体已经提交申请或审核已经通过直接点击下一步即可]

![image.png](/docs-assets/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information/FnOEdguR1tYlf8ZXInIKNrvzgk0b-ed6d43122c93.webp)

### 第二步：网站基本信息填写 [#第二步网站基本信息填写]

![](/docs-assets/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information/FmaQ3XtyGGUUheIBO3dReNNwO5nM-813ced57bf13.webp)
![](/docs-assets/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information/FvUkTg77f-umRVDiLylNAKP4bjru-3eb8a737663a.webp)

* 填写注意事项：（务必按照要求填写，否则将被退回）
  注: 您的网站若不涉及前置审批，请不要在选项内容中打勾；如果没有您的网站服务内容，就无需选择。

  1. 网站名称：应与其主办单位性质等信息对应一致。如主办单位性质为个人的网站，不得以“某某有限公司”等与其主命名；不得以域名作为网站名称。主办单位性质为非政府机构或非政府授权机构的网站，不得以“某某市人民政府”、“某某监察”等公共事务关键字命名；主办单位性质为非国家级单位的网站，不得以“中国”“中华”“维权”等字头命名。无新闻（省委宣传部获得前置审批）、出版（省出版局获得前置审批）、教育（省教育厅获得前置审批）、卫生（省卫生厅获得前置审批）、药监（省食品药品监管局获得前置审批）、文化（省文化厅获得前置审批）、广电（省广电厅获得前置审批）等前置审批或专项审批的网站，不得以相关领域。关键词命名。如未经新闻管理部门前置审核同意的，不得以“新闻网”命名。
  2. 如果您的虚拟主机只对应一个IP，可以填写同一个IP地址；如果对应多个如实填写起止IP即可。
  3. 网络接入服务商，域名注册服务商：可以选择境内与境外，在境内可以按照地域去进行选择，当找不到所使用的服务商时，选择其他可以手动输入服务商名称等信息。
  4. 网站服务类型：单位可选择单位门户网站，个人可选择博客/个人空间，如有其他类型内容可如实勾选。
  5. 互联网危险品信息发布，网址内容中前置审批内容选择时，均需要上传相应的资质证明文件以备核实。

### 第三步：网站负责人信息填写 [#第三步网站负责人信息填写]

如果网站负责人信息/信息安全负责人信息/舆情引导员信息与开办人主体负责人信息相同，直接打钩即可自动填充；如果不同则根据实际情况分别填写。
![](/docs-assets/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information/FnOaM4qA3yt9daGjBkEhI7VB5ADX-9681b0983478.webp)

* 填写注意事项：
  负责人姓名：应填写真实姓名全称，不得填报“王先生”、“李小姐”、“个人”或者加带数字或字母的姓名等明显不真实的姓名。

### 第四步：提示说明 [#第四步提示说明]

请认真阅读，如果没有异议，勾选“我已阅读信息网络安全保护方案”点击【提交】，公安民警会在3-5个工作日给已反馈，反馈的信息将以短信形式通知，也可登录网站在系统消息中查看。
![](/docs-assets/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information/FtxW79lh2iwUVe5UGyOTLya8297T-b8269343f199.webp)

* 特别注意：
  非交互式网站初步审核完成后即完成备案，交互式网站需要进行面审或实地检查，具体时间将以短信告知。
  如收到公安机关面审通知，请按照短信通知的时间携带所需证件到公安机关进行材料完整性检验；
  如收到公安机关实地审核通知：请按照通知的时间做好准备，配合公安民警进行安全检查。

### 第五步：审核通过发放备案号 [#第五步审核通过发放备案号]

在完成以上审核以后，公安机关将会发放公安部备案号，您需要将备案号放置网站首页下端 ；您可以将网站备案代码放置在网站上，获取代码方法：在已备案网站中查看网站详情，点击【点击复制备案号】即可获得备案代码。
![](/docs-assets/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information/Fjns64cIY9G53x32G8UoARLrU8_v-1ff5b9c74207.webp)
![](/docs-assets/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information/Fuecw-fsq_ZY0wld0iTXBD1_JvNq-c62758fae599.webp)


# 外网流出流量和 GET 请求次数问题 (/faq/account-finance/4405-%E5%A4%96%E7%BD%91%E6%B5%81%E5%87%BA%E6%B5%81%E9%87%8F%E5%92%8CGET%E8%AF%B7%E6%B1%82%E6%AC%A1%E6%95%B0%E9%97%AE%E9%A2%98)



最近更新时间: 2026-05-07 13:25:24

# 外网流出流量 [#外网流出流量]

外网流出流量的费用属于对象存储的费用。
如果使用了七牛测试域名或者融合 CDN 域名访问资源，是**不会计算**外网流出流量的。
只有以下五种情况会计算外网流出流量：

1. 使用第三方 CDN 回源七牛对象存储空间的回源请求。
2. 使用 [qshell](/products/kodo/0-qshell) 工具的 [qdownload](https://github.com/qiniu/qshell/blob/master/docs/qdownload.md) 命令下载，但没有指定 cdn\_domain 。
3. 使用 [kodo-browser](/products/kodo/1-kodo-browser) 工具不使用自有域名下载资源。
4. 调用 [AWS S3协议](/products/kodo/development-guidelines/aws-s3-compatible) 下载空间资源。
5. 使用 [空间源站域名](/products/kodo/kodo-console-guide/bucket-management/kodo-domain-name-management/1-set-the-custom-source-domain-name) 下载资源。

# GET 请求 [#get-请求]

七牛对象存储的 GET 请求次数与 HTTP 协议中的 GET 方法的请求不是同一个概念，不是说对域名发起了一次 GET 请求，就会计算一次 GET 请求次数。
如果使用七牛的测试域名或者融合 CDN 域名访问资源，如果没有进行回源，是**不会计算** GET 请求数的。
只有以下五种情况会计算 GET 请求次数：

1. 使用七牛的测试域名或者融合 CDN 域名访问资源，进行了回源请求。
2. 使用第三方 CDN 回源七牛对象存储空间的回源请求。
3. 使用 [qshell](/products/kodo/0-qshell) 工具的 [qdownload](https://github.com/qiniu/qshell/blob/master/docs/qdownload.md) 命令下载，但没有指定 cdn\_domain 。
4. 使用 [空间源站域名](/products/kodo/kodo-console-guide/bucket-management/kodo-domain-name-management/1-set-the-custom-source-domain-name) 下载资源。
5. 使用 [kodo-browser](/products/kodo/1-kodo-browser) 工具不使用自有域名下载资源。
6. 调用 [AWS S3协议](/products/kodo/development-guidelines/aws-s3-compatible) 下载空间资源。


# 按量计费预估常见问题 (/faq/account-finance/6218-real-spending-common-problems)



最近更新时间: 2026-05-07 15:04:27

**1.如何查看按量计费预估（当月消费明细）金额和明细？**
您可以在 财务中心-[财务概览](https://portal.qiniu.com/financial/overview) 上查看实时消费金额，点击实时消费金额或进入财务中心 - [按量计费预估](https://portal.qiniu.com/financial/bills/estimated-consume) 均可查看当月未出账的预估消费明细详情。

**2.按量计费预估金额是否已经扣费？**
按量计费预估金额并未扣费，仅占用了您的可用额度，且该部分金额不能使用、不能提现，相当于平台暂时冻结了您的可用额度，以确保您能支付月账单。待次月月账单出账扣费，您的按量计费预估金额会同时更新，释放上月被占用的可用额度，并根据您的月账单进行扣费。

**3.为什么会产生按量计费预估金额？**
只要您产生的用量超出了免费额度和已购买的资源包的抵扣范围，额外的用量都会进行计费，产生费用。

**4.如何监控当月按量计费预估的情况？**
您可以设置可用额度预警，当可用额度低于您设置的阈值时，系统会向您推送通知，关于可用额度预警可参考 [设置可用额度预警](/account/0-available-credit-warning)。

**5.当月消费较高，导致可用额度为负了会怎么办？**
当可用额度为负，账户将进入欠费流程，您可参考 [新版欠费流程](/faq/account-finance/account-problem/5996-new-owe-the-process-description)。


# 增值税专用发票抬头说明 (/faq/account-finance/6434-special-invoices-for-value-added-tax-payable-to-illustrate)



最近更新时间: 2019-12-30 14:21:43

* 根据《中华人民共和国发票管理办法》、《中华人民共和国发票管理办法实施细则》和《增值税专用发票使用规定》，纳税人销售货物、提供应税服务以及从事其他经营活动，应向购买方开具发票。

* 自2012年起，国家开始实行营业税改征增值税试点方案，并逐渐在全国范围内多行业展开。由于增值税发票管理比营业税发票管理要规范和严格得多，对于纳入了增值税管理体系的互联网、信息技术服务等行业来说，税务部门对纳税人的企业纳税管理和发票管理提出了更高的要求。其中，《增值税专用发票使用规定》明文规定专用发票开具要与实际交易相符（《规定》第十一条）。

* 用户在购买七牛云服务时，通过网络页面点击确认等方式选择接受了七牛云的服务条款，即视为双方订立了有效合约。用户实名认证主体为系统自动获取的实际交易主体，实名认证名称为系统自动获取的发票抬头，一个七牛云账号只对应一家法律主体。

* 若您尚未完成实名认证，请安排好您的时间，完成实名认证流程，以免影响后续发票申请。

* 七牛云禁止一个账号下随意变更发票抬头，主要系基于对增值税发票（尤其是专用发票）管理的严肃性考虑，这同时也是国家有关部门的要求。若您要修改发票抬头需先修改实名认证信息。实名认证重新认证通过后，即可将新实名认证名称作为专票抬头进行开票。


# 含赠送金充值提现说明 (/faq/account-finance/6450-give-gold-deposits-containing-withdrawal)



最近更新时间: 2020-01-13 15:06:59

# \*\* 1 充值赠送金概述\*\* [#-1-充值赠送金概述]

-充值赠送金只能支付按量计费的产品，不可开票、提现。

-赠送金是默认您的此次充值的现金全部用于消费的情况下所给予的赠送，当该笔充值未全部消费而申请提现时，此次赠送无效，在可提现金额中将减去对应的赠送金额。

# \*\* 2 含赠送金充值提现实例 \*\* [#-2-含赠送金充值提现实例-]

## \*\* 2.1 单笔含赠送金充值提现 \*\* [#-21-单笔含赠送金充值提现-]

充值金额 = 1000元

赠送金额 = 300元

消费金额 = 500元

提现前现金余额 = 800元

最大可提现金额 = 充值金额 - 消费金额 = 1000元 - 500元 = 500元

提现后现金余额 = 0元

备注：该笔充值赠送无效。

\*\* 若您申请提现金额小于最大可提现金额，则调整账户现金余额。\*\*
示例：

申请提现金额 = 300元

提现后现金余额 = 最大可提现金额 - 申请提现金额 = 500元 - 300元 = 200元

## **2.2 多笔含赠送金充值提现** [#22-多笔含赠送金充值提现]

### **例1 消费金额 \<= 第一笔充值金额** [#例1-消费金额--第一笔充值金额]

充值金额(1) = 1000元

赠送金额(1) = 300元

充值金额(2) = 1000元

赠送金额(2) = 300元

消费金额 = 500元

提现前现金余额 = 2000元

最大可提现金额 = 充值金额1 + 充值金额2 - 消费金额 = 1000元 + 1000元 - 500元 = 1500元

提现后现金余额 = 0元

备注：第一、二笔充值赠送均无效。

**若您申请提现额小于最大可提现金额，则调整账户现金余额。**
示例：

申请提现金额 = 300元

提现后现金余额 = 充值金额(1) + 赠送金额(1) + 充值金额(2) - 消费金额 - 申请提现金额 = 1000元 + 300元 + 1000元 - 500元 -300元 = 1500元

备注：第一笔充值赠送有效，第二笔充值赠送无效。

**若 充值赠送(2) \< 客户申请提现金额 \< 最大可提现金额**
申请提现金额 = 1100元

提现后余额 = 充值金额(1) + 充值金额(2) - 消费金额 - 申请提现金额 = 1000元 + 1000元 -500元 - 1100元 =400元

备注：两笔充值赠送均无效。

### **例2 第一笔充值金额 \< 消费金额 \<= 第一笔充值金额 + 第一笔赠送金** [#例2-第一笔充值金额--消费金额--第一笔充值金额--第一笔赠送金]

充值金额(1) = 1000元

赠送金额(1) = 300元

充值金额(2) = 1000元

赠送金额(2) = 300元

消费金额 = 1100元

提现前现金余额 = 1500元

最大可提现金额 = 充值金额(2) = 1000元

提现后现金余额 = 200元

备注：第一笔充值赠送有效，第二笔充值赠送无效。第一笔现金余额200元可继续用于消费。

**若您申请的提现金额小于最大可提现金额，则调整账户现金余额。**
示例：

申请提现金额 = 500元

提现后现金余额 = 充值金额(1) + 赠送金额(1) + 充值金额(2) - 消费金额 - 申请提现金额 =1000元 + 300元 + 1000元 - 1100元 - 500元 =700元

**若您申请提现金额大于最大可提现金额，则两笔充值赠送均无效。**
示例：

申请提现金额 = 1200元

可提现金额 = 充值金额(1) + 充值金额(2) -消费金额 =1000元 + 1000元 - 1100元 = 900元

提现后现金余额 = 0元

### **例3 消费金额 >= 第一笔充值金额+第一笔赠送金** [#例3-消费金额--第一笔充值金额第一笔赠送金]

充值金额(1) = 1000元

赠送金额(1) = 300元

充值金额(2) = 1000元

赠送金额(2) = 300元

消费金额 = 1500元

提现前现金余额 = 1100元

最大可提现金额 = 充值金额(1) + 赠送金额(1) + 充值金额(2) - 消费金额 = 1000元 + 300元 + 1000元 - 1500元 = 800元

提现后现金余额 = 0元

备注：第一笔充值赠送有效，第二笔充值赠送无效。

**若您申请提现金额小于最大可提现金额，则调整账户现金余额。**
示例：

申请提现金额 = 500元

提现后现金余额 = 最大可提现金额 - 申请提现金额 = 800元 - 500元 = 300元

## **2.3 无赠送金和含赠送金充值并存** [#23-无赠送金和含赠送金充值并存]

充值金额(1) = 300元（无充值赠送）

充值金额(2) = 1000元

赠送金额(2) = 300元

消费金额 = 1000元

提现前现金余额 = 600元

最大可提现金额 = 充值金额(1) + 充值金额(2) - 消费金额 = 300元 + 1000元 -1000元 = 300元

提现后现金余额 = 0元

备注：按照充值时间顺序扣费，第二笔充值赠送无效。充值赠送金是否为有效情况和2.2例子相同。

**若您申请提现金额小于最大可提现金额，则调整账户现金余额。**
示例：

申请提现金额 = 200元

提现后现金余额 = 最大可提现金额 - 申请提现金额 = 300元 - 200元 = 100元

### **提示：** [#提示]

上述例子中不涉及含抵用券的情况。


# 七牛工单小助手使用指南 (/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper)



最近更新时间: 2020-07-27 18:59:52

七牛云推出移动端工单小程序，通过手机即可快速提交、查看工单，关注七牛云服务公众号，第一时间获取七牛最新消息通知，解决问题，快人一步。

<br />

# 扫码获取七牛云工单小助手 [#扫码获取七牛云工单小助手]

![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/Fgyxxt-fadtMOkVXisrtp0vsTIj1-77a2d424c258.webp)

<br />

# 关联七牛账号 [#关联七牛账号]

通过点击「`我`」-「`关联七牛云账号`」
![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/Ft_M7ju5a2aQ4Jjoj05_yC9SmZ-b-ed62fe746113.webp)![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/FsKBuqDUU44Yn5U5MuOASMOE5z9q-674facedf37d.webp)

<br />

# 消息订阅 [#消息订阅]

开启微信推送功能，订阅七牛工单消息，需要先关注微信公众号『`七牛云服务`』，关注后即可第一时间获取工单回复进展
![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/FktnNAzaQkiNGa282EvILZmu0_MW-25f3db7e5fa9.webp)![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/Fju5lSg0ZsnJQSMAXs4GiHBnFlsy-87754c0cf0bc.webp)![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/FjEfsK4uW6mmFY_2G6PUMEH5RSy-4b910cfbd342.webp)![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/FlVV_TtmYxuyw31TCcaVmGFDA0OH-02033b9fcd95.webp)

<br />

# 提交工单 [#提交工单]

通过点击「`首页`」-「`创建工单`」选择具体的产品和问题类型，填写并提交工单
![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/FjwBb2Mqy3vZ2AjC9aUUSDk1Kebz-dfc52739fb02.webp)![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/FngvqaRUAojapYtm8Fuu1yRVUf2y-8a9973ccb45c.webp)![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/Fhb5TbTGUKfGHEmG6kkbVGSyeuO-d6b682c0d871.webp)![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/FrAWAikZOtjt7swcK7Eyq5mKD1ON-21c7af85f6fe.webp)

<br />

# 查看已提交工单 [#查看已提交工单]

通过点击「`首页`」-「`我的工单`」，即可查看到所有已经提交的工单，建议点击「待您处理」查看七牛工程师已经处理回复的工单
![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/FhAKBOUBO6a_AmfFaKBlSvU6uc_G-47c590139dae.webp)![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/FqrxxwRJrAXFbVKnUs6wrSMsVR-v-08560acf2f11.webp)

<br />

# 一键投诉 [#一键投诉]

通过点击工单页面，「`一键投诉`」按钮，进行问题及时升级反馈
![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/FgjvpeRIguH6wiBJ7dB3yH6CNj4K-d7f5e7ee1ef1.webp)![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/FmA_gidp6UZmrIw4P71V30M0C9p6-7b3a5031d678.webp)

<br />

# 关闭工单 [#关闭工单]

若问题已经解决，通过点击工单页面，「`关闭工单`」关掉当前工单
![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/FuFdwzns5u-tXqqI1ajFsI42R8Ln-ef84f5c606a0.webp)

<br />

# 评价工单 [#评价工单]

通过点击工单页面，「`关闭工单`」-「`立即评价`」对本次服务进行评价
![](/docs-assets/faq/account-finance/7023-qiniu-work-instructions-on-using-a-single-little-helper/Fu1h27vzB6JIC_8UFpTEN7Dcfk7i-20bf90f4013f.webp)


# 对公汇款说明 (/faq/account-finance/8169-contrary-to-the-remittance-instructions)



最近更新时间: 2026-05-09 09:53:22

为方便您通过对公汇款方式充值，七牛云为您提供浦发银行汇款专属账号。专属账号为13位数字，用于将您通过银行柜台或网银等方式向专属账号的汇款自动匹配至七牛云账户下。专属账号和七牛云发票显示账号二者实质为同一账号。建议您使用专属账号汇款，通过专属账号汇款准实时到账，缩短到账时间。

# 对公汇款流程 [#对公汇款流程]

## 1、获取专属收款账号 [#1获取专属收款账号]

位置：[财务中心 > 账户充值](http://portal.qiniu.com/financial/recharge)
点击「对公汇款」页面，在对公汇款信息处点击「复制以上收款信息」按钮获取您的专属收款账号。
![image.png](/docs-assets/faq/account-finance/8169-contrary-to-the-remittance-instructions/FnKwbezUFbf_TsKKPLHyEP6h8t57-0d6e31187f14.webp)

## 2、打款至专属收款账号 [#2打款至专属收款账号]

* 通过网上银行/手机银行/电汇/支票/柜台打款等方式打款至您的七牛云专属收款账号。
* 每个七牛账号都有对应的专属收款账号，该专属收款账号不可用于其他七牛云账号或其他客户，请注意核对，避免充错账号。
* 专属收款账号暂不支持外币汇款。

## 3、查询充值结果 [#3查询充值结果]

* 专属账号汇款到账时间：准实时到账。（具体到账时间以银行的实际到账时间为准。）
* 查询位置：[财务中心 > 成本费用 > 收支明细](https://portal.qiniu.com/financial/cost/income-expenses)
* 您也可以 [设置](http://portal.qiniu.com/notification/user-setting) 手机短信、邮件、站内信的方式接收到账信息。

# 旧版对公汇款信息 [#旧版对公汇款信息]

### 通用账号汇款特别说明 [#通用账号汇款特别说明]

* 为了您的合法权益，转账时请备注您的七牛云账号。
* 如银行不支持"@"符号输入，请使用中文“艾特”替代。eg：[mail@qiniu.com](mailto:mail@qiniu.com)；mail艾特qiniu.com。
* 银行转账会需要至少 3 个工作日到账，期间请耐心等待，如遇到问题可以联系销售或者技术支持。

### 通用收款账号信息 [#通用收款账号信息]

收款户名：上海七牛信息技术有限公司
收款银行：上海浦东发展银行杨浦支行
收款账号：98120154740008821


# 账户与财务 (/faq/account-finance)



这里用于整理账号、计费、权限和安全相关的常见问题。


# AI 大模型推理 (/faq/aitokenapi)



## 订阅管理积分相关FAQ [#订阅管理积分相关faq]

[查看原文](/faq/aitokenapi/aitoken-sub-mgmt/13459-sub-mgmt-faq)

本文主要介绍AI订阅使用相关问题

## AI推理邀请、注册FAQ [#ai推理邀请注册faq]

[查看原文](/faq/aitokenapi/share-to-earn/13461-aitoken-Invite-registration-earn)

本文主要介绍如果通过专属链接邀请注册

## 大模型接口调用FAQ [#大模型接口调用faq]

[查看原文](/faq/aitokenapi/other/13462-aitoken-use-faq)

AI 大模型推理服务问题,FAQ

更多问题请查看 [官网 FAQ](/faq)。


# 流量异常的常用处理方法 (/faq/cdn/12966-abnormal-traffic-problems-faq)



最近更新时间: 2026-08-18 14:01:18

# 简介 [#简介]

本文主要是指导您，在流量出现非预期增长的情况下，您应该如何完成流量的快速检查，然后对异常的流量、文件、ip做出快速处理，防止您的流量被进一步请求，从而造成更大的损失。

# 说明 [#说明]

* 本文只以CDN域名为例，源站域名和S3域名不在本文说明范围，全站加速域名DCDN与CDN分析方式相同，就不做赘释。

* 如果您发现您的源站域名产生的流量过高，建议您将源站域名删除，修改成CDN域名，原因是：`源站域名`防护能力不如`CDN`，源站域名不建议直接暴露公网使用，源站域名一般是直接给第三方CDN回源使用。

* 本文只针对访问量特别巨大的情况下，为您介绍如何判断和处理

# 账单与流量 [#账单与流量]

只要您将域名解析到七牛给您分配的cname，并且您使用域名进行访问，就会产生流量，CDN域名，默认每个月提供免费的10GB - HTTP流量 ，注意：`域名一旦升级到HTTPS，那么域名就不在享有免费的 10GB HTTP流量`。所以当您发现，您如果CDN流量不足10GB，但是却产生了流量计费，您需要看下，您是不是将域名升级到了HTTPS ，计费的账单也是 CDN - HTTPS流量计费。如果您之前的流量使用很低，但是近期流量费用突然增长很多，那么此时，你需要进行流量分析。

# 流量统计分析与防护 [#流量统计分析与防护]

流量统计分析有多重维度进行统计分析，可以查看带宽、流量、访问TOP靠前的文件和IP等，具体详情可以参考[流量分析](/products/cdn/data-statistics-fusion)

## 获取访问量最高的文件和ip [#获取访问量最高的文件和ip]

当您发现流量账单超出预期，流量增长过大，你可以看下，您访问最多的文件 和 ip 是什么，进入[CDN-统计分析-TOP URL/IP](https://portal.qiniu.com/cdn/statistics/log/top)进行查询

<img src="/docs-assets/faq/cdn/12966-abnormal-traffic-problems-faq/FoGr-TdDuVV5cwd4Jg6uRxBve3zW-d19f70024b3e.webp" width="800" />

## 文件删除 与 ip黑名单封禁 [#文件删除-与-ip黑名单封禁]

* 单文件访问量特别高
  当您在URL TOP 100 中发现，某个文件或者某几个文件的访问量远超其他文件，或者访问量远超您的预期，您可以将这些文件删除，然后请一定要刷新这些文件的CDN缓存，如果您只是将文件删除，但是没有刷新缓存的话，有可能您的文件删除后，文件依然是可以访问的！CDN缓存默认最大时间是30天！刷新缓存可以参考这里:[主动刷新缓存](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time#1)

* 单个ip的访问量特别高
  当您发现单个ip或者某几个ip访问量特别高的时候，您可以在 [CDN -- 域名管理](https://portal.qiniu.com/cdn/domain) -- 配置 --IP黑白名单配置中，开启黑名单，将这些个ip直接加入黑名单即可

<img src="/docs-assets/faq/cdn/12966-abnormal-traffic-problems-faq/FrBaFq3rRPkKORk7j7ILUR7ZCsDN-b1eb68cf225c.webp" width="800" />

* 某些个长的很像的ip访问量特别高
  当您发现某一批ip，或者某个网段的ip长得非常像，比如访问的ip是
  ```bash
  58.222.39.112
  58.222.39.117
  58.222.39.119
  223.108.56.24
  223.108.56.23
  223.107.67.1
  ```
  如果这种相对比较连续集中的ip，不是您正常业务的ip，您可以设置子网掩码的方式进行拉黑，比如设置黑名单ip
  ```bash
  58.222.39.0/24
  223.108.56.0/24
  223.107.67.0/24
  ```
  如果觉得ip范围小了，可以使用/8 /16更大范围的网段去屏蔽，
  其中 /24 表示 ip 的前3段有效：
  58.222.39.0/24表示的是 58.222.39.xxx 网段的全部ip,
  58.222.0.0/16 表示 58.222.xxx.xxx网段的全部ip
  58.0.0.0/8 表示 58.xxx.xxx.xxx网段的全部ip
  可以根据你们的需求自行调整这个拦截范围

* 出现奇怪的ip
  当您发现了一些ip比较奇怪，不是常规的数字ip,比如
  ```bash
     240e:978:1505:7f:0:2b:0:2564
     240e:979:9503:bf:0:7a:0:264
     240e:978:1505:7f:0:2b:0:2563
     240e:979:9503:bf:0:2e:0:266
     240e:978:1505:7f:0:2c:0:2562
     240e:979:9503:bf:0:7a:0:264
     240e:979:9503:bf:0:2e:0:266
  ```
  这种ip就是IPV6的ip,处理这种ip有两种方式
  1：将域名的IP协议调整为IPV4 , 在CDN--域名管理--配置中，修改ip协议，只选择ipv4即可
  2：将ipv6 加入黑名单，`注：ipv6不能像ipv4设置网段，只能一个一个添加`，如果麻烦，建议用方式1

## 全部CDN访问详情 [#全部cdn访问详情]

如果您觉得 TOP100中的ip可可能不全，或者存在更多的其他非预期ip访问，想要获取这些ip的访问特征、访问时间等其他信息，建议您在控制台直接下载原始[CDN日志](https://portal.qiniu.com/cdn/log)进行分析

<img src="/docs-assets/faq/cdn/12966-abnormal-traffic-problems-faq/FqJrTJyrZ01btB8chU4Xd68WUoyk-e999a612fe70.webp" width="800" />

# 流量控制的方法 [#流量控制的方法]

CDN -- 域名管理  -- 配置 – 访问控制 中已经提供了防止盗链的功能，建议客户可以按照需求去自定义配置，防盗的方式有：ip黑白名单、referer防盗链、时间戳防盗链以及回源鉴权

| 防盗量功能类型    | 功能说明                                                                                                  |
| ---------- | ----------------------------------------------------------------------------------------------------- |
| ip黑白名单     | 设置客户ip黑名单,禁止特定ip访问资源，设置ip白名单，只允许特定ip访问资源，可以有效对客户端请求来源做控制，控制访问流量。                                      |
| referer防盗链 | 对HTTP的referer请求头做检验，设置特定域名referer黑名单,禁止特定域名下访问资源，设置特定域名referer白名单，只允许特定域名下访问资源。                       |
| 时间戳防盗链     | 客户端在请求时，需要按照业务服务端返回的签名内容发起请求，请求url携带鉴权参数，CDN节点按照预设鉴权配置检验签名内容，校验通过后才继续放行。                              |
| 回源鉴权       | CDN在请求的资源时候，将特定参数和参数内容，转发到客户自定义业务鉴权服务器，业务鉴权服务器对参数内容校验，只有业务鉴权服务器返回特定的状态码，校验通过后才继续放行。                   |
| UA黑白名单     | User-Agent 字段，可以识别客户使用的操作系统及版本、CPU 类型、浏览器及版本、浏览器渲染引擎、浏览器语言、浏览器插件等；通过 User-Agent 字段的值来允许或者阻止特定用户访加速域名。 |

# 流量监控与告警 [#流量监控与告警]

除了配置相关放到措施外，七牛还提供了相关的告警功能
建议您启用流量/带宽管理的相关配置（免费），监控域名流量或带宽的消耗情况并接收告警，及时了解流量消耗的相关信息。

| 功能类型                                                                   | 功能说明                                                                                                                                                                                                      |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [流量告警监控平台](/products/cdn/3-cdn-the-alarm-service)                      | 可以对 CDN 产品下指定域名，进行多维度的流量带宽监控，达到设定的峰值后将会给用户发送告警（短信、邮件和微信），便于更加及时地发现潜在风险。                                                                                                                                   |
| [流量包管理](https://portal.qiniu.com/financial/orders/respack-mgr/current) | 如果已经购买CDN流量资源包，您可以在控制台-资源包管理处设置告警策略，当所有有效流量包余额不足设定的比例时发送告警。<br /><img src="/docs-assets/faq/cdn/12966-abnormal-traffic-problems-faq/FoXp-emlMbeHs0yaBJIw9cG3-GXS-83e084b2afd3.webp" width="500" />        |
| [流量余额管理](https://portal.qiniu.com/financial/overview)                  | 如果没有购买资源包，直接使用账号余额支付账单，可以在控制台-财务中心-财务概览处设置余额告警策略，当可用额度不足设定的余额时发送告警<br /><img src="/docs-assets/faq/cdn/12966-abnormal-traffic-problems-faq/FliKoM2haiXsBTRkzijv8yKZcEF3-67366b15c3df.webp" width="500" /> |

# 综合处理方式 [#综合处理方式]

1：检查异常流量详情
2：针对异常流量，删除异常文件，刷新文件缓存，根据您的需求，配置对应的防盗措施，简单一点的可以配置ip黑名单，当然您也可以设置其他方式
3：设置监控与告警，流量带宽告警，必要的时候，您可以同时设置资源包余额告警和账号余额告警
4：定期检查流量带宽日志，如果发现异常，及时更新防盗策略


# 微信小程序使用七牛CDN，Referer防盗链如何设置 (/faq/cdn/13076-domain-name-hotlinking-prevention-wechat)



最近更新时间: 2026-04-29 14:54:28

### 简介 [#简介]

Referer防盗链可在‌存储空间（Bucket）‌或‌CDN节点‌两级配置：
‌存储空间级‌：仅管控直接访问源站域名的请求。
‌CDN级‌：管控通过CDN域名的所有请求（含缓存命中场景）。
用户实际通过CDN域名访问资源，因此需**在‌CDN侧配置防盗链‌**。若仅在存储空间设置，可能因CDN缓存或拦截导致规则失效。

### 如何开启CDN Referer 防盗链 [#如何开启cdn-referer-防盗链]

您业务使用微信小程序的话，除了您自己网站涉及域名外，还需要额外放行小程序官方域名

```text
  servicewechat.com
*.servicewechat.com
```

1，登录 七牛管理控制台 ，在左侧点击 CDN ，在 [域名管理](https://portal.qiniu.com/cdn/domain)中，找到需要开启 Referer 防盗链的域名，点击 配置
![image.png](/docs-assets/faq/cdn/13076-domain-name-hotlinking-prevention-wechat/Fleo2DHMiV3N9SM0oZ4_NqymEqYl-b7494bb1074f.webp)

2，下拉弹窗，找到 访问控制 -> Referer 防盗链，点击 修改配置：
![image.png](/docs-assets/faq/cdn/13076-domain-name-hotlinking-prevention-wechat/FkGygWwx4C-_ee06oeAZlumFQBO9-cd5c3b41587c.webp)

3，点击 开启 ，然后配置具体的黑白名单规则：
![Description](/docs-assets/faq/cdn/13076-domain-name-hotlinking-prevention-wechat/FlTPG336NVDzMZhpsRjhzHiLXbyS-ae423adab123.webp)


# 视频教程 - 绑定域名 (/faq/cdn/1388-video-tutorials-binding-domain)



最近更新时间: 2023-06-25 19:40:53

如何绑定域名，进行cname 解析

[https://dn-odum9helk.qbox.me/lnwaoAhRqxEasksQlVu1V6n6ZwVb.mp4](https://dn-odum9helk.qbox.me/lnwaoAhRqxEasksQlVu1V6n6ZwVb.mp4)


# 常见的证书申请状态有哪些？ (/faq/cdn/3655-what-are-common-certificate-application-status)



最近更新时间: 2017-08-31 16:01:22

# 已完成 [#已完成]

证书验证成功并已签发证书，可以使用。

# 域名循环验证中 [#域名循环验证中]

已提交证书申购，等待用户DNS验证域名所有权。

# DNS验证超时 [#dns验证超时]

24小时内没有通过DNS验证。

原因：

1. 没有进行DNS验证；
2. TXT解析内容填写错误

# 订单被拒绝/安全审核失败 [#订单被拒绝安全审核失败]

* 用户短时间多次提交或重复信息提交订单；
* 域名中包含非法关键字导致安全审核失败。

# 提交订单审核不通过 [#提交订单审核不通过]

* 域名中含有敏感信息，未通过CA机构的反钓鱼审核，请尝试更换域名。
* 域名是被列入CA机构黑名单，请尝试更换域名。
* 相同信息频繁申请或信息不是真实信息，请尝试更换信息。


# SSL 证书相关的一些问题 (/faq/cdn/3673-general-issues)



最近更新时间: 2026-09-14 10:20:27

1. 目前七牛免费证书是 DV 单域名证书，即1个证书对应 1 个域名。不支持多域名和泛域名绑定。
2. OV 和 EV 证书支持多个标准域名，多个标准域名 + 多个泛域名。但是要激活证书多域名的能力，首次绑定必须 ≥2 个域名。
3. 申请主域名如 qiniu.com 的 SSL 证书，默认会在证书域名中添加 www 域名如 [www.qiniu.com](http://www.qiniu.com) ，因此无需重复申请；
4. 同样，如果您申请 www 的二级域名，将同时为您添加主域名使用权限。但如果您是申请的三级域名，如 [www.abc.qiniu.com](http://www.abc.qiniu.com) ，则只能支持该域名，不会支持 abc.qiniu.com。
5. Q:证书过期后怎么办? 证书管理中可以查看证书的有效期，当证书快过期时用户可以重新申请证书并绑定域名。如果已经过期的证书，需要域名点击 HTTPS 配置，然后关闭 HTTPS ，关闭完成后，再重新申请一键HTTPS免费升级即可。


# Symantec 证书为什么相比其他证书要贵一些？ (/faq/cdn/3698-symantec-certificate-why-some-expensive-compared-to-other-certificate)



最近更新时间: 2017-08-31 16:02:49

# 原因一 [#原因一]

传输层加密仅仅是 SSL 证书的作用之一；SSL 证书更主要的用处其实在于验证网站及其背后企业的真实性以及合法性。

* 更贵的 SSL 证书的验证过程通常更加严谨。DV（Domain Validation）级别的证书（如你提到的 GeoTrust QuickSSL）在签发之前只会验证你对域名的使用权，并不对域名使用者本身进行任何验证。而更高端一点的 OV（Organization Validation）会验证域名背后的公司 / 组织的真实性和合法性（个人用户通常是无法获得 OV 证书的）。并且和 DV 不同，OV 证书签发之前是需要 paperwork 的，需要提交相关的证明、执照等材料。过程更复杂、签发更严谨，价格自然就更高。
* 另外，你购买证书时往往还同时为顾客购买了一份保险（warranty）：如果由于 CA 的失误给一个诈骗 / 非法的公司或组织颁发了证书，并且顾客在这种网站上消费造成了财产损失，CA 会在一定程度上对顾客进行赔付。不同价格的证书的赔付额度差异很大，条款亦可能有所不同。例如 RapidSSL 的保额为 $10,000 美元，而 Symantec Secure Site Pro 则为 $1,750,000 美元。
* 总结：购买 SSL 证书时所付出的成本除了用于加密之外，其实更多的是为了让访客相信你的网站是合法的、可信赖的。

# 原因二 [#原因二]

比较价格的时候，只考虑外观效果（绿锁）和加密强度这两个因素是不完全的，其他因素：

* 证书的适用范围、功能、有效期
* 颁发公司的公信力
* 证书这种东西，信任链的顶层就是颁发公司，知名公司的信用当然比一个名不见经传的小公司值钱得多
* 颁发公司对证书密钥的保护能力
* 服务条款的差别
* 证书维护、更新、废弃，担保、赔偿

# 原因三 [#原因三]

证书不仅是加密用的，也是身份的证明。一个信任的CA颁发的证书，证明效力就要比不信任的CA颁发的证书更好。贵的证书也是这样，它的证明效力，要比便宜的证书多很多的。

# 原因四 [#原因四]

付费证书的价值在于其签名，签名意义在于标示你是可信的服务方而非伪造的钓鱼者。另外赛门铁克 pro 系列证书除支持 RSA 算法外还支持 ECC 算法。

# 原因五 [#原因五]

另外 单纯从技术角度，symantec和 GeoTrust 的区别如下：

* 算法支持上 Symantec（支持RSA DSA ECC三种算法）Geotrust（支持RSA DSA两种算法）
* 兼容性 Symantec > Geotrust ； Symantec（原verisign）可兼容市面上所有的浏览器，对移动端的支持也是最好的
* OCSP 响应速度：Symantec > Geotrust
* CA 安全性 方面  Symantec > Geotrust  ，symantec是国际知名安全厂商，CA的安全级别也是国际第一的安全系数。
* Symantec 证书除实现加密传输以外，还另外有恶意软件扫描和漏洞评估的附加功能。GeoTrust证书没有
* Symantec对证书有商业保险赔付保障，金额最高为175万美金，GeoTrust最高为150万美金


# 证书链是什么？ (/faq/cdn/3703-the-certificate-chain-is-what)



最近更新时间: 2017-08-09 09:11:48

* 完整的证书内容一般分为3级，服务端证书-中间证书-根证书，即 end-user certificates， intermediates Certificates 和 root Certificates。
  * end-user ：用来加密传输数据的公钥的证书，是https中使用的证书。开发者牛小七把证书部署在qiniu.com 的服务器上。
  * intermediates：CA用来认证公钥持有者身份的证书，即确认https使用的end-user证书是属于qiniu.com的证书。
  * root：用来认证intermediates证书是合法证书的证书。

* 简单来说，end-user证书上面几级证书都是为了保证end-user证书未被篡改，保证是CA签发的合法证书，进而保证end-user证书中的公钥未被篡改。我们使用end-user certificates来确保加密传输数据的公钥(public key)不被篡改，而又如何确保end-user certificates的合法性呢？这个认证过程跟公钥的认证过程类似，首先获取颁布end-user certificates的CA的证书，然后验证end-user certificates的signature。一般来说，root CAs不会直接颁布end-user certificates的，而是授权给多个二级CA，而二级CA又可以授权给多个三级CA，这些中间的CA就是intermediates CAs，它们才会颁布end-user certificates。

* 七牛云证书管理，会在用户上传证书的时检测证书的完整性，证书链不完整会自动帮用户补全证书链，但无法保证补全的证书链100%是正确的。所以需要用户选择使用自传的证书还是系统补全后的证书。


# 域名配置 FAQ (/faq/cdn/3880-the-domain-name-configuration-faq)



最近更新时间: 2026-07-02 15:49:05

| Q1：已经配置CNAME，为何还是提示请配置CNAME，CNAME应该如何正确配置？                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CNAME 记录解析需要到域名提供商处配置，问题参考：[配置失败原因](/faq/cdn/domain-name-configuration-problem/3884-why-did-the-cname-parsing-or-display-please-match-cname)；更多配置请参考： [帮助文档](/products/cdn/1-custom-domain-name-binding-process)。 |

<br />

| Q2：时间戳防盗链是什么？如何实现？                                                                             |
| ---------------------------------------------------------------------------------------------- |
| 参考文档：[时间戳防盗链](/faq/cdn/domain-name-configuration-problem/1670-timestamp-hotlinking-prevention) |

<br />

| Q3：域名希望覆盖范围从大陆调整到海外，使用场景需要从图片小文件调整到点播，如何操作？ |
| ------------------------------------------- |
| 此类需求必须要提交工单，说明域名和具体的需求，由七牛工程师来调整。           |

<br />

| Q4：如何更换空间绑定域名？                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 更换存储空间绑定的CDN加速域名：参考 [设置自定义CDN加速域名](/products/kodo/kodo-console-guide/bucket-management/kodo-domain-name-management/0-set-the-custom-cdn-to-accelerate-the-domain-name) 文档绑定新的CDN加速域名，然后去域名购买商平台配置CNAME解析，解析成功后新的CDN域名配置就完成了。然后在自己业务端修改外链中的域名为新绑定的CDN加速域名即可 |
| 更换存储空间绑定的自定义源站域名：参考 [设置自定义源站域名](/products/kodo/kodo-console-guide/bucket-management/kodo-domain-name-management/1-set-the-custom-source-domain-name) 文档绑定新的自定义源站域名，然后去域名购买商平台配置CNAME解析，解析成功后新的自定义源站域名配置就完成了。然后在自己业务端修改外链中的域名为新绑定的自定义源站域名即可                 |

<br />

| Q5：物联网卡使用CDN如何设置白名单？                                 |
| ---------------------------------------------------- |
| CDN默认没有访问限制，如果物联网卡有域名白名单限制，可以在物联网卡里面将需要请求的CDN域名加白处理。 |

<br />

| Q6：CDN是否支持设置指定省份或国家走加速？                                              |
| -------------------------------------------------------------------- |
| 不支持，如果需要限制某些省份或国家访问，可以在CDN域名购买商平台或域名DNS托管商平台将不需要访问的省份或国家解析至127.0.0.1 |

<br />

| Q7：CDN是否支持热点视频瘦身？                                                                                          |
| ---------------------------------------------------------------------------------------------------------- |
| 支持，具体可以参考 [CDN热点视频瘦身](/products/kodo/development-guidelines/dev-the-data-processing/3-hot-video-slim) 说明文档 |

<br />

| Q8：CDN如何临时屏蔽所有访问？                                                                                                                                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 您可以在域名购买商平台将域名的cname解析指向127.0.0.1 或 设置ip白名单为1.1.1.1来处理，ip黑白名单配置操作参考：[/products/cdn/configuration-management-fusion/access-control-configuration/3-ip-black-and-white-list](/products/cdn/configuration-management-fusion/access-control-configuration/3-ip-black-and-white-list) |

<br />

| Q9：国内域名使用CDN是否需要ICP备案？                                                                                                                                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CDN域名覆盖范围选择中国大陆或全球覆盖的情况下，是必须要有ICP备案，域名可以在 [工信部官网](https://beian.miit.gov.cn/#/Integrated/recordQuery) 可以查询到备案信息即可。需要了解域名ICP备案流程和要求，可以参考 [备案简介](/products/qvm/section-fpr5/9-record-introduction) 说明 |

<br />

| Q10：已备案过的域名，为啥提示未备案？                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------- |
| 您可以在 [工信部官网](https://beian.miit.gov.cn/#/Integrated/recordQuery) 查询确认下备案信息是否可以查询到？如果查询不到，说明ICP备案信息可能被注销了，需要您找之前备案的平台确认下具体情况。 |

<br />

| Q11：您的账号xxx在过去 90 天内没有流量，我司将于 7 天后停用如上域名 |
| ---------------------------------------- |
| 过去90天，没有流量且没有任何操作的域名会被停用，停用前会发送通知告知用户。   |
| 建议解决方案：您只需在域名停用前使用该域名访问资源产生流量即可避免停用。     |

<br />

| Q12：CDN是否支持WSS协议，即WebSocket Secure |
| ---------------------------------- |
| CDN暂时不支持websocket                  |

<br />

| Q13：创建域名失败，提示域名冲突？                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------ |
| 产生原因是对应域名在其他七牛账号已创建使用导致的；                                                                                                |
| 1、如对应域名在其他七牛账号下还未删除，您可以参考 [域名找回](/products/cdn/the-domain-name-management/3-the-domain-name-back) 文档操作处理；                |
| 2、如对应域名在其他七牛账号下已被删除，需要您 [提交工单](https://support.qiniu.com/tickets/new-for-person) 由技术支持人员为您人工过户处理（注意：每月1-3号为出账期，不支持域名过户）； |
| 3、注意：域名找回后，当月未出账的所有CDN流量费用由新账号承担                                                                                         |

<br />

| Q14：CDN支持etag设置吗？ |
| ----------------- |
| 不支持               |

<br />

| Q15：CDN可以指定空间或者指定目录，不要有缓存吗？                                                                              |
| -------------------------------------------------------------------------------------------------------- |
| 支持，CDN域名支持后缀、目录方式配置缓存，配置操作参考 [缓存配置](/products/cdn/configuration-management-fusion/2-cache-configuration) |

<br />

| Q16：为什么下载的CDN日志没有UA信息？                 |
| -------------------------------------- |
| 日志中UA字段显示为”-“，是因为该请求未携带User-Agent头导致的。 |

<br />

| Q17：CDN支持「限制单个 IP 每秒请求数（QPS）」吗？ |
| ------------------------------- |
| 目前暂不支持                          |

<br />

| Q18：如何快速部署「EdgeOne」？ |
| -------------------- |
| 目前暂不支持EdgeOne        |

<br />

| Q19：误删CDN域名，如何处理？                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------ |
| 域名删除后，无法恢复，需要继续使用的话，您重新创建下CDN域名并配置CNAME解析即可，创建域名操作参考：[域名接入](/products/cdn/the-domain-name-management/0-the-domain-name-to-access) 文档 |

<br />

| Q20：多个七牛云账号怎么使用同一个一级域名创建二级加速域名？                                                 |
| ------------------------------------------------------------------------------- |
| 每个账号新域名接入都要完成1次接入验证的，这个只能将之前的TXT解析修改成现在需要认证的 TXT记录值了，另外，完全相同的域名不能多次绑定           |
| 也就是 1.iiiii5.cn 可以在 A账号绑定 ， 2.iiiii5.cn 可以在 B账号绑定，在 A账号绑定 1.iiiii5.cn 不能在B 账号绑定 |

<br />

| Q21：流量护盾告警通知不支持按拦截状态过滤                                     |
| ---------------------------------------------------------- |
| 流量护盾本身不能按“已拦截就不通知、只有必要时才通知”这样区分发送，邮件是否频繁主要还是由告警规则和接收人配置决定。 |

如果您希望只发给某个邮箱发送，可以把其他邮箱从告警接收人里移除，并把告警阈值或持续时间调高来减少重复提醒。 |

<br />

| Q22：泛域名删除失败                     |
| ------------------------------- |
| 泛域名删除的前提需要将其下的泛子域名全部删除后才能删除泛域名的 |

<br />

| Q23：CDN域名创建失败，提示源站与加速域名相同，怎么处理？                                    |
| ------------------------------------------------------------------ |
| 这是因为相同域名已经作为自定义源站域名绑定在存储空间了，无法继续作为CDN加速域名绑定，需要您更换一个未绑定过的其他二级或三级域名。 |

<br />

| Q24：配置CDN与空间Referer防盗链配置目前403无法访问？                                |
| ----------------------------------------------------------------- |
| 这是因为CDN与空间Referer配置会冲突导致的403，如果需要Referer防盗链配置的话，单独配置CDN的Refere即可。 |


# 访问下载问题 FAQ (/faq/cdn/3883-download-problem-faq)



最近更新时间: 2026-07-20 11:11:02

| Q1：下载失败，响应非 200 状态码，我应该怎么处理？                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------- |
| 参考文档：[通过 http 状态码，判断下载失败原因](/faq/cdn/other-fusion/problem-diagnosis-method/3885-through-the-http-status-code-download-failure-reason) |

<br />

| Q2：怎样实现视频链接只能播放，不能下载？                                                                                                                                                                                                                                |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 播放其实就是一种形式的下载，所以只能播放不能下载是实现不了的，但我们可以用一些方式去避免别人下载：  <br />方法 1 ：可以开启域名 [时间戳防盗链](/faq/cdn/domain-name-configuration-problem/1670-timestamp-hotlinking-prevention) ，使得视频链接只在一段时间内可以访问。<br />方法 2 ：用网页播放器播放视频，可以隐藏掉播放链接。虽然链接可以通过抓包获得，但是此方法可以屏蔽掉大部分的小白用户。 |

<br />

| Q3：如何打包下载多个文件？                                                                                      |
| --------------------------------------------------------------------------------------------------- |
| 无法通过一次请求，下载多个文件，但是可以用 [mkzip](/products/dora/file-processing/4-mkzip) 命令，在云端将多个文件打包，然后直接下载该 zip 文件。 |

<br />

| Q4：下载速度太慢，如何解决？                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 下载速度慢一般有以下几种情况：  <br />1.使用七牛测试域名。七牛的测试域名有单 IP 访问次数和带宽的限制，更换自定义的 CDN 加速域名，可以解决。<br />2.用户本地的 DNS 设置有问题，跟本地出口 IP 不属同省同运营商，可以绑定公有dns服务器223.5.5.5 114.114.114.114 后，再进行访问测试。<br />3.创建域名时使用场景选择有误，比如将网页平台的域名用作视频点播。这种情况需要给七牛提交工单，修改域名使用场景。<br />4.每次访问时URL都携带了随机参数，导致每次访问时CDN都回源拉取资源，导致加载慢的，建议在业务端请求时去除URL中携带的随机参数，或者参考 [缓存配置](/products/cdn/configuration-management-fusion/2-cache-configuration) 配置忽略对应请求参数来处理。<br />5. 客户网络下行带宽较差，可以参考 [网络测试](/faq/cdn/other-fusion/problem-diagnosis-method/1324-mobile-terminal-network-test-tool-android-ios) 检查客户网络情况。<br />6.如果确认客户网络正常，主要是未击中CDN缓存的资源加载慢，可以对相关资源做下 【文件预取】（[控制台预取文件](/products/cdn/2-refresh-the-prefetch-fusion)，[文件预取API](/products/cdn/8-fusion-api-cache-management#P23)) 操作；同时针对不同类型的文件设置核实的[缓存策略](/products/cdn/configuration-management-fusion/2-cache-configuration)。 |

<br />

| Q5：上传前文件的大小和下载的文件大小不一致是什么原因？                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 首先 [刷新 CDN 缓存](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time) ，刷新 10 分钟后，可通过 [检查文件 md5](/faq/cdn/refresh-the-cache-problem/3644-refresh-the-cache-fails-consistency-method-validation-file) 的方式，来看文件和原文件是否一致。 |

<br />

| Q6：为什么浏览器访问文件不是预览，而是直接下载？                                                            |
| ------------------------------------------------------------------------------------ |
| 浏览器会判断文件是否是自己支持预览的格式，如果文件直接下载，说明该浏览器不支持该文件格式。比如 webp 格式的图片，只有 chrome 浏览器支持，其他浏览器不支持。 |

<br />

| Q7：如何实现数据迁移？                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 同一账号、不同区域的数据迁移，可以通过 [跨区域同步功能迁移数据](/faq/cdn/3883-download-problem-faq) 操作。<br />其他情况，可以使用 [qshell](/products/kodo/0-qshell) 工具。先用 qdownload 命令批量下载到本地，再用 qupload 批量上传到另一空间。 |

<br />

| Q8：如何禁止访问某个文件？                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 如果文件是存储在【七牛存储空间】的，您可以调用 [修改文件状态](/products/kodo/rs/11-modify-the-file-status) 接口将对应文件禁用来实现。<br /> &#x2A;*注意：**<br />文件状态禁用后，如需全网生效，需要刷新下CDN缓存（[七牛控制台刷新CDN缓存](/products/cdn/2-refresh-the-prefetch-fusion)，[调用API接口刷新CDN缓存](/products/cdn/8-fusion-api-cache-management#P21)）。 |

<br />

| Q9：CDN域名同时大量并发观看在线视频是否会卡顿？                   |
| -------------------------------------------- |
| 不会，CDN节点默认没有访问速度和带宽限制，视频加载速度主要取决于本地客户端下行带宽大小 |

<br />

| Q10：网站已停止访问CDN域名，为什么还有CDN流量及费用产生？                                                                                                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1、因为CDN域名配置还在CDN节点，客户端还是能正常请求到CDN资源并产生流量；<br /> 2、如果不需要访问CDN的话，需要在七牛控制台将CDN域名 [停用并删除](/products/cdn/the-domain-name-management/1-domain-name-operation#2) 下，CDN域名删除后才会无法请求进来。<br />3、七牛账单存在一天延迟，假如您在昨天删除了CDN域名，在昨天删除域名之前的流量费用，会在今天出账更新，理论上就是今天之后的流量账单才不会继续更新，注意，这个一定要删除了CDN域名后的第2天，流量费用才会保持不变 |

<br />

| Q11：访问资源返回404状态码时，是否会计算CDN流量？ |
| ----------------------------- |
| 会计算，CDN流量统计不区分状态码             |

<br />

| Q12：为什么我文件删除了，还有CDN流量？                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1：文件删除后，需要主动[刷新 CDN 缓存](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time)才可以 <br /> 2: 文件删除后且刷新了缓存，但是文件还有少部分流量，这个是404状态码产生的流量导致，只要客户端在持续请求，就会产生少部分的404响应流量，相比源文件，流量会大幅度降低，可以检查[**CDN详细日志**](/products/cdn/data-statistics-fusion/log-analysis/5-cdn-log-fusion)，看下对应的URL的响应状态码是不是非200的响应。 |

<br />

| Q13：微信小程序中无法访问资源，提示「请在“小程库右上角更多->反馈与投诉”中和开发者反馈。」如何处理？                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 可以先在微信中直接请求资源外链看下是否正常？<br /> 1、直接请求正常，但小程序访问失败，说明CDN是正常的，问题应该在小程序这一层，需要您那边技术排查下小程序问题；<br /> 2、如果直接请求也失败，可以提供下具体错误信息，[提交工单](https://support.qiniu.com/tickets/new-for-person) 反馈技术支持人员进一步排查 |

<br />

| Q14：为什么CDN域名的动态查询请求没有请求源站？                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CDN一般用于静态资源的缓存加速，如果是动态请求的话，建议绑定 [全站加速](/products/dcdn/0-dcdn-guide-to-the-console) 域名来访问；如果源站同时存在动态和静态资源请求，可以参考 [缓存配置](/products/cdn/configuration-management-fusion/2-cache-configuration) 文档对静态资源设置缓存时间，最后设置一个全局不缓存来处理。 |

<br />

| Q15：为什么CDN域名在中国大陆区域访问很慢？                                                                                                                                                                                  |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是您选择了海外覆盖范围导致的，可以参考 [如何自主切换域名覆盖范围？](/faq/cdn/7456-seven-cattle-console-switch-how-autonomous-domain-coverage) 去核实确认下域名覆盖范围，如果需要中国大陆区域访问的话，需要修改为中国大陆区域覆盖。如果确认域名覆盖范围已经是中国大陆了，可以参考「Q4：下载速度太慢，如何解决？」 进一步排查。 |

<br />

| Q16：为什么无法访问，返回403？                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 403一般是域名配置了referer、ip、ua、时间戳、回源鉴权等防盗链策略 或 存储空间是私有空间导致的，可以通过以下步骤排查确认<br />1、参考 [访问控制配置](/products/cdn/configuration-management-fusion/access-control-configuration) 检查是否触发CDN防盗链策略拦截导致的？<br />1、参考 [设置Referer防盗链](/products/kodo/kodo-console-guide/bucket-management/space-settings/4-set-the-referer-hotlinking-prevention) 检查是否触发存储referer策略导致的？<br />3、参考 [设置访问控制](/products/kodo/kodo-console-guide/bucket-management/space-settings/0-set-access-control) 检查空间是否是私有的？是的话，需要生成 [下载凭证](/products/kodo/development-guidelines/security/0-download-token) 才可以访问。 |

<br />

| Q17：为什么视频无法播放、加载慢或黑屏？                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1、无法播放或黑屏：一般是视频编码格式浏览器不支持或视频本身存在异常导致的，可以通过 [avinfo](/products/dora/audio-and-video-processing-api/2-audio-and-video-metadata-information-avinfo) 命令查询视频元信息和编码格式；<br /> a、如果 avinfo 命令返回 `{"error":"unknown format"}` 错误，说明视频本身存在异常导致的，需要您检查上传前的原视频情况；<br /> b、如果 avinfo 命令返回正常，返回视频编码格式是h265的，由于h265视频编码格式浏览器端支持度不高，建议转换为h264的视频编码格式；可以使用网上第三方工具转码 或 在七牛创建 [转码任务](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/2-task) 处理；<br /> 2、加载慢：一般是视频moov元信息后置或视频码率太大导致，可以通过 [avinfo](/products/dora/audio-and-video-processing-api/2-audio-and-video-metadata-information-avinfo) 命令查询码率信息；moov元信息位置查询可以使用 `ffprobe -v trace 视频文件外链 2>&1 \| grep -E "moov\|mdat"` 命令查询，如果 moov 出现在 mdat 之后 说明 moov 后置了。<br />解决方法：<br />1)、您可以调用「普通音视频转码」[/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 接口，进行转码，转码命令：avthumb/mp4 即可把元信息提前，这样可以加快资源播放。<br /> 2)、控制台操作转码：<br /> a）、新建工作流模板，参考[文档](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template#1) 「工作流模板」-「新建新建工作流」-「工作流节点配置」 -「添加普通转码」（选择预设 「SYSTEM\_MP4\_COPY」） - 「添加输出」- 点击「保存」<br /> b）、使用第1步创建的工作流模板，新建任务，参考[文档](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/2-task#3「任务管理」-「新建任务」-「选择输入文件」)(需要转码的视频文件) - 「选择工作流模板」- 点击「确定」提交任务 |

<br />

| Q18：为什么图片在手机端可以加载展示，浏览器不能？                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是图片格式在浏览器端不支持导致的，您可以使用 [imageInfo](/products/dora/image-processing-api/2-pictures-basic-information-imageinfo) 命令查看图片格式；可以将图片格式转换为png、jpg、jpeg等这种浏览器基本都支持的格式；图片格式转换命令参考 [格式转换](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/3-format-conversion) |

<br />

| Q19：无法访问CDN或存储空间资源？                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1、可以先基于 Q1 方法排查看下；<br /> 2、如果无状态码返回，响应超时，建议先确认下本地客户端网络是否正常？可以尝试更换手机流量或其他wifi网络访问测试验证；<br /> 3、ping域名节点返回127.0.0.1地址，一般是本地开启了网络代理导致的，可以关闭本地网络代理后再访问测试；如果本地未开网络代理，可以尝试修改本地dns服务器为223.5.5.5 或 114.114.114.114 公有dns服务器后，重新访问测试；<br /> 4、如果上述方法都无效，可以提供相关错误信息和资源URL等信息，然后 [提交工单](https://support.qiniu.com/tickets) 反馈技术支持人员进一步排查确认 |

<br />

| Q20：CDN域名已配置证书，https还是无法访问？                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1、可以先检查下域名DNS解析是否正确？CDN域名DNS解析配置参考：[CNAME配置](/products/cdn/the-domain-name-management/2-cname-configuration) <br /> 2、域名DNS解析正常，可以参考 [HTTPS配置](/products/cdn/configuration-management-fusion/4-https-configuration) 检查下 TLS版本是否设置太低导致的？可以都勾选提交成功后，再访问测试 <br />![image.png](/docs-assets/faq/cdn/3883-download-problem-faq/Fmxq6Ry-Ljj5o4iMndouAb2Mp1Uv-2811643b0928.webp) <br /> 3、上述检查都正常的话，可以右键打开浏览器检查模式，复现后获取下console和network中的错误信息，可以 [提交工单](https://support.qiniu.com/tickets) 反馈技术支持排查确认。 |

<br />

| Q21：全站加速域名访问504或超时失败，如何处理？                                                                                                 |
| -------------------------------------------------------------------------------------------------------------------------- |
| 一般是源站响应慢或源站异常导致的，建议优先排查确认源站情况；如果确认源站正常，可以 [提交工单](https://support.qiniu.com/tickets) 反馈技术支持进一步排查确认；<br />说明：全站加速默认回源超时时间10s |

<br />

| Q22：https网站下http域名无法正常访问？                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 由于浏览器端安全策略问题，目前Chrome、火狐等浏览器默认会将https协议网站内置http协议URL强制升级为https发起访问，这是浏览器端的处理策略，七牛侧无法控制。处理方式：1、整站降为http协议2、整站升级为https协议，参考文档[https配置](/products/cdn/configuration-management-fusion/4-https-configuration) |

<br />

| Q23：m3u8或mp4的h264编码格式的视频在ios端无法播放，Android正常，是什么原因？                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是由于视频编码等级（Level）过高导致的，可以通过转码将视频编码等级降为Baseline。<br />解决方法：<br />1)、您可以调用「普通音视频转码」[/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 接口，进行转码，转码命令：avthumb/mp4/vcodec/libx264/h264Profile/baseline 即可将编码等级降为Baseline；<br /> 2)、控制台操作转码：<br /> a）、新建工作流模板，参考[文档](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template#1) 「工作流模板」-「新建新建工作流」-「工作流节点配置」 -「添加普通转码」（`选择自定义预设：编码配置 - 编码格式 - 选择H.264，最下面的高级参数 - 编码等级 选择 baseline`，其他参数不动，默认即可） - 「添加输出」- 点击「保存」<br /> b）、使用第1步创建的工作流模板，新建任务，参考[文档](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/2-task#3「任务管理」-「新建任务」-「选择输入文件」)(需要转码的视频文件) - 「选择工作流模板」- 点击「确定」提交任务 |

<br />

| Q24：为什么CDN访问文件时，返回的Content-Type响应头与存储空间不不一样？                                                                                                                                                                                                                                                    |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CDN默认不会修改文件响应头信息，可以参考 [HTTP响应头配置](/products/cdn/configuration-management-fusion/6-the-http-response-header-configuration) 文档看下是否您主动设置了 Content-Type 响应头导致的？是的话，可以删除Content-Type响应头配置，然后 [刷新CDN缓存](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time) 后，再重新访问测试看看 |

<br />

| Q25：http链接访问正常，https链接访问失败？                                                                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是CDN域名未配置https证书或已绑定证书过期导致的。<br />https证书配置参考：[HTTPS配置](/products/cdn/configuration-management-fusion/4-https-configuration)，<br />证书过期处理方式参考 [HTTPS 相关问题 FAQ](/faq/cdn/3887-https-issues-related-to-the-faq) 中的 Q6 处理说明 |

<br />

| Q26：域名访问报错ERR\_NAME\_NOT\_RESOLVED？                                                                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ERR\_NAME\_NOT\_RESOLVED，这个错误意味着 DNS（域名系统）解析失败，即无法将域名转换为对应的 IP 地址。                                                                                                                                                                                              |
| 1、尝试更换 DNS 服务器，例如使用 Google 的公共 DNS（8.8.8.8 和 8.8.4.4）或  223.5.5.5，备用选择 180.76.76.76。（a.在 Windows 上，你可以通过控制面板 -> 网络和共享中心 -> 更改适配器设置 -> 右键点击你的网络连接 -> 属性 -> Internet 协议版本 4 (TCP/IPv4) -> 使用下面的 DNS 服务器地址。b.在 macOS 上，前往系统偏好设置 -> 网络 -> 高级 -> DNS，然后添加新的 DNS 服务器； |
| 2、看下是否是进行了本地host；检查 hosts 文件（通常位于 C:\Windows\System32\drivers\etc\hosts 在 Windows 上，或在 /etc/hosts 在 macOS 或 Linux 上），查看是否有错误的条目将域名映射到错误的 IP；                                                                                                                    |
| 3、切换网络，重新访问看下。                                                                                                                                                                                                                                                  |

<br />

| Q27：文件无法访问，报404 \{"error":"Document not found"}，是什么原因？ |
| ------------------------------------------------------ |
| 是因为文件已被删除导致的，建议去存储空间检查下文件是否还在？                         |

<br />

| Q28：对象存储空间资源支持设置一次性下载凭证吗？                                                                                                                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 不支持，私有空间下载凭证是根据过期时间实现的，有效期内可以多次请求下载。<br />如需实现一次性下载功能，可以将 [空间转换为公开空间](/products/kodo/kodo-console-guide/bucket-management/space-settings/0-set-access-control)，自己实现 [回源鉴权](/products/cdn/configuration-management-fusion/access-control-configuration/2-back-to-the-source-authentication) 策略，然后在CDN域名配置自己的回源鉴权服务地址来实现。 |

<br />

| Q29：为什么访问日志里存在大量 /qiniu\_do\_not\_delete\_\*.gif                             |
| ---------------------------------------------------------------------------- |
| 这类文件 iniu\_do\_not\_delete\_\*.gif是域名修改配置时，各个cdn节点为了检测配置正常下发所进行测试时的测试资源，忽略即可 |


# HTTPS 相关问题 FAQ (/faq/cdn/3887-https-issues-related-to-the-faq)



最近更新时间: 2026-06-08 12:04:02

| Q1: 升级 https，是否影响 http 的访问？                    |
| ---------------------------------------------- |
| 不管是在域名升级 http 的过程中，还是升级 https 后，都不影响 http 的访问。 |

<br />

| Q2: 域名升级 https 后，流量费用有哪些改变？                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 查看七牛官网的 [七牛云价格方案](https://www.qiniu.com/pricing)，点击“CDN ”，可以看到流量计费的规则。<br />其中，https 的域名，不管是用 http 协议访问，还是 https 协议访问，都是按照 https 的标准计费的。<br />如果对费用还有疑问，可以拨打 400-101-8589 转 1 号线销售咨询。 |

<br />

| Q3: 修改CDN或DCDN域名HTTPS配置的密码是什么？                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------ |
| 修改CDN或DCDN域名HTTPS配置的密码为『七牛账号登录密码』，如忘记七牛账号登录密码了，可参考 [重置密码](/faq/account-finance/account-problem/3965-reset-password) 方式重置登录密码后，再重新操作。 |

<br />

| Q4: 如何关闭 http 访问，而不是设置 http 强制跳转 https？ |
| --------------------------------------- |
| 这种不支持，只能开启强制https方式来处理                  |

<br />

| Q5: 如何关闭 https？                                                                                         |
| ------------------------------------------------------------------------------------------------------- |
| 只有证书过期，才可以在控制台，CDN--域名管理--配置--https配置中，关闭https。证书未过期，你在控制台无法直接操作关闭，可以提交工单我们内部处理关闭，注意关闭后https访问会提示证书相关报错 |

<br />

| Q6: 域名证书过期，怎么办？                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 证书域名已过期，您可以在控制台中，将域名降级到http,然后重新选择使用七牛免费证书，一键升级到https即可。或者您也可以上传您的自有证书，然后在HTTPS配置处，替换到您自己的证书即可。具体可以参考[HTTPS配置](/products/cdn/configuration-management-fusion/4-https-configuration) |

<br />

| Q7: 需要使用https,域名怎么升级到https？                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 您可以在控制台中，选择使用七牛免费证书，一键升级到https即可，具体可以参考[HTTPS配置](/products/cdn/configuration-management-fusion/4-https-configuration)。或者您也可以上传您的自有证书，然后在HTTPS配置处，替换到您自己的证书即可。 |

<br />

| Q8: 已经上传自有证书，为什么绑定时无法选择？                                                                                                                                                                                                                                                                                                          |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是自有证书适用域名与需要绑定的域名不匹配导致的。<br /> 比如：<br />1、自有证书适用 [www.qiniu.com](http://www.qiniu.com) 和 qiniu.com，说明该证书只能绑定在www\.qiniu.com 和 qiniu.com这2个域名使用；<br /> 2、自有证书适用 \*.qiniu.com 这种二级泛域名证书，则只能绑定在 test.qiniu.com、123.qiniu.com 这种二级域名上使用，无法绑定在 qiniu.com 主域名、三级子域名（示例：test.123.qiniu.com）或四级子域名(示例：test.123.456.qiniu.com) 等其他其他子域名。 |

<br />

| Q9: 是否支持国密证书绑定？ |
| --------------- |
| 目前暂不支持。         |

<br />

| Q10: 资源可以在浏览器中直接访问，但是在网站里面不能访问？                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 这种情况下，一般有两种情况:<br />第一种情况是资源域名没有设置跨域头，请求被跨域拦截，一般情况下，如果您的源站是七牛存储，默认都是携带跨域头，如果你的源站是您自己的服务器，需要浏览器F12看下，您的CDN请求是否有携带跨域头，如果没有，可以在CDN--域名管理--配置中，添加自定义响应头，Access-control-allow-origin:\* , 参考[HTTP响应头配置](/products/cdn/configuration-management-fusion/6-the-http-response-header-configuration)\<br>第二种情况就是最常见的情况，https网站混用了http的资源，如果您的网站是https的，但是CDN域名是http的话，浏览器默认会禁止加载http的请求，解决方案要么将网站设置为http的，或者将CDN域名升级到https即可。 |

<br />

| Q11: CDN域名证书到期前会通知吗？                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 会通知，CDN域名证书会在证书剩余有效期不足29天、7天、3天、1天和过期后多次发送通知；证书更新完成后就不会发生通知。<br /> `注意：` 需要在 [消息设置](https://portal.qiniu.com/notification/user-setting/basic/product) - `域名证书服务提醒` 设置通知方式和接收人信息。<br />![image.png](/docs-assets/faq/cdn/3887-https-issues-related-to-the-faq/Fpri1pccCeBjSrmn4_9tzjkzxHOX-fb3ee6476df4.webp) |

<br />

| Q12: 给CDN域名“一键申请免费证书时，提示域名不满足免费证书申请条件”，如果处理？                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是您的域名开启了IP黑白名单、referer黑白名单、时间戳防盗链或回源鉴权功能导致的，这种情况无法使用【一键申请免费证书】功能，需要您参考 [手动申请并绑定证书](/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate) 步骤手动申请并配置证书。 |


# 流量异常情况的原因和处理方法 (/faq/cdn/3888-traffic-problems-faq)



最近更新时间: 2026-06-16 15:13:17

| Q1:流量突增、流量明显高于正常业务量，应该如何处理？                                                                                                                                                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1.可以 [下载日志](https://portal.qiniu.com/cdn/log) 进行 [统计分析](/faq/kodo/basic-use-of/1451-how-to-own-space-ip-access-number)。<br />2.可以针对CDN域名，在 [告警服务](/products/cdn/3-cdn-the-alarm-service) 开启配置 告警，当使用量超过您设置的告警值会进行通知。<br />3.如果通过分析，得出流量确实产生于被盗刷或者是被攻击，可以在域名 “防盗链配置” 中，配置防盗链。 |

<br />

| Q2:域名被攻击，为何停用或者删除了域名后，依然还有流量？                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 当域名仍然解析到七牛，七牛对于攻击的请求会给出非 200 的响应，这种响应有通信头的流量的消耗，当攻击频次巨大时，会产生计费的流量。<br />当域名是自定义域名，建议调整解析到 1.1.1.1。若调整解析为空，攻击者可能更换攻击方式，绑定 host 攻击。<br />当域名是七牛提供的域名，需要提交工单联系七牛调整域名解析。 |

<br />

| Q3:为什么使用http下载消耗的却是https流量？                                              |
| ------------------------------------------------------------------------ |
| 域名如果开通了 https，那么统一按照 https 收费。<br />如果有些请求使用 http，可以新增一个专门用来 http 访问的域名。 |

<br />

| Q4:为什么资源删除后依然会产生流量？                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 这个是资源在访问后，会在cdn中生成缓存，下次访问的时候直接会从cdn中加载资源，而不用回源到源站去加载资源，有效缩短加载时间，这个本身就是cdn的优势所在。所以文件删除后需要调用刷新接口去删除cdn的缓存，这样才能保证文件删除后无法继续访问。如何刷新缓存：1. 通过api 接口刷新：[https://developer.qiniu.com/fusion/api/1229/cache-refresh](https://developer.qiniu.com/fusion/api/1229/cache-refresh) 2. 通过portal.qiniu.com 控制台刷新缓存，点击左侧cdn => 刷新预取 |

<br />

| Q5:top内referer为什么有这么多值为：servicewechat.com的请求？             |
| --------------------------------------------------------- |
| 这是正常的来源页统计，表示您的 CDN 资源主要是被 servicewechat.com 页面引用后产生了访问流量 |

servicewechat.com和\*.servicewechat.com为微信小程序侧的referer值|


# 域名已经做解析如何通过验证 (/faq/cdn/3890-domain-name-already-how-do-parsing-by-verifying)



最近更新时间: 2026-08-21 11:31:16

# 域名解析方法 [#域名解析方法]

解决方法：在验证域名前加上 `_dnsauth`。

以 jsdemo.gugaobai.top 为例，如果做了 A 记录解析或者 cname 解析，有些域名商是不可以同时再做 TXT 解析的
此时解析 \_dnsauth.jsdemo.gugaobai.top 这个域名也可以通过验证

<img src="/docs-assets/faq/cdn/3890-domain-name-already-how-do-parsing-by-verifying/FhkyxbjBaqWbkIe4hSUsf4PXnXzp-7cbad5b2d1f1.webp" width="800" />

<br />

证书签发后可以下载至本地使用

<img src="/docs-assets/faq/cdn/3890-domain-name-already-how-do-parsing-by-verifying/FmM6dXiGoEt5JV9rlNd5eMkpIs29-f7dbe0b385fd.webp" width="800" />

# 文件验证方法 [#文件验证方法]

### 1. 补全证书信息时选择文件验证 [#1-补全证书信息时选择文件验证]

<img src="/docs-assets/faq/cdn/3890-domain-name-already-how-do-parsing-by-verifying/FqWeQfcgd88sakOv5oA8CFj-ulAa-fa659bc85be5.webp" width="800" />

### 2. 获取验证信息 [#2-获取验证信息]

<img src="/docs-assets/faq/cdn/3890-domain-name-already-how-do-parsing-by-verifying/FtqdhfSBolTtKNhHGw6hAzx0kiA9-3a4df6c40243.webp" width="800" />

### 3. 本地生成一个名为 fileauth.txt 的文件，内容为上面的txt记录值 [#3-本地生成一个名为-fileauthtxt-的文件内容为上面的txt记录值]

<img src="/docs-assets/faq/cdn/3890-domain-name-already-how-do-parsing-by-verifying/Fq611qROCWzUcyE8Hcu_kEns9RIj-66a512ff1939.webp" width="800" />

### 4. 上传至域名对应的七牛空间（或者用户自己的服务器），设置前缀为记录名（如 .well-known/pki-validation/） [#4-上传至域名对应的七牛空间或者用户自己的服务器设置前缀为记录名如-well-knownpki-validation]

<img src="/docs-assets/faq/cdn/3890-domain-name-already-how-do-parsing-by-verifying/FnaDaIjTkFFOYfa6mXS705OvFFap-f2d10f6fb714.webp" width="800" />

### 5. 确认文件上传成功 [#5-确认文件上传成功]

<img src="/docs-assets/faq/cdn/3890-domain-name-already-how-do-parsing-by-verifying/FhQrSm6KUTtMSDbA2WUuX8q184iF-569e686529ce.webp" width="800" />

<img src="/docs-assets/faq/cdn/3890-domain-name-already-how-do-parsing-by-verifying/FlNY4XOIFd5MJJsbpZpfzaSgjU7A-d91cec41c540.webp" width="800" />


# SSL 证书 FAQ (/faq/cdn/3905-ssl-certificate-faq)



最近更新时间: 2026-08-19 11:01:37

| Q1: 为什么我无法上传自有证书或证书上传后不可用？                                       |
| ---------------------------------------------------------------- |
| 证书有效期需要≥30天，少于30天的证书是不能用于七牛 CDN 的。                               |
| `注意：自有证书必须是CA机构签发；Cloudflare平台签发证书只能用于Cloudflare平台，无法用于七牛或其他平台。` |

<br />

| Q2：如何上传自有证书？                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1、建议您在证书厂商下载证书时，选择 Nginx 服务器类型的证书文件；                                                                                                                                                     |
| 2、进入七牛云管理控制台：[https://portal.qiniu.com/certificate/ssl，点击](https://portal.qiniu.com/certificate/ssl，点击) 【上传自有证书】；                                                                        |
| 3、使用编辑器打开后续文件，并复制 .crt 或者 .pem 后缀的文件内容到证书内容 （公钥），复制 .key 后缀结尾的内容到 证书私钥；                                                                                                                  |
| 4、如果需要把域名升级为 HTTPS 或者修改证书 的话，需要按照以下步骤绑定证书即可：[/products/cdn/configuration-management-fusion/4-https-configuration](/products/cdn/configuration-management-fusion/4-https-configuration) 。 |

<br />

| Q3: 我申请了七牛的 SSL 证书，为何申请 SSL 证书一直待确认，有时候需要好几天？                                                                           |
| ----------------------------------------------------------------------------------------------------------------------- |
| 在证书订单页面，点击订单最后的 “详情” ，确定验证流程是否配置完成。<br />当选择 DNS 验证方式，域名除 TXT 记录外，还有 A 记录、cname 记录等记录类型，验证是不会通过的。这种情况需要重新提交订单，选择文件验证方式。 |

<br />

| Q4: 因为解析冲突，我不能选择 DNS 验证方式；因为服务器不支持 .well-known 这种目录，文件验证不能通过，我如何通过验证呢？                                            |
| ----------------------------------------------------------------------------------------------------------------- |
| 参考文档：[域名已经解析如何通过验证](/faq/cdn/3890-domain-name-already-how-do-parsing-by-verifying)\<br>文档中的第一种方法，可以解决两种情况同时存在的问题。 |

<br />

| Q5: 为什么申请 SSL 证书失败呢？                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------- |
| CA 中心验证的过程是完全黑盒的，具体失败原因无法得知。从经验看，原因有以下几种可能性：<br />1. 网站所有人与证书申请人姓名不同。<br />2. 域名中含有 “非法” 字符，比如域名中不能有 test 。<br />3. 域名涉及非法信息 / 被举报 / 被 CA 中心添加黑名单。 |

<br />

| Q6: 为什么申请 SSL 免费证书配置时间很长？                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------- |
| 通常情况下证书会在配置在 1-2 小时内颁发并完成配置，期间域名访问不受影响，部分配置不可修改。但证书颁发受 CA 中心的影响，证书颁发时间不可控，若较长时间仍未配置完成，另外建议检查下，域名是否存在CAA解析记录，如果域名存在CAA解析记录，会导致证书签发失败，任务处理延时。 |

<br />

| Q7: 证书到期了可以自动续费吗？                                |
| ------------------------------------------------ |
| 证书到期现在不支持自动续费，需要重新购买新的证书，完成验证，证书签发后部署到CDN进行替换即可。 |

<br />

| Q8: 免费证书到期后，续费报错：\[400600] 前置订单未完成，请稍后重试点击查看 ，如何处理？                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------- |
| 免费证书到期后，不需要续费，您重新申请购买新的免费证书即可。参考文档：[如何申请并使用免费证书](/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate) |

<br />

| Q9: 证书申请失败，存在CAA或DS记录                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 证书在CA机构签发的时候，会发起证书域名验证轮询，域名如果存在CAA或DS解析记录，那么就无法完成验证。需要去域名控制台，删除域名下的CAA或DS类型的解析，也就是去DNS服务商或者域名供应商（如华为云、阿里云、Cloudflare等），配置CNAME解析或者A记录解析的地方，删除多余的CAA或DS记录解析 |

<br />

| Q10: 续费SSL证书生效时间问题 |
| ------------------ |
| 从购买日开始算的，不是叠加计算    |

<br />

| Q11: 如何下载SSL证书？                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------ |
| 在七牛控制台 - 证书管理 - [我的证书](https://portal.qiniu.com/certificate/ssl#cert) 界面找到需要下载的证书，点击 「下载」 ，文件格式默认是zip压缩文件，本地自行解压即可 |

<br />

| Q12: 为什么在七牛已配置证书，访问还是提示不安全？                                          |
| -------------------------------------------------------------------- |
| 一般是域名解析不在七牛这边导致的；建议去域名购买商平台或域名DNS托管商平台确认下解析配置信息，然后去域名解析所在厂商更新对应域名证书。 |

<br />

| Q13: 证书提交后，域名所有权验证未通过，如何处理？                                                                                                                                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1、 如果您选择的是DNS验证方式：需要您去域名购买商平台根据七牛提供的验证解析信息，添加一条证书TXT验证解析记录；<br /> `注意：如果有相同主机记录的TXT解析记录，直接修改对应的记录值为最新的即可`；<br /> 2、如果您选择的是文件验证方式：需要下载验证文件，并将验证文件上传到申请证书的域名所在服务器或七牛存储空间中，文件名与七牛提供的 验证文件路径（文件名示例：.well-known/pki-validation/fileauth.txt） 保持一致。 |

<br />

| Q14: 免费证书提交申请后，域名所有权验证通过，为啥一直处于验证审核中？                                                                                              |
| ---------------------------------------------------------------------------------------------------------------------------------- |
| 域名所有权验证通过后，CA会自动轮询签发证书，一般需要15-30min左右会自动签发证书，耐心等待即可。如果长时间未审核通过，您可以提供证书订单号和域名 [提交工单](https://support.qiniu.com/tickets) 反馈技术支持核实确认。 |

<br />

| Q15: 自有证书支持API上传和部署么？                                                                                                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 支持，SSL证书上传API参考：[证书管理](/products/cdn/9-fusion-api-cert-management) 文档；<br /> `注意：上传的自有证书必须是Nginx版本的`<br /> 1、如果是CDN域名的话，证书上传后，可以调用CDN的API接口更新对应域名证书，域名升级为https接口参考：[开启 HTTPS](/products/cdn/5-fusion-api-domain-config#P26)，更新HTTPS协议域名证书接口参考：[修改 HTTPS 配置](/products/cdn/5-fusion-api-domain-config#P27) |
| 2、如果是存储空间绑定的自定义源站域名，目前暂时没有API接口，只能手动在控制台配置绑定，操作参考：[开启HTTPS访问](/products/kodo/kodo-console-guide/bucket-management/kodo-domain-name-management/1-set-the-custom-source-domain-name)                                                                                                                        |

<br />

| Q16: 2年期证书为什么自动续费失败了？                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------ |
| 一般是您修改了之前七牛提供的2年期证书验证解析配置导致的，可以先去域名购买商或DNS托管商那边确认并恢复之前的验证解析配置，然后再 [提交工单](https://support.qiniu.com/tickets) 反馈技术支持确认并处理。 |

<br />

| Q17: 付费证书续费时，是否支持复用旧证书的CSR？ |
| --------------------------- |
| 支持，续费时可以粘贴旧的CSR提交订单。        |


# CDN 命中率、回源率常见问题 (/faq/cdn/4080-the-common-problems-in-the-cdn)



最近更新时间: 2021-09-23 18:15:40

# CDN 命中率如果较低的原因是什么？ [#cdn-命中率如果较低的原因是什么]

1. 源站动态资源较多，多为不可缓存的内容，也会导致频繁回源拉取。

2. 资源访问量较低，文件热度不够，CDN 收到请求较少无法有效命中缓存。

3. 缓存配置不合理，缓存时间过短，CDN 节点频繁回源。

4. 访问资源的 URL 带参数，并且参数不断变化，当用不同的 URL 去访问 CDN 的时候，CDN 会认为这是一个新请求（即便这两个不同的 URL 其实是访问到了同一个文件，并且该文件已经缓存在节点上），会回源去拉取所请求的内容。

# CDN 什么情况下会回源拉取资源？ [#cdn-什么情况下会回源拉取资源]

1. 用户访问时，如节点上无缓存，则会回源拉取资源

2. CDN 节点上的文件超时过期，会回源拉取资源

3. 若为不缓存文件，用户访问时，会直接回源

4. 未忽略 URL 参数域名，使用该形式域名带参数访问资源，会直接回源

# 为什么我的回源流量比较高？ [#为什么我的回源流量比较高]

当回源率较低时，大部分资源会回源拉取，产生回源拉取流量。特别的，如果每个资源都会带随机参数或者全局缓存为0s，此时命中率接近0，回源流量大大增加。


# SSL 证书续费操作流程 (/faq/cdn/4153-ssl-certificate-renewal-process)



最近更新时间: 2026-04-29 16:37:14

在七牛购买的证书，支持进行续费操作，续费后将生成一个新证书订单，需要针对新生成的证书订单，进行补全信息及证书验证的操作，等待证书签发后，本次续费操作完成。

1.登录 [七牛管理控制台](https://portal.qiniu.com/create) ，在左侧点击 [SSL 证书服务](https://portal.qiniu.com/certificate/ssl)，找到待续费的证书订单，点击续费。
 <img src="/docs-assets/faq/cdn/4153-ssl-certificate-renewal-process/FlpXSWXiH7vJbgtByHbADJuJQzmd-c4383c9b0937.webp" width="800" />

2.提交订单后，会提示您进行证书信息补全：
  <img src="/docs-assets/faq/cdn/4153-ssl-certificate-renewal-process/Fl1YnAdK5Dxox_zhjiOnteKPE-r1-48ffe42902c5.webp" width="500" />
 如果您提交订单后跳过了这个按钮，后续也可以在订单页面找到这个证书，点击进行补全。
  <img src="/docs-assets/faq/cdn/4153-ssl-certificate-renewal-process/FmZq_IiwpmBnhgB-Y_xjPdMm0gr-09471f79fa1d.webp" width="800" />

3.补全信息完成后，您需要完成证书的验证配置。
 您可以在`订单详情`中获取证书的验证信息，如果您申请的是免费DV证书，您可以参考文档[**免费证书验证指南**](/products/ssl/operation-guide/1-ssl-certificate-of-free-dns-validation-guide)
 <img src="/docs-assets/faq/cdn/4153-ssl-certificate-renewal-process/FoqM2pSph8xmBVCQskjEdRQE9jBx-9e414e95c7cf.webp" width="600" />

4.证书配置成功且订单签发后，您需要在「CDN」-「域名管理」-「配置」页面，修改「HTTPS配置」，选择下拉框中可选证书，点击提交即可更换CDN域名的绑定证书。
  <img src="/docs-assets/faq/cdn/4153-ssl-certificate-renewal-process/FnABqLz16VOF4wInaPQrNkgIOb09-86b00aa69f50.webp" width="400" />


# 文件预取的意义和操作方法 (/faq/cdn/4155-the-significance-of-file-prefetching-and-operating-methods)



最近更新时间: 2026-04-29 16:34:46

# 文件预取的意义 [#文件预取的意义]

文件预取，也可称为预加热或预缓存，是指新资源提前由 CDN 拉取到 CDN 缓存节点。这样一来，用户第一次访问到该节点时，就可以直接命中缓存，无需重新回源拉取，由此提高用户第一次访问的速度。

# 提交预取请求的三种方法 [#提交预取请求的三种方法]

1. 在 [七牛管理控制台](https://portal.qiniu.com) 左侧产品列表中找到 CDN ，进去后点击 [刷新预取](https://portal.qiniu.com/cdn/refresh-prefetch) ，选择 **文件预取**。
   按要求填写需要预取的  URL，点击提交即可。

<img src="/docs-assets/faq/cdn/4155-the-significance-of-file-prefetching-and-operating-methods/Ftpll14b0XGDtvc3WYo-c87eJNaI-9b39bb69bf64.webp" width="800" />

2. 使用工具
   使用七牛云提供的 [qshell](/products/kodo/0-qshell) 命令行工具，参考使用文档，先设置密钥，然后执行  [cdnprefresh](https://github.com/qiniu/qshell/blob/master/docs/cdnprefetch.md) 命令来预取。
3. 通过API 接口提交预取请求：
   七牛各服务端的 [SDK](/sdk-tools/sdk#official-sdk) 都提供了预取的方法。
   另附：[预取接口文档](/products/cdn/8-fusion-api-cache-management)

**`注：`** 提交预取请求后 **10 分钟** 左右，预取全网生效。


# 如何开启域名强制 https 访问？ (/faq/cdn/4175-how-to-open-the-domain-name-mandatory-https-access)



最近更新时间: 2026-04-29 15:00:01

登录 [七牛管理控制台](https://portal.qiniu.com/create) ，在 [CDN - 域名管理界面](https://portal.qiniu.com/cdn/domain)，找到需要开启强制 https 的域名，点击 **配置**：
![image.png](/docs-assets/faq/cdn/4175-how-to-open-the-domain-name-mandatory-https-access/FtW_3N6sFYW8cp3smAw9FY72wUmR-63ba06feeb60.webp)

下拉弹窗，找到 HTTPS 配置 ，点击 **修改配置**：
![image.png](/docs-assets/faq/cdn/4175-how-to-open-the-domain-name-mandatory-https-access/FkTHuIldT8g9dsSRvI8SocvU8eq4-69201a778d5f.webp)

点击 **开启** 强制 HTTPS：
![image.png](/docs-assets/faq/cdn/4175-how-to-open-the-domain-name-mandatory-https-access/Fpd8TVoQn3c8tiEsEH6FZgugS3aQ-9aef1a5386f0.webp)


# 镜像存储刷新缓存方法 (/faq/cdn/4215-image-storage-refresh-the-cache-method)



最近更新时间: 2018-05-10 10:13:11

当镜像源的文件更新（或删除）后，刷新 CDN 缓存的方法有以下两种：

1. 首先将空间中该资源删除；
   然后按照 [刷新缓存的方法](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time) 文档第一条介绍的方法，提交刷新缓存请求。
2. 首先，利用 <a href="/products/kodo/rs/6-prefetch">prefetch 接口</a> 或者 [qshell](/products/kodo/0-qshell) 工具的 <a href="https://github.com/qiniu/qshell/blob/master/docs/prefetch.md?ref=developer.qiniu.com">prefetch 命令</a> 将镜像源站的资源覆盖空间中相同名称的资源；
   然后按照 [刷新缓存的方法](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time) 文档第一条介绍的方法，提交刷新缓存请求。


# 网站公安备案和查询流程 (/faq/cdn/5992-the-web-site-public-security-registration-process)



最近更新时间: 2019-07-26 11:47:56

# 如何查询公安备案信息 [#如何查询公安备案信息]

一、打开 \[全国公安机关互联网安全管理服务平台]\([http://www.beian.gov.cn/portal/index)。](http://www.beian.gov.cn/portal/index\)。) 对首次登录系统的用户，系统会自动弹出提示信息，提示您先填写开办主体信息。
二、\*\*查询方式\*\*：在未登录网站情况下点击页面上方的\`公共查询\`，如下图所示： ![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/Ftl0bIWYUoW2bM1UErrg-6Tg2OzV-0beb4b0d937c.webp)
可分别根据网站名称、网站域名、公安机关备案号来查询是否已经存在备案信息，查到显示如下页面： ![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/FqMZLglKPbVkyD32vnONUr9_K6u9-cdcc7cb83d28.webp)

# 网站公安备案流程 [#网站公安备案流程]

# 一、用户登录、注册 [#一用户登录注册]

打开 \[全国公安机关互联网安全管理服务平台]\([http://www.beian.gov.cn/portal/index)，点击\\\`联网备案登录\\\`，填写用户名、密码及验证码即可登录。](http://www.beian.gov.cn/portal/index\)，点击\\`联网备案登录\\`，填写用户名、密码及验证码即可登录。) ![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/ForsBR5Ri0Ucye7HunnLPFeMCj4g-3dd8f63e1d07.webp)
如果尚未注册，可点击\`注册\`，填写密码是注意至少八位并为“\`字母\`+\`数字\`+\`特殊符号\`”的组合。 ![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/Fiou6prHYuNT63RXc2p1agZfaujw-62785d8f2ccf.webp)

# 二、开办主体管理 [#二开办主体管理]

\*\*开办主体申请\*\*： 对于首次备案的用户，必须首先填写主办单位及负责人的真实有效信息，只有提交了主体信息后，才能在该主体下进行网站备案。开办主体性质分为个人和单位。 点击左侧菜单\`开办主体管理\`您需要根据实际情况选择自己的开办主体性质并正确填写各项信息（\*\*注：录入主体信息时所填写的信息必须真实、合法，才能审核通过，顺利完成备案。\*\*）填写完成后点击\`保存\`，公安民警审核后您会收到短信通知，也可在系统消息中查看审核结果，一般审核时间为3-5个工作日。
\*\*开办主体性质-个人\*\* ![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/Fk_Z9nfh9KaSWNZpQBu7eBp4HX3X-1160b2d5ebb2.webp)
\*\*开办主体性质-单位\*\* ![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/FuT_q0LsDHdJYhn6_eHwrNnODZ5O-d1c0e9263664.webp) ![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/FngMMhleW8Fgjmn-l658OwUP7xeI-5f2ed7913674.webp)
\*\*填写注意事项\*\*： 1. 上传的证件图片需要清晰，大小在400KB以内; 1. \*\*单位名称\*\*：形式上应完整填写网站主办者全称，如个人应填写个人姓名，企业应填写工商营业执照注册公司名称。内容应真实准确，不得以域名或数字等符号或以网站名称信息代替网站主办者信息; 1. \*\*单位性质\*\* ：应与主办单位名称等信息对应一致，如主办单位名称为某某公司，则单位性质应为企业;如主办单位为张三，则单位性质应为个人; 1. \*\*证件号码\*\*：应符合相应的格式要求，且与主办单位性质等信息（企业、事业单位、政府机关、军队、社会团体、个人等）对应一致。如主办单位性质为企业，不应填写军队代号或个人身份证等号码等非工商营业执照号码或非组织机构代码证号码; 1. \*\*投资或主管单位\*\*：网站所属者为企业、事业单位、社会团体、政府机关、军队填写法人姓名或单位最高负责人姓名; 1. \*\*负责人常住地\*\*：内容真实准确，格式标准完整。例如，农村单位应详细填写到村，城镇单位应填写到街道门牌号或信箱号; 1. \*\*办公电话\*\*：务必填写。号码应格式标准、内容真实准确，不得出现“010-00000000”等明显不真实的联系方式。

# 三、新办网站备案申请 [#三新办网站备案申请]

点击左侧菜单\`新办网站申请\`，根据要求填写真实合法的信息，填写完成后，点击\`提交\`等待公安民警审核，一般审核时间为3-5个工作日 >注：务必按照要求填写，否则将被退回 >
\*\*第一步：网站开办主体，已经提交申请或审核已经通过，直接点击\`下一步\`即可；\*\* ![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/FpJfw3_IJfBwo1bF9f1eqftHfzkZ-1c00e2403a89.webp)

***

\*\*第二步：网站基本信息填写\*\* ![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/FsXNbgQASJn_hCeoSQhLUMMq4bBP-eef429f32bf5.webp) ![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/FmcxNee7N5VAoE1wu4GGkA3A648f-c19fdead4446.webp)
\*\*填写注意事项：（务必按照要求填写，否则将被退回）\*\* >注: 您的网站在不涉及前置审批，请不要在选项内容中打勾；如果没有您的网站服务内容，就无需选择。 > 1. \*\*网站名称\*\*：应与其主办单位性质等信息对应一致。如主办单位性质为个人的网站，不得以“某某有限公司”等与其主命名；不得以域名作为网站名称。主办单位性质为非政府机构或非政府授权机构的网站，不得以“某某市人民政府”、“某某监察”等公共事务关键字命名；主办单位性质为非国家级单位的网站，不得以“中国”“中华”“维权”等字头命名。无新闻（省委宣传部获得前置审批）、出版（省出版局获得前置审批）、教育（省教育厅获得前置审批）、卫生（省卫生厅获得前置审批）、药监（省食品药品监管局获得前置审批）、文化（省文化厅获得前置审批）、广电（省广电厅获得前置审批）等前置审批或专项审批的网站，不得以相关领域。关键词命名。如未经新闻管理部门前置审核同意的，不得以“新闻网”命名；未取得电子公告专项审批的，不得以“论坛”命名。含有bbs的域名视为论坛，需到省通信管理局办理电子公告专项备案。新增ICP备案操作手册新增ICP备案操作手册（一）：增 1. \*\*网站服务类型\*\*：单位可选择单位门户网站，个人可选择博客/个人空间，如有其他类型内容可如实勾选。 1. 如果您的虚拟主机只对应一个IP，可以填写同一个IP地址；如果对应多个如实填写起止IP即可。
\*\*第三步：网站负责人信息填写\*\* 如果网站负责人信息/信息安全负责人信息/舆情引导员信息与开办人主体负责人信息相同直接打钩即可自动填充，如果不同则根据实际情况分别填写。 ![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/FulOZ6n4ne4D_DLt2pFxbnPO2zNm-23f5159b2cee.webp)
\*\*填写注意事项：\*\* \*\*负责人姓名\*\*：应填写真实姓名全称，不得填报“王先生”、“李小姐”、“个人”或者加带数字或字母的姓名等明显不真实的姓名。
\*\*第四步：提示说明\*\* 请认真阅读，如果没有异议，勾选“我已阅读信息网络安全保护方案”点击\`提交\`， 公安民警会在3-5个工作日给已反馈，反馈的信息将以短信形式通知，也可登录网站在系统消息中查看。 ![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/Fh6cc6bQVRj9H4YKnrfWH4t64Xn5-c3d96a28bc99.webp)
\*\*特别注意：\*\* 非交互式网站初步审核完成后即完成备案，交互式网站需要进行面审或实地检查，具体时间将以短信告知。 如收到公安机关面审通知，请按照短信通知的时间携带所需证件到公安机关进行材料完整性检验； 如收到公安机关实地审核通知：请按照通知的时间做好准备，配合公安民警进行安全检查。
\*\*第五步：发放备案号\*\* 在完成以上审核以后，公安机关将会发放公安部备案号，您需要将备案号放置网站首页下端 ；您可以将网站备案代码放置在网站上，获取代码方法：在已备案网站中查看网站详情，点击\`复制备案号\`即可获得备案代码。
![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/FoeR7jS6A7G3QYKzmHeNMODiYoUc-0d0becccb2be.webp)
![](/docs-assets/faq/cdn/5992-the-web-site-public-security-registration-process/FsTTv1Ka2PlIJXWSEsNxK7tnDqrW-133701059e20.webp)


# ICP备案流程 (/faq/cdn/6000-the-icp-registration-process)



最近更新时间: 2019-08-02 16:57:55

# 为什么要备案 [#为什么要备案]

根据工信部《互联网信息服务管理办法》（国务院 292 号令），网站在未完成备案之前，不能指向大陆境内服务器开通访问。如果你的网站托管在中国大陆节点服务器，就必须申请互联网内容提供商 (ICP) 备案。若网站服务器为非中国大陆节点，则不用申请备案。
1\. 对于单纯的资讯性并且不涉及直销的网站，需要申请 ICP 备案。ICP 备案可通过网站托管服务器提供商或网络空间服务商（如电信、移动、联通等）进行申请。 你可以在服务器提供商的备案系统提交 ICP 备案申请。如果你使用的是七牛云主机，请登录\[七牛云合作备案系统]\([https://portal.qiniu.com/qvm/beian?ref=developer.qiniu.com)提交备案申请。](https://portal.qiniu.com/qvm/beian?ref=developer.qiniu.com\)提交备案申请。) 七牛云 ICP 备案操作可分为：\[首次备案]\(/products/qvm/section-fpr5/0-qvm-first-guide)、\[接入备案]\(/products/qvm/section-fpr5/4-qvm-access-registration)、\[变更备案]\(/products/qvm/section-fpr5/3-qvm-change-record)、\[新增网站备案（原备案不在七牛云）]\(/products/qvm/section-fpr5/2-qvm-new-site) 和 \[增加网站备案（原备案在七牛云）]\(/products/qvm/section-fpr5/1-qvm-record-users)。 \*\*注：\*\*根据 2016 年最新要求，网站在工信部备案成功后，需在网站开通之日起 30 日内提交\[公安备案]\(/faq/cdn/5992-the-web-site-public-security-registration-process)申请。
2\. 对于商品或服务的在线平台或第三方卖方，需获得商用许可证。要申请经营性 ICP 许可证，你必须先有一个有效的 ICP 备案号。经营性备案需用户自己到当地管理局相关部门进行办理，服务商可协助提供资质以及接入协议。具体办理要求需你登录当地经营性备案网站进行查看。

# 备案准备 [#备案准备]

为节约备案时间，建议你提前做好备案准备。因各省管局要求不同，准备资料也有不同，请你访问\[工信部备案管理系统]\([http://www.beian.miit.gov.cn/)了解备案省市的备案规则准备备案资料。](http://www.beian.miit.gov.cn/\)了解备案省市的备案规则准备备案资料。) \* \*\*域名\*\* 域名所有者必须与备案主体\*\*一致并且已实名。\*\* 自 2018 年 1 月 1 日起，从事互联网信息使用的域名应为其依法依规注册所有，个人性质备案域名注册者应为本人，单位性质备案域名注册者应为单位（含公司股东）、单位主要负责人或高级管理人员。具体要求，请查看\[工业和信息化部关于规范互联网信息服务使用域名的通知]\([http://www.miit.gov.cn/newweb/n1146285/n1146352/n3054355/n3057709/n3057714/c5930543/content.html?spm=a2c4g.11186623.2.3.mFjsgs)。备案时会验证域名所有者和备案主办单位名称，网站域名所有者与网站备案主办者需一致。如果你的域名所有者与主办单位不一致，请先更改域名所有者信息。](http://www.miit.gov.cn/newweb/n1146285/n1146352/n3054355/n3057709/n3057714/c5930543/content.html?spm=a2c4g.11186623.2.3.mFjsgs\)。备案时会验证域名所有者和备案主办单位名称，网站域名所有者与网站备案主办者需一致。如果你的域名所有者与主办单位不一致，请先更改域名所有者信息。) \* \*\*备案资料\*\* 最新彩色营业执照正本、彩色法人的身份证正反面照片、公司座机、法人手机、网站负责人手机、公司邮箱、网站负责人幕布照（幕布运营商会在备案过程中邮寄）、域名证书（找域名注册商提供）等。 \*\*注：\*\*网站打开情况：网站在备案期间不能访问，要处于关闭状态。 \* \*\*工信部备案查询\*\* 若主办单位或个人证件（即备案主体）及网站域名都未进行过工信部备案，则为\*\*首次备案\*\*。先确认是否为首次备案，方便后续正确提交信息。 1. 打开\[工信部备案网站]\([http://www.beian.miit.gov.cn/)主页，单击\\\`公共查询\\\`。](http://www.beian.miit.gov.cn/\)主页，单击\\`公共查询\\`。) ![](/docs-assets/faq/cdn/6000-the-icp-registration-process/FoTKSbIibwBch-cdtAn3zJQ5N5N4-4c4a8447aee0.webp) 2. 输入网站域名或公司主体及验证码，单击\`提交\`，若为空白结果则为首次备案。 ![](/docs-assets/faq/cdn/6000-the-icp-registration-process/FvXziu8KkvZD4FkcIbeONp5nWOW1-d15a2e332bfb.webp)

# ICP备案流程图 [#icp备案流程图]

![](/docs-assets/faq/cdn/6000-the-icp-registration-process/FkSJGBJft-ubYS8ZNcKNeEf80hEh-6cd61ccdcc54.webp)

# 自主报备 [#自主报备]

## 登录企业侧备案系统 [#登录企业侧备案系统]

1\. 打开\[工信部备案部级系统]\([http://www.beian.miit.gov.cn/)或住所所在地省局系统网站（入口：工信部主页-->管局系统),如下图所示。](http://www.beian.miit.gov.cn/\)或住所所在地省局系统网站（入口：工信部主页-->管局系统\),如下图所示。) 2. 在“自行备案导航”栏目输入\`接入商所在省\`，\`接入商名称\`及\`验证码\`，单击\`进入\`。
![](/docs-assets/faq/cdn/6000-the-icp-registration-process/FtxE7IjyhHoCok6ULX7_dhdowF7A-4f45faf7cfa9.webp) ![](/docs-assets/faq/cdn/6000-the-icp-registration-process/Frf-1DAVdC2XGzSw9T4rou7euZKC-8f7142263c40.webp)
4\. 获取接入服务的企业名单\*\*（只能选择一个接入服务商）\*\*，单击\`某一接入商名称\`打开企业侧备案系统办理网站备案业务。 ![](/docs-assets/faq/cdn/6000-the-icp-registration-process/FhPbk8LIBduhS-ylEmxHD1BHuhx-c35c42ce08d2.webp)

## 提交信息 [#提交信息]

登录到企业侧备案系统后-->\*\*填写\*\*备案信息-->接入服务商\*\*校验\*\*所填信息并\*\*反馈\*\*。 ![](/docs-assets/faq/cdn/6000-the-icp-registration-process/FnPoBjJrq-rQvzfhLYHu2c8fIw0-247a62fe391c.webp)

# 由接入服务商代为提交 [#由接入服务商代为提交]

网站主办者\*\*委托\*\*接入服务商代为报备网站的全部备案信息并核实信息真伪-->接入服务商\*\*核实\*\*备案信息-->提交到\*\*省管局系统\*\*。 如果你使用的是七牛云主机，可登录\[七牛云合作备案系统]\([https://portal.qiniu.com/qvm/beian?ref=developer.qiniu.com)提交备案申请。具体步骤，请参考\\\[首次备案指南\\](https://portal.qiniu.com/qvm/beian?ref=developer.qiniu.com\)提交备案申请。具体步骤，请参考\\\[首次备案指南\\)]\(/products/qvm/section-fpr5/0-qvm-first-guide)。

## 接入服务商核实备案信息流程： [#接入服务商核实备案信息流程]

1\. 接入服务商对网站主办者提交的备案信息进行当面核验：当面采集网站负责人照片； 2. 依据网站主办者证件信息核验提交至接入服务商系统的备案信息； 3. 填写《网站备案信息真实性核验单》。 \* 如果备案信息无误，接入服务商提交给省管局审核； \* 如果信息有误，接入者在备注栏中注明错误信息提示后退回给网站主办者进行修改。

# 省通信管理局审核 [#省通信管理局审核]

网站主办者所在地省管局对备案信息进行审核 \* 审核不通过，则退回企业侧系统由接入服务商修改； \* 审核通过，生成的备案号、备案密码（并发往网站主办者邮箱）和备案信息上传至部级系统，并同时下发到企业侧系统，接入服务商将备案号告知网站主办者。


# 常见问题 - 未备案冻结域名 (/faq/cdn/6292-common-problems-for-the-record-to-freeze-the-domain-name)



最近更新时间: 2026-04-29 15:24:20

# 简介 [#简介]

 在域名备案被工信部吊销后，七牛将会对您的域名进行冻结，本文列出了部分您可能需要了解的问题。
<font color="#4671D5"><a href="#Q0">Q：未备案冻结的域名如何解冻？</a></font>
<font color="#4671D5"><a href="#Q1">Q：如何查询备案？</a></font>
<font color="#4671D5"><a href="#Q2">Q：域名之前备案过了还会因为未备案冻结？</a></font>
<font color="#4671D5"><a href="#Q3">Q：备案吊销后如何处理？</a></font>
<font color="#4671D5"><a href="#Q4">Q：某些工具可以查询到备案，但还是被冻结了？</a></font&#x3E;
 
 如果本文仍然无法解决您的问题，您也可以通过 &#x2A;*[工单系统](https://support.qiniu.com/tickets/new)** 将您的问题反馈给我们。

<a id="Q0" />

***

# Q：未备案冻结的域名如何解冻？ [#q未备案冻结的域名如何解冻]

 备案完成后，可以先在「&#x2A;*[域名信息备案管理系统](http://beian.miit.gov.cn/publish/query/indexFirst.action)**」查询备案是否已经公示，确认已经公示后，在 **七牛管理控制台** 页面选择 [**CDN**](https://portal.qiniu.com/cdn/overview) ，选择 [**域名管理**](https://portal.qiniu.com/cdn/domain) ，点击您需要解冻域名后的 **解冻** 字样，即可发起解冻任务。备案完成后，工信部一般会延迟1个工作日左右进行公示，解冻域名将以实际公示情况为准。

<a id="Q1" />

<img src="/docs-assets/faq/cdn/6292-common-problems-for-the-record-to-freeze-the-domain-name/FhsUaiNoFtg-BNcHtVbxEqq34GdM-e38da3c0f359.webp" width="900" />

# Q：如何查询备案？ [#q如何查询备案]

 您可以通过「[**域名信息备案管理系统**](http://beian.miit.gov.cn/publish/query/indexFirst.action)」对备案信息进行查询。
 查询方式：左侧「公共查询」-「备案查询」-「备案信息查询」，在网站域名处输入您的备案主域名，正确验证码后点击提交，如果域名没有备案信息，会提示`「没有符合条件的记录」`。

<a id="Q2" />

<img src="/docs-assets/faq/cdn/6292-common-problems-for-the-record-to-freeze-the-domain-name/FoezLDYDG7V8oo-o76o0P11FAE3t-071a26427bb6.webp" width="800" />

# Q：为什么域名之前备案过了还会被未备案冻结？ [#q为什么域名之前备案过了还会被未备案冻结]

<a id="Q3" />

 备案吊销是指对备案信息做收回并注销，由有管辖权力的部门停止原来准许进行某项活动的对象停止该项活动并收回准许文本的执行过程，一般带有强制性。起因基本是由于该对象违背或违反了发放文本时的约定所致，七牛检测到备案信息失效后，会对域名执行冻结操作。

# Q：备案吊销后如何处理？ [#q备案吊销后如何处理]

<a id="Q4" />

 确认备案被吊销后，您可以在原域名备案处，重新进行备案。

# Q：某些工具可以查询到备案，但还是被冻结了？ [#q某些工具可以查询到备案但还是被冻结了]

 网络上的备案查询工具都有一定的延迟，需要以工信部官网的公示结果为准，查询方式参考「<font color="#4671D5"><a href="#Q1">如何查询备案</a></font>」。


# 账单问题 - 存储CDN回源流出流量 (/faq/cdn/6358-bills-storage-cdn-back-to-the-origin-of-traffic)



最近更新时间: 2019-12-11 17:40:10

# 问：账单中「标准存储CDN回源流出流量」是什么含义？ [#问账单中标准存储cdn回源流出流量是什么含义]

答：
下图为CDN访问的简化流程图，后续步骤号码将对应流程图中标号。

<img src="/docs-assets/faq/cdn/6358-bills-storage-cdn-back-to-the-origin-of-traffic/FlzgLWCIX8jz_s2Ua41TjYP-HzAN-d4c5903ca8d8.webp" width="800" />

## 场景1：CDN节点「**没有缓存**」时，需要回源站拉取资源并缓存，访问步骤为： [#场景1cdn节点没有缓存时需要回源站拉取资源并缓存访问步骤为]

1： 客户访问端发送访问请求到CDN节点。
2： CDN节点进行回源，发送请求到七牛云存储。
3： 七牛云存储返回数据给CDN节点。
4： CDN节点缓存数据，并由CDN返回数据给客户端。
计费说明：该过程中，产生的计费项目为流程 3 产生的**存储CDN回源流出流量** + 流程 4 产生的**CDN访问流量**。

## 场景2：CDN节点「**有缓存**」时，访问步骤为： [#场景2cdn节点有缓存时访问步骤为]

1： 客户访问端发送访问请求到CDN节点。
4： CDN节点返回数据给客户端。

计费说明：该过程中，产生的计费项目为流程 4 产生的**CDN访问流量**。所以，并不是每次请求都会产生这两项计费。如果CDN有缓存没有进行回源，就不会产生**存储CDN回源流出流量**。

***

# 问：如何区分 存储CDN回源流出流量 和 CDN访问流量 呢？ [#问如何区分-存储cdn回源流出流量-和-cdn访问流量-呢]

答：**存储CDN回源流出流量**是由七牛的存储机房流出的流量（流程3），**CDN访问流量**是由CDN节点流出的流量（流程4）。

***

# 问：为什么账单中 存储CDN回源流出流量 比 CDN访问流量 还高呢？ [#问为什么账单中-存储cdn回源流出流量-比-cdn访问流量-还高呢]

答：CDN回源流出流量高的可能原因有

1. 业务主要是视频业务，但是创建域名时域名场景选择了网页平台，下载时边下边播，回源时完整回源，导致即使只观看一小部分，也会产生完整的回源流量费用。`建议空间可以绑定不同域名，视频业务使用点播平台域名播放`，域名场景不影响使用，但会针对特定场景有一定的优化。
2. 资源访问时，如果`每次都带了不同的query参数`，或者`把缓存时间设置非常小`，会导致强制CDN节点回源，所以每次访问都会产生了**存储CDN回源流出费用**。

***

# 问：可以关闭存储CDN回源流出流量吗？ [#问可以关闭存储cdn回源流出流量吗]

答：不能，CDN节点至少需要有1次回源拉取行为才能完成缓存，在此过程中存储产生的流量都需要进行计费。


# 常见问题 - CDN功能咨询 (/faq/cdn/6389-function-of-consulting-the-faq)



最近更新时间: 2026-06-09 10:51:51

# 简介 [#简介]

 七牛默认使用 CDN 域名访问存储资源，如果您正在使用 CDN 产品，可能会涉及到资源的缓存/预取问题，本文列出了部分您可能需要了解的问题列表。
<font color="#4671D5"><a href="#Q1">Q1：CDN 是否支持 websocket 加速？</a></font>
<font color="#4671D5"><a href="#Q2">Q2：CDN 是否支持 HTTP2 访问？</a></font>
<font color="#4671D5"><a href="#Q3">Q3：微信小程序要求的 TLS 版本必须大于等于1.2怎么处理？</a></font>
<font color="#4671D5"><a href="#Q4">Q4：CDN 访问的链接长度限制是多少？</a></font>
<font color="#4671D5"><a href="#Q5">Q5：CDN 支持 指定端口访问 吗？</a></font>
<font color="#4671D5"><a href="#Q6">Q6：CDN 支持 海外访问加速 吗？</a></font>
<font color="#4671D5"><a href="#Q7">Q7：CDN 有带宽限制吗 ？</a></font>
<font color="#4671D5"><a href="#Q8">Q8：测试域名有使用限制吗 ？</a></font>
<font color="#4671D5"><a href="#Q9">Q9：测试域名能恢复吗？ </a></font>
<font color="#4671D5"><a href="#Q10">Q10：没有域名或者域名还没有进行ICP备案，可以使用CDN加速吗？ </a></font>
<font color="#4671D5"><a href="#Q11">Q11：域名使用场景可以修改吗，小文件场景和下载场景都能用吗？ </a></font>
<font color="#4671D5"><a href="#Q12">Q12：已经创建的域名可以修改名称吗？ </a></font>
<font color="#4671D5"><a href="#Q13">Q13：CDN支持中文域名以及中文转义域名吗？ </a></font>
<font color="#4671D5"><a href="#Q14">Q14：CDN支持gzip或者br压缩吗？ </a></font>
<font color="#4671D5"><a href="#Q15">Q15：CDN支持配置流量带宽上限、qps访问限制、UA黑名单、单链接访问限速吗？ </a></font>
<font color="#4671D5"><a href="#Q16">Q16：空间上绑定的域名默认就有CDN加速吗，不要加速可以吗？ </a></font>
<font color="#4671D5"><a href="#Q17">Q17：买CDN资源包可以提速吗，怎么让CDN更快？ </a></font>
<font color="#4671D5"><a href="#Q18">Q18：CDN可以对服务器上部署的网站加速吗？ </a></font>
<font color="#4671D5"><a href="#Q19">Q19：CDN支持配置自定义请求头吗？ </a></font>
<font color="#4671D5"><a href="#Q20">Q20：CDN支持短链接吗？ </a></font>
<font color="#4671D5"><a href="#Q21">Q21：CDN支持对某个资源访问做限制吗？ </a></font>
<font color="#4671D5"><a href="#Q22">Q22：七牛提供域名吗？ </a></font>
<font color="#4671D5"><a href="#Q23">Q23：七牛CDN域名支持配置HSTS么？ </a></font>
<font color="#4671D5"><a href="#Q24">Q24：全站加速支持根据目录配置缓存吗？ </a></font>
<font color="#4671D5"><a href="#Q25">Q25：域名所有权验证失败，如何处理？ </a></font>

 
 如果本文仍然无法解决您的问题，您也可以通过 &#x2A;*[工单系统](https://support.qiniu.com/tickets/new)** 将您的问题反馈给我们。

<div id="Q1" />

| Q1: CDN 是否支持 websocket 加速？ |
| -------------------------- |
| 暂不支持 websocket 加速。         |

<br />

<div id="Q2" />

| Q2: CDN 是否支持 HTTP2 访问？                            |
| ------------------------------------------------- |
| 支持，在 控制台 - CDN - 域名管理 中，修改 https 配置可以开启 http2 访问。 |

<br />

<div id="Q3" />

| Q3: 微信小程序要求的TLS版本必须大于等于1.2怎么处理？                          |
| -------------------------------------------------------- |
| 域名需要先开启 HTTPS，然后开启 HTTP 2 功能，HTTP 2.0 默认使用 TLS1.2 及以上版本。 |

<br />

<div id="Q4" />

| Q4: CDN 访问的链接长度限制是多少？          |
| ------------------------------ |
| URL 参数限制为 750 字节内，暂时无法支持更长url。 |

<br />

<div id="Q5" />

| Q5: CDN或全站加速 支持指定端口访问吗？                                           |
| ----------------------------------------------------------------- |
| CDN 域名仅支持默认的 80/443 端口访问，不支持自定义端口访问；但是 CDN 配置回源时，支持回源到您的服务器的指定端口。 |
| DCDN全站加速 域名仅支持默认的 80/443 端口访问，不支持自定义端口访问，且 全站加速 回源配置时，也不支持指定端口。   |

<br />

<div id="Q6" />

| Q6: CDN 支持 海外访问加速 吗？                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CDN可以配置海外加速，在CDN -- 域名管理 -- 配置 -- 覆盖范围中，设置海外或者全球加速线路，即可支持海外节点加速访问，修改覆盖范围参考[这里](/faq/cdn/7456-seven-cattle-console-switch-how-autonomous-domain-coverage) |

<br />

<div id="Q7" />

| Q7: CDN 有带宽限制吗？                                                                                       |
| ----------------------------------------------------------------------------------------------------- |
| CDN默认无带宽限制，如果您的带宽达到10Gbps，建议您可以[提交工单](https://support.qiniu.com/tickets/new)或者通过您的商务联系我们，提前报备，预留充足资源。 |

<br />

<div id="Q8" />

| Q8: 测试域名有使用限制吗 ？                                                                   |
| ---------------------------------------------------------------------------------- |
| 测试域名限制比较多，测试域名无法修改，无法进行https配置，默认忽略全部参数缓存，默认只有30天使用期限，到期自动回收，单日限制10GB回源流量。         |
| 更多限制您参考[测试域名使用规范](/faq/cdn/other-fusion/1319-test-domain-access-restriction-rules) |

<br />

<div id="Q9" />

| Q9: 测试域名能恢复吗？  |
| -------------- |
| 测试域名一旦删除，无法恢复。 |

<br />

<div id="Q10" />

| Q10: 没有域名或者域名还没有进行ICP备案，可以使用CDN加速或者访问吗吗？                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------- |
| CDN加速必须绑定域名，没有域名无法使用CDN加速，根据工信部要求，凡是使用CDN国内加速的，必须拥有ICP备案，使用海外CDN暂时无法备案，但是必须要有域名，没有域名的话，您可以先去域名供应商处购买域名，七牛没有域名售卖，测试域名也不会售卖的。 |

<br />

<div id="Q11" />

| Q11: CDN 选错了应用场景可以修改吗，不同的场景有什么区别，都能用吗？                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 已创建完成的域名，无法修改使用场景，不同的场景都可以使用，不同的是图片小文件适合js 图片等文件快速访问，下载平台适合zip、dmg、apk等大文件下载分发，点播平台适合视频文件分发，基本都是可以使用，详细介绍您参考[使用场景说明文档](/products/cdn/3-usage-scenarios-fusion)，如果您一定要修改使用场景，需要您[提交工单](https://support.qiniu.com/ticket/new)联系我们。 |

<br />

<div id="Q12" />

| Q12: 已经创建的域名可以修改名称吗？                       |
| ------------------------------------------ |
| 已经创建的域名不可以修改名称，需要重新创建新的域名，已创建的域名只能修改域名的配置。 |

<br />

<div id="Q13" />

| Q13: CDN支持中文域名以及中文转义域名吗？ |
| ------------------------ |
| CDN不支持中文域名以及中文转义域名       |

<br />

<div id="Q14" />

| Q14: CDN支持gzip或者br压缩吗？                                                                                               |
| -------------------------------------------------------------------------------------------------------------------- |
| CDN控制台当前不支持配置gzip压缩，需要源站支持。源站如果是七牛存储空间，存储源站默认支持gzip压缩，源站如果是您的服务器，需要您服务器支持gzip压缩，CDN会将客户端的gzio压缩请求透传到您源站，需要源站响应压缩后的内容 |

<br />

<div id="Q15" />

| Q15: CDN支持配置流量带宽上限、qps访问限制、UA黑名单、单链接访问限速吗？                                         |
| ---------------------------------------------------------------------------------- |
| CDN当前只支持 IP黑白名单，UA黑白名单，时间戳防盗链，回源鉴权以及referer防盗链5种防御方式，流量带宽上限、qps访问限制以及单链接访问限速都是不支持的 |

<br />

<div id="Q16" />

| Q16: 空间上绑定的域名默认就有CDN加速吗，不要加速可以吗？                                               |
| ------------------------------------------------------------------------------ |
| 空间上绑定的域名默认就有加速效果，如果不要加速，只能绑定成源站域名，源站域名在空间设置--域名管理中，绑定自定义源站域名，自定义源站域名没有加速，没有缓存。 |

<br />

<div id="Q17" />

| Q17: 买CDN资源包可以提速吗，怎么让CDN更快？                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 资源包只是抵扣账单使用，和CDN下载速度没有任何关系。                                                                                                                                                |
| CDN下载速度主要取决于本地的下行带宽，本地独占下行带宽越高，CDN下载速度越快，一般如果本地带宽达到100-200Mbps，理论下载速度会在7MB/s \~ 20MB/s。避免出现跨境访问的情况，如果域名是纯海外加速，国内访问，或者域名是国内加速但是在海外访问，会出现访问慢的情况，建议调整域名覆盖范围，将域名设置成同境访问或者全球加速。 |
| 如果您的速度只有2-3MB/s，且本地带宽正常，没有跨境访问的情况，您可以[提交工单](https://support.qiniu.com/ticket/new)联系我们协查。                                                                                   |

<br />

<div id="Q18" />

| Q18: CDN可以对服务器上部署的网站加速吗？                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CDN可以配置域名回源，源站不是七牛存储，直接回源您的服务器，对服务器上的站点进行整体加速，DCDN也是可以支持对服务器网站进行加速，详情可以参考[域名回源](/faq/cdn/domain-name-configuration-problem/4064-understanding-and-setting-up-the-way-back-to-the-source-host) |

<br />

<div id="Q19" />

| Q19: CDN支持配置自定义请求头吗？ |
| -------------------- |
| CDN不支持配置自定义请求头。      |

<br />

<div id="Q20" />

| Q20: CDN支持短链接吗？                    |
| ---------------------------------- |
| CDN不支持配置短链接，建议您将文件名设置短一点，或者不使用中文名。 |

<br />

<div id="Q21" />

| Q21: CDN支持对某个资源访问做限制吗？ |
| ---------------------- |
| 不支持，CDN配置都是针对域名级别的。    |

<br />

<div id="Q22" />

| Q22：七牛提供CDN域名吗？     |
| ------------------- |
| 不提供，需要您自行去域名服务厂商购买。 |

<br />

<div id="Q22" />

| Q23：七牛CDN域名支持配置HSTS么？ |
| --------------------- |
| 暂不支持。                 |

<br />

<div id="Q24" />

| Q24：全站加速支持根据目录配置缓存吗？                                                                                |
| --------------------------------------------------------------------------------------------------- |
| 支持，全站加速支持根据目录、后缀方式配置缓存策略，具体参考 [缓存配置](/products/dcdn/configuration/2-dcdn-cache-configuration) 说明文档。 |

<br />

<div id="Q25" />

| Q25：域名所有权验证失败，如何处理？                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是域名验证解析配置错误或验证文件无法访问导致的；<br /> 1、DNS验证方式：主机记录一般是 verification，且记录值必须是七牛通过的；<br /> 2、文件验证方式：需要在主域名下保证能访问到，[http://主域名/verification.html](http://主域名/verification.html) 文件且响应内容与七牛提供一致。<br /> 域名所有权验证说明文档参考：<br /> 全站加速域名： [域名归属校验](/products/dcdn/2-domain-verify-introduce) <br /> CDN加速域名： [域名归属校验](/products/cdn/4-cdn-domain-verify-introduce) |

<br />

<div id="Q26" />

| Q26：域名刚刚创建为什么会产生流量？                  |
| ------------------------------------ |
| 域名创建的时候，会有节点可用性测试，这个测试流量一般非常低，可以忽略的。 |


# 常见问题 - 缓存刷新/资源预取 (/faq/cdn/6390-prefetch-cache-refresh-resources-faq)



最近更新时间: 2026-07-20 10:36:35

# 简介 [#简介]

 七牛默认使用 CDN 域名访问对象存储资源，如果您正在使用 **对象存储 / CDN 产品**，可能会涉及到资源的缓存/预取问题，本文列出了部分您可能需要了解的问题列表。
<font color="#4671D5"><a href="#Q0">Q0：资源已经在源站删除，为什么还能访问？</a></font>
<font color="#4671D5"><a href="#Q1">Q1：资源已经覆盖/重新上传，为什么还能访问到旧文件？</a></font>
<font color="#4671D5"><a href="#Q2">Q2：如何刷新 CDN 缓存？</a></font>
<font color="#4671D5"><a href="#Q3">Q3：刷新文件 和 刷新目录 分别是什么含义？</a></font>
<font color="#4671D5"><a href="#Q4">Q4：刷新 和 文件预取 有什么区别？</a></font>
<font color="#4671D5"><a href="#Q5">Q5：如何强制回源，不读取 CDN 缓存？</a></font>
<font color="#4671D5"><a href="#Q6">Q6：如何修改缓存时间？</a></font>
<font color="#4671D5"><a href="#Q7">Q7：为什么已经上传的文件有时会出现404，等待一段时间就会正常？</a></font>
<font color="#4671D5"><a href="#Q8">Q8：CDN 节点的缓存会实时和源站同步更新吗？</a></font>
<font color="#4671D5"><a href="#Q9">Q9：如何查看刷新任务是否处理成功？</a></font>
<font color="#4671D5"><a href="#Q10">Q10：提交任务报错 \[403023] urls admin submitted belong to more than one user </a></font>
<font color="#4671D5"><a href="#Q11">Q11：为什么刷新任务已经执行成功，还是访问到旧缓存？</a></font>
<font color="#4671D5"><a href="#Q12">Q12：CDN 访问为什么会存在缓存问题？</a></font>
<font color="#4671D5"><a href="#Q13">Q13：CDN缓存刷新和预取额度可以调整吗？</a></font>
<font color="#4671D5"><a href="#Q14">Q14：CDN缓存刷新和预取失败，是什么原因？</a></font&#x3E;
 
 如果本文仍然无法解决您的问题，您也可以通过 &#x2A;*[工单系统](https://support.qiniu.com/tickets/new-for-person)** 将您的问题反馈给我们。

***

<div id="Q0" />

| Q0: 资源已经在源站删除，为什么还能访问？                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 当前访问到了该资源在 CDN 节点的缓存。<br />资源从源站删除之后，缓存仍然会在 CDN 节点保存，所以用户仍然可以访问到，需要刷新 CDN 缓存。<br />说明：如果您使用了七牛的对象存储，默认绑定CDN加速域名，如果需要刷新缓存，请参考文档[刷新缓存的方法](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time) |

<br />

<div id="Q1" />

| Q1: 资源已经覆盖/重新上传，为什么还能访问到旧文件？                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 当前访问到了旧文件在 CDN 节点的缓存。<br /> 在源站某个资源的内容变更之后，旧缓存仍然会在 CDN 节点保存，刷新 CDN 缓存即可重新回源获取资源。<br /> 说明：如果您使用了七牛的对象存储，默认绑定CDN加速域名，如果需要刷新缓存，请参考文档[刷新缓存的方法](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time) |

<br />

<div id="Q2" />

| Q2: 如何刷新 CDN 缓存？                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 刷新缓存方法请参考文档[刷新缓存的方法](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time)                                                                                                                                                                   |
| 方法1:  portal.qiniu.com 控制台刷新缓存，点击左侧 cdn — 刷新预取；<br /> 方法2:  api 接口地址：[https://developer.qiniu.com/fusion/api/1229/cache-refresh](https://developer.qiniu.com/fusion/api/1229/cache-refresh); <br /> 方法3:  qshell命令行工具：[/products/kodo/0-qshell](/products/kodo/0-qshell) |

<br />

<div id="Q3" />

| Q3: 刷新文件 和 刷新目录 分别是什么含义？                                        |
| --------------------------------------------------------------- |
| 缓存刷新分为 刷新文件 和 刷新目录。                                             |
| 刷新文件：是以单条url为单位进行缓存刷新。<br /> 目录刷新：是以目录为单位，将该域名对应目录下的所有文件进行缓存刷新。 |

<br />

<div id="Q4" />

| Q4: 刷新 和 文件预取 有什么区别？                                                         |
| ---------------------------------------------------------------------------- |
| 刷新的含义为清空缓存，预取的含义为主动进行缓存                                                      |
| 刷新后，所有 CDN 节点上对应的资源缓存失效，用户再次触发访问时，CDN 节点将执行回源拉取，刷新操作用于文件更新或删除后，保证用户能访问到最新资源。 |
| 预取后，资源将被主动缓存到 CDN 节点，用户通过 CDN 访问对应预取过的资源时，不需要重复回源，可以提升用户的访问速度。               |

<br />

<div id="Q5" />

| Q5: 如何强制回源，不读取 CDN 缓存？                                                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 由于 CDN 上默认是根据url缓存的，可以在访问链接后加上 ?\<随机数> ，如原始url为 [http://a.com/1.txt](http://a.com/1.txt) ，那么访问 [http://a.com/1.txt?\&lt;随机数字](http://a.com/1.txt?\&lt;随机数字)> 就可以强制进行回源了，如果您的资源更新频率较高，可以在cdn配置中，修改资源的缓存时间。 |
| `注意：`<br /> 1. 使用该方法强制回源的域名不能配置 忽略 URL 参数 ，否则随机数无效。<br /> 2. 随机数也会被缓存，需要强制回源时尽量不使用重复的随机数测试。                                                                                                               |

<br />

<div id="Q6" />

| Q6: 如何修改缓存时间？                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 如果需要部分前缀或后缀文件不缓存，可以在控制台-域名管理中，修改该域名的缓存配置为自定义，根据您的业务需求设置缓存时间，操作参考 [缓存配置](/products/cdn/configuration-management-fusion/2-cache-configuration) 说明文档。<br /> 修改完成后，节点对新的缓存将会依据配置进行，如需清空旧配置情况时已触发的缓存，可以尝试刷新目录缓存。 |

<br />

<div id="Q7" />

| Q7: 为什么已经上传的文件有时会出现404，等待一段时间就会正常？                                     |
| ---------------------------------------------------------------------- |
| 如果在文件上传完成之前触发访问，会报错 404 ，404 默认会缓存 10 秒左右，如果重复请求该资源，会在上传完成后 10 秒内访问正常。 |

<br />

<div id="Q8" />

| Q8: CDN 节点的缓存会实时和源站同步更新吗？                                  |
| ---------------------------------------------------------- |
| CDN 缓存更新依赖主动触发刷新任务，或者根据控制台配置的缓存有效时间，过期后重新回源拉取，默认情况下不会主动更新。 |

<br />

<div id="Q9" />

| Q9: 如何查看刷新任务是否处理成功？                                                          |
| ---------------------------------------------------------------------------- |
| 方法1：可以在控制台 - cdn - 刷新预取 - 操作记录中查看；                                           |
| 方法2：调用CDN的接口查询，文档参考 [刷新查询](/products/cdn/8-fusion-api-cache-management#P22)。 |

<br />

<div id="Q10" />

| Q10: 提交任务报错 \[403023] urls admin submitted belong to more than one user |
| ----------------------------------------------------------------------- |
| 提交刷新/预取任务的域名必须是当前账户在 CDN 域名管理中已经创建的域名，无法刷新其他账户或未创建的域名。                  |

<br />

<div id="Q11" />

| Q11: 为什么刷新任务已经执行成功，还是访问到旧缓存？                                                    |
| ------------------------------------------------------------------------------- |
| 1. 检查本地浏览器缓存是否清空，可以尝试更换浏览器或者无痕模式；                                               |
| 2. 确认下访问 URL 是否携带了其他参数，刷新时是否连带参数进行刷新；                                           |
| 3. https 和 http 部分场景下独立缓存，如果之前刷新的是 https 链接，并且用 http 访问过该资源，可以再尝试刷新 http 的链接试下。 |

<br />

<div id="Q12" />

| Q12: CDN 访问为什么会存在缓存问题？                  |
| --------------------------------------- |
| CDN 服务利用多级缓存原理进行加速，所以通过 CDN 的访问默认都会被缓存。 |

<br />

<div id="Q13" />

| Q13：CDN缓存刷新和预取额度可以调整吗？                                                                                 |
| ------------------------------------------------------------------------------------------------------ |
| 默认刷新额度：每天文件刷新限额 500 个，目录刷新 10 个，文件预取限额 100 个；如需提升，可以提交 [工单](https://support.qiniu.com/tickets) 咨询技术支持。 |

<br />

<div id="Q14" />

| Q14：CDN缓存刷新和预取失败，是什么原因？                                                                                                                                                                                         |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是您的CDN域名配置了全局不缓存（缓存时间为0）导致的，缓存规则配置操作参考 [缓存配置](/products/cdn/configuration-management-fusion/2-cache-configuration);，如果已配置缓存策略，且缓存时间不为0，但刷新或预取还是失败，可以提交 [工单](https://support.qiniu.com/tickets) 咨询技术支持进一步核实确认。 |


# 常见问题 - CDN资源包相关问题 (/faq/cdn/6779-common-problems-cdn-resource-bundle-related-issues)



最近更新时间: 2026-06-17 16:44:46

# 简介 [#简介]

 在官网和控制台，七牛推出了资源包可供购买，本文列出了部分关于CDN资源包您可能需要了解的问题。
<font color="#4671D5"><a href="#Q0">Q0：如何购买资源包？</a></font>
<font color="#4671D5"><a href="#Q1">Q1：如何选择合适的CDN资源包？各选项的含义是什么？</a></font>
<font color="#4671D5"><a href="#Q2">Q2：如何查看资源包余量？</a></font>
<font color="#4671D5"><a href="#Q3">Q3：资源包可以叠加使用吗？抵扣顺序是什么？</a></font>
<font color="#4671D5"><a href="#Q4">Q4：资源包是否可以用于海外CDN加速？</a></font>
<font color="#4671D5"><a href="#Q5">Q5：使用量超出资源包后如何计费？</a></font>
<font color="#4671D5"><a href="#Q6">Q6：今天8点后购买的资源包，为什么没有进行抵扣？</a></font>
<font color="#4671D5"><a href="#Q7">Q7：CDN资源包可以抵扣对象存储的视频资源下载流量吗？</a></font>

 
 如果本文仍然无法解决您的问题，您也可以通过 &#x2A;*[工单系统](https://support.qiniu.com/tickets/new)** 将您的问题反馈给我们。

***

<div id="Q0" />

# Q0：如何购买资源包？ [#q0如何购买资源包]

 限时活动入口： [【CDN特惠五折日间包】](https://marketing.qiniu.com/activity/20200423?entry=index-advert)

 长期活动入口： [【财务中心-购买资源包】](https://portal.qiniu.com/financial/respack/fusion-composite)

<div id="Q1" />

# Q1：如何选择合适的CDN资源包？各选项的含义是什么？ [#q1如何选择合适的cdn资源包各选项的含义是什么]

 购买资源包前，需要了解您的账户CDN业务的使用情况。

## 第一步：CDN域名所属协议（HTTP/HTTPS） [#第一步cdn域名所属协议httphttps]

  在 **管理控制台** 页面选择 [**CDN**](https://portal.qiniu.com/cdn/overview) ，选择 [**域名管理**](https://portal.qiniu.com/cdn/domain) ，查看「协议」，并购买对应的「HTTP/HTTPS」资源包，如下图所示。

注：如果域名协议为HTTPS，通过HTTP/HTTPS访问时产生的流量都计为HTTPS流量。
![image.png](/docs-assets/faq/cdn/6779-common-problems-cdn-resource-bundle-related-issues/FkJSQB8ROG61_YiSfPCnKOhx3dJG-4a32e4c67960.webp)

## 第二步：CDN域名的使用场景（动态/静态） [#第二步cdn域名的使用场景动态静态]

  在 **管理控制台** 页面选择 [**CDN**](https://portal.qiniu.com/cdn/overview) ，选择 [**域名管理**](https://portal.qiniu.com/cdn/domain) ，查看「使用场景」，并购买对应的「静态/动态」资源包。

 静态加速场景：图片小文件/下载分发/点播平台

 动态加速场景：动态加速

 如下图所示。
![image.png](/docs-assets/faq/cdn/6779-common-problems-cdn-resource-bundle-related-issues/Fn9TPPAWMrSl7f5iAjVbQyqEMKd7-7606b1dbfd69.webp)

## 第三步：资源包可用时间(全时段/日间时段/闲时段) [#第三步资源包可用时间全时段日间时段闲时段]

1. 全时段流量包：全时段指每天 0:00 - 24:00
2. 日间时段流量包：日间时段指每天 09:00 - 18:00
3. 闲时流量包：闲时段指每天 00:00 - 09:00
   叠加使用规则和抵扣顺序参考 <font color="#4671D5"><a href="#Q3">资源包可以叠加使用吗？抵扣顺序是什么？</a></font>

## 第四步：CDN域名的使用量 [#第四步cdn域名的使用量]

  在 **管理控制台** 页面选择 [**CDN**](https://portal.qiniu.com/cdn/overview) ，选择 [**统计分析**](https://portal.qiniu.com/cdn/statistics/usage) ，查看「用量统计」，您可以参考近期的流量使用情况，对不同场景/协议下域名的使用量进行估算，选择合适的资源包大小，如下图所示。
![image.png](/docs-assets/faq/cdn/6779-common-problems-cdn-resource-bundle-related-issues/Fia4Oty-iRYZaciPZYFn-7gt3kIB-5e056626826a.webp)

* 1：「已选域名」支持一键筛选 HTTP/HTTPS 协议进行统计。
* 2：CDN资源包支持中国大陆使用，您可以在「计费区域」中选择中国大陆进行筛选。
* 3：所选时间范围内，符合筛选条件的域名产生的总流量。

<div id="Q2" />

# Q2：如何查看资源包余量？ [#q2如何查看资源包余量]

 由于七牛目前按量付费资源采取月结算模式，系统每天8点左右将根据用户已使用的用量进行计费，更新一次实时消费明细，即实时消费明细为预估账单和余额预扣除，没有实际完成扣除，所以默认情况下，资源包的余量需要每个月完成月账单出账后更新状态，我们也可以通过下面的方法预估算资源包的使用情况。

 `资源包剩余大小 = 历史月账单抵扣后剩余 - 本月消费预抵扣大小`

## 第一步：查看历史月账单抵扣后剩余 [#第一步查看历史月账单抵扣后剩余]

  在 **管理控制台** 页面选择 [**财务中心**](https://portal.qiniu.com/financial/overview) ，选择 [**订单管理** - 资源包管理](https://portal.qiniu.com/financial/orders/respack-mgr/current)，点击需要查看的资源包「详情」，进入订单详情后，点击「查看用量详情」。
![image](/docs-assets/faq/cdn/6779-common-problems-cdn-resource-bundle-related-issues/FtMKtdgkRuloeEcyHp-2V7HNhKS6-4be65ef85fef.webp)

 您可以看到上一次月账单结算后资源包的剩余可用量，以及历史月份每次月账单结算后，资源包的抵扣情况。
![image.png](/docs-assets/faq/cdn/6779-common-problems-cdn-resource-bundle-related-issues/FqagpEB2VmfP1PgnjmHRNVxCrWZs-0ba7cca6444d.webp)

## 第二步：查看本月消费预抵扣大小 [#第二步查看本月消费预抵扣大小]

注：实时消费明细 每日8点更新，更新用量的使用时间是截止本日0点，非实时动态更新。

  在 **管理控制台** 页面选择 [**财务中心**](https://portal.qiniu.com/financial/overview) ，选择 [**实时消费明细**](https://portal.qiniu.com/financial/orders)，查看从「上次月账单结算完成后」到「当日0点」的预估账单，参考下图，账单中可以下载「资源包抵扣明细」，抵扣明细中包含本月可用量/当前已用/本月剩余可用等参数。
![image.png](/docs-assets/faq/cdn/6779-common-problems-cdn-resource-bundle-related-issues/FhcjKeaQGrvjfZmVEM1vqL-v-vFo-d095fd7ae578.webp)

## 第三步：预估资源包余量 [#第三步预估资源包余量]

 以上图中的「国内HTTP全时段静态加速流量100G」资源包为例，第一步获取到历史月账单抵扣后剩余96G，第二步中获取到本月HTTP资源包已经抵扣2GB，那么该资源包的余量为：

 资源包剩余大小 = 历史月账单抵扣后剩余 - 本月消费预抵扣大小 = 96GB - 2GB = 94GB

<div id="Q3" />

# Q3：资源包可以叠加使用吗？抵扣顺序是什么？ [#q3资源包可以叠加使用吗抵扣顺序是什么]

 资源包可叠加购买。
 相同资源包出账时将按照资源包过期先后顺序依次抵扣，若当过期时间相同时，根据流量产生时段，在日间时段优先抵扣日间时段资源包，在闲时段优先抵扣闲时资源包，最后抵扣全时段流量包。
 不同类型的资源包抵扣顺序为：
 首先，根据流量的时间判断产生的流量类型为 闲时/日间/全时段 流量，优先抵扣 闲时/日间 流量包，后抵扣 全时段 流量包。
 其次，抵扣实名认证用户每月享有的免费流量额度。
 然后，根据流量包的下发策略「按月分配不结转/按月分配可结转/一次性分配」，优先抵扣 按月分配不结转资源包，再是 按月分配可结转资源包，最后是 一次性分配资源包。
 最后，按照剩余有效期，优先抵扣快过期的资源包。

<div id="Q4" />

# Q4：资源包是否可以用于海外CDN加速？ [#q4资源包是否可以用于海外cdn加速]

 资源包目前仅支持中国大陆范围使用，海外CDN加速暂不支持。

<div id="Q5" />

# Q5：使用量超出资源包后如何计费？ [#q5使用量超出资源包后如何计费]

 在资源包生效期间内，若当月用量超出可用资源包额度，出账时将优先抵扣完资源包额度，超出部分再按照官网 [价格表 - 【CDN】](https://www.qiniu.com/prices)结算。

<div id="Q6" />

# Q6：今天8点后购买的资源包，为什么没有进行抵扣？ [#q6今天8点后购买的资源包为什么没有进行抵扣]

 实时消费明细 每日8点更新，更新用量的使用时间是截止本日0点，非实时动态更新，当月生效的资源包，您可以在购买后第二天，在财务中心查看实时消费明细账单。

<div id="Q7" />

# Q7：CDN资源包可以抵扣对象存储的视频资源下载流量吗？ [#q7cdn资源包可以抵扣对象存储的视频资源下载流量吗]

 1、如果存储空间绑定的是`CDN加速域名，且域名解析配置是CDN加速域名CNAME值`，使用对应CDN域名访问空间资源时，产生的是CDN流量，可以使用CDN资源包抵扣；<br /> 2、如果存储空间绑定的是`自定义源站域名，且域名解析配置的是自定义源站域名CNAME值`，使用对应自定义源站域名访问空间资源时，产生的是外网流出流量，无法使用CDN资源包抵扣，需要购买 [对象存储-外网流出流量资源包](https://qmall.qiniu.com/template/MTEy?spec_combo=MzE0NQ\&ref=index) 才可抵扣。
![image.png](/docs-assets/faq/cdn/6779-common-problems-cdn-resource-bundle-related-issues/FmOPq01ZsWgureyrAtduvvLZg78e-94cf52a3877c.webp)


# 未备案域名访问限制 (/faq/cdn/6885-nocpi-domain-access-restrictions)



最近更新时间: 2026-05-08 16:29:54

七牛 CDN 支持为海外业务客户提供加速服务，但对于未备案域名访问有以下限制。

## 国内 ip 无法访问未备案域名 [#国内-ip-无法访问未备案域名]

对于海外未备案域名，七牛 CDN 可提供在纯海外区域（不含中国大陆）的加速访问；但受到相关监管规则限制，目前国内 ip 默认无法访问未备案的海外加速域名。
如果实际业务需要域名可被国内 ip 访问，建议您在[工信部域名信息备案管理系统](http://beian.miit.gov.cn/state/outPortal/loginPortal.action)进行备案，然后重新将域名配置为全球加速。

<img src="/docs-assets/faq/cdn/6885-nocpi-domain-access-restrictions/FknOmykXxWfhSDBV7rAWPr7So_lC-cde6847326a4.webp" width="800" />

如有其他配置需求，可联系七牛销售进行申请和业务审核。

## 备案吊销情况说明 [#备案吊销情况说明]

原有已备案的纯海外加速域名如果备案被吊销，七牛将同样禁止国内 ip 访问。因此对于有备案的海外加速域名，强烈建议转为全球加速区域。


# 检测到域名源站发生改变，需重新修改回源鉴权配置 (/faq/cdn/7454-detected-domain-source-station-change-need-to-change-back-to-the-source-authentication-configuration)



最近更新时间: 2026-08-27 16:15:24

# 一、提示“检测到域名源站发生改变，需重新修改回源鉴权配置”原因 [#一提示检测到域名源站发生改变需重新修改回源鉴权配置原因]

当“私有空间”切换为“公开空间”时，『七牛控制台』-『CDN』-『域名管理』-『配置』界面提示“**检测到域名源站发生改变，需重新修改回源鉴权配置**”

![](/docs-assets/faq/cdn/7454-detected-domain-source-station-change-need-to-change-back-to-the-source-authentication-configuration/FrlOz7pZBpZtDlaSdEeJT4dzq7sbe-da6388ea602f.webp)

<br />

# 二、如何去掉这行红字？ [#二如何去掉这行红字]

1、找到『回源鉴权』，点击『修改配置』

![image.png](/docs-assets/faq/cdn/7454-detected-domain-source-station-change-need-to-change-back-to-the-source-authentication-configuration/FnUgu0sdS7kHrGkSaY6UO6X3Prrm-413dd0ece9eb.webp)

<br />

2、找到『开启』，点击一下，让其变成『关闭』状态

![image.png](/docs-assets/faq/cdn/7454-detected-domain-source-station-change-need-to-change-back-to-the-source-authentication-configuration/FseAT-iiqF8oDkZDhH7PntzmvMna-5f038f1ed160.webp)

<br />

3、点击『确认』，点击之后，域名会自动处理，一般在 15 - 20 分钟内会处理完成

![image.png](/docs-assets/faq/cdn/7454-detected-domain-source-station-change-need-to-change-back-to-the-source-authentication-configuration/FtSi_wqB9KB5i4JhovXnVOX6xTJ5-264311e94f72.webp)

<br />

> **如果长时间验证不通过，建议拨打 400-101-8589 转 2 号线，联系技术支持处理。**


# 监测到域名源站在七牛私有 BUCKET，建议打开回源鉴权功能 (/faq/cdn/7455-monitoring-the-source-domain-stood-seven-cows-private-bucket-suggested-that-open-source-authentication-function)



最近更新时间: 2026-08-27 16:15:54

# 一、提示“监测到域名源站在七牛私有 BUCKET，建议打开回源鉴权功能”原因 [#一提示监测到域名源站在七牛私有-bucket建议打开回源鉴权功能原因]

当“公开空间”切换为“私有空间”时，『七牛控制台』-『CDN』-『域名管理』-『配置』界面提示“&#x2A;*监测到域名源站在七牛私有 BUCKET，建议打开回源鉴权功能。**”

![image.png](/docs-assets/faq/cdn/7455-monitoring-the-source-domain-stood-seven-cows-private-bucket-suggested-that-open-source-authentication-function/Ft2hh9FL1ouCq8RwRXC0y2z08J6Z-a84b8cc13a7a.webp)

<br />

# 二、如何去掉这行提示？ [#二如何去掉这行提示]

1、找到『回源鉴权』，点击『修改配置』

![image.png](/docs-assets/faq/cdn/7455-monitoring-the-source-domain-stood-seven-cows-private-bucket-suggested-that-open-source-authentication-function/Fqd3Yy1Rtz1y1t9nXaWI_l3JrhY1-4e1be7224868.webp)

<br />

2、找到『关闭』，点击一下，让其变成『开启』状态

![image.png](/docs-assets/faq/cdn/7455-monitoring-the-source-domain-stood-seven-cows-private-bucket-suggested-that-open-source-authentication-function/FnN4BB-u6PaLPaPXoT26lAajMK-N-ff5921684038.webp)

<br />

3、点击『确认』，点击之后，域名会自动处理，一般在 15 - 20 分钟内会处理完成

![image.png](/docs-assets/faq/cdn/7455-monitoring-the-source-domain-stood-seven-cows-private-bucket-suggested-that-open-source-authentication-function/FgqEtfYpTLxB2U3PCm_DwRfClHlE-d0c2dd0e7f7a.webp)

<br />

> **如果长时间验证不通过，建议拨打 400-101-8589 转 2 号线，联系技术支持处理。**


# 如何自主切换域名覆盖范围？ (/faq/cdn/7456-seven-cattle-console-switch-how-autonomous-domain-coverage)



最近更新时间: 2026-08-27 16:15:01

### **自 2020年10月20日 起，『七牛控制台』-『域名管理』目前已支持用户自主切换域名覆盖区域（中国大陆、全球、海外）** [#自-2020年10月20日-起七牛控制台-域名管理目前已支持用户自主切换域名覆盖区域中国大陆全球海外]

<br />

1、在『域名管理』-『配置』界面，点击『修改』按钮
![image.png](/docs-assets/faq/cdn/7456-seven-cattle-console-switch-how-autonomous-domain-coverage/Fg5ZH_FOcS7hjjQ9RHZAUg9ne61K-c966b3ca9e52.webp)

<br />

2、选择好“服务区域”后，点击『确认』，点击之后域名会自动处理，一般在 15 - 20 分钟内会处理完成
![image.png](/docs-assets/faq/cdn/7456-seven-cattle-console-switch-how-autonomous-domain-coverage/Fua-8npi7GFYOnejemLXiU3M4_UO-9f2027ca0786.webp)

<br />

> **注意**
> 以下两种情况暂不支持『七牛控制台』自主切换：
>
> 1. 对于未备案域名不能从海外加速切换至全球或国内
> 2. 特殊计费方式的域名需要联系技术支持说明情况后，由七牛技术支持操作

> **如果长时间验证不通过，建议拨打 400-101-8589 转 2 号线，联系技术支持处理。**


# 如何查询CDN资源访问量？ (/faq/cdn/7457-how-to-query-the-cdn-resource-traffic)



最近更新时间: 2026-04-29 15:09:00

| Q1: 如何查询访问量最大的CDN资源？                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| 可以在 [**七牛控制台 - 访问分析**](https://portal.qiniu.com/cdn/statistics/log/access) 界面查询 top100 资源URL，操作详情参考：[**统计分析**](/products/cdn/data-statistics-fusion) |

<br />

| Q2: 如何查询每个资源的访问量和访问次数？                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 查询每个资源的访问量和访问次数，需要您下载CDN日志，根据CDN日志自己统计分析下。<br />CDN日志下载方式：<br />  1. 在 [**七牛控制台**](/products/cdn/data-statistics-fusion/log-analysis/5-cdn-log-fusion) 下载。<br />  2. 调用 [**API接口**](/products/cdn/10-fusion-api-log-download) 下载。 |


# CDN 下线或冻结域名解析逻辑变更 (/faq/cdn/9268-offline-or-freezing-dns-logical-adjustment)



最近更新时间: 2021-09-23 18:19:58

# 背景 [#背景]

由于近期出现不法分子通过七牛 CNAME 域名传播违规资源的情况，受相关信息监管部门要求，七牛 CDN 将调整用户主动操作下线或欠费冻结后的域名解析逻辑。

# 调整说明 [#调整说明]

2021年10月10日之前，用户主动下线或欠费冻结加速域名后，加速域名会被解析回用户源站。为避免相关合规风险，自2021年10月11日起，&#x2A;*下线或欠费冻结的域名会解析至不可用地址。**
因此，在用户主动下线或欠费冻结之后，将无法通过加速域名访问源站内容。

# 应对方案 [#应对方案]

若希望在域名下线后，可以继续通过加速域名访问源站，可自行修改 DNS 配置，将加速域名的 CNAME 记录指向您的源站即可。
![image.png](/docs-assets/faq/cdn/9268-offline-or-freezing-dns-logical-adjustment/FkdTbkIRsyswhwY-mm-9X12NDtqY-695751a10a2a.webp)


# CDN (/faq/cdn)



## 如何配置域名的 CNAME [#如何配置域名的-cname]

[查看原文](/faq/cdn/4175-how-to-open-the-domain-name-mandatory-https-access)

CNAME的简单介绍，如何在七牛控制台获取 CNAME 解析值，以及如何在域名解析服务商执行 CNAME 解析操作。

## 测试域名使用规范 [#测试域名使用规范]

[查看原文](/products/cdn/the-domain-name-management/0-the-domain-name-to-access)

本文介绍了测试域名的特征和访问限制。

## 刷新缓存的方法 [#刷新缓存的方法]

[查看原文](/faq/cdn/4215-image-storage-refresh-the-cache-method)

提交刷新缓存请求、携带 url 参数刷新和镜像存储刷新缓存的方法和注意事项介绍

## HTTPS 相关问题 FAQ [#https-相关问题-faq]

[查看原文](/faq/cdn/4175-how-to-open-the-domain-name-mandatory-https-access)

HTTP 升级 HTTPS，访问、价格等问题解答

## CDN 节点 IP 的获取方法 [#cdn-节点-ip-的获取方法]

[查看原文](/faq/cdn/4215-image-storage-refresh-the-cache-method)

介绍了获取用户访问到的 CDN 节点 IP 的方法

## 为什么做了 CNAME 解析还是显示请配置 CNAME [#为什么做了-cname-解析还是显示请配置-cname]

[查看原文](/products/cdn/3-cdn-the-alarm-service)

显示 “请配置CNAME” 是域名还没有成功cname解析的状态，本文介绍了cname没有成功解析的几种场景和解决办法。

## 域名配置 FAQ [#域名配置-faq]

[查看原文](/products/cdn/the-domain-name-management/3-the-domain-name-back)

有关域名配置（cname 配置、时间戳防盗链等）的常见问题解答

## 刷新预取 FAQ [#刷新预取-faq]

[查看原文](/products/cdn/2-refresh-the-prefetch-fusion)

刷新,缓存,预取,刷新额度,镜像存储刷新

更多问题请查看 [官网 FAQ](/faq)。


# 内容审核资源包使用方法 (/faq/censor/5702-how-to-check-zyb)



最近更新时间: 2026-05-08 17:16:51

**Q：如何购买内容审核资源包？**
A：购买入口：[https://qmall.qiniu.com/template/MTA5?spec\_combo=MjkzNQ](https://qmall.qiniu.com/template/MTA5?spec_combo=MjkzNQ)

**Q：如何查询内容审核资源包使用情况？**
A：
1.进入财务中心 - 订单列表：[https://portal.qiniu.com/financial/orders/respack-mgr/current](https://portal.qiniu.com/financial/orders/respack-mgr/current)

2.找到对应三鉴资源包，点击详情
![](/docs-assets/faq/censor/5702-how-to-check-zyb/FoiZJvYxbtmu1bIWaPs_NZLy8Fu6-4ab13530c606.webp)

3.在右边名目处，点击「xxx资源包」
![](/docs-assets/faq/censor/5702-how-to-check-zyb/FuOb_lfaql5PNHPsY3kO5e_sf_c5-5aa886aceb32.webp)

4.在详情处可查看截止上个月底的已使用量、余量
![](/docs-assets/faq/censor/5702-how-to-check-zyb/FlXK2veK-Nna0vwLyPAw0sfF-I0j-dddf58915335.webp)

5.进入财务系统 - 实时消费明细，可查看截止今天本月的资源包抵扣量
![](/docs-assets/faq/censor/5702-how-to-check-zyb/Fr9G3CLtPD6OdhrvxN_xHcQnnQz2-bd1ab626a9ee.webp)

6.`总使用量 = 截止上个月底的余量 - 截止今天本月的资源包抵扣量`
比如
截止上个月底的余量 = 45426500张
截止今天本月的资源包抵扣量 = 10615600张
则总使用量 = 45426500 - 10615600 = 34810900张


# 内容审核控制台资源加载失败 (/faq/censor/7178-censor-resource-loading-failure)



最近更新时间: 2020-10-12 17:21:15

![](/docs-assets/faq/censor/7178-censor-resource-loading-failure/Fj3TUkvMKJAbL1b6zZ_K81agVY7O-f084befbb004.webp)

内容审核控制台，在复核时资源加载失败，常见问题及解决办法如下：

**1. Chrome 浏览器用户请检查网站安全设置，允许显示混合内容**
Chrome 80 版本开始，会逐渐屏蔽网站的混合内容（https 网站加载 http 的图片视频资源），如果对应的存储空间不能提供 https 的域名，则需要用户手动允许加载混合内容
操作如下：

点击地址栏右边的锁图标 -> 网站设置 -> 权限 -> 不安全内容 -> 设置为允许

![](/docs-assets/faq/censor/7178-censor-resource-loading-failure/FvVojMoPVzvtsLTW38XfkzLuIBHh-68790814b058.webp)

![](/docs-assets/faq/censor/7178-censor-resource-loading-failure/FkDuqC4hVCSmMENawix4E2BW62lf-da01fd071251.webp)

**2. 检查存储空间是否有可用域名，并且域名可用**
内容审核控制台将通过存储空间设置的可用域名访问资源，**并且优先使用默认域名**

![](/docs-assets/faq/censor/7178-censor-resource-loading-failure/FtjmscnFewqqhwYF-Hvszp1ORp5U-cdcec669f477.webp)

**3. 请检查对应存储空间中的资源是否存在，已删除的资源将无法显示**


# 内容审核 (/faq/censor)



## 内容审核资源包使用方法 [#内容审核资源包使用方法]

[查看原文](/faq/censor/5702-how-to-check-zyb)

介绍内容审核资源包使用方法

## 内容审核控制台资源加载失败 [#内容审核控制台资源加载失败]

[查看原文](/faq/censor/7178-censor-resource-loading-failure)

内容审核控制台资源加载失败，常见问题及解决办法

更多问题请查看 [官网 FAQ](/faq)。


# 接收对象管理-Webhook：如何获取企业微信机器人 (/faq/console/10490-receptionmanagement-wechat)



最近更新时间: 2022-03-28 18:06:00

**1. 在 PC 版企业微信中找到需要接收消息通知的企业微信群。选中并右键单击企业微信群，在弹框中单击【添加群机器人】。**

![image2021-5-14\_16-55-43.png](/docs-assets/faq/console/10490-receptionmanagement-wechat/Fl-CdAQ8LYb7U0GSjVX4IMVXEYzr-b5b2c2504e37.webp)

**2. 在弹框中单击【新创建一个机器人】，自定义机器人名称，填写完后单击【添加机器人】，即可获取webhook地址。**
![image2021-5-14\_16-58-45.png](/docs-assets/faq/console/10490-receptionmanagement-wechat/FpE1lmVB9_DRnQYmXo72g_FYcAhG-ecd740faf3e1.webp)


# 管理控制台 (/faq/console)



# 全站加速 (/faq/dcdn)



暂无已同步的 FAQ 条目。

更多问题请查看 [官网 FAQ](/faq)。


# 云主机 EVM (/faq/evm)



# 智能多媒体服务常见问题 (/faq/dora/13579-smart-multimedia-services-faq)



最近更新时间: 2026-09-24 14:45:13

# 智能多媒体服务常见问题 [#智能多媒体服务常见问题]

## Q: 七牛云的imageMogr2图片参数304缓存生效时imageMogr2是否计费咨询 [#q-七牛云的imagemogr2图片参数304缓存生效时imagemogr2是否计费咨询]

答：不重复计费的情况，如果请求的图片处理参数完全相同，且访问的CDN节点已缓存了该处理结果，则后续重复访问该节点不会再次计费，直接从缓存返回结果。


# 图片鉴黄服务接口协议 (/faq/dora/1406-image-as-a-yellow-service-interface-protocols)



最近更新时间: 2021-07-21 15:15:54

## 请求 [#请求]

### 请求报文格式 [#请求报文格式]

GET \<DownloadURI>?nrop HTTP/1.1
Host: \<DownloadHost>

### 请求头部 [#请求头部]

| 头部名称 | 必填 | 说明                                                                                    |
| ---- | -- | ------------------------------------------------------------------------------------- |
| Host | 是  | 下载服务器域名，可为七牛三级域名或自定义二级域名，参考[域名绑定](/products/cdn/1-custom-domain-name-binding-process) |

***

## 响应 [#响应]

### 响应报文格式 [#响应报文格式]

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

\{
    // ...nrop data...
}

### 响应头部 [#响应头部]

| 头部名称          | 必填 | 说明                         |
| ------------- | -- | -------------------------- |
| Content-Type  | 是  | MIME类型，固定为application/json |
| Cache-Control | 是  | 缓存控制，固定为no-store，不缓存       |

### 响应内容 [#响应内容]

■ 如果请求成功，返回包含如下内容的JSON字符串（已格式化，便于阅读）：

\{
    "code": "\<ResultCode         int>",
    "message": "\<ResultMessage   string>",
    "fileList": \[
        \{
            "rate": \<Rate        float>,
            "label": \<Category   int>,
            "name": "\<FileName   string>",
            "review": \<Review    boolean>
        }
    ],
    "statistic": \[
        \<Statistics              int>,
        ...
    ],
    "reviewCount": \<ReviewCount  int>,
    "nonce": "\<Nonce             string>",
    "timestamp": "\<Timestamp     string>"
}

| 字段名称           | 必填 | 说明                                                                                                                                                         |
| -------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`         | 是  | 处理状态(0：调用成功; 1：授权失败； 2：模型ID错误； 3：没有上传文件； 4：API版本号错误； 5：API版本已弃用； 6：secretId 错误； 7：任务Id错误，您的secretId不能调用该任务； 8：secretId状态异常； 9：尚未上传证书； 100：服务器错误； 101：未知错误) |
| `message`      | 是  | 与`code`对应的状态描述信息                                                                                                                                           |
| `fileList`     | 否  | 鉴别的图片文件列表                                                                                                                                                  |
| `rate`         | 是  | 介于0-1间的浮点数，表示该图像被识别为某个分类的概率值，概率越高、机器越肯定；您可以根据您的需求确定需要人工复审的界限。                                                                                              |
| `label`        | 是  | 介于0-2间的整数，表示该图像被机器判定为哪个分类，分别对应： 0：色情； 1：性感； 2：正常                                                                                                           |
| `name`         | 是  | 鉴别图片文件的文件名                                                                                                                                                 |
| `review`       | 是  | 是否需要人工复审该图片                                                                                                                                                |
| `statistic`    | 否  | 图像机器判定结果统计数组，分别对应判定为0-3的数据总量                                                                                                                               |
| `callRecordId` | 否  | 调用的唯一标识符，用于后续的人工复审的结果反馈                                                                                                                                    |
| `APIVersion`   | 是  | API的版本                                                                                                                                                     |
| `reviewCount`  | 否  | 需要人工复审的图片数量                                                                                                                                                |
| `nonce`        | 是  | 随机数                                                                                                                                                        |
| `timestamp`    | 是  | 当前的服务器的Unix时间，UTC格式时间字符串                                                                                                                                   |

■ 如果请求失败，请参考以上`code`和`message`字段的说明。

## 示例 [#示例]

在Web浏览器中输入以下图片地址：

[http://qiniuphotos.qiniudn.com/gogopher.jpg?nrop](http://qiniuphotos.qiniudn.com/gogopher.jpg?nrop)

返回结果（内容经过格式化以便阅读）

\{
    "code": 0,
    "message": "succeed.",
    "fileList": \[
        \{
            "rate": 0.9558794498443604,
            "label": 2,
            "name": "czfh1cATkoExQ\_AMVyg1zw==.resize",
            "review": false
        }
    ],
    "statistic": \[
        0,
        0,
        1
    ],
    "reviewCount": 0,
    "nonce": "0.31666339887306094",
    "timestamp": "Wed, 06 May 2015 07:42:27 GMT"
}

**另一种方式安装。**

在左边的“添加资源”中，点击下面的“第三方数据处理” > "图片签黄"。

**![00157466c70adc4c151d1b2eb96b3f9](/docs-assets/faq/dora/1406-image-as-a-yellow-service-interface-protocols/00157466c70adc4c151d1b2eb96b3f9-12cbe7d24ad9.webp)**


# 智能多媒体服务 (/faq/dora)



## persistent ID 的常见问题 [#persistent-id-的常见问题]

[查看原文](/faq/dora/other-dora/3643-how-to-acquire-persistent-id)

本文介绍了 persistent ID 的概念、获取方法和使用方法

## avthumb参数formats格式及解释 [#avthumb参数formats格式及解释]

[查看原文](/faq/dora/av-processing/1320-avthumb-parameters-formats-format-and-explanation)

格式及解释介绍

## avthumb参数vcodec格式及解释 [#avthumb参数vcodec格式及解释]

[查看原文](/faq/dora/av-processing/1385-avthumb-parameter-vcodec-format-and-explanation)

格式及解释介绍

## 使用七牛进行视频的剪辑 [#使用七牛进行视频的剪辑]

[查看原文](/products/dora/section-cc46gx/3-video-capture01)

视频剪辑

## avthumb参数acodec格式及解释 [#avthumb参数acodec格式及解释]

[查看原文](/faq/dora/av-processing/1432-avthumb-parameter-acodec-format-and-explanation)

格式及解释介绍

## 视频支持格式 [#视频支持格式]

[查看原文](/faq/dora/av-processing/1455-support-video-format)

列表展示

## 视频文字水印支持字体列表 [#视频文字水印支持字体列表]

[查看原文](/faq/dora/other-dora/11230-image-text-watermarking-support-font-list)

本节列出七牛视频文字水印处理支持的所有字体。

## 关于七牛的流媒体队列 [#关于七牛的流媒体队列]

[查看原文](/products/dora/console-guide/3-the-queue)

流媒体队列功能及使用介绍

更多问题请查看 [官网 FAQ](/faq)。


# 关于53端口默认关闭的说明 (/faq/las/12987-las-faq-port-53)



最近更新时间: 2026-05-06 18:11:31

## **概述** [#概述]

53端口为 DNS（Domain Name Server，域名服务器）服务器所开放，主要用于域名解析，通过 DNS 服务器可以实现域名与 IP 地址之间的转换，只要记住域名就可以快速访问网站。

根据《中华人民共和国电信条例》及《电信业务经营许可管理办法》，开展递归解析服务需要相应的增值电信业务经营许可证，即B26-1互联网域名解析服务业务牌照。因此，如您需要使用七牛云全栈应用服务器向公众提供递归解析服务，开通服务器53端口，需要提供相应增值电信业务经营许可证。

## **常见问题** [#常见问题]

### **1. 什么是互联网域名解析服务？** [#1-什么是互联网域名解析服务]

**互联网域名解析**是实现互联网域名和 IP 地址相互对应关系的过程。
**互联网域名解析服务**是指在互联网上通过架设域名解析服务器和相应软件，实现互联网域名和 IP 地址的对应关系转换的服务。域名解析服务包括权威解析服务和递归解析服务两类。

* 权威解析：指为根域名、顶级域名和其他各级域名提供域名解析的服务。
* 递归解析：指通过查询本地缓存或权威解析服务系统实现域名和 IP 地址对应关系的服务。

其中开展递归解析服务需要获得互联网域名解析服务业务的增值电信业务经营许可证。

### **2. 什么是服务器53端口？** [#2-什么是服务器53端口]

53端口为 DNS（Domain Name Server，域名服务器）服务器所开放，主要用于域名解析。七牛云的全栈应用服务器产品，默认会<u>**封禁53端口的入向访问**</u>。

### **3.53端口的入向访问被封禁对我的服务器会有什么影响？** [#353端口的入向访问被封禁对我的服务器会有什么影响]

如您未进行互联网域名解析服务业务，入向访问禁用53端口对您的服务器、业务不会有影响。

### **4.个人能从事互联网域名解析服务业务吗？** [#4个人能从事互联网域名解析服务业务吗]

电信业务经营者需为依法设立的公司，个人不能从事这项业务，您需要以公司的名义办理相应增值电信业务经营许可证，才能开展互联网域名解析服务业务。

### **5.如何办理“B26-1互联网域名解析服务业务”增值电信业务许可证？** [#5如何办理b26-1互联网域名解析服务业务增值电信业务许可证]

具体办理方式可以咨询您主体所在省通信管理局。

### **6.确实需要提供递归解析服务、且已办理好相关牌照，如何操作解除53端口封禁？** [#6确实需要提供递归解析服务且已办理好相关牌照如何操作解除53端口封禁]

您可以通过[**工单**](https://support.qiniu.com/tickets/new-for-person/form?category=%E5%85%B6%E4%BB%96\&space=%E5%85%A8%E6%A0%88%E5%BA%94%E7%94%A8%E6%9C%8D%E5%8A%A1%E5%99%A8)联系我司、按要求提交相应材料，通过审核后为您解除53端口封禁。

### **7.不提供递归解析服务，是否可以开通53端口用来提供权威解析服务？** [#7不提供递归解析服务是否可以开通53端口用来提供权威解析服务]

可以，您可以通过[**工单**](https://support.qiniu.com/tickets/new-for-person/form?category=%E5%85%B6%E4%BB%96\&space=%E5%85%A8%E6%A0%88%E5%BA%94%E7%94%A8%E6%9C%8D%E5%8A%A1%E5%99%A8)联系我司、按要求提交相应材料，通过审核后为您解除53端口封禁。

### **8.未办理相关许可证开展递归解析服务业务会有什么影响？** [#8未办理相关许可证开展递归解析服务业务会有什么影响]

根据《中华人民共和国电信条例》 第六十九条：（一）违反本条例第七条第三款的规定或者有本条例第五十八条第（一）项所列行为，擅自经营电信业务的，或者超范围经营电信业务的，由国务院信息产业主管部门或者省、自治区、直辖市电信管理机构依据职权责令改正，没收违法所得，处违法所得3倍以上5倍以下罚款；没有违法所得或者违法所得不足5万元的，处10万元以上100万元以下罚款；情节严重的，责令停业整顿。

## **相关政策法规要求** [#相关政策法规要求]

**《电信业务经营许可管理办法》**
第四十六条 违反本办法第十六条第一款、第二十八条第一款规定，擅自经营电信业务或者超范围经营电信业务的，依照《中华人民共和国电信条例》第六十九条规定予以处罚，其中情节严重、给予责令停业整顿处罚的，直接列入电信业务经营失信名单。

**《互联网域名管理办法》**
第三十六条 提供域名解析服务，应当遵守有关法律、法规、标准，具备相应的技术、服务和网络与信息安全保障能力，落实网络与信息安全保障措施，依法记录并留存域名解析日志、维护日志和变更记录，保障解析服务质量和解析系统安全。涉及经营电信业务的，应当依法取得电信业务经营许可。

**《电信业务经营许可管理办法》**
第二十四条 提供接入服务的增值电信业务经营者应当遵守下列规定：（三）不得为未依法取得经营许可证或者履行非经营性互联网信息服务备案手续的单位或者个人提供接入或者代收费等服务。


# ICP 备案相关问题 (/faq/las/12988-las-faq-domain-icp)



最近更新时间: 2026-10-15 11:35:15

## **1、为什么我的网站域名解析到七牛云全栈应用服务器无法访问？** [#1为什么我的网站域名解析到七牛云全栈应用服务器无法访问]

七牛应工信部要求，对未履行备案手续，在中国内地提供非经营性互联网信息服务的网站实行封堵措施。因此您的网站在未备案的情况下将无法在中国内地服务器访问，您可以[联系商务](https://support.qiniu.com/tickets)、协助您完成备案操作。管局审核通过后您的网站便可正常访问。感谢您的支持与理解！

## **2、购买七牛云全栈应用服务器如何完成域名的 ICP 备案？** [#2购买七牛云全栈应用服务器如何完成域名的-icp-备案]

**备案前提条件**

* <u>
    **购买时长不少于 1 年的包年包月云主机（包含独立公网 IP）。**
  </u>

**备案周期**

* 约 20～30 个工作日（自完备资料提交开始计算）

LAS 的 ICP 备案目前还不支持系统提交，请[联系商务](https://support.qiniu.com/tickets)、协助您完成备案操作。


# 资源栈常见问题排查 (/faq/las/13334-faq-rsf-troubleshooting)



最近更新时间: 2026-03-03 13:05:45

# 资源栈常见问题排查指南 [#资源栈常见问题排查指南]

本文档帮助用户排查在控制台使用资源栈（Formation）时遇到的常见问题。

## 受支持的 Terraform Provider 白名单 [#受支持的-terraform-provider-白名单]

以下是当前资源栈支持的 Terraform Provider 列表：

| Provider  | Source              | 版本     | 用途                         |
| --------- | ------------------- | ------ | -------------------------- |
| qiniu     | qiniu/qiniu         | 1.0.0  | 管理七牛云资源                    |
| random    | hashicorp/random    | 3.8.0  | 生成随机数                      |
| time      | hashicorp/time      | 0.13.1 | 处理时间相关操作                   |
| archive   | hashicorp/archive   | 2.7.1  | 处理压缩文件                     |
| cloudinit | hashicorp/cloudinit | 2.3.7  | 生成 cloud-init 配置文件         |
| external  | hashicorp/external  | 2.3.5  | 执行外部程序并获取其输出               |
| null      | hashicorp/null      | 3.2.4  | 提供空资源，配合 provisioner 等机制使用 |
| http      | hashicorp/http      | 3.5.0  | 发起 HTTP 请求                 |
| tls       | hashicorp/tls       | 4.1.0  | 生成和解析 RSA 公私钥、证书等          |
| local     | hashicorp/local     | 2.5.3  | 操作本地文件和目录                  |
| docker    | kreuzwerker/docker  | 3.6.2  | 管理主机上的 Docker 容器和镜像        |

> **注意**：使用未在白名单中的 Provider 会导致资源栈创建/更新失败。如需支持新的 Provider，可以提交工单申请。

更多信息请参考[七牛 Provider 官方文档](https://github.com/qiniu/terraform-module/tree/main/docs/qiniu-provider)。

***

## 日志及产物的目录结构 [#日志及产物的目录结构]

`<artifactsStorageBucket>` 是资源栈创建时指定的产物存储路径，格式为 `kodo://<bucket-name>/<目录>/`。如果创建资源栈时未指定，系统会自动生成并创建对应的 Kodo 空间：

* **自动生成格式**：`kodo://rfs-<8位随机字符>-<regionID>-artifacts/`
  * `<8位随机字符>`：由数字和小写字母（`0-9a-z`）随机生成
  * `<regionID>`：RFS 服务所在的区域 ID（如 `cn-east-1`）
  * 示例：`kodo://rfs-a3b7f9k2-cn-east-1-artifacts/`
* **空间复用**：同一用户在同一区域的所有资源栈共享同一个自动创建的空间，不会重复创建
* **空间区域**：默认在 LAS 所在区域创建，如果该区域没有 Kodo 服务，会自动选择就近区域

资源栈的执行日志和产物按以下目录结构组织：

```text
<artifactsStorageBucket>/
└── r-<revision>/                              # 每个 revision 对应一次执行操作
    ├── logs/
    │   ├── terraform-log-<uuid>.log           # Terraform 内部执行日志
    │   └── rfsjob-log-<uuid>.log              # RFSJob 执行过程日志
    ├── apply_results/                         # 执行 apply 操作时的产物
    │   ├── artifacts/
    │   │   └── log.json                       # Terraform 结构化日志
    │   └── content/                           # Terraform 实际执行的模块代码
    └── plan_results/                          # 执行 plan 操作时的产物
        ├── artifacts/
        │   └── log.json                       # Terraform 结构化日志
        └── content/                           # Terraform 实际执行的模块代码
```

> **说明**
>
> * `apply_results/` 和 `plan_results/` 分别对应 apply（创建/更新/删除）和 plan（计划）操作的产物，目录内部结构相同。
> * **revision** 是资源栈的版本号，每次执行操作（无论成败）都会生成一个新的 revision 目录用于存储日志；操作成功后，资源栈版本号才会递增。

### 日志文件说明 [#日志文件说明]

| 日志文件                                    | 内容说明                                                                      | 适用场景                        |
| --------------------------------------- | ------------------------------------------------------------------------- | --------------------------- |
| `logs/terraform-log-&lt;uuid&gt;.log`   | Terraform 自身的内部执行日志                                                       | 排查 Terraform 引擎层面的问题        |
| `logs/rfsjob-log-&lt;uuid&gt;.log`      | RFSJob 执行过程日志，包含 Git Clone、tfplan 文件下载、`init → plan → apply` 执行流程、上传对象存储等 | 排查执行流程问题（如 Git 拉取失败）        |
| `&lt;操作&gt;_results/artifacts/log.json` | Terraform 执行过程输出的**结构化日志**（`&lt;操作&gt;` 为 `apply` 或 `plan`）               | **首选查看**——语法错误、接口调用错误等均记录在此 |
| `&lt;操作&gt;_results/content/`           | Terraform 真正执行的模块代码（包含内部自动生成的代码文件）                                        | 查看 Terraform 实际执行的代码内容      |

***

## 常见问题 [#常见问题]

### 1. 创建/更新/删除资源栈失败 [#1-创建更新删除资源栈失败]

**问题现象**：资源栈状态变为 `CreateFailed`（创建失败）、`UpdateFailed`（更新失败）或 `DeleteFailed`（删除失败）。

<img src="/docs-assets/faq/las/13334-faq-rsf-troubleshooting/FvRBdwXOeoxcQ0gBcbeyLOvik8Ae-e60e5fccf69f.webp" width="500" />

**可能原因**：

* Terraform 模板语法错误
* Git 仓库拉取失败（地址错误、权限不足、网络不可达等）
* 使用了不受支持的 Terraform Provider（参见[白名单](#受支持的-terraform-provider-白名单)）
* 输入变量（Variables）的值不符合类型或约束要求
* 云资源 API 调用失败（资源不足、余额不足、参数非法等）

**排查步骤**：

1. 在资源栈详情页，鼠标移动到**状态说明**，获取初步错误信息
2. 进入 `<artifactsStorageBucket>/r-<revision>/` 目录（revision 编号可在资源栈详情页的版本信息中查看），按优先级查看日志：
   > **提示**：可在资源栈详情页点击**当前版本**右侧的图标，直接跳转到对象存储的对应目录。
   * 查看 `<操作>_results/artifacts/log.json`——包含结构化的错误信息和上下文，能定位大部分问题
   * 查看 `logs/rfsjob-log-<uuid>.log`——排查 Git Clone 失败、执行流程中断等问题
   * 查看 `logs/terraform-log-<uuid>.log`——排查 Terraform 引擎层面的异常

**解决方案**：

1. **修正配置后重新更新**：根据错误信息修正 Terraform 配置，执行"更新"操作重新部署
   > **提示**：若界面弹出 `强制重试资源栈` 提示，说明当前错误不可直接重试，必须先修正配置后再操作。
   >
   > <img src="/docs-assets/faq/las/13334-faq-rsf-troubleshooting/FoVEGibx3aPT11eHjkuFqji8q6T4-eb401714ebb3.webp" width="500" />
2. **重试操作**：系统会使用相同配置重新执行 `terraform apply`，适用于偶发错误（网络异常、Git 仓库临时不可用等）

> **注意**：以上排查步骤适用于所有资源栈失败类问题（包括下文中的问题 2、3、4），均可通过查看对应 revision 目录下的日志来定位原因。

### 2. 更新资源栈失败，提示资源在平台外被修改 [#2-更新资源栈失败提示资源在平台外被修改]

**问题现象**：更新资源栈失败，日志中提示检测到资源在平台外发生变更。

<img src="/docs-assets/faq/las/13334-faq-rsf-troubleshooting/FkN38DmywY3Wdp_DhhXrjfvqiYrY-7dc12b5a811c.webp" width="500" />

**可能原因**：

* 资源栈管理的云资源被通过控制台或 API 直接修改（如手动调整了虚拟机配置）
* 资源栈记录的状态与云资源的实际状态不一致

**解决方案**：

1. 更新时有一个**是否同步资源状态**的选项，选择**同步**重新更新——系统会先同步资源的最新状态，再执行更新操作
   <img src="/docs-assets/faq/las/13334-faq-rsf-troubleshooting/Fpx25idnWlMfhdm-YOR7ZGGYc0st-44aaaccfeb74.webp" width="500" />
2. **建议**：通过资源栈统一管理资源变更，避免直接修改资源栈管理的云资源

### 3. 更新资源栈后部分资源被替换 [#3-更新资源栈后部分资源被替换]

**问题现象**：更新资源栈后，某些资源被删除并重新创建（Replace），而非原地更新（Update）。

**可能原因**：

* 某些资源属性的变更不支持原地更新（in-place update），Terraform 只能通过先创建新资源再删除旧资源（Replace）来完成变更

**解决方案**：

1. **更新前先预览变更**——创建一个 Update 类型的资源栈计划（StackPlan），查看 `resourceChanges` 中 action 为 `Replace` 的资源，确认无误后再应用
   <img src="/docs-assets/faq/las/13334-faq-rsf-troubleshooting/Fq4doWwcflOMpVXWHaHpPLnZnEEe-f78333e3a903.webp" width="500" />

2. **注意**：`Replace` 操作会先创建新资源再删除旧资源，可能导致短暂的服务中断。对于有状态的资源（如数据库实例、云盘等），旧资源删除后其存储的数据将**永久丢失且无法恢复**，请务必在操作前完成数据备份

3. 如果不希望资源被替换，请调整 Terraform 配置，避免修改会触发替换的属性（具体哪些属性会触发替换，请参考对应 Provider 的文档说明）

### 4. 应用资源栈计划时提示"需要执行 Refresh" [#4-应用资源栈计划时提示需要执行-refresh]

**问题现象**：应用资源栈计划时提示 `StackNeedRefresh`，查看计划详情时，资源偏移（Resource Drift）列表不为空。

StackNeedRefresh 提示：

<img src="/docs-assets/faq/las/13334-faq-rsf-troubleshooting/FnlYx2l1reuR6lcwThrnnX48lyz-eaef1f26ceb9.webp" width="500" />

资源偏移（Resource Drift）列表示例：

<img src="/docs-assets/faq/las/13334-faq-rsf-troubleshooting/FmgoQeWpMpojzW0c13cJ5tjyouMt-584e3912ace1.webp" width="500" />

**可能原因**：

* 计划创建后到应用期间，资源在平台外发生了变更
* 系统检测到了资源偏移（Resource Drift）

> **资源偏移**表示系统检测到某些资源在资源栈之外被修改。偏移类型包括：
>
> | 偏移类型   | 说明           |
> | ------ | ------------ |
> | Update | 资源的属性在平台外被更新 |
> | Delete | 资源在平台外被删除    |

**解决方案**：

1. 查看偏移列表，确认哪些资源发生了变更
2. 若变更是预期的，在**是否同步资源状态**的选项中，选择**同步**后应用计划
   <img src="/docs-assets/faq/las/13334-faq-rsf-troubleshooting/FtPDDnYgbao_qy4akmunTscHjZkq-54b6ee52d9a8.webp" width="500" />
3. 若变更非预期，先排查是否有人手动修改了云资源
4. 也可以删除当前计划，重新创建新计划（新计划会基于最新状态生成）
5. **建议**：通过资源栈统一管理资源变更，避免在平台外直接操作资源栈管理的资源


# LAS全栈应用服务器常见问题 Q&A (/faq/las/13371-las-refund)



最近更新时间: 2026-08-17 16:31:50

**Q1：全栈应用服务器区域购买错误，可以更换区域吗？**
A：不支持更换区域，您可以参考下面 `全栈应用服务器退款流程` 操作退款后重新购买。
`注意：如果是通过活动购买的特价服务器，退款后将不再享有活动额度，无法继续购买特价服务器。`

***

**Q2：全栈应用服务器退款流程**
A：
1、进入LAS服务器，[实例列表](https://portal.qiniu.com/las/vm/instances)；
2、点击更多，可以找到：释放/退订
![image.png](/docs-assets/faq/las/13371-las-refund/Fp91Uoc2oT4e2UC6tV5f1GC4IGWo-cc0ed546d2a5.webp)

***

**Q3：全栈应用服务器如何重置登录密码？**
A：
1、 在 [LAS实例管理界面](https://portal.qiniu.com/las/vm/instances) ，先点击 更多，再点击 `重置密码` 按钮进行密码重置
![image.png](/docs-assets/faq/las/13371-las-refund/FvLcGlpg7rpwNHlQwaXCLK_DS39R-717a4e888628.webp)
2、输入新密码后，点击 `确定` 后服务器会自动重启。
![image.png](/docs-assets/faq/las/13371-las-refund/FmVYg93x7bLCWmDqrEHCHB9CNLfJ-4bd972d51f65.webp)

***

**Q4：全栈应用服务器如何配置安全组？**
A：可以参考下这个文档进行配置：[/products/las/las-security-group/13519-las-security-group-create](/products/las/las-security-group/13519-las-security-group-create)

***

**Q5：全栈应用服务器LAS是否支持IPV6？**
A：目前暂不支持，如需IPV6网络，建议购买 [QVM云主机](/products/qvm/0-qvm-linux-quickstart) 产品。

***

**Q6：全栈应用服务器 LAS 如何扩缩容系统盘？**
A：目前暂不支持，可以通过自定义镜像重新创建实例实现。具体操作步骤可以查看：[基于自定义镜像实现系统盘的扩容/缩容](/products/las/4-instance-disk-upgrade)

***

**Q7：全栈应用服务器LAS海外服务器中国大陆访问慢，或者连接超时？**
A：海外las服务器不推荐中国大陆使用，建议中国大陆服务选择中国大陆服务器。
![image.png](/docs-assets/faq/las/13371-las-refund/Fh9jnFsXT5sbYe4R3IPbO2cGUCRh-6547b976ed7e.webp)

***

**Q8：全栈应用服务器LAS购买的ip显示地区和服务器不一致，例如购买的是日本区域的，注册地在德国？**
A：是正常现象。比如您看到的IP注册地在德国（法兰克福），但该IP实际发布和路由在您购买的日本区域，服务器的实际部署位置和访问体验不受影响。网络延迟仍基于日本节点，无需担心。

***

**Q9：LAS全栈应用服务器有流量限制么？**
A：没有。

***

**Q10：LAS全栈应用服务器选错系统镜像，如何重置系统？**
`注意：重置系统会清理服务器数据，操作前请做好本地数据备份`
A：
1、进入LAS服务器，[实例列表](https://portal.qiniu.com/las/vm/instances) 先将对应服务器操作关机；
2、关机后，点击更多，可以找到：重置系统 重装系统即可。
![image.png](/docs-assets/faq/las/13371-las-refund/FoN_OfQTeG05gGxPO9zNdRv7-1O5-2a7111b1e348.webp)

**Q11：LAS全栈应用服务器是否支持windows镜像？**
A：目前暂时不支持windows系列镜像。

***

**Q12：全栈应用服务器需要更换ip**
A：全栈应用服务器**不支持**更换ip。

***

**Q13：与LAS服务器一起购买的系统盘可以挂载到另外一个LAS服务器使用吗？**
A：不支持；如果需要挂载磁盘，可以在七牛控制台 - [磁盘](https://portal.qiniu.com/las/vm/disks) 购买与服务器同区域的云盘，然后将其挂载到对应LAS服务器。

***

**Q14：共享IP的全栈应用服务器实例支持更换为独立IP吗？**
A：暂不支持，共享IP实例使用参考 [共享公网IP实例端口分配规则与业务端口开放指南](/faq/las/13426-shared-public-ip-port-allocation-guide) ；如需独立IP实例，建议在 [全栈应用服务器 LAS](https://portal.qiniu.com/las/vm/instances/create) 控制台购买公网访问方式为 `固定IPv4` 的实例。
![image.png](/docs-assets/faq/las/13371-las-refund/FnsPFtmvO8rBWLDhxCfNplgYjVQf-b4274cfbb2e8.webp)

***

**Q15：全栈应用服务器ssh登录卡顿，服务器内部操作响应慢，如何处理？**
A：如果是海外服务器，在中国大陆区域操作时，出现上述情况，是预期的，建议中国大陆服务选择中国大陆服务器；
![image.png](/docs-assets/faq/las/13371-las-refund/Fh9jnFsXT5sbYe4R3IPbO2cGUCRh-6547b976ed7e.webp)
如果只是在中国大陆区域管理海外服务器，可以通过七牛控制台的 [web命令行](/products/las/cloud-server/server-login/1-remote-to-linux-instance-via-remote-tool-in-browser) 方式登录管理
B：如果是海外服务器在海外操作或中国大陆服务器在中国大陆操作时，出现上述情况：<br /> 1、可以先检查下本地电脑网络情况，看下是不是本地网络不佳导致的？<br /> 2、确认本地网络正常后，可以通过七牛控制台的 [web命令行](/products/las/cloud-server/server-login/1-remote-to-linux-instance-via-remote-tool-in-browser) 方式登录服务器内部后，检查下服务器内部进程、cpu和网络带宽占用情况，看下是否是负载跑满或带宽跑满导致的？

```bash
1)、带宽占用情况
A、查看各网卡流量
sudo sar -n DEV 1 5
B、按进程查看带宽占用情况
sudo nethogs <网卡名>  # 如 eth0

2)、查看整体负载与CPU使用率
top
说明：在 top 界面中按 Shift + P，按 CPU 使用率降序排列，定位高占用进程（关注 PID 和 COMMAND）

3)、或者使用htop命令查看
A、安装命令
sudo yum install -y htop  # CentOS/RHEL
sudo apt install -y htop  # Ubuntu/Debian
B、执行命令
htop
说明：按 F6 → 选择 PERCENT_CPU 排序
```

***

**Q16：是否提供测试IP，查看网络延迟情况？**
A：目前没有测试IP，需要测试网络延迟，可以根据自身业务需求购买对应区域低配置的按量付费服务器，再去测试验证

***


# 共享公网IP实例端口分配规则与业务端口开放指南 (/faq/las/13426-shared-public-ip-port-allocation-guide)



最近更新时间: 2026-04-10 15:46:47

## 1. 概述 [#1-概述]

目前只有**新人专享机型**使用共享公网IP实例，通过商城购买的实例为独立IP实例。

共享公网IP实例的公网IP未直接绑定至服务器网卡。因此，端口映射需由系统统一调度管理。本文档旨在帮助用户理解端口分配规则，并规范业务端口开放的操作流程。

## 2. 默认端口策略 [#2-默认端口策略]

|               | **共享 IP 实例**                                                                            | **独立 IP 实例**                     |
| ------------- | --------------------------------------------------------------------------------------- | -------------------------------- |
| **SSH登录端口**   | 特定端口，查看IP:之后的 `&lt;端口&gt;` <br /> 登录命令： ssh root\@IP -p 特定端口                            | 默认 22端口 <br /> 登录命令：ssh root\@IP |
| **自定义外网访问端口** | 不支持自定义端口，需在控制台启用端口映射配置。<br />如将自定义的`8080`端口映射到随机分配的`公网端口`,<br />使用ip:公网端口访问主机内的8080端口服务 | 无需额外操作，直接ip:8080即可               |
| **公网端口数量限制**  | 单实例**最多10个**映射端口                                                                        | 无限制                              |
| **适用场景**      | 轻量业务、测试环境、成本敏感型                                                                         | 生产环境、多端口服务、高灵活需求                 |

## 3. 公网端口开放教程 [#3-公网端口开放教程]

### 3.1 自助添加端口映射 [#31-自助添加端口映射]

1. 登录[控制台](https://portal.qiniu.com/las/vm/instances)，查看需要调整的共享 ip实例。

   ![image.png](/docs-assets/faq/las/13426-shared-public-ip-port-allocation-guide/Fml8wvqaOESlC6ah3l2ivoUTlxx2-ff30280b0ca1.webp)

2. 点击进入端口映射配置界面。

   ![image-20260409173111689.png](/docs-assets/faq/las/13426-shared-public-ip-port-allocation-guide/FgNdZOFyCiZGZ-tA1LXpwzlS0cb-d7403f53dc18.webp)

3. 点击“添加映射规则”，在弹窗中填写需要转发的内网端口，然后点击“确定”。

   ![image-20260409170545780.png](/docs-assets/faq/las/13426-shared-public-ip-port-allocation-guide/FvNV_EMlJV7Jg7YU9JpHxnArET9J-3a012a6c0370.webp)

### 3.2 工单申请 [#32-工单申请]

> 适用于超过 10 个映射规则，无法自助完成的情况。

1. 登录控制台，进入【[工单系统](https://support.qiniu.com/tickets/new-for-person/form?category=%E5%85%B6%E4%BB%96\&space=%E5%85%A8%E6%A0%88%E5%BA%94%E7%94%A8%E6%9C%8D%E5%8A%A1%E5%99%A8)】
2. 填写申请信息，**务必注明**：
   * 需开放的内网端口号（如 `8080`）
   * 协议类型（TCP / UDP）
   * 业务用途简述（便于审核）
3. 提交后，工单将流转至后台团队处理
4. 配置完成后，系统将通过工单回复告知公网端口号及访问方式

**示例工单内容**

```
【端口开放申请】
实例ID：xxxxxxxx
内网端口：8080
协议类型：TCP
业务说明：部署Web应用，需对外提供HTTP服务
```


# MTU 黑洞导致 Docker 容器网络异常处理 (/faq/las/13489-las-docker-pmtu-black-hole)



最近更新时间: 2026-05-29 10:33:29

标准网络下的虚拟机 MTU 上限通常为 1480，Docker 默认 1500 会导致大包被分片或丢弃。需要把 Docker daemon 与已创建网络的 MTU 都改成 1480。

## 常见现象 [#常见现象]

MTU 不匹配的典型表现是「小包通、大包挂」——三次握手正常，业务数据一上量就异常：

* `curl`、`wget` 拉小页面正常，拉大文件中途 hang 住或长时间无进度
* `apt update` / `apt install`、`yum`、`pip`、`npm` 拉到一半卡住、超时、`Connection reset`
* `git clone` 在 `Receiving objects` 阶段卡死或反复重试
* HTTPS 握手能完成，但加载页面长时间空白；HTTP 请求超时但 `ping` 正常
* 容器之间或容器到外网 SSH 能登录但执行 `ls` 大目录、`scp` 大文件就断
* 数据库连接能建立，但跑大结果集查询超时

## 问题确认 [#问题确认]

虚拟机内执行：

```sh
ip link show eno1 | grep mtu
# 期望看到 mtu 1480
# ip link show en0 | grep mtu # CentOS 系统

ip link show docker0 | grep mtu
# 看到 mtu 1500
```

或者通过容器执行：

```sh
docker run --rm nicolaka/netshoot ping -M do -s 1452 -c 3 8.8.8.8   # 应该通
docker run --rm nicolaka/netshoot ping -M do -s 1453 -c 3 8.8.8.8   # 应该失败：Message too long 或丢包
```

## 处理办法 [#处理办法]

### 1. 修改 Docker daemon 默认 MTU [#1-修改-docker-daemon-默认-mtu]

编辑 `/etc/docker/daemon.json`（不存在则新建）：

```bash
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json > /dev/null <<'EOF'
{
  "mtu": 1480
}
EOF
```

如果文件已存在其他配置，只需在 JSON 中加入 `"mtu": 1480` 字段，不要整体覆盖。

然后重启 Docker：

```bash
sudo systemctl restart docker
```

确认默认 `bridge` 网络配置：

```bash
docker network inspect bridge | grep -i mtu
# 期望看到 "com.docker.network.driver.mtu": "1480"
```

### 2. 已存在的自定义网络 [#2-已存在的自定义网络]

`daemon.json` 的 `mtu` 只对默认 `bridge` 网络生效。已经用 `docker network create` 创建的网络需要重建，或在创建时显式指定：

```bash
docker network create \
  --opt com.docker.network.driver.mtu=1480 \
  my-net
```

### 3. docker-compose 场景 [#3-docker-compose-场景]

在 `docker-compose.yml` 中为自定义网络指定 MTU：

```yaml
networks:
  default:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: 1480
```

## 验证 MTU 配置 [#验证-mtu-配置]

改完后先确认新容器的网卡 MTU 已生效：

```bash
docker run --rm nicolaka/netshoot ip link show eth0 | grep mtu
# 期望看到 mtu 1480
```

再跑一次不分片边界测试，确认 1480 的包能通过，超过 1480 的包会被拦住：

```bash
docker run --rm nicolaka/netshoot ping -M do -s 1452 -c 3 8.8.8.8
# -s 1452 = 1480 - 20 (IP头) - 8 (ICMP头)，应该通

docker run --rm nicolaka/netshoot ping -M do -s 1453 -c 3 8.8.8.8
# -s 1453 会让 IP 包超过 1480，应该失败：Message too long 或丢包
```


# 绍兴地区全栈应用服务器80和443端口开放问题 (/faq/las/13496-las-shaoxing)



最近更新时间: 2026-06-02 15:34:50

绍兴 GPU 服务器的 80、443 端口默认不通、需要备案才能开，如果您需要开启，可以工单提供下这个资料，这边提交材料去做备案。材料没问题，顺利的话1～2周处理完成。
[绍兴联通网站备案所需资料及简单流程](https://dn-odum9helk.qbox.me/Fq1dJBcRX7k-xF-UFHyZL-JO8--8?attname=%E7%BB%8D%E5%85%B4%E8%81%94%E9%80%9A%E7%BD%91%E7%AB%99%E5%A4%87%E6%A1%88%E6%89%80%E9%9C%80%E8%B5%84%E6%96%99%E5%8F%8A%E7%AE%80%E5%8D%95%E6%B5%81%E7%A8%8B.wps)


# 全栈应用服务器 (/faq/las)



## 关于53端口默认关闭的说明 [#关于53端口默认关闭的说明]

[查看原文](/faq/las/12987-las-faq-port-53)

关于53端口关闭的说明

## 未备案域名访问被拦截 [#未备案域名访问被拦截]

[查看原文](/faq/las/12988-las-faq-domain-icp)

未备案域名访问被拦截的说明

## 资源栈常见问题排查 [#资源栈常见问题排查]

[查看原文](/faq/las/13334-faq-rsf-troubleshooting)

介绍资源栈常见问题的排查方法

## LAS全栈应用服务器常见问题 Q\&A [#las全栈应用服务器常见问题-qa]

[查看原文](/faq/las/13371-las-refund)

LAS 全栈应用服务器常见问题问答

## 共享公网IP实例端口分配规则与业务端口开放指南 [#共享公网ip实例端口分配规则与业务端口开放指南]

[查看原文](/faq/las/13426-shared-public-ip-port-allocation-guide)

本文档面向使用共享公网IP实例的用户，系统说明端口分配机制、默认开放策略、端口数量限制及业务端口申请流程。帮助用户理解为何部分端口无法直接访问，并指导完成端口映射配置，保障业务正常对外提供服务。

更多问题请查看 [官网 FAQ](/faq)。


# Miku常见问题FAQ (/faq/mikustream/13500-mikustream-live-record-create-api-httpurl)



最近更新时间: 2026-08-19 11:07:50

| Q1：回放录制httpurl返回的链接的域名不是指定的域名？                                                                    |
| ------------------------------------------------------------------------------------------------- |
| httpurl返回是默认的，不能修改，所以不建议依赖这个 httpurl 返回的数据，留意参数 fname 即可，然后自行加一段逻辑拼接url，http(s)://自定义域名/fname 即可。 |

<br />

| Q2：miku直播推流生成在对象存储中的/recordings目录下的m3u8文件和/fragments目录下的ts文件是否会被自动删除？                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 会自动删除，文件保留时间取决于直播空间您设置的 &#x2A;*`存储过期时间`** ；如果要永久保存，需要您调用 [生成指定时间范围录制文件](/products/mikustream/mikustream-live-recording-api/0-mikustream-live-record-create-api) 接口通过设置 expireDays 参数去修改。![image.png](/docs-assets/faq/mikustream/13500-mikustream-live-record-create-api-httpurl/FhY-DdBzshdX9gEy1UM5uCT58MeF-5e5797856ed5.webp) |

<br />

| Q3：miku直播空间绑定了域名，但无法拉流，为什么？                                                                                                              |
| ---------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是您绑定域名时选择的播放协议与拉流使用的协议不一致导致的，比如您绑定时选择了rtmp协议，拉流时使用了http协议。如果同一个域名需要同时支持rtmp、flv、HLS拉流，绑定域名时选择 &#x2A;*`通用`** 即可。                        |
| ![image.png](/docs-assets/faq/mikustream/13500-mikustream-live-record-create-api-httpurl/FsXzWcAmT734kA1vR7WHl214Ci7Q-4185f24892ac.webp) |

<br />

| Q4：miku直播空间的录制回放域名如何绑定？                                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 录制回放域名是绑定在 &#x2A;*`存储空间`** 的，配置操作参考：[设置自定义CDN加速域名](/products/kodo/kodo-console-guide/bucket-management/kodo-domain-name-management/0-set-the-custom-cdn-to-accelerate-the-domain-name) |

<br />

| Q5：miku直播使用WHIP协议推流，flv、m3u8格式拉流失败，报500错误，怎么处理？                        |
| ---------------------------------------------------------------------- |
| WHIP协议推流，只支持使用WHEP低延迟方式拉流，不支持flv、m3u8拉流导致的。如需使用flv、m3u8拉流，请使用rtmp协议推流。 |

<br />


# Miku 快直播 (/faq/mikustream)



暂无已同步的 FAQ 条目。

更多问题请查看 [官网 FAQ](/faq)。


# 如何对空间内的文件进行多媒体处理 (/faq/kodo/12875-dora-kodo)



最近更新时间: 2026-08-07 11:48:43

## 一、创建多媒体任务 [#一创建多媒体任务]

### 1、创建转码需要使用的队列，可以点击这个链接进行创建：[队列](https://portal.qiniu.com/dora/media-gate/pipeline) [#1创建转码需要使用的队列可以点击这个链接进行创建队列]

![image.png](/docs-assets/faq/kodo/12875-dora-kodo/FlMGQEGwaydyREnq97LHqIbZrKHj-11961c693d05.webp)

### 2、在[空间管理](https://portal.qiniu.com/kodo/bucket)进入对应文件存储的空间 [#2在空间管理进入对应文件存储的空间]

![image.png](/docs-assets/faq/kodo/12875-dora-kodo/FrJeSw0MMgq3PDZVeQ249XVE8LR0-40b0577df3a7.webp)

### 3、创建转码需要使用的工作流模板，点击【工作流模板】，点击【新建工作流】 [#3创建转码需要使用的工作流模板点击工作流模板点击新建工作流]

![image.png](/docs-assets/faq/kodo/12875-dora-kodo/FvrzoeOl4vuKCTBgOZmymeR8BYME-3889f5dd4066.webp)

### 进行工作流创建，点击红框内的“+”，添加对应的转码命令，再次点击“+”可以设置输出信息 [#进行工作流创建点击红框内的添加对应的转码命令再次点击可以设置输出信息]

![image.png](/docs-assets/faq/kodo/12875-dora-kodo/FokqSAEpeH1JIMukNWLi7toJTOdL-069efa1ef72d.webp)
![image.png](/docs-assets/faq/kodo/12875-dora-kodo/Flawa8nW-2jcQbmOzvsk21Nyc-3b-4c79d469a500.webp)

### 4、点击【任务与工作流】下的【任务管理】 [#4点击任务与工作流下的任务管理]

![image.png](/docs-assets/faq/kodo/12875-dora-kodo/Fnr7M5taEuEP0Th9TymzGpLQePUq-a1c89de8a719.webp)

### 5、点击【创建任务】 [#5点击创建任务]

![image.png](/docs-assets/faq/kodo/12875-dora-kodo/Fh-1WyMjJEVa0LVl_W52E_ts5o3k-6915b0ca854f.webp)

### 6、选择对应的文件，工作流，队列，进行转码提交 [#6选择对应的文件工作流队列进行转码提交]

![image.png](/docs-assets/faq/kodo/12875-dora-kodo/Fu4PnJR53TLNXMm5c93bXAvcbXWR-79d9cafefe62.webp)

## 二、创建任务触发器（上传自动触发转码） [#二创建任务触发器上传自动触发转码]

### 1、参考上面的流程1-3创建好工作流模版 [#1参考上面的流程1-3创建好工作流模版]

### 2、点击【任务触发器】，并点击【新建任务触发器】 [#2点击任务触发器并点击新建任务触发器]

![image.png](/docs-assets/faq/kodo/12875-dora-kodo/FtJLLhi3FchI6D0HC_kKvrHIkiJY-5c5073b32579.webp)

### 3、设置好需要触发的工作流，根据需要处理的文件设置好【规则策略】，跟进需要处理的文件类型（视频、图片等）设置好【输入过滤源】，上传自动触发转码一定要开启【强制执行数据处理】 [#3设置好需要触发的工作流根据需要处理的文件设置好规则策略跟进需要处理的文件类型视频图片等设置好输入过滤源上传自动触发转码一定要开启强制执行数据处理]

![image.png](/docs-assets/faq/kodo/12875-dora-kodo/Fn-PL10marHTQLK1BKBjMTMBRYlq-5241111f5662.webp)


# 对象存储常见问题FAQ (/faq/kodo/13086-kodo-problem-faq)



最近更新时间: 2026-08-07 11:48:43

# **1. 为什么现在不支持创建文件夹或目录了？** [#1-为什么现在不支持创建文件夹或目录了]

【对象存储控制台】-【文件管理】界面支持【显示目录】或【隐藏目录】方式展示文件列表，可以在 文件管理 界面自主切换展示方式。文件管理操作说明文档：[/products/kodo/kodo-console-guide/file-management](/products/kodo/kodo-console-guide/file-management)

### **1) 切换为【显示目录】操作如下图，切换后可以在控制台创建文件夹或目录** [#1-切换为显示目录操作如下图切换后可以在控制台创建文件夹或目录]

<img src="/docs-assets/faq/kodo/13086-kodo-problem-faq/FuW-ERrW1xg6Il6Gj3MJTQVLix2D-3331c3d6bf9f.webp" width="800" />

### **2) 切换为【隐藏目录】操作如下图，切换后无法在控制台创建文件夹或目录** [#2-切换为隐藏目录操作如下图切换后无法在控制台创建文件夹或目录]

<img src="/docs-assets/faq/kodo/13086-kodo-problem-faq/FnVj-A3Eh9q2sqzCpodnT-UbREop-a687bcd34713.webp" width="800" />

# **2. 如何把对象存储空间的部分文件或所有文件打包成一个压缩包？** [#2-如何把对象存储空间的部分文件或所有文件打包成一个压缩包]

可以使用 [多文件压缩（mkzip）](/products/dora/file-processing/4-mkzip) 接口对存储空间的资源进行打包压缩。

### **1) 接口调用示例如下** [#1-接口调用示例如下]

go SDK调用示例：[https://github.com/qiniu/go-sdk/blob/master/examples/video\_pfop.go](https://github.com/qiniu/go-sdk/blob/master/examples/video_pfop.go)
Nodejs SDK调用示例：[https://github.com/qiniu/nodejs-sdk/blob/master/examples/video\_pfop.js](https://github.com/qiniu/nodejs-sdk/blob/master/examples/video_pfop.js)
ruby SDK调用示例：[https://github.com/qiniu/ruby-sdk/blob/develop/examples/pfop\_watermark.rb](https://github.com/qiniu/ruby-sdk/blob/develop/examples/pfop_watermark.rb)
python SDK调用示例：[https://github.com/qiniu/python-sdk/blob/master/examples/pfop\_watermark.py](https://github.com/qiniu/python-sdk/blob/master/examples/pfop_watermark.py)
php SDK调用示例：[https://github.com/qiniu/php-sdk/blob/master/examples/pfop\_mkzip.php](https://github.com/qiniu/php-sdk/blob/master/examples/pfop_mkzip.php)
java SDK调用示例：[https://github.com/qiniu/java-sdk/blob/master/examples/pfop\_watermark.java](https://github.com/qiniu/java-sdk/blob/master/examples/pfop_watermark.java)

### **2) 注意：** [#2-注意]

上述示例只展示了异步pfop接口调用方式，示例代码中的处理命令需要参考 [多文件压缩（mkzip）](/products/dora/file-processing/4-mkzip) 文档说明自行调整修改。

# **3. 如何把静态文件迁移到其他云平台友商？** [#3-如何把静态文件迁移到其他云平台友商]

您好，这个我们这边暂时只有其他友商迁移到我们这边的方案：[数据迁移](/products/kodo/data-migration)
您这边可以将文件url拿到其他云平台友商的服务器下载一下看下或者友商侧寻找迁移文档。

# **4. 文件已经删除，但还是存在很多恶意流量，如何清除缓存？** [#4-文件已经删除但还是存在很多恶意流量如何清除缓存]

可以在存储侧或者CDN侧操作刷新缓存
1，存储刷新缓存的方法参考：[/products/kodo/kodo-console-guide/file-management/15-refresh-the-cdn-cache](/products/kodo/kodo-console-guide/file-management/15-refresh-the-cdn-cache)
2，CDN刷新缓存方法请参考：[/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time)
方法1: portal.qiniu.com 控制台刷新缓存，点击左侧 cdn => 刷新预取
方法2: api 接口地址：[https://developer.qiniu.com/fusion/api/1229/cache-refresh](https://developer.qiniu.com/fusion/api/1229/cache-refresh)
Tip : url 刷新，全网生效 10min 左右，目录刷新需要 30min 左右

# **5. 为什么外链域名无法选择？** [#5-为什么外链域名无法选择]

是因为您的存储空间未绑定自定义域名导致，需要您参考[文档](/products/kodo/kodo-console-guide/bucket-management/kodo-domain-name-management) 绑定自己的域名，然后才可以选择对应的外链域名进行访问下载。


# 密钥安全使用须知 (/faq/kodo/1334-the-access-key-secret-key-encryption-key-safe-use-instructions)



最近更新时间: 2026-08-07 11:48:43

# 安全机制 [#安全机制]

数据安全性是云存储服务的重中之重。云存储的安全机制主要需要考虑以下几个因素：

* 如何判断该请求方是否合法，且对目标空间有相应的访问权限。
* 因为服务的访问协议同时支持HTTP和HTTPS，服务端需要判断收到的请求是否经过篡改。
* 相比上传新资源，覆盖文件或删除已有资源拥有更高的风险。因此对上传或修改动作，需要确认请求方是否拥有修改或删除的权限。

在使用七牛云存储服务的过程中，需要考虑安全机制的场景主要有如下几种：

* 上传资源
* 访问资源
* 管理和修改资源

这三个场景需要考虑不同的安全因素，因此七牛针对性的提供了三种安全机制：[上传凭证](/faq/kodo/1334-the-access-key-secret-key-encryption-key-safe-use-instructions)、[下载凭证](/faq/kodo/1334-the-access-key-secret-key-encryption-key-safe-use-instructions)和[管理凭证](/faq/kodo/1334-the-access-key-secret-key-encryption-key-safe-use-instructions)。

因为凭证的生成需要用到[SecretKey](/faq/kodo/1334-the-access-key-secret-key-encryption-key-safe-use-instructions#aksk)，因此该生成动作不应在不受信任的环境中进行。需要注意的是，开发者绝不能将密钥包含在分发给最终用户的程序中，无论是包含在配置文件中还是二进制文件中都会带来非常大的密钥泄漏风险。

SecretKey可在下面这地方获取：

![凭证创建和使用流程](/docs-assets/faq/kodo/1334-the-access-key-secret-key-encryption-key-safe-use-instructions/Fp5zMuYakcMWYnWR8ZMVyMhFclpH-a23d8f102056.webp)

# 密钥 [#密钥]

密钥（AccessKey/SecretKey）用于以上几种凭证的生成。以 SecretKey 为参数，配合适当的签名算法，可以得到原始信息的数字签名，防止内容在传递过程中被伪造或篡改。

密钥通常为成对创建和使用，包含一个AccessKey和一个SecretKey。其中AccessKey会在传输中包含，而用户必须保管好SecretKey不在网络上传输以防止被窃取。若SecretKey被恶意第三方窃取，可能导致非常严重的数据泄漏风险。因此，如发现SecretKey被非法使用，管理员应第一时间在[七牛开发者平台](https://portal.qiniu.com/)上更换密钥。

在具体描述各种凭证的详细生成过程中我们会看到AccessKey和SecretKey是如何被使用的。

**凭证的详细生成** 跳转链接： [/faq/kodo/1334-the-access-key-secret-key-encryption-key-safe-use-instructions](/faq/kodo/1334-the-access-key-secret-key-encryption-key-safe-use-instructions)

# 使用场景 [#使用场景]

七牛推荐客户将 AccessKey和一个SecretKey 放在服务端，由服务端生成令牌后颁发给客户端使用。

比如，上传文件的时候：

1. 业务服务器的服务端生成上传令牌（UploadToken）
2. 客户端程序（iOS、Android 以及 Web）拿到这个上传令牌之后就可以直接将文件上传到七牛

# 错误案例 [#错误案例]

把 AK/SK 放在客户端 SDK 中来做签名生成令牌，随 App 被发布出去。

这样做会被人家反编译之后拿到 AK/SK，之后他们就可以对你的账号进行操作。

实际上 Web 端 js 也是可以做签名的，只是你不可能把明文的 AK/SK 放在 Web 端，这样做更加危险。

将 AK/SK 加密后存放在客户端，等用户启动应用的时候再将 AK/SK 解密出来放在内存中，关闭应用后这对 AK/SK 即消失。

这样的做法也是不科学的，因为你的 AK/SK 在 后台 随时可以更改，特别是在被泄漏之后建议使用一对新的 AK/SK。如果你写死在 App 中将其发布，就只能通过发布新版本的 App 来更新这对 AK/SK。

# 最后建议 [#最后建议]

出于安全考虑，建议您根据自己的场景周期性地更换密钥。


# 对象存储空间同时绑定cdn域名和源站域名 (/faq/kodo/13495-kodo-cdn--domain-name)



最近更新时间: 2026-08-07 11:48:43

对象存储空间可以绑定[cdn域名](/products/cdn/0-fusion-quick-start)和[源站域名](/products/kodo/kodo-console-guide/bucket-management/kodo-domain-name-management/1-set-the-custom-source-domain-name)，如果是使用同一个域名，建议**二者选其一**。
如果同一个域名同时绑定cdn和源站域名，可能会出现以下问题：
1、cname解析冲突，一个域名同时只能有一个解析生效，域名购买厂商可能无法重复添加两次cname解析，能够添加，同时也只有一个解析生效；
2、cdn域名和源站域名收费不同，cdn域名访问会产生cdn流量+cdn回源流量，源站域名会产生外网流出流量；
3、cdn域名和源站域名支持一些配置，如果配置错地方，可能导致配置不生效，比如域名是进行cdn域名解析，但是https是配置在源站域名这边，https会无法正常访问等


# 批量转换存储类型 (/faq/kodo/13502-batch-types)



最近更新时间: 2026-08-07 11:48:43

# 批量转换存储类型 [#批量转换存储类型]

您这边可以使用qhsell工具进行批量转存储类型的

###### 1:下载qshell工具 [#1下载qshell工具]

qshell工具：[/products/kodo/0-qshell#9](/products/kodo/0-qshell#9)

###### 2:通过listbucket2命令进行列举需要转换类型的文件，可根据时间、后缀等条件进行列举，列举后保存到本地txt文件下 [#2通过listbucket2命令进行列举需要转换类型的文件可根据时间后缀等条件进行列举列举后保存到本地txt文件下]

listbucket2命令：[https://github.com/qiniu/qshell/blob/master/docs/listbucket2.md](https://github.com/qiniu/qshell/blob/master/docs/listbucket2.md)

###### 3:通过第二步列举出来的txt文件进行batchchtype批量转换命令进行转换即可，具体命令参数参考下列文档（注意：归档与深度归档类型文件需要先解冻后才能操作转换，解冻命令参考4） [#3通过第二步列举出来的txt文件进行batchchtype批量转换命令进行转换即可具体命令参数参考下列文档注意归档与深度归档类型文件需要先解冻后才能操作转换解冻命令参考4]

batchchtype命令：[https://github.com/qiniu/qshell/blob/master/docs/batchchtype.md](https://github.com/qiniu/qshell/blob/master/docs/batchchtype.md)

###### 4:如果是归档与深度归档类型文件需要先解冻的文件，需要通过第二步列举出来的txt文件，先进行解冻，解冻后再执行第三步即可 [#4如果是归档与深度归档类型文件需要先解冻的文件需要通过第二步列举出来的txt文件先进行解冻解冻后再执行第三步即可]

batchrestorear命令：[http://github.com/qiniu/qshell/blob/master/docs/batchrestorear.md](http://github.com/qiniu/qshell/blob/master/docs/batchrestorear.md)


# 视频教程 - 图片样式 (/faq/kodo/1395-video-tutorials-pictures-style)



最近更新时间: 2019-01-04 17:50:46

图片样式处理

[http://dn-odum9helk.qbox.me/spjc/4.mp4](http://dn-odum9helk.qbox.me/spjc/4.mp4)


# 视频教程 - wp插件配置 (/faq/kodo/1397-wp-plugin-video-tutorial)



最近更新时间: 2019-01-07 17:08:15

wp 插件如何配置

[WP插件配置视频教程](http://dn-odum9helk.qbox.me/wjw/spjc/6.mp4)


# 视频教程 - 镜像加速 (/faq/kodo/1686-video-tutorials-image-acceleration)



最近更新时间: 2019-01-07 17:04:27

镜像加速
七牛只支持静态加速，建议登录等操作不要放在七牛
[镜像加速视频](http://dn-odum9helk.qbox.me/wjw/spjc/mirror-src.mp4)


# 批量获取下载外链的方法 (/faq/kodo/4072-batch-obtains-download-chain-method)



最近更新时间: 2026-08-07 11:48:43

**批量获取文件外链，用三种方式进行获取**

## 七牛提供如下解决方案： [#七牛提供如下解决方案]

* 使用[qshell](/products/kodo/0-qshell)的[listbucket2](https://github.com/qiniu/qshell/blob/master/docs/listbucket2.md)功能，先基于需求，抽取文件列表，然后对文件列表进行拼接，七牛的链接默认是 [http://空间域名/文件名的格式](http://空间域名/文件名的格式) ，如果是私有空间的链接，那么还需要在此基础上，额外调用 qshell的batchsign才可以
* 使用[kodo-browser](/products/kodo/1-kodo-browser)直接导出外链
* 使用[官方服务端SDK](/sdk-tools/sdk#official-sdk)已经封装集成的list接口，先去获取文件列表，然后再去拼接访问链接，如果私有空间，还需要额外调用生成私有链接方法，`不推荐使用`

### qshell获取列表 [#qshell获取列表]

`使用listbucket2前，必须先登录账号`，使用qshell account 进行登录，如果已经登陆过，那么无需重复登录。ak sk 空间名称如果不了解是什么，可以阅读[常见的关键参数](/faq/kodo/7450-the-third-party-plug-in-key-parameters)

1. 登录，抽取文件列表

```bash
      qshell account 您的ak 您的sk 空间名称
      qshell listbucket2 空间名称 --show-fields Key -o fileList.txt
```

2. 过滤出第一列的 key ，并拼接域名。实现方法有很多，下面介绍一种：
   在 linux 或 macOS 终端，执行如下命令：

```
      cat fileList.txt | awk -F ' ' ' {print "http://空间域名/"$1}' > urlList.txt
```

urlList.txt 的输出结果：

```
      http://空间域名/hello.jpg
      http://空间域名/hello.mp4
      http://空间域名/hhh
      http://空间域名/jemygraw.jpg
```

### 使用经验 [#使用经验]

* windows 也可以安装 awk 和 cat 工具，具体可以百度下，和qshell一样，awk 和 cat 也是通用的脚本命令行工具

* 由于qshell是一个脚本命令行工具，所以需要在cmd或者终端中运行，mac与linux系统会经常使用到终端，下载合适版本到本地解压，直接chmod +x qshell 即可执行命令行。
  `但是如果您需要使用windows操作系统的话，可能您对cmd不是那么熟悉，强列推荐参考这里`
  [**windows环境下安装qshell教程**](/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial#2)


# 301重定向策略 (/faq/kodo/4117-301-redirect-strategy)



最近更新时间: 2026-08-07 11:48:43

七牛的存储源站设置了301重定向的策略，当访问的资源不存在，七牛源站会执行301重定向策略，尝试去掉文件名前缀的多出的 "/" 来获取资源，保证访问的稳定性。

例子：

假设存储空间中有 a.jpg ，访问 [http://url/a.jpg](http://url/a.jpg) 属于正常情况。如果访问 [http://url//a.jpg](http://url//a.jpg) ，七牛存储源站会先查找 /a.jpg ，如果不存在 /a.jpg ，七牛源站就会尝试查找 a.jpg 。如果存在，就返回给客户端；如果不存在就返回 Document not found。

**注意**：

1：如果存储空间设置了镜像存储，如果七牛源站查找 /a.jpg 不存在，会先去镜像源查找 /a.jpg 。如果镜像源存在资源，将资源同步到七牛，并且f返回到客户端；如果不存在，再执行七牛源站的 301 重定向策略。

2：如果存储空间存在 /a.jpg 资源，访问 [http://url/a.jpg](http://url/a.jpg) 不会重定向到 [http://url//a.jpg。](http://url//a.jpg。)


# python 异步 fetch demo (/faq/kodo/5710-python-asyncfetch-the-demo)



最近更新时间: 2026-08-07 11:48:43

python2 版本

```
# -*- coding: utf-8 -*-
# flake8: noqa

import requests
import json
import hmac
from hashlib import sha1
from base64 import urlsafe_b64encode
from urlparse import urlparse

"""
1. 该demo 是基于 python2.7 的
2. 客户需要依赖 requests 库，需要 install
3. 客户需要填写如下参数
    a. 抓取到七牛空间的 URL
    b. 抓取后保存到七牛空间的 key
    c. 抓取的目标 bucket
    d. 回调的 URL（必填项可以写一个无效 404 的地址）
    e. 回调的 body（这个如果没有的话也可以写空串）
4. sohuvideo 是华东空间，zone 是 z0；sohumedia 是华北空间，zone 是 z1

"""

access_key = '...'
secret_key = '...'

def urlsafe_base64_encode(data):
    """urlsafe的base64编码:

    对提供的数据进行urlsafe的base64编码。规格参考：
    [/products/kodo/development-guidelines/0-appendix#1](/products/kodo/development-guidelines/0-appendix#1)

    Args:
        data: 待编码的数据，一般为字符串

    Returns:
        编码后的字符串
    """
    ret = urlsafe_b64encode(bytes(data))
    return bytes(ret)

def __token(data):
    data = bytes(data)
    hashed = hmac.new(bytes(secret_key), data, sha1)
    return urlsafe_base64_encode(hashed.digest())


def token_of_request(url, body=None, content_type=None):
    """带请求体的签名（本质上是管理凭证的签名）

    Args:
        url:          待签名请求的url
        body:         待签名请求的body
        content_type: 待签名请求的body的Content-Type

    Returns:
        管理凭证
    """
    parsed_url = urlparse(url)
    query = parsed_url.query
    path = parsed_url.path
    data = path
    if query != '':
        data = ''.join([data, '?', query])
    data = ''.join([data, "\n"])

    if body:
        mimes = [
            'application/json'
        ]
        if content_type in mimes:
            data += body

    return '{0}:{1}'.format(access_key, __token(data))


bucket_name = 'bucket_name'

fetch_url = 'http://xxx.abc.com/123.kpg'

key = '123.jpg'

callbackurl = 'https://xxx.xxx.cn/callback'

callbackbody = '$(bucket)'


# z0为华东存储区域，z1为华北存储区域，z2为华南存储区域，na0为北美存储区域
zone = 'z0'

token = token_of_request("http://api-{}.qiniu.com/sisyphus/fetch".format(zone))


url = 'http://api-{}.qiniu.com/sisyphus/fetch'.format(zone)
s = json.dumps({'bucket': bucket_name, 'url': fetch_url,
                'key': key, 'callbackurl': callbackurl,
                'callbackbody': callbackbody})
headers = {"Authorization": "QBox {}".format(token)}
r = requests.post(url, data=s, headers=headers)
print(r.headers)
print(r.status_code)
print(r.content)
print("finished")

```

<br />

python3版本

```
# -*- coding: utf-8 -*-

import requests
import json
import hmac
from hashlib import sha1
from base64 import urlsafe_b64encode
from urllib.parse import urlparse


access_key = '...'
secret_key = '...'

def urlsafe_base64_encode(data):
    """urlsafe的base64编码:

    对提供的数据进行urlsafe的base64编码。规格参考：
    [/products/kodo/development-guidelines/0-appendix#1](/products/kodo/development-guidelines/0-appendix#1)

    Args:
        data: 待编码的数据，一般为字符串

    Returns:
        编码后的字符串
    """
    ret = urlsafe_b64encode(b(data))
    return s(ret)

def s(data):
    if isinstance(data, bytes):
        data = data.decode('utf-8')
    return data

def b(data):
    if isinstance(data, str):
        return data.encode('utf-8')
    return data

def __token(data):
    data = b(data)
    hashed = hmac.new(b(secret_key), data, sha1)
    return urlsafe_base64_encode(hashed.digest())


def token_of_request(url, body=None, content_type=None):
    """带请求体的签名（本质上是管理凭证的签名）

    Args:
        url:          待签名请求的url
        body:         待签名请求的body
        content_type: 待签名请求的body的Content-Type

    Returns:
        管理凭证
    """
    parsed_url = urlparse(url)
    query = parsed_url.query
    path = parsed_url.path
    data = path
    if query != '':
        data = ''.join([data, '?', query])
    data = ''.join([data, "\n"])

    if body:
        mimes = [
            'application/x-www-form-urlencoded'
        ]
        if content_type in mimes:
            data += body

    return '{0}:{1}'.format(access_key, __token(data))






bucket_name = ''

fetch_url = 'http://xxx.xxx.com/123.jpg'

key = '123.jpg'

callbackurl = 'https://xxx.xxx.com/callback'

callbackbody = '$(bucket)'

callbackbodytype = None

file_type = None

md5 = None

# z0为华东存储区域，z1为华北存储区域，z2为华南存储区域，na0为北美存储区域
zone = 'z0'

token = token_of_request("http://api-{}.qiniu.com/sisyphus/fetch".format(zone))


url = 'http://api-{}.qiniu.com/sisyphus/fetch'.format(zone)
s = json.dumps({'bucket': bucket_name, 'url': fetch_url,
                'key': key, 'callbackurl': callbackurl,
                'callbackbody': callbackbody})
headers = {"Authorization": "QBox {}".format(token)}
r = requests.post(url, data=s, headers=headers)
print(r.headers)
print(r.content)
print(r.status_code)
print("finished")
```


# 存储上传下载域名 (/faq/kodo/5869-store-uploads-and-downloads-the-domain-name)



最近更新时间: 2026-08-07 11:48:43

参考文档[存储区域](/products/kodo/2-region-endpoint-fq)


# 常见的关键参数 (/faq/kodo/7450-the-third-party-plug-in-key-parameters)



最近更新时间: 2026-08-07 11:48:43

# 什么是 AccessKey/SecretKey ？ [#什么是-accesskeysecretkey-]

`AccessKey/SecretKey`：是管理账号的一对密钥，您可以在【控制台】--【个人中心】--【密钥管理】查看。
或者您也可以访问链接查看您账号的`AccessKey/SecretKey`：[https://portal.qiniu.com/user/key](https://portal.qiniu.com/user/key)
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/FpeZ5y1RxeJQMO6CTHwIUeO3XIOo-9813ee28fdd2.webp)
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/Fl70oDUYZ5CaKurtjPnYuod-Nx-498226337f81.webp)

# 什么是 Bucket ？ [#什么是-bucket-]

`Bucket`：是您在七牛创建的存储空间的名称，您可以在【控制台】--【对象存储】--【空间管理】--【空间名称】进行查看。
或者您也可以访问链接查看：[https://portal.qiniu.com/kodo/bucket](https://portal.qiniu.com/kodo/bucket)
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/FvsA03KFu1YqUTKO9tTlUX99xsrb-1a94fc82aa25.webp)

# 什么是 Domain/Url ？ [#什么是-domainurl-]

`Domain`：是您存储空间绑定的域名，有些对接插件使用的`Url`，假如`domain` 是`a.com`，那么`url`就是 `http://a.com/`
您可以在【控制台】--【对象存储】--【空间管理】--【域名】，查看存储绑定的域名。
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/Fjw1K5MxDuyuRIdCbaiEeTymOaR9-f89c1e4c5ef4.webp)
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/Fqtf8SjdhTaTh-4F0f0G3Vw-ogQM-b8c001f42c0d.webp)

# 如何创建存储空间 [#如何创建存储空间]

创建存储空间参考[文档](/products/kodo/0-console-quickstart#step1)
**创建步骤**
您可以在【控制台】--【对象存储】--【空间管理】进行空间的创建。
或者您也可以访问链接进行创建：[https://portal.qiniu.com/kodo/bucket](https://portal.qiniu.com/kodo/bucket)
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/FgxmFW_tDDs2F7iXcjVdAa0pnYqT-71087b17ed79.webp)

# 如何绑定自定义域名 [#如何绑定自定义域名]

绑定自定义域名参考[文档](/products/cdn/the-domain-name-management/0-the-domain-name-to-access)
**绑定步骤**
1.添加自定义域名
您可以在【控制台】--【CDN】--【域名管理】，点击【添加域名】进行域名绑定
或者您也可以访问链接进行绑定：[https://portal.qiniu.com/cdn/domain](https://portal.qiniu.com/cdn/domain)
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/Fn7McbERoiRp6w0e9auoYgcDkCCU-bbbcbf16b899.webp)
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/FoMPounKN3gzfMZLmmQRzOvYBZl4-6dfc978101d9.webp)
2.在源站配置这里选择对应的存储空间进行绑定
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/FobdVaEyEiNCifXuPd6_81e1ZPKk-f315e2e717f9.webp)
3.CNAME解析配置
域名绑定好后，需要在域名厂商进行cname解析的配置，点击【如何配置CNAME】，可以查看具体配置的参考文档。
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/Fv4lW2vGcv5JMpDikjMsVCCAJ26I-66d8a05c44a7.webp)
点击【复制CNAME】，可以复制域名cname解析的记录值，复制好记录值，可以去域名厂商进行配置。
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/FitwjgqVEc4dW0s4TnbaoZ1nkpNa-f41720ed2112.webp)
点击【解析】，解析类型选择cname，主机记录为：cdn，记录值：就是在七牛控制台复制过来的数值，粘贴就好了，点【保存】。
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/FtmimOvl2FaiX5cDG3cFUbAg9AID-be4878c9bac2.webp)
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/FgQLJ1L84JPZG2fnsMBBoBwTmcCi-a52dd85de9f9.webp)
4.解析添加完成后，进行验证
Windows系统可以通过Win+R 或 点击左下角的【开始】按钮打开【开始】菜单，打开【运行】，输入cmd回车。 在命令行模式下输入nslookup 您的加速域名，例如 nslookup cdn.qingxiaoyu.vip，在结果中可以看到您复制的cname值即可。
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/FmMv8noqN40990sBbtBqRX9RqOHh-703a3e395f4d.webp)
MAC和Linux系统您可以通过如图所示的命令 dig 您的加速域名 查看，例如 dig cdn.qingxiaoyu.vip，第一条是否解析到您配置的CNAME值。
![](/docs-assets/faq/kodo/7450-the-third-party-plug-in-key-parameters/Fk_mw0L1LstvoUZBF4IRcRjuQ3GH-58c3836bb406.webp)


# 对象存储 (/faq/kodo)



## 如何获取存储文件的外链接 [#如何获取存储文件的外链接]

[查看原文](/faq/kodo/basic-use-of/access-to-resources-common-problems/1321-how-to-acquire-the-outside-storage-file-links)

本文主要说明了针对公开空间和私有空间的访问方法。

## 七牛云上传下载操作指南 [#七牛云上传下载操作指南]

[查看原文](/products/kodo/rs/8-upload)

本文介绍如何上传文件到七牛云，以及下载文件的两种方式。

## 如何上传base64编码图片到七牛云 [#如何上传base64编码图片到七牛云]

[查看原文](/products/kodo/rs/shard-to-upload)

base64 编码图片的上传接口，以及 js, java 的上传示例代码

## 七牛镜像存储使用手册 [#七牛镜像存储使用手册]

[查看原文](/faq/kodo/image-storage-common-problems/1376-seven-cattle-image-storage-instruction-manuals)

镜像存储的业务模型、配置步骤及常见问题介绍

## 上传慢、上传失败等常见FAQ [#上传慢上传失败等常见faq]

[查看原文](/faq/kodo/13086-kodo-problem-faq)

对于上传慢、上传失败等上传常见问题的处理方法

## 空间属性maxAge实现对缓存控制 [#空间属性maxage实现对缓存控制]

[查看原文](/products/kodo/kodo-console-guide/bucket-management/space-settings/1-settings-file-the-client-cache)

通过配置 maxAge 实现在规定的时效内使客户端缓存更新的效果

## 什么是样式以及样式分隔符？ [#什么是样式以及样式分隔符]

[查看原文](/products/kodo/development-guidelines/dev-the-data-processing/1-dev-the-picture-style)

样式、样式分隔符的含义及使用方法

## 什么是原图保护？ [#什么是原图保护]

[查看原文](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/media-styles/1-set-the-original-protection)

对象存储原图保护功能相关的常见问题

更多问题请查看 [官网 FAQ](/faq)。


# 负载均衡常见问题 (/faq/qvm/5144-the-common-problems-in-load-balancing)



最近更新时间: 2020-08-13 17:54:46

# 问题：负载均衡均衡的是什么？ [#问题负载均衡均衡的是什么]

<br />

负载均衡是按特定调度算法把流量分发到后端服务器上，其中：

* 四层（TCP 和 UDP）是基于连接做流量调度。TCP 和 UDP 创建一个 socket 访问负载均衡实例，这个源和目的 IP 和端口就是一个连接。

* 七层（HTTP/HTTPS）是基于请求做调度。比如 http get 请求访问一个页面。

<br />

# 问题：为什么请求不均衡？ [#问题为什么请求不均衡]

<br />

负载均衡请求不均衡的原因可能有以下几种：

* 开启了会话保持功能

配置了会话保持，当访问负载均衡实例的客户端又很少时，容易导致不均衡，尤其在使用少量客户端对负载均衡进行测试的时候。比如 TCP 监听，开启了会话保持（四层是基于来源地址做会话保持），使用一台客户端对负载均衡实例进行压测，就会导致不均衡。

* 健康检查异常

后端服务器的健康建状态异常会导致不均衡，尤其在压测的时候容易忽略后端服务器的健康检查状态，如果有后端服务器健康检查失败或者健康检查状态经常跳跃会导致不均衡。

* TCP Keepalive 保持长连接

后端服务器有些开启了 TCP Keepalive 保持长连接，有些没有开启，则连接会在保持长连接的后端服务器上堆积，造成不均衡。

排查和解决方法：

* 查看各台后端服务器的权重是否相同

* 在相关时间段内是否有健康检查失败或波动现象，查找波动的原因；或者健康检查没有配置正确的响应码2xx，3xx导致了健康检查显示正常，但后端服务有异常

* 是否同时使用了加权最小连接数（WLC）调度方式和会话保持，如果是，尝试改为加权加权轮询（WRR）算法和会话保持。

<br />

# 问题：负载均衡各监听连接超时时间是多少？ [#问题负载均衡各监听连接超时时间是多少]

<br />

| 监听       | 超时时间  |
| -------- | ----- |
| TCP 监听   | 900 秒 |
| UDP 监听   | 90 秒  |
| HTTP 监听  | 60 秒  |
| HTTPS 监听 | 60 秒  |


# 迁移工具常见问题 (/faq/qvm/5145-the-common-problems-in-migration-tool)



最近更新时间: 2020-08-13 17:54:46

<a id="step05" />

# 日志错误 [#日志错误]

<br />

| 问题                                    | 故障排查                                                                                                                                                                                                                                                                                                  |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Linux 服务器日志错误提示`check rsync failed`   | 请检查系统是否已安装 rsync 组件                                                                                                                                                                                                                                                                                   |
| Linux 服务器日志错误提示`check virtio failed`  | 请检查系统是否安装 virtio 驱动                                                                                                                                                                                                                                                                                   |
| Linux 服务器日志错误提示`check selinux failed` | 请检查是否已禁用 SElinux。你可以运行 setenforce 0 临时关闭 SELinux                                                                                                                                                                                                                                                      |
| Linux 服务器日志错误提示`Do Grub Failed`       | 请检查源服务器是否安装了系统引导程序 GRUB（GRand Unified Bootloader）。你可以[安装 1.9 以上版本的系统引导程序 GRUB ](/faq/qvm/the-remote-connection/5146-how-to-install-grub-for-linux-server)后重试                                                                                                                                          |
| 日志错误提示`TimeStamp`                     | 请检查系统时间是否为正确时间                                                                                                                                                                                                                                                                                        |
| 日志错误提示`Unknown Error`                 | 请检查配置文件 user\_config.json 中参数 platform 取值是否正确                                                                                                                                                                                                                                                         |
| 日志错误提示`Permission denied`             | 日志文件提示如`rsync: send_files failed to open "…": Permission denied (13)`的错误信息时，表明迁云工具无权访问该目录或文件夹，导致 rsync 失败。此时你可以通过配置 rsync\_excludes\_linux.txt 或者 Rsync/etc/rsync\_excludes\_win.txt 过滤该目录或文件夹，然后重试                                                                                                   |
| 日志错误提示`NotEnoughBalance`              | 中转实例的默认付费模式为按量付费，你的账号余额不足时，无法顺利迁云。你需要更新账户状态后重试。                                                                                                                                                                                                                                                       |
| 日志错误提示`InvalidImageName.Duplicated`   | 指定的参数 image\_name 不能与你已有的镜像名称重复                                                                                                                                                                                                                                                                       |
| 日志错误提示`Connect to Server Failed`      | 该错误表示无法连接中转实例。你可以按以下步骤检查：（1）查看日志文件详细信息（2）中转实例状态是否正常（3）本地网络服务是否正常。迁云工具需要访问 80、443、8703 和 8080 通信端口，请确保你的服务器已经放行这些端口（4）问题解决后，再次运行主程序重试                                                                                                                                                                  |
| 日志错误提示`Do Rsync Disk x Failed`        | 该错误表示文件传输中断。你可以按以下步骤检查：（1）查看错误日志文件详细信息。如果错误日志文件中多次出现\*\* return: 3072 **或** return: 7680 \*\*信息提示，请确认源服务器数据库服务或者容器服务是否未开启状态，如 Oracle、MySQL、MS SQL Server、MongoDB 和 Docker 等服务。你需要先暂停服务或者排除相关数据文件目录后再迁云（2）中转实例状态是否正常（3）本地网络服务是否正常。迁云工具需要访问 80、443、8703 和 8080 通信端口，请确保你的服务器已经放行这些端口。（4）问题解决后，再次运行主程序重试 |

说明：

* [迁云工具](/products/qvm/1-server-migration-qiniu)支持断点恢复，文件传输过程支持断点续传。一般情况下如果主程序异常中断或提示迁移不成功，故障排查处理完问题后，你可以再次运行主程序恢复迁云工作。

* 成功迁移 Windows Server 2008 及以上版本的 Windows 服务器，启动实例后你需要先使用 Reset File Permission 工具修复默认文件系统权限，以保证实例服务及组件正常。

<br />

<a id="step01" />

# 问题：迁移 Windows 服务器后，启动实例发现数据盘缺失或者盘符错乱？ [#问题迁移-windows-服务器后启动实例发现数据盘缺失或者盘符错乱]

<br />

情况一：如果数据盘盘符缺失，你可以打开磁盘管理器，重新添加即可。

**1. **打开**控制面板 > 系统与安全 > 管理工具 > 计算机管理**

**2. **单击左侧菜单栏中的**磁盘管理**，找到并右击盘符缺失的数据盘，选择**更改驱动器和路径**

**3. **单击**添加**并添加数据盘盘符

**4. **选择**装入以下空白 NTFS 文件夹中**，单击**确定**即可

情况二：如果数据盘盘符错乱，你可以打开磁盘管理器，重新更改即可。

**1. **打开**控制面板 > 系统与安全 > 管理工具 > 计算机管理**

**2. **单击左侧菜单栏中的**磁盘管理**，找到并右击盘符缺失的数据盘，选择**更改驱动器和路径**

**3. **单击**更改**并更改数据盘盘符

**4. **选择**分配以下驱动器号**，单击**确定**即可

<br />

<a id="step02" />

# 问题：迁移 Linux 服务器后，启动实例发现原数据盘目录下没有数据？ [#问题迁移-linux-服务器后启动实例发现原数据盘目录下没有数据]

<br />

迁移带数据盘的 Linux 服务器后，启动实例时默认不挂载数据盘。你可以在启动 QVM 实例后运行`ls /dev/vd*`命令查看数据盘设备，根据实际需要手动挂载，并编辑`/etc/fstab`配置开机自动挂载。

<br />

<a id="step03" />

# 问题：迁移 Linux 服务器后，根据该自定义镜像创建的实例为何不能启动？ [#问题迁移-linux-服务器后根据该自定义镜像创建的实例为何不能启动]

<br />

（1）检查驱动。创建 I/O 优化的实例时，请确保源服务器已经安装 virtio 驱动。

（2）检查源系统引导配置是否正确。

（3）如果你的源服务器系统是内核版本较低的 CentOS 5 或者 Debian 7，而且自带的 GRUB 程序版本低于 1.99，你可以[安装 1.9 以上版本的系统引导程序 GRUB ](/faq/qvm/the-remote-connection/5146-how-to-install-grub-for-linux-server)后重试。

<br />

<a id="step04" />

# 问题：启动 Others Linux 实例后，网络服务不正常？ [#问题启动-others-linux-实例后网络服务不正常]

<br />

导入 Others Linux 类型镜像时，QVM 不会对该自定义镜像所创建的实例做任何配置工作，包括相关的网络配置、SSH 配置等。此时，你需要自行修改系统相关网络配置。迁云工具生成的镜像网络配置有变化，默认以 DHCP（Dynamic Host Configuration Protocol）的方式获取 IP 地址。如果网络配置失败，请提交工单联系技术支持。


# 后端服务器常见问题 (/faq/qvm/5147-the-backend-server-common-problems)



最近更新时间: 2026-09-30 10:36:52

# 问题：负载均衡实例最多支持添加多少 QVM 实例？ [#问题负载均衡实例最多支持添加多少-qvm-实例]

<br />

默认每个负载均衡实例可以添加 200 个 QVM 实例，一个 QVM 实例可以被 50 个负载均衡实例关联。**但是**如果你需要添加更多 QVM 实例，请提交工单申请。通过审核后，为你提升配额。

为了保证你对外服务的稳定与高效，建议你根据业务分类或应用服务的模块划分将提供不同服务或执行不同任务的应用服务器配置在不同的负载均衡实例上。

<br />

# 问题：负载均衡运行中是否可调整服务器数量？ [#问题负载均衡运行中是否可调整服务器数量]

<br />

可以

你可以在任意时刻增加或减少负载均衡的后端服务器实例数量并且支持不同服务器实例之间的切换。但是为了保证你对外服务的稳定，确保在执行上述操作时，开启了负载均衡的健康检查功能并保证负载均衡后端至少有一台正常运行的服务器实例。

<br />

# 问题：后端服务器实例为什么访问不了负载均衡服务？ [#问题后端服务器实例为什么访问不了负载均衡服务]

<br />

这和负载均衡 TCP 的实现机制有关。在四层 TCP 协议服务中，不支持后端服务器实例既作为 Real Server 又作为客户端向所在的负载均衡实例发送请求。因为返回的数据包只在云服务器内部转发，不经过负载均衡，所以在后端服务器实例上去访问负载均衡的服务地址是不通的。

<br />

# 问题：QVM 实例在接入负载均衡服务前添加了白名单，对负载均衡服务有影响么？ [#问题qvm-实例在接入负载均衡服务前添加了白名单对负载均衡服务有影响么]

<br />

若 QVM 实例在接入负载均衡前设置了访问白名单，那么接入负载均衡后需要将负载均衡的白名单添加到 QVM 实例中，否则可能会引起网站`403`报错。

需要添加的负载均衡地址包括 100.64.0.0/10、10.158.0.0/16、10.159.0.0/16 和 10.49.0.0/16。

<br />

# 问题：为什么有 10 或 100 开头的 IP 在频繁访问 QVM 实例？ [#问题为什么有-10-或-100-开头的-ip-在频繁访问-qvm-实例]

<br />

负载均衡系统除了会通过系统服务器的内网 IP 将来自外部的访问请求转到后端 QVM 实例之外，还会对 QVM 实例进行健康检查和可用性监控，这些访问的来源都是由负载均衡系统发起的。

负载均衡系统的地址段为 100.64.0.0/10、10.158.0.0/16、10.159.0.0/16 和 10.49.0.0/16，所以会有很多 10或 100 开头的 IP 地址访问 QVM 实例。

为了确保你对外服务的可用性，确保对上述地址的访问配置了放行规则。

<br />

# 问题：要使用负载均衡服务，QVM实例是否需要进行特殊配置？ [#问题要使用负载均衡服务qvm实例是否需要进行特殊配置]

<br />

添加到负载均衡实例的后端 QVM 实例，一般不需要进行特别的配置。

但是，如果后端 QVM 实例的操作系统为 Linux 并且使用了 TCP 监听，确保系统配置文件`/etc/sysctl.conf`中以下三个配置的值为零：

```
net.ipv4.conf.default.rp_filter = 0
net.ipv4.conf.all.rp_filter = 0
net.ipv4.conf.eth0.rp_filter = 0
```

如果部署在同一内网网段下的 QVM 实例之间有通信需求，需要检查如下参数的配置是否正确：

```
net.ipv4.conf.default.arp_announce =2
net.ipv4.conf.all.arp_announce =2
```

更改配置后，执行 sysctl -p 更新配置。

<br />

# 问题：QVM 实例设置权重的作用是什么？ [#问题qvm-实例设置权重的作用是什么]

<br />

权重比越高的 QVM 实例将被分配到更多的访问请求，你可以根据后端 QVM 实例的对外服务能力和需求来区别设定。

假设负载均衡池中的 A 和 B 两台 QVM 实例的权重均配置成 100 和均配置成 50 都是一样的，在 A 和 B 两台 QVM 实例健康检查状态均正常的情况下，QVM 实例 A 和 B 均分前端请求的流量。但是如果 A 和 B 的权重分别设置为 10 和 100，在 A 和 B 两台 QVM 实例健康检查状态均正常的情况下，A 承担 10/(10+100) 的流量，B 承担 100/(10+100) 的流量。

如果你同时开启了会话保持功能，有可能会造成后端 QVM 实例访问不均衡，建议你暂时关闭会话保持功能再观察一下是否依然存在这种情况。

当负载均衡分发到后端 QVM 实例的请求不均匀时，参考以下方法检查处理：

* 统计一个时间段内后端 QVM 实例的 Web 服务访问日志的数据量。访问日志查看方法：

* Nginx 和 Apache：打开日志目录`/access.log`

* IIS：打开 IIS 管理界面，鼠标放在需要设置开启日志的站点上，单击右键，选择**属性**，选择**网站**选项卡，单击**启用日志记录**

* 按照负载均衡的配置，对比多个 QVM 实例日志的数量是否有差距。

  如果设置了会话保持，需要剥离相同 IP 的访问日志。如果负载均衡配置了权重，要根据权重比例计算日志中访问比例是否正常。

<br />

# 问题：服务器状态异常，如何回退到异常之前的状态？ [#问题服务器状态异常如何回退到异常之前的状态]

<br />

无法回退
如果您之前有创建过系统快照或者镜像，基于镜像重新创建实例即可。

<br />

# 问题：突发型机器能不能升级到经济型 [#问题突发型机器能不能升级到经济型]

<br />

不可以，建议主机生成镜像，然后基于镜像重新生成主机实例，原按量主机可以控制台直接释放，包年包月的主机需要提交工单申请释放退款


# 云主机反向解析的申请流程 (/faq/qvm/5390-cloud-host-reverse-dns-application-process)



最近更新时间: 2020-08-13 17:54:46

qvm 反向解析需要提交工单由售后工程师操作，提交工单时请注明 主机所在区域（北京、上海等）和 ip 对应的解析域名。

FAQ:

Q: 1个IP地址是否允许指向多个反解域名 ?

A:  一个IP只允许对应一个反解域名

Q: 设置提交后，如何测试是否生效？

A: 提交后2分钟后会在权威DNS上生效, 可以使用 dig 命令查看

\`
dig -x 47.254.32.63 +short
gw8.4cun.com.

\`


# Linux上NFS性能只有几MB速度 (/faq/qvm/5608-linux-on-nfs-performance-are-only-a-few-mb-speed)



最近更新时间: 2020-08-13 17:54:46

Linux nfs客户端对于同时发起的NFS请求数量进行了控制，若该参数配置较小会导致IO性能较差，请查看该参数：

```bash

cat /proc/sys/sunrpc/tcp_slot_table_entries

```

默认编译的内核该参数最大值为256，可适当提高该参数的值来取得较好的性能，请以root身份执行以下命令：

```bash

echo "options sunrpc tcp_slot_table_entries=128" >> /etc/modprobe.d/sunrpc.conf
echo "options sunrpc tcp_max_slot_table_entries=128" >>  /etc/modprobe.d/sunrpc.conf
sysctl -w sunrpc.tcp_slot_table_entries=128

```

修改完成后，您需要重新挂载文件系统或重启机器。


# 安全组常用端口和特殊端口解封 (/faq/qvm/6656-security-group-common-ports-and-special-unsealed)



最近更新时间: 2020-08-13 17:54:46

通过了解典型应用的默认端口，您可以更准确地添加或修改安全组规则。

# **使用背景** [#使用背景]

添加安全组规则时，您必须指定通信端口或端口范围，然后安全组根据允许或拒绝策略决定是否转发数据到ECS实例。例如，使用Xshell客户端远程连接QVM实例时，当安全组检测到从公网或内网有SSH请求，会同时检查入方向上发送请求的设备的IP地址是否在允许放行的安全组规则中、22端口是否开启，只有匹配到的安全组规则允许放行该请求时，方才建立数据通信。

另外部分运营商判断\*\*端口25、135、139、444、445、5800、5900等为高危端口，并默认屏蔽。\*\*即使您添加的安全组规则放行了这些端口，在受限地区仍无法访问。建议您修改为其它非高危端口承载业务。

# **常用端口** [#常用端口]

参见下表查看常用端口的使用说明。

| 端口          | 服务                                     | 说明                                                                                                                       |
| ----------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| 21          | FTP                                    | FTP服务所开放的端口，用于上传、下载文件。                                                                                                   |
| 22          | SSH                                    | SSH端口，用于通过命令行模式或远程连接软件（例如PuTTY、Xshell、SecureCRT等）连接Linux实例。                                                              |
| 23          | Telnet                                 | Telnet端口，用于Telnet远程登录ECS实例。                                                                                              |
| 25          | SMTP                                   | SMTP服务所开放的端口，用于发送邮件。基于安全考虑，QVM实例25端口默认受限，如需解封，[**请参见TCP 25端口控制台解封申请**](#info)。                                           |
| 80          | HTTP                                   | 用于HTTP服务提供访问功能，例如，IIS、Apache、Nginx等服务。                                                                                   |
| 110         | POP3                                   | 用于POP3协议，POP3是电子邮件收发的协议。                                                                                                 |
| 143         | IMAP                                   | 用于IMAP（Internet Message Access Protocol）协议，IMAP是用于电子邮件的接收的协议。                                                            |
| 443         | HTTPS                                  | 用于HTTPS服务提供访问功能。HTTPS是一种能提供加密和通过安全端口传输的一种协议。                                                                             |
| 1433        | SQL Server                             | SQL Server的TCP端口，用于供SQL Server对外提供服务。                                                                                    |
| 1434        | SQL Server                             | SQL Server的UDP端口，用于返回SQL Server使用了哪个TCP/IP端口。                                                                            |
| 1521        | Oracle                                 | Oracle通信端口，ECS实例上部署了Oracle SQL需要放行的端口。                                                                                   |
| 3306        | MySQL                                  | MySQL数据库对外提供服务的端口。                                                                                                       |
| 3389        | Windows Server Remote Desktop Services | Windows Server Remote Desktop Services（远程桌面服务）端口，可以通过这个端口使用软件连接Windows实例。                                                |
| 8080        | 代理端口                                   | 同80端口一样，8080端口常用于WWW代理服务，实现网页浏览。如果您使用了8080端口，访问网站或使用代理服务器时，需要在IP地址后面加上:8080。安装Apache Tomcat服务后，默认服务端口为8080。              |
| 137、138、139 | NetBIOS协议                              | <br />- 137、138为UDP端口，通过网上邻居传输文件时使用的端口。<br />- 139通过这个端口进入的连接试图获得NetBIOS/SMB服务。<br />NetBIOS协议常被用于Windows文件、打印机共享和Samba。 |

<a id="info" />

# **特殊端口——TCP25端口解封申请** [#特殊端口tcp25端口解封申请]

TCP 25端口的出方向封禁可能影响您通过TCP 25 端口连接第三方邮件服务商的SMTP服务器对外部发送邮件。如需解封，请按照以下模板[提交工单](https://support.qiniu.com/tickets/new/form?category=%E5%85%B6%E4%BB%96%E7%B1%BB%E5%92%A8%E8%AF%A2\&space=%E4%BA%91%E4%B8%BB%E6%9C%BA)。

```
模板：

您好：
    希望解封服务器邮件通信端口：
    解封原因及理由(下面仅为示例，请按照您的详细情况说明)：
			1. 产品是邮箱客户端产品，须要用到25和110号端口，否则邮件系统不能使用，同时服务器会通过邮件，为我们的用户发送一些版本更新等通知性邮件
			2. 服务器端通过邮件将我们用户反馈的意见，转发到技术人员邮箱，方便技术人员及时处理问题；

解封服务器ID及IP:
实例ID: xxx
对应IP：xxx

我们同意并承诺：不发送垃圾邮件，如果其IP被国际反垃圾组织列黑，七牛云有权立即停止其服务。
这些端口不会做其他用途，请放心开通这些邮箱端口，谢谢!
```

说明：

1. 一般情况下，在您提交解封申请一个工作日后，七牛云会根据您提交的申请理由进行审核，并将审核结果以邮件的方式通知您。


# noresvport挂载参数问题检查及整改步骤 (/faq/qvm/6912-inspection-and-rectification-steps-noresvport-mount-parameters-problem)



最近更新时间: 2020-08-13 17:54:46

本文介绍如何检查并修复 noresvport 挂载参数问题。

> 说明：只适用于Linux系统的用户，Windows用户请忽略。

# **第一步：检查是否使用 noresvport 挂载参数** [#第一步检查是否使用-noresvport-挂载参数]

1. 在 QVM 实例上下载check\_noresvport.py检查脚本。

```
wget -N https://code.aliyun.com/nas_team/nas-client-tools/raw/master/linux_client/check_noresvport.py -P /tmp/
```

2. 使用python执行检查脚本。

```
python2.7 /tmp/check_noresvport.py
```

如果脚本输出：本台 ECS 无须处理 noresvport 问题，则无须处理。否则请执行第二步： noresvport 参数修复方法。

# **第二步：noresvport参数修复方法** [#第二步noresvport参数修复方法]

建议在业务低峰进行修复。

1. 如果使用 QVM 直接挂载NAS，请使用参数-r再次执行检查脚本。

```
python2.7 /tmp/check_noresvport.py -r
```

# **第三步：更新自动挂载配置** [#第三步更新自动挂载配置]

* 如果配置过自动挂载，请更新自动挂载参数，加入 noresvport 挂载参数。详情请参见[Linux自动挂载NFS文件系统](/products/qvm/nas/section-2djvgu/6-automatically-mount-nfs-file-systems)。
* 如果没有配置过自动挂载，跳过此步骤。

修复完成后，**请再次执行第一步：检查是否使用 noresvport 挂载参数**，确认修复生效。如果仍有问题请及时[提交工单](https://support.qiniu.com/tickets/new/form?category=%E5%85%B6%E4%BB%96%E7%B1%BB%E5%92%A8%E8%AF%A2\&space=%E4%BA%91%E4%B8%BB%E6%9C%BA)。

# **常见问题** [#常见问题]

1.为什么要使用 noresvport 参数挂载 NAS？不重新挂载会有什么后果？
答：如果发生网络切换或者后端服务的 HA 倒换，小概率会造成 NFS 文件系统阻塞，则可能需要几分钟时间连接才会自动恢复，极端情况下甚至需要重启 QVM 才能恢复。使用 noresvport 参数后，恢复几秒即可自动完成恢复。

2.什么情况会引发网络切换或者后端服务的 HA 倒换？
答：NAS 服务是稳定的，网络切换或者后端服务的HA倒换都是罕见情况。后端服务升级会触发上述切换，但导致客户端阻塞的概率很低，并且在升级之前我们会提前通知相关集群的用户，留出充足时间使用 noresvport 参数。其他可能引发切换的场景，还有负载均衡调整、服务端硬件故障等情况，有一定的不可预测性，所以即使服务端没有升级安排，也请尽快使用 noresvport 参数避免这样的风险。

3.为什么需要重新挂载？还有没有其他的方案？
答。需要重新挂载的原因是要把之前没有使用 noresvport 参数的 TCP 连接断掉，然后使用 noresvport 参数挂载时，会建立新的 TCP 连接。为了把旧的  TCP 连接断掉，就必须把 NAS 相关的业务都停掉，然后执行umount卸载。如果不希望重新挂载，可以考虑新建NAS挂载点，使用 noresvport 参数挂载到新的本地路径，然后把业务进程逐步迁移过去，最后废弃老的挂载路径和挂载点。


# 云主机 (/faq/qvm)



## 迁移工具常见问题 [#迁移工具常见问题]

[查看原文](/faq/qvm/5145-the-common-problems-in-migration-tool)

迁移工具常见问题

## 负载均衡常见问题 [#负载均衡常见问题]

[查看原文](/faq/qvm/5144-the-common-problems-in-load-balancing)

负载均衡常见问题

## 后端服务器常见问题 [#后端服务器常见问题]

[查看原文](/faq/qvm/5147-the-backend-server-common-problems)

后端服务器常见问题

## 为什么云主机连接不上 Redis？ [#为什么云主机连接不上-redis]

[查看原文](/faq/qvm/the-remote-connection/5099-connection-on-redis)

为什么云主机连接不上 Redis？

## 云主机反向解析的申请流程 [#云主机反向解析的申请流程]

[查看原文](/faq/qvm/5390-cloud-host-reverse-dns-application-process)

云主机反向解析的申请流程

## 七牛主机礼品卡使用介绍 [#七牛主机礼品卡使用介绍]

[查看原文](/faq/qvm/qvm-other-faq/5675-seven-niuyun-host-gift-card-use-is-introduced)

本文主要介绍七牛云主机礼品卡的使用.

## 如何为 Linux 服务器安装 GRUB [#如何为-linux-服务器安装-grub]

[查看原文](/faq/qvm/the-remote-connection/5146-how-to-install-grub-for-linux-server)

如何为 Linux 服务器安装 GRUB

## Linux上NFS性能只有几MB速度 [#linux上nfs性能只有几mb速度]

[查看原文](/faq/qvm/5608-linux-on-nfs-performance-are-only-a-few-mb-speed)

本文将介绍如何优化NFS挂在NAS速度慢的问题

更多问题请查看 [官网 FAQ](/faq)。


# 视频监控常见问题 (/faq/qvs/13577-video-surveillance-faqs)



最近更新时间: 2026-09-14 18:39:30

Q: 定向流量卡、物联网卡、摄像头、监控设备需要添加定性的白名单IP，这些IP是什么？
A: 国内空间：SIP 可添加 `121.41.37.111 、47.98.160.100`
流媒体&对讲服务器IP（主要是拉流观看和语音对讲）：

* 华东视频监控空间：`114.230.92.187、61.160.198.6、223.112.202.242、223.111.129.148`
* 华南视频监控空间：`183.60.220.78、183.60.150.21`
* 华北视频监控空间：`111.62.101.178、124.236.65.35、121.29.19.51`


# 视频监控-时间防盗链 (/faq/qvs/6819-preventing-hotlinking)



最近更新时间: 2026-08-18 11:57:15

时间戳防盗链通过使用约定的加密字符串来对具有访问有效期的资源链接进行一些加密计算得到一个 token 值，然后访问外链里面带上这个 token 和截止时间戳去访问七牛qvs节点，七牛qvs节点会用同样的算法来计算访问链接是否合法，如果不合法则返回403 Forbidden，否则返回所要访问的资源。

# **签算token说明** [#签算token说明]

**操作步骤：**

1. 获取鉴权 key
   操作说明：请参考[域名管理](/products/qvs/user-guide/0-namespace-management#2)
   开启时间防盗链开关，设置key即可，可自动生成亦可手动输入。
   ![image.png](/docs-assets/faq/qvs/6819-preventing-hotlinking/Ftx0nLnkvucDZBDJrBOaeD3nUaCd-41c8ed721f82.webp)
2. 设置过期时间(unixtimestamp)
3. 签名token生成过程: 通过上面两步生成中间串 s = key+url\_base64\_encode(path)+e  key为第一个步获取的key, path为为请求流的播放path,e为第二步中unix 时间戳的十六进制表示, 然后
   token = md5(s).to\_lower(), 其中 to\_lower() 表示生成的 md5 字符串用小写字母表示

**签名参数传递方式：**
例如播放地址是：
[http://qvs-live-hdl.qiniu.com:2045/3k5ndkiqvggnz/stream1.flv](http://qvs-live-hdl.qiniu.com:2045/3k5ndkiqvggnz/stream1.flv)

最终形成的播放地址是：
[http://qvs-live-hdl.qiniu.com:2045/3k5ndkiqvggnz/stream1.flv?token=xxxx\&e=xxxx](http://qvs-live-hdl.qiniu.com:2045/3k5ndkiqvggnz/stream1.flv?token=xxxx\&e=xxxx)

**参考实例:**
需要获取一个当前时间5分钟后过期的防盗链签名 url.

播放地址为: [http://qvs-live-hdl.qiniu.com:2045/3k5ndkiqvggnz/stream1.flv](http://qvs-live-hdl.qiniu.com:2045/3k5ndkiqvggnz/stream1.flv)
portal上已经开启了时间戳防盗链, 设置了主密钥key为123
假设当前时间的时间戳为: 1590468504
过期时间是5分钟后, 所以过期时间戳为: 1590468504 + 5 \* 60 = 1590468804
换算为16进制: 5ecca0c4 (一定要全小写)
即参数 e=5ecca0c4

中间字符串的生成规则是: S= key + url\_base64\_encode(path) + t
key 是设置时输入的密钥, 这里是 key=123
path 是 URL 中的 path 部分, URL是[http://qvs-live-hdl.qiniu.com:2045/3k5ndkiqvggnz/stream1.flv](http://qvs-live-hdl.qiniu.com:2045/3k5ndkiqvggnz/stream1.flv), 则 path=/3k5ndkiqvggnz/stream1.flv

所以 S=123LzNrNW5ka2lxdmdnbnovc3RyZWFtMS5mbHY=5ecca0c4

\*\* 注：本文提到的 url\_base64\_encode 算法，都是base64安全编码，下同\*\*

再用 md5算法 token = md5(S).to\_lower()
得到:
token=74e0b06fce024b4743bca95bd62b2fe0
e=1590468804
所以最终生成的5分钟后过期的播放地址是: [http://qvs-live-hdl.qiniu.com:2045/3k5ndkiqvggnz/stream1.flv?token=74e0b06fce024b4743bca95bd62b2fe0\&e=1590468804](http://qvs-live-hdl.qiniu.com:2045/3k5ndkiqvggnz/stream1.flv?token=74e0b06fce024b4743bca95bd62b2fe0\&e=1590468804)

# **快速接入** [#快速接入]

为了方便用户可以快速的接入测试，视频监控portal中提供了地址生成器，可以快速生成带时间戳的防盗链的推拉流地址。

**说明：** 需要保证的选择的域名已经开启了时间防盗链功能，否则生成的地址为不带时间防盗链的地址。
![](/docs-assets/faq/qvs/6819-preventing-hotlinking/FoQeUBzcGsQOuwgr6COUklihrzPF-541df4ae692b.webp)


# 如何进行视频流的录制和截图 (/faq/qvs/6873-how-to-make-recording-and-screenshots)



最近更新时间: 2020-07-28 19:26:03

本文主要是讲述如何进行视频流的录制和截图

## **准备工作：** [#准备工作]

**已注册七牛开发者平台**
若尚无七牛开发者平台账号，需要先进行注册；访问[七牛官网](https://www.qiniu.com/)，点击右上角的[注册](https://portal.qiniu.com/signup)，进行七牛帐号注册。

**开通存储服务**
如果需要对监控视频流进行录制或者截图，需要使用存储服务，用于存储回看录制的视频和截图。故需要开通存储服务，创建对应的bucket，详情请参照[创建存储空间](/products/kodo/0-console-quickstart#step1)

**已创建空间**
若尚未创建空间，需要先完成空间的创建，通过portal方式创建请参考[【创建空间】](/products/qvs/user-guide/0-namespace-management#1)；通过API创建请参考[【创建空间API】](/products/qvs/space-management/0-create-namespace)

## **方式一：** [#方式一]

通过portal配置。
&#x2A;*操作步骤：**
1.登录[七牛开发者平台](https://sso.qiniu.com/?client_id=PIapUKqa3u6S24H868BelwrG0OFu8dS7AxVQ8oz8HznLXhgrl2BnjaO9cs9LzxK2\&redirect_url=https:%2F%2Fportal.qiniu.com%2Fapi%2Fgaea%2Fsso%2Fsignin%3Fredirect%3D%252Fcreate)。
2.模板管理->添加录制模板->配置模板，详情可参考[【创建录制模板】](/products/qvs/user-guide/template-management/0-recording-the-template)或[【创建截图模板】](/products/qvs/user-guide/template-management/1-screenshot-of-the-template)
3.空间管理->配置->模板配置->编辑->配置对应的录制和截图模板
4.使用获取到的推流地址进行测试
5.推流一段时间后可在“视频流管理”的“录制回放”中查看已录制文件

## **方式二：** [#方式二]

通过API进行配置。
&#x2A;*操作步骤：**
1.创建模板并获取模板id,模板类型可为录制或截图，请参考[【创建模板API】](/products/qvs/template-management/0-create-template)
2.给空间绑定模板，请参考[【更新空间API】](/products/qvs/space-management/2-update-namespace)
参考请求示例：

```
curl --request PATCH \
  --url http://qvs.qiniuapi.com/v1/namespaces/2akrars3vpsxa \
  --header 'authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:u372aQV0359mzwTVGxn22sRgFYc=' \
  --header 'content-type: application/json' \
  --data '{"operations":[{"key":"recordTemplateId","op":"replace","value":"p2cxr0r8ydxj"}]
}'
```

3.使用获取到的推流地址进行测试
4.推流一段时间后可查询录制记录，请参考[【查询录制记录API】](/products/qvs/recording/2-query-recordhistories)
*注：截图步骤和录制操作步骤类似*


# 视频监控-流状态回调使用说明 (/faq/qvs/7022-about-the-back-flow-state)



最近更新时间: 2020-12-09 11:29:12

1.如何触发流状态回调？
空间中需要配置回调地址，这是前提条件。具体操作如下

* 通过api创建或者更新空间的客户，可以填充callBack字段，该字段就是回调地址，例如该字段形式为 [www.qiniu.com/callback](http://www.qiniu.com/callback) 或者 11.11.11.11:8888/callback
* 用户也可以通过视频监控(qvs)的官方控制台，在portal中，添加回调地址(后续的portal版本会添加对流状态回调的支持)

2.触发回调的时机和格式？

* 在流连接和断开时，会分别触发回调
* 回调的格式，采用http post请求。body采用json编码，并固定以下几个字段，根据实际情况会调整，并保持兼容。

```
{
  "type": "stream"          // 回调类型
	"nsId": "xx",            // 空间id, (字符串类型)
	"streamId": "xx",        // 流id， (字符串类型)
	"streamState": 1,        // 0:流断开 1:流连接, (整型)
	"timeSec": xx,   // streamState为0,代表流断开的时间戳；streamState为1,代表流连接的时间戳，(整型)
	"reqId": "xx" //唯一标示，(字符串类型)
}
```

* 视频监控(qvs)回调,需要客户侧具备接受http post请求和解析的能力。
* 视频监控(qvs)回调的http post示例如下

```
curl -X POST \
--url http://11.11.11.11:8888/callback \
-H "Content-Type:application/json" \
--data '{"type": "stream", "nsId": "xxx","streamId": "xxx", "streamState": xxx, "timeSec": xxx, "reqId": "xxx"}'

其中url"11.11.11.11:8888/callback"就是客户在空间中已配置好的回调地址
```


# 视频监控-国标ID命名规范 (/faq/qvs/7027-gb-id-naming-conventions)



最近更新时间: 2026-05-06 17:51:01

国标ID由中心编码（8位）、行业编码（2位）、类型编码（3位）和序号（7位）四个码段共20位十进制数字字符构成，即系统编码 =中心编码 + 行业编码 + 类型编码 + 序号。
国标ID命名的详细说明见**详细编码规则**。其中：

* 中心编码：指用户或设备所归属的监控中心的编码，按照监控中心所在地的行政区划代码确定，当不是基层单位时空余位为0。行政区划代码采用GB/T 2260-2007规定的行政区划代码表示。
* 行业编码：是指用户或设备所归属的行业，行业编码对照详见**行业编码规范**。
* 类型编码指定了设备或用户的具体类型，其中的前端设备包含公安系统和非公安系统的前端设备，终端用户包含公安系统和非公安系统的终端用户。

# **详细编码规则** [#详细编码规则]

![](/docs-assets/faq/qvs/7027-gb-id-naming-conventions/Fuj02qI3ly7-hr4IDO1N4_4WZLjR-5e69b87eb793.webp)
![](/docs-assets/faq/qvs/7027-gb-id-naming-conventions/FoPgz7dWKKh3OWOdI_kJTIVt8xXo-77f88fec4496.webp)
![](/docs-assets/faq/qvs/7027-gb-id-naming-conventions/Fi8leTOJKtQgiWZRujHp9D0qf04D-3af62496d7b7.webp)

# **行业编码规范** [#行业编码规范]

![](/docs-assets/faq/qvs/7027-gb-id-naming-conventions/FqLf9tzBhlZ4XlXwzs_JV4vrBQ6q-abf86a59a752.webp)


# 视频监控 (/faq/qvs)



## 视频监控-时间防盗链 [#视频监控-时间防盗链]

[查看原文](/faq/qvs/6819-preventing-hotlinking)

视频监控（qvs）时间戳防盗链

## 如何进行视频流的录制和截图 [#如何进行视频流的录制和截图]

[查看原文](/faq/qvs/6873-how-to-make-recording-and-screenshots)

如何进行视频流的录制和截图

## 视频监控-流状态回调使用说明 [#视频监控-流状态回调使用说明]

[查看原文](/faq/qvs/7022-about-the-back-flow-state)

关于流状态回调的说明

## 视频监控-国标ID命名规范 [#视频监控-国标id命名规范]

[查看原文](/faq/qvs/7027-gb-id-naming-conventions)

视频监控-国标ID命名规范

更多问题请查看 [官网 FAQ](/faq)。


# SSL常见问题FAQ (/faq/ssl/13476-Q&A)



最近更新时间: 2026-09-15 13:21:21

# SSL 证书常见问题与解决方案 [#ssl-证书常见问题与解决方案]

## 问题 1：域名高风险导致证书签发失败 [#问题-1域名高风险导致证书签发失败]

**原因**：域名存在高风险，需要自行处理好安全风险后，才能重新申请提交。



***

## 常见问题解答 [#常见问题解答]

### Q1：SSL 证书订单是否支持删除？ [#q1ssl-证书订单是否支持删除]

> **不支持**。

***

### Q2：SSL 证书是否支持延期？ [#q2ssl-证书是否支持延期]

> 购买的证书不是续期证书，**证书有效期无法进行延长**。

***

### Q3：SSL 免费证书续费报错，是否支持续费？ [#q3ssl-免费证书续费报错是否支持续费]

> 免费证书**目前不支持续费**，需要重新申请新的免费证书进行使用。

***

### Q4：域名配置了防盗链且无法关闭，如何申请 SSL 证书？ [#q4域名配置了防盗链且无法关闭如何申请-ssl-证书]

> 域名配置了防盗链，一般无法使用 `一键升级 HTTPS`，此时只能使用**手动申请 SSL 证书**，且选择 **DNS 验证类型**的证书。

**手动申请并使用免费 SSL 证书步骤如下：**

| 步骤             | 操作说明                              | 参考链接                                                                                 |
| -------------- | --------------------------------- | ------------------------------------------------------------------------------------ |
| 1. 免费证书申请      | 证书品牌：TrustAsia 限免<br />证书种类：DV 限免 | [立即申请](https://portal.qiniu.com/certificate/apply)                                   |
| 2. 补全信息        | 按页面提示填写相关信息                       | —                                                                                    |
| 3. 免费证书验证      | 完成 DNS 验证流程                       | [验证指南](/products/ssl/operation-guide/1-ssl-certificate-of-free-dns-validation-guide) |
| 4. 升级 HTTPS 配置 | 配置 HTTPS 加速                       | [配置指南](/products/cdn/configuration-management-fusion/4-https-configuration)          |

***

### Q5：SSL 证书申请卡在验证环节怎么办？ [#q5ssl-证书申请卡在验证环节怎么办]

> 如果证书申请卡在**文件验证**环节，可能是 CA 无法检测到验证文件。

**解决方案：**

**方案一：放开海外访问限制，或加白 CA 验证服务 IP**

将以下 IP 加入白名单：

| 区域 | IP 地址          |
| -- | -------------- |
| 国内 | 101.89.87.34   |
| 国内 | 180.167.86.3   |
| 国内 | 8.146.209.70   |
| 国内 | 101.43.128.119 |
| 国内 | 8.137.56.95    |
| 国内 | 43.136.173.110 |
| 国内 | 8.162.2.5      |
| 国内 | 8.148.67.87    |
| 海外 | 54.241.185.53  |
| 海外 | 54.241.96.97   |
| 海外 | 52.28.224.233  |
| 海外 | 3.126.196.126  |
| 海外 | 52.82.97.93    |
| 海外 | 69.235.167.224 |
| 海外 | 54.189.196.217 |

**方案二：重新申请证书并改用 DNS 解析验证方式**

1. 登录控制台 → 申请免费 SSL 证书
2. 选择 **DNS 验证**
3. 按指引配置 DNS 解析记录

***


# SSL 证书服务 (/faq/ssl)



## SSL常见问题FAQ [#ssl常见问题faq]

[查看原文](/faq/ssl/13476-Q\&A)

SSL证书、常见问题、签发

更多问题请查看 [官网 FAQ](/faq)。


# 常见问题 (/faq/tutugo/13075-tutugo-FAQ)



最近更新时间: 2025-08-27 14:22:30

# 常见问题 [#常见问题]

## 商品图品类可定制吗 [#商品图品类可定制吗]

目前控制台暂时不支持商品图品类定制的自助操作，如您需要定制化服务，请联系客服人员

## 商品图品类定制需要多久 [#商品图品类定制需要多久]

具体的定制时间与商品品类和印花提取精度相关，通常3个工作日即可完成

## 一次任务的时长是多久 [#一次任务的时长是多久]

单张图片的处理时长大约是50秒左右，一个任务的时长根据待处理图片的数量决定，待处理的图片数量越多，处理所需时长越长


# 拓图 AI (/faq/tutugo)



## 常见问题 [#常见问题]

[查看原文](/faq/tutugo/13075-tutugo-FAQ)

FAQ

更多问题请查看 [官网 FAQ](/faq)。


# 社区生态 (/sdk-tools/community)



社区 SDK 与插件通常由第三方维护，适合作为历史项目、特定框架或迁移阶段的补充参考。生产环境接入前请确认仓库活跃度、许可证和兼容版本。

## 社区 SDK [#社区-sdk]

| SDK              | 维护者       | 链接                                                                               |
| ---------------- | --------- | -------------------------------------------------------------------------------- |
| PHP SDK          | zither    | [GitHub](https://github.com/zither/simple-qiniu-sdk)                             |
| PHP SDK          | hfcorriez | [GitHub](https://github.com/hfcorriez/php-qiniu)                                 |
| PHP SDK          | guoking   | [GitHub](https://github.com/guoking/qiniu-php-sdk)                               |
| Python SDK       | yueyoum   | [GitHub](https://github.com/yueyoum/seven-cow)                                   |
| Python SDK       | shell     | [GitHub](https://github.com/shell909090/python-qiniu)                            |
| Scala SDK        | livehl    | [Git 仓库](http://git.oschina.net/livehl/qiniu-scala-sdk)                          |
| fibjs SDK        | Rube      | [GitHub](https://github.com/Hi-Rube/qn-fibjs)                                    |
| React Native SDK | buhe      | [GitHub](https://github.com/qiniu/react-native-sdk)                              |
| Node.js SDK      | 小问        | [GitHub](https://github.com/iwillwen/node-qiniu)                                 |
| Node.js SDK      | fengmk2   | [GitHub](https://github.com/fengmk2/qn)                                          |
| Javascript SDK   | 小问        | [GitHub](https://github.com/iwillwen/qiniu.js/tree/develop)                      |
| Csharp SDK       | 王明        | [GitHub](https://github.com/icattlecoder/qiniu-csharp-sdk/blob/master/README.md) |
| Qiniu-wxapp-SDK  | 柳橙汁       | [GitHub](https://github.com/gpake/qiniu-wxapp-sdk/blob/master/README.md)         |

## 社区插件 [#社区插件]

| 插件                  | 适用场景        | 链接                                                       |
| ------------------- | ----------- | -------------------------------------------------------- |
| AutoScaleDnspodTool | CDN 自动切量    | [GitHub](https://github.com/dagedaniao/AutoDnsPodScript) |
| HadSky 插件           | 轻论坛附件存储     | [文档](http://www.hadsky.com/read-306-1.html)              |
| qnupload            | 多 bucket 上传 | [GitHub](https://github.com/cheneydc/qnupload)           |
| Drupal 插件           | 内容管理系统      | [文档](https://groups.drupal.org/node/354683)              |
| Opoopress 插件        | 静态博客部署      | [文档](http://opoo.org/deploy-opoopress-to-qiniu/)         |
| Django 插件           | Django 存储后端 | [GitHub](https://github.com/piglei/django-qiniu)         |
| Ueditor 插件          | 编辑器图片上传     | [文档](http://my.oschina.net/duoduo3369/blog/174655)       |
| Solo 插件             | Java 博客系统   | [文档](http://symphony.b3log.org/article/1385649507137)    |
| PaperClip (Ruby)    | Ruby 附件上传   | [GitHub](https://github.com/lidaobing/paperclip-qiniu)   |
| Backup to Qiniu     | 数据备份        | [GitHub](https://github.com/lidaobing/backup2qiniu)      |
| Ueditor(php)        | PHP 编辑器图片上传 | [GitHub](https://github.com/widuu/qiniu_ueditor_1.4.3)   |
| React Qiniu         | React 上传组件  | [GitHub](https://github.com/lenage/react-qiniu)          |
| Joomla 插件           | 图片视频媒体管理    | [文档](http://www.zmax99.com/doc/com-zmaxcdn/peizhi-qiniu) |
| WordPress 插件        | KODO 附件存储   | [文档](https://qq52o.me/2741.html)                         |


# 官方 SDK (/sdk-tools/sdk)



<span id="official-sdk" />

# 官方 SDK [#官方-sdk]

## 对象存储 SDK [#对象存储-sdk]

<span id="sdk" />

### 服务端 [#服务端]

| SDK     | 安装                                                               | 文档                            |
| ------- | ---------------------------------------------------------------- | ----------------------------- |
| Java    | [java-sdk](https://github.com/qiniu/java-sdk/releases)           | [文档](/products/kodo/0-java)   |
| Go      | [go-sdk](https://github.com/qiniu/go-sdk)                        | [文档](/products/kodo/go)       |
| Node.js | [nodejs-sdk.v6](https://github.com/qiniu/nodejs-sdk.v6/releases) | [文档](/products/kodo/nodejs)   |
| Python  | [python-sdk](https://github.com/qiniu/python-sdk/releases)       | [文档](/products/kodo/2-python) |
| PHP     | [php-sdk](https://github.com/qiniu/php-sdk/releases)             | [文档](/products/kodo/php)      |
| C#      | [csharp-sdk](https://github.com/qiniu/csharp-sdk/releases)       | 文档                            |
| C/C++   | [c-sdk](https://github.com/qiniu/c-sdk/releases)                 | [文档](/products/kodo/3-cpp)    |
| Ruby    | [ruby-sdk](https://github.com/qiniu/ruby-sdk/releases)           | [文档](/products/kodo/4-ruby)   |
| Rust    | [rust-sdk](https://github.com/qiniu/rust-sdk)                    | [文档](/products/kodo/6-rust)   |

### 客户端 [#客户端]

| SDK                   | 安装                                                           | 文档                                      |
| --------------------- | ------------------------------------------------------------ | --------------------------------------- |
| JavaScript            | [js-sdk](https://github.com/qiniu/js-sdk/releases)           | [文档](/products/kodo/javascript)         |
| Android               | [android-sdk](https://github.com/qiniu/android-sdk/releases) | [文档](/products/kodo/android)            |
| Objective-C (iOS/Mac) | [objc-sdk](https://github.com/qiniu/objc-sdk/releases)       | [文档](/products/kodo/1-objc)             |
| Flutter               | [dart-sdk](https://github.com/qiniu/dart-sdk)                | [文档](/products/kodo/5-flutter-sdk)      |
| 鸿蒙                    | [js-sdk](https://github.com/qiniu/js-sdk)                    | [文档](/products/kodo/8-kodo-harmony-sdk) |

## 音视频 SDK [#音视频-sdk]

| 场景  | 平台      | 安装                                                                                          | 文档               |
| --- | ------- | ------------------------------------------------------------------------------------------- | ---------------- |
| 推流  | iOS     | [PLMediaStreamingKit](https://github.com/pili-engineering/PLMediaStreamingKit/releases)     | [文档](/sdk-tools) |
| 推流  | Android | [PLDroidMediaStreaming](https://github.com/pili-engineering/PLDroidMediaStreaming/releases) | [文档](/sdk-tools) |
| 连麦  | iOS     | [QNRTC-iOS](https://github.com/pili-engineering/QNRTC-iOS)                                  | [文档](/sdk-tools) |
| 连麦  | Android | [QNRTC-Android](https://github.com/pili-engineering/QNRTC-Android)                          | [文档](/sdk-tools) |
| 短视频 | iOS     | [PLShortVideoKit](https://github.com/pili-engineering/PLShortVideoKit/releases)             | [文档](/sdk-tools) |
| 短视频 | Android | [PLDroidShortVideo](https://github.com/pili-engineering/PLDroidShortVideo/releases)         | [文档](/sdk-tools) |

<Callout type="info">
  移动端和音视频 SDK 接入前，建议同时查看 [SDK 隐私声明](/products/mikustream/2-privacy-policy) 与 [SDK 合规说明](/products/mikustream/1-compliance-instructions)。
</Callout>


# 开发者工具 (/sdk-tools/tools)



<Cards>
  <Card title="qshell" href="/products/kodo/0-qshell">
    基于七牛 API 服务的命令行工具，适合批量上传、下载、同步和资源管理。
  </Card>

  <Card title="Kodo Browser" href="/products/kodo/1-kodo-browser">
    对象存储图形化管理工具，适合人工管理 bucket 和对象资源。
  </Card>

  <Card title="上传诊断工具" href="/products/kodo/diagnostic-tools/0-upload-webtest">
    用于排查上传慢、上传失败和网络连通性问题。
  </Card>

  <Card title="qdoractl" href="/products/dora/processing-mechanism/1-directions-for-use-pfop">
    自定义数据处理命令行工具。
  </Card>
</Cards>

## 使用建议 [#使用建议]

| 场景          | 推荐工具                                                                      |
| ----------- | ------------------------------------------------------------------------- |
| 批量上传、下载、同步  | [qshell](/products/kodo/0-qshell)                                         |
| 图形化查看和管理对象  | [Kodo Browser](/products/kodo/1-kodo-browser)                             |
| 上传失败、上传慢排查  | [上传诊断工具](/products/kodo/diagnostic-tools/0-upload-webtest)                |
| 自定义数据处理任务管理 | [qdoractl](/products/dora/processing-mechanism/1-directions-for-use-pfop) |


# API 说明 (/account/access-management/0-iam-api-introduction)



最近更新时间: 2026-05-06 17:55:34

# 请求说明 [#请求说明]

## 域名 [#域名]

请求域名为 api.qiniu.com

## 鉴权 [#鉴权]

IAM 接口鉴权同七牛其他服务一样，使用 Authorization 头鉴权，用于验证请求合法性的认证信息。该头部应严格按照[管理凭证](/products/kodo/development-guidelines/security/access-token)进行填充，否则会返回 401 错误码。例如 `Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1 ...` 或 `Authorization: UpToken QNJi_bYJlmO5LeY08FfoNj9w_r...`。

## 接口规格 [#接口规格]

请参考 [IAM go-SDK API](https://github.com/qiniu/go-sdk/tree/master/iam)

## 示例请求 [#示例请求]

```shell
curl https://api.qiniu.com/iam/v1/users -H "Authorization: Qbox j853F3bLkWl59I5BOkWm6q1Z1 ..."
```


# IAM 简介 (/account/access-management/0-iam-introduction)



最近更新时间: 2026-05-06 17:12:21

# 综述 [#综述]

**权限管理系统（Identity & Access Management，IAM）** 为用户提供了管理账号下资源访问控制的能力。

在系统中，根用户通过创建和分配虚拟账号（IAM User）来将自己对资源的访问权限共享给其他用户，通过配置策略（Policy）并应用到用户（User）/ 用户组（User Group）实现对资源访问的管理。

# 主要概念 [#主要概念]

## 根用户（Root User） [#根用户root-user]

根用户是在七牛开发者管理平台（portal.qiniu.com）注册的用户，拥有 UID，是七牛云服务各产品都能识别的用户。

## IAM 用户 [#iam-用户]

IAM 用户是由根用户创建的虚拟账户，IAM 用户的身份根据被赋予的权限以其对应的根用户的身份来操作资源。

## 用户组（User Group） [#用户组user-group]

用户组用于组织拥有相同权限的用户，降低权限管理的维护难度。

## 权限（Permission） [#权限permission]

权限决定了被授权的用户是否拥有对某个（些）资源执行某个操作的权力。

> 权限 = 效果(Effect) + 动作(Action) + 资源(Resource)

所有虚拟账号在未被授权时没有对任何资源执行任何操作的权利。

### 效果（Effect） [#效果effect]

效果决定了一条权限所描述内容的是肯定（Allow）语义还是否定（Deny）语义。

例如：

* Effect = Allow: 显式授予用户某个权限
* Effect = Deny: 显式拒绝用户某个权限

### 动作（Action） [#动作action]

动作描述了对特定资源的一个操作。

例如：

* Action = ListDomains: 列举域名列表
* Action = CreateDomain: 创建一个新的域名
* Action = \*: 所有操作

### 资源（Resource） [#资源resource]

资源是用户在七牛使用的具体云服务产品。

资源由七牛资源名称（Qiniu Resource Names, QRN）表示，格式为：

> qrn:product:zone:uid:resource

各部分含义是：

* qrn: 统一标识前缀
* product: 七牛产品
* zone: 七牛可用区
* uid: 七牛用户 uid
* resource: 具体资源定义，由各产品线规定（AWS ARN的参考）

例如:

* Resource = qrn:cdn::123456789:domain/iamtest.cn: 用户 123456789 在 cdn 上配置的对应唯一 id 为 iamtest.cn 的域名
* Resource = qrn:kodo:nb:123456789:my\_bucket/path/to/example.jpg: 用户 123456789 在 kodo 上名为 my\_bucket 的空间下的文件 path/to/example.jpg
* Resource = \*: 所有资源
* 实际请求中，为了简化，一般会省略 zone 和 uid，资源 QRN 定义一般为 qrn:product:::resource（如 qrn:cdn:::domain/iamtest.cn），表示用户在产品 cdn 上配置的域名 iamtest.cn

### 策略（Policy） [#策略policy]

策略是定义权限的载体，通过策略可以声明一个或多个权限，并应用到用户/用户组上。

权限不能以孤立于策略之外的形式存在。

以下是一个策略的示例：

```

{
    "data": {
        "Statement": [{
            "Effect": "Allow",
            "Action": [
                "cdn/CreateDomain",
                "cdn/UpdateDomain"
            ],
            "Resource": [
                "qrn:cdn:::domain/www.qiniu.com",
                "qrn:cdn:::domain/www.qiniu.io"
            ]
        }]
    }
}
```


# 支持审计日志的云服务事件 (/account/audit-log/0-audit-log-events)



最近更新时间: 2023-05-09 15:05:28

本文为您介绍支持审计日志的云服务事件。


# 日志结构定义 (/account/audit-log/0-audit-log-object)



最近更新时间: 2023-05-09 15:05:33

本文为您介绍审计日志的关键字段解释。

## 关键字段 [#关键字段]

| 名称                      | 类型              | 描述                                                             |
| ----------------------- | --------------- | -------------------------------------------------------------- |
| event\_id               | String          | 日志 ID                                                          |
| event\_type             | String          | 事件类型：<br />- UNKNOWN：未知<br />- CONSOLE：控制台事件<br />- API：API 事件 |
| event\_time             | String          | 事件发生时间（UTC 格式）                                                 |
| user\_identity          | UserIdentity    | 请求者的身份信息                                                       |
| event\_rw               | String          | 读写类型：<br />- UNKNOWN：未知<br />- READ：读<br />- WRITE：写           |
| service\_name           | String          | 服务名称                                                           |
| event\_name             | String          | 事件名称                                                           |
| source\_ip              | String          | 源 IP 地址                                                        |
| user\_agent             | String          | 客户端代理                                                          |
| resource\_names         | Array of String | 操作的资源名称列表                                                      |
| request\_id             | String          | 请求 ID                                                          |
| request\_url            | String          | 请求 URL                                                         |
| request\_params         | String          | 请求的输入参数                                                        |
| response\_data          | String          | 请求的返回数据                                                        |
| response\_code          | Integer         | 请求的返回码                                                         |
| response\_message       | String          | 请求的返回信息                                                        |
| additional\_event\_data | String          | 额外备注信息                                                         |

**UserIdentity**

| 名称              | 类型     | 描述                                                                                                                              |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| account\_id     | String | 当前请求所属的七牛云账号 ID                                                                                                                 |
| principal\_id   | String | 当前请求者的 ID，需结合 principal\_type 来确认请求者身份                                                                                          |
| principal\_type | String | 请求者身份类型：<br />- UNKNOWN：未知<br />- ROOT\_USER：七牛云账号 ID<br />- IAM\_USER：IAM 子账号 ID<br />- QINIU\_ACCOUNT：当七牛云账号跨账号操作时，记录七牛云账号 ID |
| access\_key\_id | String | 当前请求身份所属的 AccessKey ID                                                                                                          |


# 下载账单 (/account/bill-management/0-bill-download)



最近更新时间: 2026-05-08 17:20:20

### （1）下载多月账单汇总金额与支付情况 [#1下载多月账单汇总金额与支付情况]

![image.png](/docs-assets/account/%280-manual%29/bill-management/0-bill-download/FgallTaIr5h1lU61jXoh5j6Yia-J-f625d55640b8.webp)

### （2）下载账单详情 [#2下载账单详情]

支持下载 PDF 或 XLSX
![image.png](/docs-assets/account/%280-manual%29/bill-management/0-bill-download/Fn_ECxW8tPeI7PMpuu8mpHjUonJl-8d35e10842e1.webp)

### （3）下载账单列表与按账号汇总账单 [#3下载账单列表与按账号汇总账单]

仅支持财务管理主账号或管理员账号下载按账号汇总账单
![image.png](/docs-assets/account/%280-manual%29/bill-management/0-bill-download/FhhxxeZ9w-ffVIlMxYFo_W8ArOmd-e218254ee7cd.webp)


# 查看账单 (/account/bill-management/0-bill-review)



最近更新时间: 2024-11-27 16:17:57

## 账单范围 [#账单范围]

账单包含按量计费产品和包年包月（订单）产品费用。

## 出账时间 [#出账时间]

每月第四个自然日出上月账单，请在每月出账后查看完整账单。如 8 月账单，请在 9 月 4 日后查看

## 扣费时间 [#扣费时间]

出账后立即触发扣费，您可在收支明细查看扣费详情。

## 账单查看 [#账单查看]

位置：财务中心-账单管理-账单
账单概览：查看汇总账单金额，总体支付情况，点击「查看详情」按钮可查看账单更细粒度信息。
![image.png](/docs-assets/account/%280-manual%29/bill-management/0-bill-review/FsGKI2H4YIzJynu2j7eyE7h1E07h-f2c1b3e79980.webp)
账单列表：支持按产品、账号（若财务管理主账号或管理员账号）汇总。
![image.png](/docs-assets/account/%280-manual%29/bill-management/0-bill-review/FpCb3E6jwGMPXZ2K09t5SNBIyCx9-755cfd66e62b.webp)
还款明细：支持查看某笔充值支付的对应月份账单
![image.png](/docs-assets/account/%280-manual%29/bill-management/0-bill-review/FtranD951_nSUpO1dViLo6dmmcXg-0215686e2d2d.webp)


# 按量计费预估明细 (/account/bill-management/0-real-spending-detail)



最近更新时间: 2026-04-30 17:45:37

目前按量付费资源采取月结算模式，对于还未出账结算的资源，系统每天将根据用户已使用的用量进行计费，生成按量计费预估明细，用户可以通过该明细来了解按量付费（后付费）资源的消耗情况。并且，在账户内会暂时冻结实时消费金额，冻结的金额并未实际消耗，月账单出账扣费后，按量计费预估金额将重新调整。

# 一 管理页面 [#一-管理页面]

登录七牛云管理控制台，进入 财务中心 >  [按量计费预估](https://portal.qiniu.com/financial/bills/estimated-consume)。
![111.png](/docs-assets/account/%280-manual%29/bill-management/0-real-spending-detail/Fh6bYcgDZhLJlw49E9UIvdihYZTh-d2eb2f4817f7.webp)

# 二 计费说明 [#二-计费说明]

**1.计费对象。**
已使用未出账结算的按量付费资源。

**2.计费周期。**
计费周期是从未出账月份1号0:00至当天0:00。可根据上月账单是否出账，分为两种情况：
上月账单已出账时：计费周期是从本月1号0:00至当天0:00。
上月账单未出账时：计费周期是从上月1号0:00至当天0:00。

**3.计费算法。**

* 流量：本月累计到当天的流量乘以阶梯价格计费。
* 标准存储空间、低频存储空间：当月平均存储量按阶梯价格计费，再乘当月已发生天数除以当月总天数得出的费用。
  示例：
  截止至2019-09-14 的存储空间费用，假设存储空间的单价为 P元/GB/月。
  9月平均存储空间量=（9月1号存储空间量+9月2号存储空间量+…+9月13号存储空间量）/13
  9月已发生天数13天，9月总天数30天。
  已产生的费用为：9月平均存储空间量\*P\*13/30 元。
* 带宽计费。
  日带宽：每天的每5分钟打点取带宽计费点再按阶梯价格计费，再累加每天的计费。
  月带宽：按当月已发生天数的每五分钟打点取带宽计费点，再按阶梯价格计费，再按当月天数折算。
  示例：
  客户按月峰值计费，截止至2019-09-14 9月份的月峰值为 X Mbps，单价为 P 元/Mbps。
  9月已发生天数13天，9月总天数30天。
  已产生的费用为：X\*P\*13/30 元。

**4.流量抵扣说明。**
抵扣顺序：免费额度→资源包。
产生计量后，系统会优先抵扣符合条件的免费额度和资源包，超出部分的计量再按阶梯价格计费。

# 三 更新时间和频率 [#三-更新时间和频率]

**1.更新时间。**
每天更新：每天凌晨系统会开始更新预估实时消费明细，一般上午8点更新完毕，请您以上午8点后的数据为准。
出账后立即更新：当实时消费明细包含的计费月份正式出账后，实时消费明细会立即更新为本月实时消费。

**2.更新频率。**
每天更新一次。

# 四 特别说明 [#四-特别说明]

**1.按量计费预估不是最终账单费用。**
遇到计费周期不足整月、用户购买资源包、供应商日志延迟等情况，按量计费预估明细可能会和最终账单金额有些出入，因此按量计费预估明细仅做参考。
&#x2A;*2.按量计费预估明细的计费算法与账单的计费算法不完全一致。**


# 分账账单 (/account/cost-center/0-separate-bill)



最近更新时间: 2023-02-08 20:46:12

# 介绍 [#介绍]

### 概述 [#概述]

分账账单将账单金额分拆至资源粒度，目前支持将存储、CDN 账单金额分别分拆至存储空间、域名粒度。

### 应用场景 [#应用场景]

可用于财务成本核算，项目 / 部门单独计算成本，为您企业内部成本分摊提供参考（不作为对账依据）。

### 分账账单三种展示形式 [#分账账单三种展示形式]

1、分账明细
将账单中计费项金额按照组成该计费项的存储空间 / 域名用量分摊。
![image.png](/docs-assets/account/%280-manual%29/cost-center/0-separate-bill/Foitrag8OcO4poKmgkOnagncP7vv-d14aa9fdb14f.webp)

2、按资源汇总
将分账明细分别按照存储空间、域名汇总。
![image.png](/docs-assets/account/%280-manual%29/cost-center/0-separate-bill/FnZ3_CZphmE-KfSNFos9PxDUCJzk-349a08e879c7.webp)

3、按标签汇总
将分账明细按预先设置好的分账标签汇总。
![image.png](/docs-assets/account/%280-manual%29/cost-center/0-separate-bill/FncCtLGh_qjMTFVj2H0eJzsXFPdI-63f9a497c350.webp)

# 操作流程 [#操作流程]

### 1、开启分账账单 [#1开启分账账单]

联系商务或提交工单，开启分账功能。开启分账功能后才能看到分账账单页面。

### 2、生成分账账单 [#2生成分账账单]

每月出账后系统自动生成分账账单，推荐每月第 5 日起查看。

### 3、查看 / 下载分账账单 [#3查看--下载分账账单]

您可在分账账单页面自助查看 / 下载相应的分账账单。
![image.png](/docs-assets/account/%280-manual%29/cost-center/0-separate-bill/FhKRHbl0t60qyJvoFtspcUNlhaFS-43083fb71f66.webp)
![image.png](/docs-assets/account/%280-manual%29/cost-center/0-separate-bill/Ft6brt2yr0p_UH9uWeGbRwK6TvI3-c09fe5f00a7d.webp)
![image.png](/docs-assets/account/%280-manual%29/cost-center/0-separate-bill/Fk3C77L5cjQE1vsI40XVDDWfiSWm-e40569a30f96.webp)


# 分账标签 (/account/cost-center/0-separate-tag)



最近更新时间: 2026-05-08 17:43:52

# 介绍 [#介绍]

### 概述 [#概述]

分账标签作为分账账单的辅助功能，方便您将分拆后的账单按分账标签汇总。目前仅支持将存储标签设置为分账标签。

### 应用场景 [#应用场景]

用户域名 / 存储空间数量较多，并且希望按不同层级分摊账单金额。如按照“项目 - 部门 - 分公司”分别分摊账单金额。

### 使用方式 [#使用方式]

1、【按标签汇总】页面可查看 / 下载按分账标签汇总后的金额。
![image.png](/docs-assets/account/%280-manual%29/cost-center/0-separate-tag/FmD5R07QxzGIH0UukW8oLaG0vDvY-a1dce9ee8d3a.webp)
2、分账标签会作为单独一列展示在【分账明细】、【按资源汇总】页面中，可下载后按分账标签筛选汇总。
![image.png](/docs-assets/account/%280-manual%29/cost-center/0-separate-tag/FrckHxesl91kaqRBPC5xdaOSPmle-bcca3723a1eb.webp)

# 操作流程 [#操作流程]

### 1、开启分账功能 [#1开启分账功能]

联系商务或提交工单，开启分账功能。开启分账功能后才能看到分账标签页面。

### 2、查看详情 [#2查看详情]

点击【详情】按钮，可查看标签与资源绑定情况。
![image.png](/docs-assets/account/%280-manual%29/cost-center/0-separate-tag/Fil81IFDfoGrj-FZd6BmGH1cLPGP-d7b4c99658f0.webp)
![image.png](/docs-assets/account/%280-manual%29/cost-center/0-separate-tag/Fs4BaW_WBORi_AS-_1V14Amgqq9f-65518a5e7940.webp)

### 3、设置分账标签 [#3设置分账标签]

设置时间：每月月末 24:00 前设置的分账标签才能在当月分账账单中展示，例如 6月30日 24:00 前设置的分账标签才能在 6 月分账账单中展示。
设置数量：最多可设置 15 个分账标签。
![image.png](/docs-assets/account/%280-manual%29/cost-center/0-separate-tag/Frzc9QkNVGL5SIldQ1WzzGTJZkTs-1475f7fcaefd.webp)

### 4、新增 / 修改 / 删除标签 [#4新增--修改--删除标签]

新增 / 修改标签请前往相应的产品线页面设置，设置后会自动同步到分账标签页面。
若在产品线页面删除标签，则在分账标签页面也会自动删除该标签，无论该标签是否设置为分账标签。

### 5、查看/下载分账账单 [#5查看下载分账账单]

【按标签汇总】页面可查看 / 下载按分账标签汇总后的金额。
分账标签也会作为单独一列展示在【分账明细】、【按资源汇总】页面中，可下载后按分账标签筛选汇总。
![image.png](/docs-assets/account/%280-manual%29/cost-center/0-separate-tag/Fj2yYXUnZU50Gu7dWrquQyPHq4ah-6271aaef2db3.webp)


# 产品简介 (/account/enterprise-account-management/0-product-description)



最近更新时间: 2024-08-15 19:11:34

七牛云企业账号管理是为企业用户提供的多账号集中管理服务。企业用户可以创建组织并邀请其他账号加入组织，集中管理组织内账号的账单、转账支付等财务功能，更好地满足企业管理便捷性、安全性和合规性需求。
![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/0-product-description/FjadsEDMaHCSfme-pOxHxiPG0_uu-d9ed7c346013.webp)

### **管理员账号** [#管理员账号]

指对组织中所有成员账号拥有最高管理权限的账号，创建组织的账号自动成为管理员，且管理员角色不能移交给其他账号。管理员账号具有成员账号管理和成员财务管理的权限。

### **成员账号** [#成员账号]

除管理员账号之前，其余账号均为成员账号，由管理员邀请进入组织，接受管理员统一管理。

### **成员账号管理** [#成员账号管理]

邀请成员账号加入组织：只有管理员账号可以邀请其他账号加入组织，成为成员账号。若邀请财务主账号，需对方接受邀请。若邀请财务从账号则需要主账号和从账号都接受邀请。
移除成员账号：在成员账号符合删除条件的情况下，管理员账号可以移除成员账号。

### **成员财务管理** [#成员财务管理]

查看成员账号月结算单：管理员账号可查看成员账号月结算单。（暂时不支持查看“实时消费明细”。）
查看成员账号可用额度：管理员账号可查看成员账号的现金余额、赠送金余额、信用额度、欠费金额、实时消费金额。
划拨资金：管理账号可为成员账号划拨资金。应用：因财务主账号会为从账号自动支付欠费，当组织内有多个主账号时，可统一充值给管理员账号，再为其他主账号统一划拨。
回收资金：划拨资金未使用时，管理员账号可将其回收。
设置汇总可用额度预警：汇总可用额度是针对一组主从账号整体计算的。管理员账号可设置某组主从账号的汇总可用额度阈值，当额度低于该阈值时，为管理员发送通知，提醒管理员为其他主账号划拨资金。

### **财务主/从账号&财务模式** [#财务主从账号财务模式]

财务管理主从账号：主账号和从账号分别出各自账单，主账号可查看从账号账单。从账号支付订单或按量计费产品时，优先使用从账号自己资金抵扣，当从账号余额不足时系统自动划拨主账号的资金为从账号支付。
财务托管主从账号：从账号本身无账单，用量自动合并到主账号上统一出账。从账号支付订单时用主账号余额支付，不能使用自己钱包支付。


# 提现 (/account/fund-management/0-withdrawal-instructions)



最近更新时间: 2026-09-18 17:58:32

### 重要提示：为保障您的资金安全，所有充值只能退回到原充值账号。 [#重要提示为保障您的资金安全所有充值只能退回到原充值账号]

# 提现方式 [#提现方式]

### 原路提现 [#原路提现]

* 微信充值（充值时间小于 330 天）
* 支付宝充值（充值时间小于 330 天）
* 网上银行充值（充值时间小于 80 天）

### 线下提现 [#线下提现]

* 银行转账
* 超出线上渠道退款时间导致无法原路提现的充值

### 商务申请 [#商务申请]

* 转账金额请提交工单或联系商务为您申请

# 到账时效 [#到账时效]

* 原路提现：预计需要3\~15个工作日，遇节假日顺延
* 线下提现：预计需要5\~15个工作日，七牛打款后具体到账时间以银行为准

# 特别说明 [#特别说明]

* 若充值金额已经开票，请您先[申请退票](/account/invoice-management/0-invoice-refund)再申请提现
* 申请提现前请先清理资源，并在申请时自行扣除实时消费金额
* 因存在实时消费，审核人员会根据实时消费情况调整提现金额，因而最终打款金额和申请金额有不一致的可能性
* 因账号违法违规触发冻结，无法直接申请提现，请先进行账号申诉，在[申诉平台](https://www.qiniu.com/appeal)申诉解冻，解冻完成后才可以提现

# 提现操作指引 [#提现操作指引]

### 位置：财务中心-财务概览-提现 [点击前往](https://portal.qiniu.com/financial/withdraw) [#位置财务中心-财务概览-提现-点击前往]

1、根据充值特征选择提现方式
![image.png](/docs-assets/account/%280-manual%29/fund-management/0-withdrawal-instructions/FubDieLeXq92uvQO1ah3arPPFTrG-f9ef375f73c7.webp)
2、选择充值流水并填写提现金额
![image.png](/docs-assets/account/%280-manual%29/fund-management/0-withdrawal-instructions/FnqwPOHHoZiRWn5MWWH0n5Fmfi7H-bd55f470d70b.webp)
3、请填写原因方便我们提供更好的服务，线下提现需要填写银行收款账户
未认证用户可申请原路提现，但不可自助申请线下提现，请先认证或联系商务为您申请
![image.png](/docs-assets/account/%280-manual%29/fund-management/0-withdrawal-instructions/FlbYAUmORKKUUCA6LgNYHBKa4i6M-b01363eed4dc.webp)
4、点击【提交】等待内部人员为您审核
![image.png](/docs-assets/account/%280-manual%29/fund-management/0-withdrawal-instructions/Fvug5sPc89L9Q1O8FOLz2xiDV9UB-9e23c3e52e2d.webp)

注：海外账号如需提现需要提交工单联系技术支持或联系商务经理进行处理


# 如何进行企业认证？ (/account/identity-verification/0-enterprise-certification-started-quickly)



最近更新时间: 2026-07-08 10:24:02

企业账号认证有两种认证方式：企业银行卡打款认证、企业法人/被授权人扫脸验证。
注：目前暂不支持事业单位和律师事务所进行法人认证，如需认证请选择银行转账验证方式；工商变更或注册时间不超过 14 天的企业请选择银行转账验证方式

**在七牛控制台进入 [实名认证](https://portal.qiniu.com/developer/user/identity) 界面提交认证资料即可。**

# 银行转账验证 [#银行转账验证]

## 第一步 [#第一步]

**填写企业信息和财务信息**

* 请确保证件照清晰。
* 请填写开户银行与支行。
* 可使用社会信用码、营业执照、非营利组织的证件进行认证。
* 企业名称需和营业执照及银行对公账号的企业名称保持一致。
* 若所提供的证件是复印件需要加盖公司公章。
  ![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-enterprise-certification-started-quickly/FqjjEojGb_eL9N_vMBu1NJiaetHI-d031ea2cd1d7.webp)
  ![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-enterprise-certification-started-quickly/FjUgcluThNodVZtAqKx43Mnkg5nd-0ea1b8c89130.webp)
  ![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-enterprise-certification-started-quickly/Fg5gHcZxvLP6nwMG7W0oa_0uXtnv-6a5fb6e8b6c4.webp)

## 第二步 [#第二步]

**待审核**

七牛云将在 3 个工作日内完成基本信息的审核，审核结果会以短信的方式通知。

## 第三步 [#第三步]

**待汇款**

七牛云将在 3 个工作日内向您所填写的银行卡里面打一笔0.01～0.99 元之间的小额款项，请在收到款项后，回填打款金额完成认证。

## 第四步 [#第四步]

**待验证收款**

## 第五步 [#第五步]

**认证完成**

# 法人/被授权人扫脸验证 [#法人被授权人扫脸验证]

## 第一步 [#第一步-1]

**填写企业信息和认证人信息**

* 请准备好企业营业执照等企业证件，目前支持社会信用码、营业执照、非营利组织的证件进行认证。
* 若所提供的证件是复印件需要加盖公司公章。
* 上传营业执照扫描件，系统会识别证件自动填写企业名称和证件号，检查系统识别的名称和证件号，可手动更正。
* 填写产品和行业信息
* 选择您的身份是法人或被授权人，若选择被授权人需要填写法人信息并上传授权书
* 提交表单

![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-enterprise-certification-started-quickly/FlhNZCC8N7Z3KAqo9j48ZuXC_ukT-4e768ddec117.webp)

## 第二步 [#第二步-1]

**点击“立即提交”，弹出用于人脸认证的二维码**

![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-enterprise-certification-started-quickly/FtRtRTxzGzdKswW3D7W8Dd_n0BuG-82c0b8851568.webp)

## 第三步 [#第三步-1]

**用手机微信扫描二维码进行人脸认证**

* 营业执照和人脸认证没问题直接认证成功
* 营业执照或用户信息不匹配会进入人工审核，三个工作日内审核完成
  ![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-enterprise-certification-started-quickly/FjpOcZi9wVXjf9FvCsbL5XAzAWiq-879ecb2b784b.webp)


# 如何进行企业认证变更？ (/account/identity-verification/0-how-to-make-enterprise-certification-changes)



最近更新时间: 2026-09-18 17:46:44

企业账号认证变更有两种方式：变更企业认证名称；变更企业认证主体。

# 变更企业认证名称 [#变更企业认证名称]

企业名称变更认证仅公司名称发生了变更。企业账号变更企业名称，需要上传变更后的企业证件扫描件。

## 第一步 [#第一步]

进入“个人中心”页面，选择“[实名认证](https://portal.qiniu.com/developer/user/identity)”，选择“变更企业名称”。
![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-how-to-make-enterprise-certification-changes/FoO3-5ft88DkAzsMCAGod_3a20l8-b606212285df.webp)

## 第二步 [#第二步]

进入“变更企业名称”页面。填写变更后的企业信息，并上传企业名称变更认证的材料。
![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-how-to-make-enterprise-certification-changes/Fq1xnpShNSfhjXFMceVyCtboanc6-1244a6d26a0b.webp)

## 第三步 [#第三步]

单击“提交认证”，进入认证审核页面。您的企业认证变更申请已提交，七牛将在 3 个工作日内完成审核。请耐心等待审核结果，审核成功，变更即可生效。

# 变更企业认证主体 [#变更企业认证主体]

企业主体变更是指变更前与变更后的企业不是同一主体，资源与资金的归属主体发生了变更。企业账号变更企业主体，需要填写企业认证变更申请表，并上传已实名认证的材料和新认证的材料。

## 第一步 [#第一步-1]

进入“个人中心”页面，选择“[实名认证](https://portal.qiniu.com/developer/user/identity)”，选择“变更企业实体”。
![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-how-to-make-enterprise-certification-changes/FoO3-5ft88DkAzsMCAGod_3a20l8-b606212285df.webp)

## 第二步 [#第二步-1]

进入“变更企业实体”页面。根据页面提示，填写变更后的企业信息并上传已实名认证的材料和新认证的材料。
变更申请表模板为word文件格式，上传的附件格式不支持word，上传时需转换为照片。
![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-how-to-make-enterprise-certification-changes/FgwmMXOINZEfwz4lxFEmNy7Oe6Ba-4439b4aba4c7.webp)

## 第三步 [#第三步-1]

单击“提交认证”，进入认证审核页面。您的企业认证变更申请已提交，七牛将在 3 个工作日内完成审核。请耐心等待审核结果，审核成功，变更即可生效。

# 原企业注销变更申请需要提交工单沟通 [#原企业注销变更申请需要提交工单沟通]


# 如何进行个人认证？ (/account/identity-verification/0-quick-start-personal-authentication)



最近更新时间: 2026-07-08 10:23:43

个人认证有三种认证方式：个人扫码认证；个人银行卡转账认证；个人银行卡认证
&#x2A;*在七牛控制台进入 [实名认证](https://portal.qiniu.com/developer/user/identity) 界面提交认证资料即可。**

# **扫码认证** [#扫码认证]

扫码实名认证是通过现场对着真实本人录制视频。
视频录制成功后，系统进行活体检测及人证核身校验，校验通过立即完成认证。

# 第一步 [#第一步]

使用手机微信扫描二维码。

![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-quick-start-personal-authentication/FhjSVcv3AmBE9BWaIVrReZqLLZWW-fc1b01ad47b4.webp)

# 第二步 [#第二步]

手机端根据页面提示，手动输入个人身份信息。

# 第三步 [#第三步]

根据界面引导进行人脸核验。人脸识别成功，系统会提示您认证成功，人脸识别失败，系统会提示您认证失败。

PC端会同步您在手机端的认证结果。

<br />

# **银行转账验证** [#银行转账验证]

**该认证方式需填写个人信息及财务信息**

若个人信息审核无误后，七牛云会向您所填写的银行卡里面打一笔0.01～0.99 元之间的小额款项，请在收到款项后，回填打款金额完成认证。

# 第一步 [#第一步-1]

**填写个人信息和财务信息**

* 请确保持证件照清晰。
* 请填写开户银行及支行信息。
* 银行开户名需要与认证填写的身份证信息一致。

![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-quick-start-personal-authentication/FsWpsziIIqJMYRLUaHlQituK3lFE-c559d350e3d0.webp)
![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-quick-start-personal-authentication/FmFhlXshO0nTpb4RE6wnzG5sldbv-d0687d14f8b1.webp)

# 第二步 [#第二步-1]

**基本信息审核**

七牛云将在 3 个工作日内完成基本信息的审核，审核结果会以短信的方式通知。

# 第三步 [#第三步-1]

**待汇款**

七牛云将在 3 个工作日内向您所填写的银行卡里面打一笔0.01～0.99 元之间的小额款项，请在收到款项后，回填打款金额完成认证。

# 第四步 [#第四步]

**待验证收款**

请输入附言对应的打款金额进行认证。

<font color="red">
  注意：输错 3 次后会自动认证失败，需发起重新认证。
</font>

# 第五步 [#第五步]

**认证完成**

<br />

# **银行卡认证** [#银行卡认证]

银行卡认证是以个人客户的银行卡进行实名认证，支持个人借记卡和信用卡。个人客户可以输入银行卡信息进行实名认证。

# 第一步 [#第一步-2]

使用手机微信扫描二维码。
![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-quick-start-personal-authentication/FrO5q4xRyhJjLfM0Anhcgisx4F1N-b86abc1f1233.webp)
![image.png](/docs-assets/account/%280-manual%29/identity-verification/0-quick-start-personal-authentication/FmccJZc9vSibkaCdKU8sq2Y_3A0m-1f118b366e33.webp)

# 第二步 [#第二步-2]

手机端根据页面提示，拍摄完整面部照片，完成上传。

# 第三步 [#第三步-2]

返回PC端继续操作。填写完整相关信息，点击“立即提交”按钮完成认证。


# 认证说明 (/account/identity-verification/0-the-identity-authentication)



最近更新时间: 2025-06-10 10:31:21

# 简介 [#简介]

实名认证即认证使用主体身份。据《网络安全法》规定，用户必须进行实名认证，否则不得使用相关服务。

个人客户可进行个人认证或企业认证，企业客户只可进行企业认证。个人认证成功后也可升级成企业认证。企业认证成功后不可降级为个人认证。

如账号为企业使用，请务必进行企业认证。因为个人认证与企业认证在账号归属上有极大不同，同时遇到人员变更或账号财务纠纷，错误的账号属性可能对个人/企业产生不良影响或带来经济损失。

<br />

# 注意事项 [#注意事项]

| 实名认证细则须知                                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 银行转账认证需先审核基本信息，所有银行信息请务必填写正确并精确到具体支行。审核通过后七牛将往填写的银行信息中汇入一笔小额认证款项，您在收到款项后在七牛认证界面回填正确的收款金额即可完成认证。如银行汇款失败或回填金额不正确，认证将自动失败。（该认证如在工作日15:00之前提交，可当天处理完成。15：00点之后提交则需隔天处理完成，如遇周末或法定节假日将自动顺延。） |
| 目前仅支持使用中国大陆身份证及营业执照进行认证，海外用户或其它需求客户请[提交工单](https://support.qiniu.com/tickets/category)或联系您专属销售经理。                                                                                      |

***

<br />

# 快速入门 [#快速入门]

<br />

* **[如何进行个人认证](/account/identity-verification/0-quick-start-personal-authentication)**

* **[如何进行企业认证](/account/identity-verification/0-enterprise-certification-started-quickly)**


# 发票申请 (/account/invoice-management/0-invoice-application)



最近更新时间: 2026-05-08 17:12:52

## 相关提示 [#相关提示]

1、开票金额为 1000 元以上时才可申请开具增值税专用发票。
2、申请发票金额小于 100 元需支付快递费 5 元，快递费将在现金账户中扣除；超过 100 元免收快递费。
3、每月前 3 个工作日为账期，在此期间的开票申请需等到当月第 4 个工作日方可开票。
4、申请开票前请先设置默认开票信息。普通发票填写后即可开票，专用发票需审核后才可开票。审核需要 1\~3 个工作日。
5、企业索取增值税普通发票时，应提供纳税人识别号或统一社会信用代码，否则不得作为税收凭证。
6、增值税专用发票抬头需要和企业实名认证抬头一致。[增值税专用发票抬头说明](/faq/account-finance/6434-special-invoices-for-value-added-tax-payable-to-illustrate)
7、[退票说明](/account/invoice-management/0-invoice-refund)。
8、响应税务机关要求，支持您申请开具电子（数电）专票/普票，其法律效力、基本用途、基本使用规定等与纸质发票相同。若您需要纸质发票请联系商务或提交工单为您处理。

## 操作地址 [#操作地址]

控制台 > 财务中心 >发票管理    [点击前往](https://portal.qiniu.com/financial/invoice)

## 操作步骤 [#操作步骤]

### 第一步 添加开票信息 [#第一步-添加开票信息]

点击【开票信息管理】，添加开票信息。增值税普通发票的开票信息填写后无需审核，专用发票开票信息需要人工审核通过后才能使用。
![image.png](/docs-assets/account/%280-manual%29/invoice-management/0-invoice-application/FheTvBeTsw2Negm-FXv-MFVgkN6t-97604b36f97c.webp)

### 第二步 设置默认开票信息 [#第二步-设置默认开票信息]

将本次开票需要使用的开票信息设为默认开票信息。（增值税专用发票只有通过审核后才可设为默认开票信息）
![image.png](/docs-assets/account/%280-manual%29/invoice-management/0-invoice-application/FkRJuSEGtDzcmRSK5hpiM3VT30py-e431aa2d616b.webp)

### 第三步 申请开票 [#第三步-申请开票]

返回发票管理页面，点击【申请开票】按钮进入发票申请页面，勾选 6 个月之内的充值流水。
![image.png](/docs-assets/account/%280-manual%29/invoice-management/0-invoice-application/Fm0jqctVfR6VEkjtHCvY7SvxrROd-e25d056a9742.webp)

### 第四步 填写交付邮箱 [#第四步-填写交付邮箱]

开票后将开出的电子发票发送至该邮箱，支持下载 PDF、OFD、XML 格式。
![image.png](/docs-assets/account/%280-manual%29/invoice-management/0-invoice-application/FkB1y-EC42ef_aa-4VRJKlI0DQgv-fb1e5a85db20.webp)

### 第五步 提交申请 [#第五步-提交申请]

等待相关业务人员为您审核、开票，约 1～3 个工作日。


# 发票获取 (/account/invoice-management/0-invoice-obtained)



最近更新时间: 2023-11-02 11:01:33

### 电子发票 [#电子发票]

* 平台下载：发票开出后，您可在发票列表下载电子发票，支持下载 PDF 格式。
  ![image.png](/docs-assets/account/%280-manual%29/invoice-management/0-invoice-obtained/FmVc4msDCmJVfgJf9hMTOrMF0y-f-b0de88520e78.webp)
* 邮箱交付：若您申请时填写了交付邮箱，电子发票开出后会发送至该邮箱，支持下载 PDF、OFD、XML 格式。

### 纸质发票 [#纸质发票]

通过快递邮寄到您申请开票时填写的地址，可通过快递编号查看快递信息。


# 退票说明 (/account/invoice-management/0-invoice-refund)



最近更新时间: 2023-11-13 17:30:15

## 一 电子（数电）发票 [#一-电子数电发票]

### 1.1 专票 [#11-专票]

填写的《增值税专用发票退票说明（数电）》（[点击下载](https://static.qiniu.com/invoice_electric/%E5%A2%9E%E5%80%BC%E7%A8%8E%E4%B8%93%E7%94%A8%E5%8F%91%E7%A5%A8%E9%80%80%E7%A5%A8%E8%AF%B4%E6%98%8E%EF%BC%88%E6%95%B0%E7%94%B5%EF%BC%89.doc))，联系商务或创建工单提交退票申请。
【注】使用增值税发票综合服务平台开票的客户，要特别注意，申请专票（已抵扣）退票时，需由我司发起红冲，客户方系统确认后，才能开负数发票。
![image.png](/docs-assets/account/%280-manual%29/invoice-management/0-invoice-refund/Fm8IJS46gyU7eDKBf_sY6fHhrBsc-da42f848d4c6.webp)

### 1.2 普票 [#12-普票]

填写的《增值税普通发票退票说明（数电）》（[点击下载](https://static.qiniu.com/invoice_electric/%E5%A2%9E%E5%80%BC%E7%A8%8E%E6%99%AE%E9%80%9A%E5%8F%91%E7%A5%A8%E9%80%80%E7%A5%A8%E8%AF%B4%E6%98%8E%EF%BC%88%E6%95%B0%E7%94%B5%EF%BC%89.docx))，联系商务或创建工单提交退票申请。

## 二 纸质发票 [#二-纸质发票]

### 2.1 专票 [#21-专票]

填写《增值税专用发票退票说明（纸质）》（[点击下载](https://static.qiniu.com/invoice_electric/%E5%A2%9E%E5%80%BC%E7%A8%8E%E4%B8%93%E7%94%A8%E5%8F%91%E7%A5%A8%E9%80%80%E7%A5%A8%E8%AF%B4%E6%98%8E%EF%BC%88%E7%BA%B8%E8%B4%A8%EF%BC%89.doc)），并同发票一起回寄。
收件信息

* 地址：上海浦东新区张江亮秀路81号浦东软件园Q座
* 收件人: 销售运营部
* 联系电话：18017393053

### 2.2 普票 [#22-普票]

填写《普通发票退票说明》（[点击下载](https://dn-odum9helk.qbox.me/%E6%99%AE%E9%80%9A%E5%8F%91%E7%A5%A8%E9%80%80%E7%A5%A8%E8%AF%B4%E6%98%8E%E6%A8%A1%E7%89%88.pdf?attname=)），并同发票一起回寄。
收件信息

* 地址：上海浦东新区张江亮秀路81号浦东软件园Q座
* 收件人: 销售运营部
* 联系电话：18017393053


# 取消订单 (/account/order-management/0-cancel-the-order)



最近更新时间: 2022-07-27 16:18:24

1.当您下错订单且未支付时，可以通过点击【取消】按钮，对订单进行取消。

<img src="/docs-assets/account/%280-manual%29/order-management/0-cancel-the-order/FlSFiStqYDrXuiUZfoSqADDSgHTa-6672e3d4b4c4.webp" width="70%" />

<br />

2.点击取消后会弹出本次要取消的商品订单信息，请确认无误后点击【确定】。

<img src="/docs-assets/account/%280-manual%29/order-management/0-cancel-the-order/FrGWRtgX9rrP5hQyD9iiNG-rOe6w-15de8131ce3a.webp" width="70%" />

<br />

<font color="red">
   

  **注意：**

   
</font>

1.一但取消后，不可恢复订单。若取消错误，请重新购买；

2.通过购物车合并下单的订单，取消时会一并取消，请注意弹出的商品信息。


# 导出订单 (/account/order-management/0-export-orders)



最近更新时间: 2026-05-06 12:51:36

支持客户导出订单列表中所有订单信息，用于公司归档、分析等使用。
可前往[订单列表](https://portal.qiniu.com/financial/orders/list)，筛选需要的订单点击【导出】

<img src="/docs-assets/account/%280-manual%29/order-management/0-export-orders/FlJV5EAz552FC8PLKsnY54FQLsFJ-917b2d6ff30f.webp" width="70%" />


# 订单退款 (/account/order-management/0-order-a-refund)



最近更新时间: 2026-10-09 19:13:32

退款仅指用户以现金方式支付的订单金额，不包含代金券抵扣的部分，退订成功后退款金额将退还至账户余额或原路退还。

## 退款规则 [#退款规则]

| 退款商品类型 | 退款条件                                                                                                                                                                  | 退款操作                                                                                                    |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| 资源包商品  | 1.资源包未使用：未使用指没有已出账的用量（若资源包一次性买了多个，需保证整体都没有使用，部分使用也无法退款）2.资源包未过期：资源包未到结束时间以上两个条件需同时满足，方可申请                                                                             | 联系 [工单沟通界面左下角的专属商务微信](https://support.qiniu.com/tickets) 或提交 [工单](https://support.qiniu.com/tickets) 申请 |
| 云主机    | 见[参考文档](/products/qvm/1-five-days-have-no-reason-to-refund)                                                                                                           | 见[参考文档](/products/qvm/1-five-days-have-no-reason-to-refund)                                             |
| 证书     | 免费域名型(DV) SSL 证书无法申请退款；已经由CA机构成功颁发的 SSL 证书，签发不超过30天的可以取消、申请退款；已完成订单支付、审核流程中非客户缘故所导致的未成功颁发的 SSL 证书可申请退款。详情见[参考文档](/products/ssl/section-i4zv20/2-ssl-a-refund-service) | 前往[证书管理列表](https://portal.qiniu.com/certificate/ssl)自助申请退款                                              |
| 短视频SDK | 一但授权发出，不支持退款。若有特殊情况，可咨询销售                                                                                                                                             | 联系销售或提工单咨询                                                                                              |

## 退款资金流向 [#退款资金流向]

以下情况**全部满足**的情况下，退款金额会直接回到您的原支付渠道：

1. 使用通过支付宝、微信或网银支付等三方支付渠道**预付费**购买的订单（先用三方支付渠道充值余额后，用余额支付的订单不在此例）；
2. 付款成功后 330 天内产生的退款；
3. 退订的订单未开过发票；
4. 用户当前可用余额大于等于 0（不包含信用额度）。

除了上述情况以外，退款金额会退至您的七牛云账户余额。您可以通过账户余额提现的方式将账户余额提现到原支付渠道。提现相关操作和规则见[提现](https://developer-doc.qiniu.com/account/fund-management/0-withdrawal-instructions)。


# 支付订单 (/account/order-management/0-payment-order)



最近更新时间: 2022-07-27 16:18:17

1.云商城/产品页/活动页面选品下单或者已经有订单的可前往[订单列表](https://portal.qiniu.com/financial/orders/list)，找到需要支付的订单点击【去支付】

<img src="/docs-assets/account/%280-manual%29/order-management/0-payment-order/FgZlWPPY0_1Xh-9nR3gE07gswzKS-29d220266de1.webp" width="70%" />

<br />

2.确认商品明细，若有可用抵用券可选择券后核对最终需要支付的金额，选择支付方式后点击【确认支付】

<img src="/docs-assets/account/%280-manual%29/order-management/0-payment-order/FoJREkvCUaPiMYiZc6laDoB9mbPF-a323b3506ce6.webp" width="70%" />

<font color="red"> &#x2A;*注意：** </font>
通过购物车合并下单或者组合售卖的多商品，支付时会自动合并，需要一并完成支付。


# 订单状态说明 (/account/order-management/0-the-order-status-shows)



最近更新时间: 2022-07-27 16:18:26

|订单状态|说明|
\|-|-|-|
|未支付|客户提交订单之后，还未支付的状态|
|已过期|客户未在支付过期时间内完成支付，订单过期，无法再进行支付|
|作废|客户自己取消或者系统自动取消的订单所处的状态|
|已支付|客户对订单进行了付款|
|后付费|客户用信用额度或者与销售申请，商品可先使用后付钱|


# 查看订单详情 (/account/order-management/0-to-view-the-order-details)



最近更新时间: 2026-05-08 17:52:23

订单详情包含订单信息、商品信息、订单金额信息等。

1.进入“订单管理”页面

<img src="/docs-assets/account/%280-manual%29/order-management/0-to-view-the-order-details/FkplgOOlWisOM__ugvkmI6h-f1iy-585f7ec3f66d.webp" width="70%" />

<br />

2.可根据您的查询需求，通过订单列表筛选器找到目标订单，并点击【详情】

<img src="/docs-assets/account/%280-manual%29/order-management/0-to-view-the-order-details/Fl7l0r9yOFG5EQzo2qxu_V0rVIEf-9e12fda5b36d.webp" width="70%" />

<br />

***

<font color="red"> &#x2A;*注意：** </font>
1.QVM（云主机）产品订单在上述订单管理页面可以查到，但详细的订单信息建议前往[云主机订单管理](https://portal.qiniu.com/qvm/vm/instance)界面查看，主机的订单管理会包含更多主机商品信息；

2.SSL（证书）产品订单在上述订单管理页面可以查到，但详细的订单信息及证书颁发建议前往[证书订单管理](https://portal.qiniu.com/certificate/ssl)界面查看；

3.短视频SDK产品订单在上述订单管理页面可以查到，但详细的授权信息建议前往[SDK授权管理](https://portal.qiniu.com/sdk/licenses)界面查看。


# 购买资源包 (/account/resource-package-management/0-buy-the-resource-bundle)



最近更新时间: 2026-05-06 13:57:58

主要购买方式：

* 自助下单：可通过云商城自助选择资源包进行购买[前往云商城](https://qmall.qiniu.com/?develop)
* 销售代您下单：联系您的销售经理帮您进行下单

| 资源包分类   | 资源包细分                       | 购买地址                                                                                   |
| ------- | --------------------------- | -------------------------------------------------------------------------------------- |
| 存储      | 国内标准存储空间（华东、华北、华南）          | [去购买](https://qmall.qiniu.com/template/MTEy?spec_combo=MzA0Ng)                         |
|         | 国内低频存储空间（华东、华北、华南）          | [去购买](https://qmall.qiniu.com/template/MTEy?spec_combo=MzA3OQ)                         |
|         | 国内归档存储空间（华东、华北、华南）          | [去购买](https://qmall.qiniu.com/template/MTEy?spec_combo=MzExMg)                         |
|         | 归档直读存储空间（华东、华北、华南）          | [去购买](https://qmall.qiniu.com/template/MTEy?spec_combo=MzUxNg)                         |
|         | 智能分层存储空间（华东、华北、华南）          | [去购买](https://qmall.qiniu.com/template/MTEy?spec_combo=MzU0Mw)                         |
|         | 外网流出流量                      | [去购买](https://qmall.qiniu.com/template/MTEy?spec_combo=MzE0Mg\&ref=develop)            |
|         | 回源流量                        | [去购买](https://qmall.qiniu.com/template/MTEy?spec_combo=MzE3NQ\&ref=develop)            |
| CDN     | 国内CDN加速流量                   | [去购买](https://qmall.qiniu.com/template/NTI?ref=develop\&spec_combo=MTk0OA)             |
|         | 海外CDN加速流量                   | [去购买](https://qmall.qiniu.com/template/NTU?ref=develop\&spec_combo=MjEzNA)             |
| 直播、音视频类 | 标准协议直播                      | [去购买](https://qmall.qiniu.com/template/MTMw?spec_combo=MzU2Mg)                         |
|         | 超低延时协议直播                    | [去购买](https://qmall.qiniu.com/template/MTMw?spec_combo=MzU3OA)                         |
|         | 极速直播转码                      | [去购买](https://qmall.qiniu.com/template/MzE?spec_combo=MTUyMg)                          |
|         | 智能直播鉴黄                      | [去购买](https://qmall.qiniu.com/template/MzQ?ref=develop\&spec_combo=MTU2Nw)             |
|         | 视频监控                        | [去购买](https://qmall.qiniu.com/template/NDY=?ref=develop\&spec_combo=MTgxMw)            |
| 视频转码    | H.264 普通转码、H.265 普通转码       | [去购买](https://qmall.qiniu.com/template/NjQ?ref=develop\&spec_combo=MjQwNw)             |
|         | 锐智转码                        | [去购买](https://qmall.qiniu.com/template/NzA=?spec_combo=MjU4Nw)                         |
|         | 实时转码                        | [去购买](https://qmall.qiniu.com/template/MTI5?spec_combo=MzU0MA)                         |
| AI内容审核  | 鉴黄、鉴暴恐、鉴政、图片广告识别等           | [去购买](https://qmall.qiniu.com/template/MTA5?ref=develop\&ref=index\&spec_combo=MjkzNQ) |
|         | 人脸核验（权威人脸比对、动作活体检测、防翻拍活体检测） | [去购买](https://qmall.qiniu.com/template/MTI1?spec_combo=MzQ5OQ)                         |
|         | 票证自动识别 OCR（身份证、营业执照）        | [去购买](https://qmall.qiniu.com/template/MTIy?spec_combo=MzQ2Nw)                         |
|         | 语音识别                        | [去购买](https://qmall.qiniu.com/template/MTE2?spec_combo=MzI5OA)                         |
| AI大模型推理 | AI 国产模型系列                   | [去购买](https://qmall.qiniu.com/template/MTMx?spec_combo=MzU4NQ)                         |
|         | AI 全球模型系列                   | [去购买](https://qmall.qiniu.com/template/MTM2?spec_combo=MzYxNw)                         |


# 管理资源包 (/account/resource-package-management/0-manage-the-resource-bundle)



最近更新时间: 2026-05-08 18:08:12

购买了资源包以后，可以通过资源包管理页来查看资源包的详情，包括资源包名称、总量、剩余量、生效时间、失效时间、导出每月数据等。若想通过API查询资源包信息，请参见“资源包管理API”

## 1.当月概览（[前往查看](https://portal.qiniu.com/financial/orders/respack-mgr/current)） [#1当月概览前往查看]

展示当月生效中的资源包在当月的用量情况，按类型汇总展示。如华东存储有2个生效中的资源包，则合并展示为存储空间-华东地区-不限时段
![image.png](/docs-assets/account/%280-manual%29/resource-package-management/0-manage-the-resource-bundle/FjqqUziz2_geSvBYCoy3zftHWwvE-264657a1380a.webp)

<br />

## 2.设置余量预警 [#2设置余量预警]

默认预警线为70%，当各个资源包类型的当月已使用量/当月总可用量>=70%时，会触发预警通知（短信、邮件），告知用户使用情况，提醒用户及时补包。同时这里也支持客户自定义预警线，自定义后会按照客户的预警线值发送信息。

<img src="/docs-assets/account/%280-manual%29/resource-package-management/0-manage-the-resource-bundle/FhrKxTfeccsa7eQwAsbhFveA-XJ5-a3e1109d2258.webp" width="70%" />

<br />

<img src="/docs-assets/account/%280-manual%29/resource-package-management/0-manage-the-resource-bundle/FnJgWEXr5KemfOW3qRIbU6O7vYZv-3fe79fe41fd2.webp" width="70%" />

<br />

## 3.导出当月明细 [#3导出当月明细]

点击导出后，自动下载当月所有可用资源包的使用数据excel文件。（注意：每月月初1\~3日出账期间，数据可能更新不及时，仅数据展示上延迟，实际计量及抵扣准确）

<img src="/docs-assets/account/%280-manual%29/resource-package-management/0-manage-the-resource-bundle/FlbD2rgBNimkeP8zOkkD2cT3Vix5-316cc70e2626.webp" width="70%" />

<br />

## 4.所有资源包（[前往查看](https://portal.qiniu.com/financial/orders/respack-mgr/all)） [#4所有资源包前往查看]

这里展示用户账号下的所有购买的资源包（不包含已经退款的资源包）。可通过筛选器，快速查找目标资源包。
![image.png](/docs-assets/account/%280-manual%29/resource-package-management/0-manage-the-resource-bundle/FgezCLq9iKenNhc2gileJ3u_bx_8-45434f528d21.webp)

<br />

## 5.导出历史抵扣明细 [#5导出历史抵扣明细]

点击【所有资源包】筛选器下方的导出，即可导出历史月份资源包抵扣明细。

<img src="/docs-assets/account/%280-manual%29/resource-package-management/0-manage-the-resource-bundle/Fs6HfYlL7pJWjWltiK2v8qTM1v3V-036185a59bb3.webp" width="70%" />

<br />

## 6.查看资源包详情 [#6查看资源包详情]

点击对应的资源包【详情】，即可查看该资源包的使用情况，不仅展示历史已出账的抵扣用量，当月未出账的抵扣量也会显示出来.

<img src="/docs-assets/account/%280-manual%29/resource-package-management/0-manage-the-resource-bundle/FlNYzGajJ4RYUujrIVA0iXdkkW68-1261edf77f47.webp" width="70%" />


# 资源包常见问题 (/account/resource-package-management/0-the-resource-bundle-common-problems)



最近更新时间: 2026-07-02 10:21:37

# 简介 [#简介]

 
<font color="#4671D5"><a href="#Q1">Q1、购买后，为什么实时消费产生的计费用量没有抵扣？</a></font>
<font color="#4671D5"><a href="#Q2">Q2、抵扣的量为何与购买的量不一致？</a></font>
<font color="#4671D5"><a href="#Q3">Q3、为什么我查看资源包管理显示资源包有剩余，但是却没有继续抵扣我的计费项用量？</a></font>
<font color="#4671D5"><a href="#Q4">Q4、我购买了直播流量包或视频监控流量包或海外CDN加速包，为何不能抵扣当月实时账单金额？</a></font>
<font color="#4671D5"><a href="#Q5">Q5、为什么当月实际使用CDN产品0.6GB，资源包却抵扣了1GB？</a></font>
<font color="#4671D5"><a href="#Q6">Q6、为什么新买的miku直播流量资源包无法抵扣直播云流量？</a></font>
<font color="#4671D5"><a href="#Q7">Q7、如何查询资源包抵扣规则和支持的模型或计费项？</a></font>
<font color="#4671D5"><a href="#Q8">Q8、资源包生效时间选错了，如何处理？</a></font>
<font color="#4671D5"><a href="#Q9">Q9、如何查看资源包 **适用范围和抵扣规则** ？</a></font>

<br />

<div id="Q1" />

<br />

**Q1、购买后，为什么实时消费产生的计费用量没有抵扣？**

请先确保资源包类型与计费项是否一致，若一致，购买后数据非实时更新，一般次日查看即可。若不一致，则无法抵扣，可申请退款重买正确的资源包。

<br />

<div id="Q2" />

<br />

**Q2、抵扣的量为何与购买的量不一致？**

请先查看资源包详情，判断该包类型是否为融合资源包，若为融合包，需要按抵扣系数去推算是否抵扣完毕。
![image.png](/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-common-problems/Fv0dxF8Z5V6Iz50m3UifN0J_I8tu-82bc6d54f1ea.webp)

<img src="/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-common-problems/FrCasdR5GgPxcxa9ANQXm3mQ6Rz4-fa734fc145a7.webp" width="70%" />

<br />

**具体示例**：
您购买了AI的融合包，在当月计量上产生了deepseek-r1模型输入100token、输出100toekn，则该融合包按抵扣系数，输出的抵扣系数是4，一共使用资源包500token。

<br />

<div id="Q3" />

<br />

**Q3、为什么我查看资源包管理显示资源包有剩余，但是却没有继续抵扣我的计费项用量？**

请您先核对下该资源包的结转方式，若为按月分配的资源包，在资源包管理中会展示结束时间为止全部用量总和，实际每月最多可抵扣的还是有固定限额，超过每月分配的限额，不能预支后面月份的容量。

**具体示例**：

购买了国内存储资源包100GB按月分配不可结转，有效期6个月，则该资源包展示总容量是100\*6=600GB，实际是按每个月分配100GB，当月最多只能用100GB。

<img src="/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-common-problems/Fpvj0-MJt6viwqy72IE5jxQs7MVI-43b58881deaa.webp" width="70%" />

<br />

<br />

<div id="Q4" />

<br />

**Q4、我购买了直播流量包或视频监控流量包或海外CDN加速包，为何不能抵扣当月实时账单金额？**

1）直播流量包：若您开通并使用了直播产品，直播产品默认是带宽计费，流量包只能抵扣流量计费，请检查您的计费方式是否为流量计费[去切换](https://portal.qiniu.com/financial/price?product=mikustream)；若不是，可手动切换或联系销售、提工单更改。（注意：切换后从切换操作日当天开始走流量计费，切换前的仍按带宽计费。）
![image.png](/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-common-problems/FmxeLxq-v7w56A2zpS_j5_bxF7GN-d6cbc5d81686.webp)

<br />

2）视频监控流量包：若您开通并使用该产品，该产品默认是带宽计费，流量包只能抵扣流量计费，请检查您的计费方式是否为流量计费[去查看](https://portal.qiniu.com/financial/price?product=qvs)。
若不是，可手动切换或联系销售、提工单更改。（注意：切换后从切换操作日当天开始走流量计费，切换前的仍按带宽计费。）
![image.png](/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-common-problems/FjqNrxqCV9joaazoMICEFWqgfiM7-7c1376f814d4.webp)

3）海外CDN通用加速包：海外通用加速包虽然是各个海外地区通用，本质上还是融合资源包，按一定抵扣系数实现多地区可用。若您的海外CDN计费项为“海外未分区”，则不可以使用该包。需要联系销售或提工单，改成海外分区计费才可以使用。

<br />

<div id="Q5" />

<br />

**Q5、为什么当月实际使用CDN产品0.6GB，资源包却抵扣了1GB？**

资源包最小抵扣单位为对应产品计费项的最小计量单位向上取整，各计费项的最小计量单位具体可参考官网价格页面。

<br />

<div id="Q6" />

<br />

**Q6、为什么新买的miku直播流量资源包无法抵扣直播云流量？**

直播云产品和miku直播是2个不同的产品，无法使用miku直播流量资源包抵扣直播云产品产生的流量费用。

<br />

<div id="Q7" />

<br />

**Q7、如何查询资源包抵扣规则和支持的模型或计费项？**

可以在 [资源包管理](https://portal.qiniu.com/financial/orders/respack-mgr/all) 点击 所有资源包，然后点击对应资源包的 `详情`，进去后点击 `适用范围和抵扣规则` 查看
![image.png](/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-common-problems/FpdLYoU_vI5OHek1WudXb_Stghue-9b836007f31e.webp)
![image.png](/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-common-problems/Fk4IrIwY_n7I4IvwJVQYqgRNg5p8-0a7576f71b62.webp)

<br />

<div id="Q8" />

<br />

**Q8、新购且未抵扣使用的资源包生效时间选错了，如何处理？**

可以在 [订单列表](https://portal.qiniu.com/financial/orders/list) 找到对应资源包订单号，然后添加 [工单](https://support.qiniu.com/tickets) 界面左下角的专属商务微信，联系商务沟通处理。

<br />

<div id="Q9" />

<br />

**Q9、如何查看资源包 **适用范围和抵扣规则** ？？**

1、购买前：可以在 [云商城](https://qmall.qiniu.com/) 商品分类 - 选择对应产品后，在购买界面点击 `适用范围和抵扣规则` 查看
![image.png](/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-common-problems/FijnlKl7fqQX8rGHJFrt4vKzt7uD-b6069288fe4b.webp)
![image.png](/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-common-problems/FrFWruX6n4rdASUxITgiNDfzqJnK-5fa98efb31b2.webp)
2、购买后：可以在 [资源包管理](https://portal.qiniu.com/financial/orders/respack-mgr) 界面找到对应资源包后，点击 `详情` - `适用范围和抵扣规则` 查看
![image.png](/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-common-problems/Fv0dxF8Z5V6Iz50m3UifN0J_I8tu-82bc6d54f1ea.webp)

<img src="/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-common-problems/FrCasdR5GgPxcxa9ANQXm3mQ6Rz4-fa734fc145a7.webp" width="70%" />


# 资源包介绍 (/account/resource-package-management/0-the-resource-bundle-is-introduced)



最近更新时间: 2026-08-18 11:53:05

## 资源包介绍 [#资源包介绍]

资源包（预付费）是七牛针对部分云服务计费项推出的优惠产品，您可以通过购买不同的资源包来抵扣对应的计费项用量，如国内CDN中国大陆资源包可以抵扣CDN-HTTP-中国大陆、CDN-HTTPS-中国大陆、动态加速-动态请求(HTTP 协议)-中国大陆、动态加速-动态请求(HTTPS 协议)-中国大陆这四种计费项产生的用量。相较于按月付费，资源包产品在一定程度上可以节省云服务成本，享受比按月计费较低的优惠价格。

## 资源包基本类型 [#资源包基本类型]

资源包当前分为两种类型：单资源包、融合资源包，区别如下：

* 单资源包：仅能抵扣唯一一种计费项，如智能直播鉴黄资源包，仅能抵扣直播鉴黄计费项产生的用量；
* 融合资源包：购买后，可以按抵扣比例抵扣多种计费项，如国内CDN中国大陆资源包。

<img src="/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-is-introduced/FrZCWwIk6YJ_JpQmDqOhijNCoz5h-fdf9c250bcc4.webp" width="70%" />

<img src="/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-is-introduced/FheXPIVjZNEWHhjCGM_O1U6S7frK-b5737e449ad4.webp" width="73%" />

***

## 资源包结转方式 [#资源包结转方式]

|结转方式类型|举例|
\|-|-|-|
|一次性分配|资源包容量为100GB。客户购买后一次性下发100GB，在有效期内可使用，过期后未用完的作废。|
|按月分配可结转|资源包容量为100GB/月 1年有效期，客户购买后，每月下发100GB，当月未用完的量会结转到次月，共发12个月。|
|按月分配不可结转|资源包容量为100GB/月 1年有效期，客户购买后，每月下发100GB，共发12个月。当月未用完的量，月底清零，次月继续下发100GB。|

***

## 资源包有效期 [#资源包有效期]

资源包下单时需要客户选择：当月1日生效或次月1日生效。

| 选项     | 说明                                    | 举例                                                                             |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------ |
| 当月1日生效 | 无论在当月中的哪一天购买，均可抵扣当月1日0点开始以后产生的对应计费项用量 | 购买时间为2022年8月13日，选择当月1日生效，1年有效期。则该资源包有效期为\[2022年8月1日0点\~2023年8月1日 0点）注意：左闭右开区间。 |
| 次月1日生效 | 无论在当月中的哪一天购买，均可抵扣次月1日0点开始以后产生的对应计费项用量 | 购买时间为2022年8月13日，选择次月1日生效，1年有效期。则该资源包有效期为\[2022年9月1日0点\~2023年9月1日 0点）注意：左闭右开区间。 |

<br />

<font color="red"> &#x2A;*注意：** </font>
资源包未到开始时间或者超过结束时间均不可用于抵扣计费项用量。超过结束时间后，该资源包将过期，即使剩余也不再可用。

***

## 特殊时段资源包 [#特殊时段资源包]

部分资源包，如CDN、直播产品提供选择【闲时段】、【日间时段】、【忙时段】等特殊时间段的资源包，购买时请注意：特殊时段的资源包仅能抵扣标注时段区间的对应计费项用量。

**具体示例**：

如购买CDN日间时段包，则仅能抵扣CDN对应计费项在9:00～18:00期间产生的用量。当您购买多种时段包时，具体的抵扣顺序可见：[资源包抵扣逻辑](/account/resource-package-management/0-the-resource-bundle-logic-deduction)

<img src="/docs-assets/account/%280-manual%29/resource-package-management/0-the-resource-bundle-is-introduced/FoQYIS9u8zs3PxUNulNtf-JA1Gos-659536c11eb0.webp" width="70%" />


# 资源包抵扣逻辑 (/account/resource-package-management/0-the-resource-bundle-logic-deduction)



最近更新时间: 2024-08-29 18:00:55

资源包支持叠加购买，若您有多个相同类型的资源包以及免费额度，则抵扣顺序为：

**免费额度 > 特殊时段（日间、闲时） > 全时段 > 过期时间 > 资源包类型（非融合/融合）**

即同类型的资源包抵扣顺序先后为：

1. 抵扣实名认证用户每月享有的免费流量额度
2. 根据流量的时间判断产生的流量类型为 闲时/日间/全时段 流量，优先抵扣 闲时/日间 流量包，后抵扣 全时段 流量包
3. 抵扣全时段资源包
4. 按资源包到期时间，优先抵扣快到期月份的资源包
5. 按照资源包类型， 优先抵扣【非融合资源包】再抵扣【融合资源包】

***

**具体示例**：

【CDN示例】
客户A买了2个CDN资源包，一个国内CDN闲时段流量10TB，有效期到2020年12月底，另一个是国内CDN全时段流量100TB，且客户有10GB免费额度，则抵扣顺序为：免费额度>国内CDN闲时段流量10TB（优先抵扣符合闲时段期间的用量）>国内CDN全时段流量100TB。


# 添加银行卡相关操作手册 (/account/overseas-payment-methods/0-payment-management)



最近更新时间: 2026-05-08 18:43:26

# 操作流程 [#操作流程]

### 1、添加银行卡 [#1添加银行卡]

前往【[支付方式管理](https://portal.qiniu.com/financial/payments)】页面，点击【添加支付方式】按钮，填写银行卡信息。

* 支持带有 Visa、Mastercard 标志的信用卡/借记卡。
* 添加银行卡过程中，会进行 3D 验证，若认证不通过请联系您的发卡行核对。
* 3D 校验后会冻结 $ 5 以验证您的身份，验证通过后会立即取消冻结（此操作并不会真正扣费）。
  ![image.png](/docs-assets/account/%280-manual%29/overseas-payment-methods/0-payment-management/FvnB5CWVWPKsvSyEHVmgl4cyidqE-f5ec63d00bb3.webp)
  ![image.png](/docs-assets/account/%280-manual%29/overseas-payment-methods/0-payment-management/Fqx8bYFl3_xk_bfzdiGm5BUBnn0o-43ada494e7a5.webp)

### 2、设置为默认支付方式 [#2设置为默认支付方式]

* 添加首张银行卡会自动设置为默认支付方式，非首张银行卡可添加时设置也可添加后自助设置；
  ![image.png](/docs-assets/account/%280-manual%29/overseas-payment-methods/0-payment-management/Fp0o_QiycUW-5OPVlrJ3CGtLiYEt-0688ef66c5cd.webp)

### 3、删除银行卡 [#3删除银行卡]

* 非默认支付方式您可自助删除；
* 默认支付方式暂时不支持删除，您可更换默认支付方式再进行删除。如有任何需求请联系商务哦～
  ![image.png](/docs-assets/account/%280-manual%29/overseas-payment-methods/0-payment-management/FsjXMhoyGbTqxfgPD1QL7YIiYb4s-d05941bba512.webp)


# 系统授信&自动付款 (/account/overseas-payment-methods/0-system-credits)



最近更新时间: 2024-03-07 15:09:16

# 概述 [#概述]

系统授信和自动付款是为您（海外用户）提供的一种后付费方式。添加银行卡后系统会自动授予您 $ 10 的初始信用额度，当您的消费金额超过当前信用额度时，系统将对您添加的银行卡自动扣费。扣费成功后，系统根据您的付款金额调整信用额度。当您的消费金额再次超过当前信用额度时重复上述操作。出账后，系统优先使用账户余额支付账单，余额不足时，差额部分从您银行卡中扣费。出账后系统根据您的消费情况再次调整信用额度。

# 详情 [#详情]

## 系统授信条件 [#系统授信条件]

添加银行卡，添加后系统会自动授予您信用额度。

## 银行卡扣费时点 [#银行卡扣费时点]

月中扣费：一般在上午 9:00 左右。
出账扣费：每月出账后（一般在每月 1～4 号）。

## 银行卡扣费金额 [#银行卡扣费金额]

月中：扣费金额=现金+赠送金-未支付金额-实时消费金额
出账后：系统优先使用账户余额支付账单，余额不足时，差额部分从您银行卡中扣费。

## 系统授信金额调整 [#系统授信金额调整]

月中：月中付款金额\*2
出账后：Min（近三个月账单金额最大值，当前信用额度）

## 系统授信金额上限 [#系统授信金额上限]

系统授信金额上限为 $ 200，当您的消费金额超过该上限则会触发自动付款。

## 银行卡扣费失败 [#银行卡扣费失败]

扣费失败后将进入账号冻结流程，为避免账号冻结影响您的使用，请保证银行卡状态正常。

## 更换默认支付方式 [#更换默认支付方式]

更换默认支付方式后，系统授信金额将恢复为初始授信金额 $ 10。


# 控制台操作安全保护说明 (/account/security-settings/0-identity-verification)



最近更新时间: 2023-09-14 15:25:59

# 功能说明 [#功能说明]

在进行一些敏感操作（修改邮箱、修改密码等）时，需要先进行身份验证，完成验证后，才可以继续进行操作，**验证后验证状态持续5分钟有效**（5分钟内无需再次验证）

未开启安全保护时，系统会使用默认的可选验证方式验证，开启安全保护后，验证时则需要使用用户开启的验证方式来进行身份验证

# 开启安全保护 [#开启安全保护]

在安全设置中开启两步验证来开启安全保护，当开启两步验证后，验证时可选的验证方式将会限定在开启两步验证时选择的身份验证方式中
![image.png](/docs-assets/account/%280-manual%29/security-settings/0-identity-verification/FpCOkLn2CJGOXFp_pSG1R9hosoHC-55bcecff9f26.webp)

![image.png](/docs-assets/account/%280-manual%29/security-settings/0-identity-verification/Fh148MXTrHMyz0qNOkQVSD3sqhBh-699c7a7b2a41.webp)

# 身份验证使用说明 [#身份验证使用说明]

在点击一些需要验证的操作后，系统会自动弹出验证模态框，可以看到可选的验证方式，同时可以点击切换到对应验证方式

![image.png](/docs-assets/account/%280-manual%29/security-settings/0-identity-verification/Fou8_wMJtO4ZliGS3FizCw_jiR38-e247e4775723.webp)

验证方式：

* 密码验证

  输入密码进行验证
  ![image.png](/docs-assets/account/%280-manual%29/security-settings/0-identity-verification/FkSd5I38l1YoZ8f3OGOLEVCehQq6-d13cc23398bd.webp)

* 手机短信验证

  发送验证码到手机后，填写验证码进行验证
  ![image.png](/docs-assets/account/%280-manual%29/security-settings/0-identity-verification/FgV1S9puw5Qa7Pa__tY059MPlo4o-593ed53a7777.webp)

* 邮箱验证

  发送验证码到邮箱后，填写验证码进行验证
  ![image.png](/docs-assets/account/%280-manual%29/security-settings/0-identity-verification/FnVW1J1VEMJktkNcR42feF6yZmDx-9e65c0c59e04.webp)

* MFA验证器验证

  填写MFA验证器中对应的验证码进行验证
  ![image.png](/docs-assets/account/%280-manual%29/security-settings/0-identity-verification/FpDVFDkABlCYV6xeYwgzG4hP0ItA-3f1c7fe9d90e.webp)

<br />

如果所有可选的验证方式都无法验证，请提交工单

![image.png](/docs-assets/account/%280-manual%29/security-settings/0-identity-verification/FlQCQFChnp9v-qVydVeKugOdwucV-00e85ff317e3.webp)


# 注册收不到手机短信验证码和邮箱激活邮件怎么办？ (/faq/account-finance/account-problem/1215-don-t-get-message-authentication-code)



最近更新时间: 2026-08-27 16:16:09

## 手机收不到短信验证码怎么办？ [#手机收不到短信验证码怎么办]

正常的话一般会在 1 分钟内会收到手机验证码。

有下面这几种解决方案

* 看下拦截短信，是否被拦截。

* 重新发送，或者换一个手机号试试（可重新注册账号）。

* 目前暂时不支持海外手机号注册。

<br />

## 邮件收不到激活邮件怎么办？ [#邮件收不到激活邮件怎么办]

正常的话一般会在 1 分钟内收到邮件验证码。

有下面这几种解决方案

* 检查你输入的邮件箱是否填写正确，激活邮件确保没有在垃圾邮箱和删除邮箱中。

* 接收方也有可能服务器拒绝了或者延迟。请等10分钟后查看下是否收到验证码邮件。

* 换一个邮件箱试试(可重新注册账号)。

* 发份邮件给自己这邮件箱试试是否能接受到。

* 若是QQ邮箱没有收到验证码邮件或者底层使用QQ邮件服务器的邮箱，请读“QQ邮箱收不到怎么办” [http://kf.qq.com/faq/120322fu63YV130805rYRFzu.html](http://kf.qq.com/faq/120322fu63YV130805rYRFzu.html)

* 当其他方式都不行，请联系技术支持 400-101-8589 转 2 号线来激活。


# 如何修改解绑MFA (/faq/account-finance/account-problem/13534-MFA)



最近更新时间: 2026-07-21 18:14:12

关闭两部步验证，可以通过人工申诉提供相关资料进行修改，将材料发送邮件到 [support@qiniu.com](mailto:support@qiniu.com)

需要提供的信息如下：

a、个人实名认证：请提供注册邮箱、注册手机号码、手持与实名认证一致的身份证正面图片、关闭两步验证的原因；

b、企业实名认证：请提供注册邮箱、实名认证的营业执照图片、申请人手持正面身份证图片（如果申请人不是法人的话，需要额外提供公司盖章的说明文件）、关闭两步验证的原因。将资料以扫描件的形式发送到[support@qiniu.com](mailto:support@qiniu.com)邮箱

邮件发送后请工单上告知我们（麻烦提供下发送邮件的邮箱账号），提供发件邮箱和联系电话。这边同步给商务为您审核处理

邮件内麻烦备注上原账号邮箱和手机号码


# 七牛实名认证细则须知 (/faq/account-finance/account-problem/1465-seven-cattle-real-name-authentication-details-information)



最近更新时间: 2026-07-02 15:45:49

| 七牛实名认证细则须知                                                |
| --------------------------------------------------------- |
| 一个身份证号能认证两个账号                                             |
| 一个企业执照号码只能认证三个 **企业用户**                                   |
| 人工审核方式身份认证提交后，在审核阶段以及认证通过后，不能修改认证信息。如审核被拒绝， **可重新发起身份认证** |

| 人脸认证失败                                                             |
| ------------------------------------------------------------------ |
| 人脸认证失败的话，可以试试使用身份证 + 银行卡的方式认证，看看是否可以，人脸验证次数如果用完了可以提交工单进行人工反馈新增认证次数 |


# 如何修改手机号码 (/faq/account-finance/account-problem/1469-change-the-phone-number)



最近更新时间: 2026-05-07 14:31:59

# 方法一 [#方法一]

点击官网右上角的管理控制台——个人面板——个人中心的安全设置更改手机，发送验证码，验证之后就可以对手机号进行修改。单击进入[修改地址](https://portal.qiniu.com/developer/user/security)。
![image.png](/docs-assets/faq/account-finance/account-problem/1469-change-the-phone-number/FrhBnzxBpJJ_Ssu8pENtoV802Tus-539acccc0fce.webp)

# 方法二 [#方法二]

[提交工单](https://support.qiniu.com/tickets/new-for-person)通过人工申诉提供相关资料进行修改，将材料发送邮件到 [support@qiniu.com](mailto:support@qiniu.com)，需要提供的信息如下：

1. 个人实名认证，请提供注册邮箱、修改原因、手持与实名认证一致的身份证正面图片、新手机号码；
2. 企业实名认证，请提供注册邮箱、修改原因、与实名认证一致的证件图片、申请人手持正面身份证图片（如果申请人不是法人的话，需要额外提供公司盖章的说明文件）、新手机号码。
   我们后台操作完毕后，重新登录系统会提示您短信验证新的手机号，验证完毕后手机号即修改完成。


# 怎么获取或者找到 Access Key 和 Secret Key (/faq/account-finance/account-problem/1479-how-to-access-or-locate-the-access-key-and-secret-key)



最近更新时间: 2026-05-07 12:19:46

获取或者找到你的Access Key和Secret Key，可以先登录进入你的帐号，点击“个人面板”，面板中点击“[密钥管理](https://portal.qiniu.com/developer/user/key)”，之后你会看到你的Access key 和 Secret Key。如下图。

![image.png](/docs-assets/faq/account-finance/account-problem/1479-how-to-access-or-locate-the-access-key-and-secret-key/FulMCuW87Mw9awkzfCGXTnCtXNZ4-ee6cbf2b75d2.webp)

如果AK SK 泄露，需要更换AK SK ，必须先创建一组新的AK / SK , 然后将老 AK / SK 停用删除
![image.png](/docs-assets/faq/account-finance/account-problem/1479-how-to-access-or-locate-the-access-key-and-secret-key/FjRP6E_Av1Opl8DTjL-AAkdL1HMr-6ef6913d03cb.webp)
![image.png](/docs-assets/faq/account-finance/account-problem/1479-how-to-access-or-locate-the-access-key-and-secret-key/FpTCiQUas2NMM4FeLTIJ6rIDMjuC-c34c4f69db40.webp)


# 账户冻结与解冻 (/faq/account-finance/account-problem/1489-freeze-and-thaw)



最近更新时间: 2026-05-07 12:04:27

# 1.冻结条件 [#1冻结条件]

当前账户余额小于当前消费金额时，且没有欠费保护期或者超过欠费保护期，系统自动对账户执行冻结操作:

* 七牛云服务将不可用。
* 账户冻结期间，因保存数据而使用的存储空间仍将计算费用。

# 2.冻结前后的通知 [#2冻结前后的通知]

通知渠道：邮件 + 短信 + 站内通知

## 通知内容以邮件为例 [#通知内容以邮件为例]

冻结前提醒

> *备注：*
>
> *这个例子中的账号这时候至少充值50元才不会被冻结。*
>
> *但是为了您的服务正常使用，建议您账户余额足够支付到本月结束；否则还会收到余额不足提醒。*

subject：\[七牛云]24 小时冻结告知邮件
截至 07-14 01:39，您的账户 [sales@qiniu.com](mailto:sales@qiniu.com) 余额为 800 元，当前已产生消费 850 元。
您的账户余额已不足支付当前消费，依照冻结用户政策，您的账户将在 24 小时后被冻结！
为了保证您能正常使用我们的服务，建议您尽快充值。
如有其他问题，请联系我们。
此致
七牛云团队

冻结后

subject：\[七牛云]冻结告知邮件
截至 07-15 01:39，您的账户 [sales@qiniu.com](mailto:sales@qiniu.com) 余额为 800 元，当前已产生消费 900 元。
依照冻结用户政策，您的账户因余额不足以支付当前消费已被冻结。
自冻结起您将无法使用七牛云服务。您的账户数据将被保留 30 个自然日，若超过 30 个自然日仍未解冻此账户，系统会默认您已放弃此账户的所有权。
 建议您尽快充值。充值后若余额大于实时使用量，账户将在 10 分钟内解冻。
如有其他问题，请联系我们。
此致
七牛云团队

# 3.解冻方法 [#3解冻方法]

请前往[帐号充值](https://portal.qiniu.com/financial/recharge)及时完成现金充值。 用户可参考账户过去使用量数据，计算未来三个月的预估费用，用户可选择一次性充入等额现金,以便享受稳定的服务。

![image.png](/docs-assets/faq/account-finance/account-problem/1489-freeze-and-thaw/FoguEOzt1mymTA1X7SJgYZwzQiY-687045bbd70a.webp)

# 4.账户冻结后的影响 [#4账户冻结后的影响]

* 当账号冻结时，七牛云服务不可用。

* 账户被冻结后,七牛云将保留账户中的所有数据连续 30 个自然日(自冻结之日起计算)。

* 账户被冻结超过连续 30 个自然日后,视同用户默认放弃数据所有权,七牛云之后将有权定期删除账户中的所有数据,并且不可恢复。

* 在账户冻结、且保留数据期间，如用户想要取回数据，请先完成现金充值缴清账户欠费款项，然后联系七牛云技术支持进行后续沟通。

* 冻结帐号期间，因保存数据而使用的服务仍在计算费用，例如：存储服务。自服务欠费冻结日起，该服务所占用的存储空间资源仍会继续按日计费。

* 七牛云不鼓励客户拖欠费用和账单。若账号因欠费而被冻结，您仍应将欠缴的费用付清，同时支付因冻结期间存储文件和任何资源所造成的额外费用。否则，七牛云将保留按照您未付费用的万分之五的标准，按日向您收取滞纳金的权利。按照规范制度和法律，七牛云有权力采取法律途径追回欠款。

# 5.账户被冻结后,充入抵用券/现金券为何不能解冻? [#5账户被冻结后充入抵用券现金券为何不能解冻]

* 抵用券/现金券不等同于现金充值，无法解除账户的冻结状态，账户欠费冻结期间，请充入现金进行解冻。

* 已充入现金会立刻用于缴清账户欠费款项，并重新判断是否继续冻结；不满足继续冻结条件的,账户将10分钟后解冻。解冻完成后,后续扣费将会优先扣除抵用券/现金券。

* 欠费期间所充值的抵用券余额仅用在下月消费时抵扣，并且不能抵消现金余额的欠费。


# 个人升级企业账户 (/faq/account-finance/account-problem/1730-personal-upgrade-corporate-account)



最近更新时间: 2026-05-07 12:59:43

个人升级企业账户，请到portal的右上角`个人面板` > `个人中心`，点击[实名认证](https://portal.qiniu.com/developer/user/identity/choice)，点击`升级至企业用户`。见下图
![image.png](/docs-assets/faq/account-finance/account-problem/1730-personal-upgrade-corporate-account/FoLGNdsnvmuOn18X3lTucjnOoKll-9641bba5012e.webp)

企业账户更换信息也可以在这修改。


# 企业认证说明 (/faq/account-finance/account-problem/3819-enterprise-certification)



最近更新时间: 2026-05-07 13:48:26

企业账号认证有两种认证方式：企业银行卡打款认证、企业法人/被授权人扫脸验证
![image.png](/docs-assets/faq/account-finance/account-problem/3819-enterprise-certification/Fvz3GG8dU5UvMHpe7Mm7u5FDT_Q8-d031ea2cd1d7.webp)

1、社会信用代码认证

统一社会信用代码由18位数字或大写拉丁字母组成，包括登记管理部门代码（1位）、机构类别代码（1位）、登记管理机关行政区划码（6位）、主体标识码（9位全国组织机构代

码）、验码（1位）五个部分组成。

![FiyvSe0UQ-1OWNP9LgoPRXN8nS0p](/docs-assets/faq/account-finance/account-problem/3819-enterprise-certification/FiyvSe0UQ-1OWNP9LgoPRXN8nS0p-0b621a091280.webp)

2、营业执照号认证

营业执照号代码号由15位数字组成，包含14位数字本体码和1位数字校验码组成，其中本体
码从左至右依次为：6位首次登记机关码、8位顺序码，1位数字校验码组成。

![FkwcN62xzJtSC\_EdUOhcFaoIIcAA](/docs-assets/faq/account-finance/account-problem/3819-enterprise-certification/FkwcN62xzJtSC_EdUOhcFaoIIcAA-b275e756d57a.webp)

3、非盈利组织认证

非盈利组织认证需要提供公司名称和组织机构代码。组织机构代码是对中华人民共和国内依法
注册、依法登记的机关、企、事业单位、社会团体，以及其他组织机构颁发一个在全国范

围内唯一的、始终不变的代码标识。全国组织机构代码由八位数字（或大写拉丁字母）本体代码和
一位数字（或大写拉丁字母）校验码组成。组织机构代码查询地址[http://www.nacao.org.cn/portal/](http://www.nacao.org.cn/portal/)

![FjkOOhsc2KaDhaaMFrciQqVkzOW7](/docs-assets/faq/account-finance/account-problem/3819-enterprise-certification/FjkOOhsc2KaDhaaMFrciQqVkzOW7-fc036ef0dc19.webp)


# 重置密码 (/faq/account-finance/account-problem/3965-reset-password)



最近更新时间: 2026-05-08 15:33:38

如果您忘记了您的登录密码，可以通过以下步骤重置您的密码：

# 步骤一 [#步骤一]

登录页面点击『忘记密码？』按钮

<img src="/docs-assets/faq/account-finance/account-problem/3965-reset-password/FkKlUnodpk1eZQQbzFZ0YD-Sw743-26c7ffa00cc4.webp" width="800" />

# 步骤二 [#步骤二]

## 通过【邮箱】找回 [#通过邮箱找回]

1. 输入忘记密码的注册邮箱，点击『找回密码』按钮，系统会发送一封重置密码的邮件到您的邮箱。

如果没有收到邮件，重置密码邮件可能被您的邮件服务商错误标记为垃圾邮件，您可以检查一下垃圾邮件中是否有重置密码邮件。

<img src="/docs-assets/faq/account-finance/account-problem/3965-reset-password/FiwtLi4AbyyWYdsSycXAn8us23ns-c36c98508122.webp" width="800" />

<img src="/docs-assets/faq/account-finance/account-problem/3965-reset-password/FouF7tpeBodh9OarKhUSMG_VxtE0-7f5b7c3a69a4.webp" width="800" />

2. 点击邮件中的『重置密码』按钮（如果按钮无法点击，您也可以根据邮件下方提示进行操作）

<img src="/docs-assets/faq/account-finance/account-problem/3965-reset-password/Fs4hAtRoBFAd0excXVeqrdcDg76W-57cea3b66213.webp" width="800" />

3. 进入重置密码页面，重新设置您的登录密码。设置完成后，点击『重置密码』按钮。

<img src="/docs-assets/faq/account-finance/account-problem/3965-reset-password/FrdzB-sGtH340IUllI4pZluDX9Gi-5ed3715ca77c.webp" width="800" />

## 通过【手机号】找回 [#通过手机号找回]

1. 输入忘记密码的注册账号绑定手机号，点击『发送』按钮，系统会弹出图形验证码，图形验证码操作成功后，系统会发送一条重置密码的短信到您的手机号。

<img src="/docs-assets/faq/account-finance/account-problem/3965-reset-password/FpUToidm610OQq9lCo3GAdbOkrlU-58faa4d59047.webp" width="800" />

2. 收到后输入短信验证码，然后点击『找回密码』，进入重置密码页面，重新设置您的登录密码。设置完成后，点击『重置密码』按钮。

<img src="/docs-assets/faq/account-finance/account-problem/3965-reset-password/FrdzB-sGtH340IUllI4pZluDX9Gi-5ed3715ca77c.webp" width="800" />

# 步骤三 [#步骤三]

提示成功后，密码修改完毕。您可以使用新设置的密码进行登录。

<img src="/docs-assets/faq/account-finance/account-problem/3965-reset-password/Fj0F1XJZ4w0Ennh5ACStK5cBYA8-17f386960cf9.webp" width="800" />


# 支付宝认证失败 (/faq/account-finance/account-problem/4073-pay-treasure-authentication-failed)



最近更新时间: 2017-09-27 09:13:57

# 问题描述 [#问题描述]

支付宝认证失败，提示支付宝账号已被认证，或者提示授权不成功。

（支付宝认证请参考：[/account/identity-verification/0-quick-start-personal-authentication](/account/identity-verification/0-quick-start-personal-authentication) ）

# 问题原因 [#问题原因]

这样的报错原因基本有两种：

## 原因一 [#原因一]

您之前有其他的七牛账号绑定过该支付宝账号。你可以登录你的支付宝账号，点击 我的->设置->账号管理->账号授权 查看你的认证产品。详情如下：

![](/docs-assets/faq/account-finance/account-problem/4073-pay-treasure-authentication-failed/FsZoOSm-vZ5ZZEfH1VoV_W2QrahU-5f5de80426b6.webp)

如果你支付宝账号已经认证过，请您使用银行转账验证方式进行验证。

## 原因二 [#原因二]

授权失败可能是支付宝账号的某些不可抗拒原因，详情您可以咨询支付宝客服电话：95188 ，或者你提交工单，将您的授权失败的页面截图以及支付宝账号通过提交工单的方式提交给我们，这边会帮您查看授权失败的原因。


# 新版欠费流程 (/faq/account-finance/account-problem/5996-new-owe-the-process-description)



最近更新时间: 2026-08-07 16:49:51

# 一、欠费规则 [#一欠费规则]

当账户的可用额度小于0时，将进入欠费流程。
关于可用额度的更多说明请参考 [新版财务概况](/account/0-the-new-financial-situation)

# 二、欠费流程 [#二欠费流程]

**1.欠费通知。**

* 欠费当天七牛云会向您发送欠费的邮件和短信通知。

**2.欠费保护期。**

* 欠费后立即进入保护期，保护期内七牛云会**每天**向您推送一次提醒。
* \*\*保护期时长：\*\*保护期时长根据您的认证状态有所不同，未认证用户保护期1天，个人认证用户保护期3天，企业认证用户保护期5天。
* \*\*保护期内限制：\*\*保护期内，您使用的服务/功能将受到一定的限制，包括无法使用余额购买预付费产品，无法新增和修改CDN域名，无法开启云主机按量付费资源，对象存储内无法新建存储空间、绑定域名、跨区域同步等操作，详情参考文档[欠费状态下各产品的限制功能](/account/0-owe-the-protection-limit-function)。
* \*\*解除保护期：\*\*保护期内充值达到充值要求后，您的账号将自动恢复正常。

**3.欠费冻结。**

* 保护期结束后，七牛云会向您发送冻结的邮件和短信通知，您的账号将直接被冻结。
* 冻结期间，因保存数据而使用的服务仍在计算费用，例如：存储服务。自服务欠费冻结日起，该服务所占用的存储空间资源仍会继续按日计费。
* 当您的充值金额达到最低充值要求后，您的账号将自动解冻，恢复正常。
* 冻结期间，如果您想要取回数据，请先完成现金充值缴清账户欠费款项，然后联系七牛云技术支持进行后续沟通。
* 若账号因欠费而被冻结，您仍需付清欠缴的费用，同时支付因冻结期间存储文件和任何资源所造成的额外费用。否则，七牛云将保留按照您未付费用的万分之五的标准，按日向您收取滞纳金的权利。按照规范制度和法律，七牛云有权力采取法律途径追回欠款。

**4.资源清空。**

* 账户被冻结超过连续 30 个自然日后，视同您默认放弃数据所有权，七牛云将有权定期删除账户中的所有数据，并且不可恢复。

# 三、欠费后如何处理 [#三欠费后如何处理]

* 欠费后请尽快进行充值，充值入口：财务中心->[账户充值](https://portal.qiniu.com/financial/recharge)。
* 充值金额：不得低于当前账户的可用额度，建议适当多充值，避免继续欠费。
  ![](/docs-assets/faq/account-finance/account-problem/5996-new-owe-the-process-description/Fsx2KYALgVvPR6YcyJBOiKweZQd1-ca52ec1908f5.webp)

# 四、常见问题 [#四常见问题]

1.账户被冻结后,充入抵用券/现金券为何不能解冻?

* 抵用券/现金券不等同于现金充值，无法解除账户的冻结状态，账户欠费冻结期间，请充入现金进行解冻。
* 已充入现金会立刻用于缴清账户欠费款项，并重新判断是否继续冻结；不满足继续冻结条件的,账户将10分钟后解冻。解冻完成后,后续扣费将会优先扣除抵用券/现金券。
* 欠费期间所充值的抵用券余额仅用在下月消费时抵扣，并且不能抵消现金余额的欠费。

2.欠费保护怎么关闭？
账号处于欠费保护期内，无法关闭，需要充值补齐欠费解除欠费保护期状态后，在 [https://portal.qiniu.com/financial/overview](https://portal.qiniu.com/financial/overview) 这个界面会有关闭按钮
![image.png](/docs-assets/faq/account-finance/account-problem/5996-new-owe-the-process-description/Ft3PQEPbE0KvWcTgK8-h7oOZJcQ7-d89029b5b395.webp)


# 企业认证提示需加盖企业红章 (/faq/account-finance/account-problem-faq/4084-enterprises-certification-tip-without-red-chapter)



最近更新时间: 2018-08-08 12:01:47

# 企业认证提示需加盖企业红章 [#企业认证提示需加盖企业红章]

问题描述：在进行企业认证时，人工审核经常会显示审核失败，失败原因是：需加盖企业红色公章

如图所示：
![](/docs-assets/faq/account-finance/account-problem-faq/4084-enterprises-certification-tip-without-red-chapter/Fk1PxBLcZIKdQ1xjO2LHOjmhvLyU-2cf61f7bdb27.webp)

解决方案：现在企业认证的方式除了需要登记机关提供的签章，还需要企业的红章作为认证依据（可使用复印件）

标准如图所示：

![](/docs-assets/faq/account-finance/account-problem-faq/4084-enterprises-certification-tip-without-red-chapter/Fh9hz3KVRZm8YrImzk8Y8ILEXNJO-476b22b703e9.webp)


# 账户与账单问题 FAQ (/faq/account-finance/account-problem-faq)



最近更新时间: 2026-09-18 18:24:40

| Q1: 账户被冻结，充值并确认到账后为何还未解冻？                                                                |
| ---------------------------------------------------------------------------------------- |
| 充值并确认到账后，一般 10 分钟内可以解冻（CDN 服务会在20分钟内逐渐恢复）。如充值后 10 分钟仍未解冻，可以联系 400-101-8589 转 1 号线联系销售处理。 |

<br />

| Q2: 实名认证已申请，需要等多久审核通过？ |
| ---------------------- |
| 一般在 1 个工作日内。           |

<br />

| Q3: 我的账户有余额，为什么会被冻结？                                                                                             |
| ---------------------------------------------------------------------------------------------------------------- |
| 当账户实时消费大于账户内的余额时，七牛会给您的注册邮箱和手机号发送邮件和短信提醒，并在 24 小时内执行冻结。<br />另外如果我们有证据显示您的账号涉及黄赌毒、VPN、非法后门等非法业务，七牛保留拒绝给您提供服务的权利。 |

<br />

| Q4: 对公转账时的备注账号问题？是否一定需要备注，忘记写了怎么办                                                                                                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 对公转账时请备注您需要充值的七牛账号邮箱（如银行不支持"@"符号输入，请使用中文“艾特”替代。eg：[mail@163.com](mailto:mail@163.com)；mail艾特163.com）或([对公汇款界面](https://portal.qiniu.com/financial/recharge) 显示的充值账户ID（一般为100开头的数字）。                                                                                     |
| 对公转账的目标账号如果是[对公汇款界面](https://portal.qiniu.com/financial/recharge)获取的专属账号，那么可以不需要备注<br />如果是直接汇款转入七牛公共的账号<br />`开户行：上海浦东发展银行杨浦支行`<br />`户名：上海七牛信息技术有限公司`<br />`账号：98120154740008821`<br />那么必须填写备注，否则无法入账，需要您[提交工单](https://support.qiniu.com/question)，提供对公转账凭证，申请协助入账。 |

<br />

| Q5: 如何获取合同？                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------- |
| 电子合同：参考([电子合同说明及操作手册](/account/0-electronic-contract-documentation-and-operation-manuals))                       |
| 纸质合同：由商务为您提交申请，如您已有商务联系方式可直接与商务沟通处理；如您没有商务联系方式，您可以在工单中提供您的联系方式，然后 [提交工单](https://support.qiniu.com/question) 来申请 |

<br />

| Q6: 对公转账时网银方式，提示系统繁忙，是否有其他对公转账方式？                                                        |
| ---------------------------------------------------------------------------------------- |
| 对公转账目前只能通过网银方式支付，您也可以使用 [微信或支付宝在线充值方式](https://portal.qiniu.com/financial/recharge) 进行充值 |

<br />

| Q7: 如何查看账号消费明细？并购买对应的资源包？                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 账单明细查看方式参考 [查看账单](/account/bill-management/0-bill-review) 说明文档，资源包购买入口 [云商城](https://qmall.qiniu.com/) ，如果您不清楚应该购买哪些资源包，您可以联系 400-101-8589 转 1 号线联系销售咨询。 |

<br />

| Q8: 6个月以上的历史充值发票或1000元以下的专票，如何申请开具？                                                                                                                                                                                  |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 6个月以上的历史充值发票或1000元以下的专票，无法自主提交申请，您可以先在 [发票管理](https://portal.qiniu.com/financial/invoice-contract/invoice/setting?from=invoice) 界面添加开票信息，审核通过后，联系商务或 [提交工单](https://support.qiniu.com/tickets/new-for-person) 为您提交申请 |

<br />

| Q9: 银行转账的实名认证加急审核                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 财务打款实名认证审核通过后，系统会在每个工作日的11:30和16:30自动安排对公打款。整个认证过程通常在1-2个工作日内完成，无法申请加急处理。请留意您的对公账户到账信息，如超过3个工作日未收到打款，可 [提交工单](https://support.qiniu.com/tickets/new-for-person) 联系我们查询进度。 |

<br />

| Q10: 银行转账的实名认证加急审核                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 财务打款实名认证审核通过后，系统会在每个工作日的11:30和16:30自动安排对公打款。整个认证过程通常在1-2个工作日内完成，无法申请加急处理。请留意您的对公账户到账信息，如超过3个工作日未收到打款，可 [提交工单](https://support.qiniu.com/tickets/new-for-person) 联系我们查询进度。 |

<br />

| Q11: 账号欠费后会提醒么？                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------- |
| 是的，欠费当天七牛云会向您发送欠费的邮件和短信通知。欠费说明参考 [新版欠费流程](/faq/account-finance/account-problem/5996-new-owe-the-process-description) |

<br />

| Q12: 为什么有可用余额，但可提现金额为0？                                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 因为充值时间在2020年3月之前导致的，2020年3月之前的充值流水暂不支持自助申请提现，请添加 [工单系统](https://support.qiniu.com/tickets) 界面左下角的专属商务微信，联系商务为您处理 或 [提交工单](https://support.qiniu.com/tickets/new-for-person) 为您处理。 |

<br />

| Q13: 为什么账号显示欠费？且很早就被冻结了？                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 这种是因为有历史未支付账单导致的，您可以参考 [查看账单](/account/bill-management/0-bill-review) 查看历史账单明细，里面有详细的计费项信息，如果您对某个计费项有疑问，您可以 [提交工单](https://support.qiniu.com/tickets/new-for-person) 咨询。 |

<br />

| Q14: 账号欠费时可以通知多个手机号和邮箱，如何实现？                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 可以在控制台 [接收人](https://portal.qiniu.com/notification/recipient/user) 中添加手机号和邮箱信息，然后在 [基础接收设置](https://portal.qiniu.com/notification/user-setting/basic/finance) 中添加多个接收人来实现。 |

<br />

| Q15: 为什么AI推广页面和CPS推广页面的邀请人数不一致？                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AI推广和CPS推广是不同的活动，两个页面数据互不相关。AI推广活动说明参考 [AI 推理邀请活动规则详细说明](/faq/account-finance/account-problem-faq)，CPS推广活动说明参考 [推广奖励规则](/products/mkt/manual/7261-cps-promotion-rules) |

<br />

| Q16: 如何注销账号？                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 可以在 [注销账号](https://portal.qiniu.com/developer/user/security/cancellation) 界面提交，提交后账号会进入注销静默期，静默期结束后，账号将自动完成注销；注销相关说明参考：[七牛云账号注销协议](https://www.qiniu.com/agreements/unregister) |

<br />

| Q17: 账号注销静默期，能不能加快注销？                                                                 |
| ------------------------------------------------------------------------------------- |
| 不能，静默期结束后，账号将自动完成注销；注销相关说明参考：[七牛云账号注销协议](https://www.qiniu.com/agreements/unregister) |

<br />

| Q18: 为什么无法注册绑定192或170开头的手机号？        |
| ----------------------------------- |
| 目前禁止注册绑定192或170开头手机号，建议使用其他手机号注册或绑定 |

<br />

| Q19: 账号或CDN域名为什么被冻结封禁了？                                                               |
| ------------------------------------------------------------------------------------- |
| 一般是账号或CDN域名资源违规导致封禁的，如果您对处置结果有异议，可以通过 [账号冻结解冻申诉](https://www.qiniu.com/appeal) 平台提交申诉 |

<br />

| Q20: 账号有资源包，为啥欠费了？                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是资源包无法抵扣产生扣费的计费项或资源包过期导致的；<br /> 1、您可以在 [按量计费预估](https://portal.qiniu.com/financial/bills/estimated-consume) 查询扣费详情，里面有详细的计费项信息；<br /> 2、如果是资源包类型购买错误，您可以添加 [工单](https://support.qiniu.com/tickets) 界面左下角的专属商务企业微信，联系商务为您走退款流程，退款后您重新购买正确的资源包。 <br /> 3、资源包是否过期可以在 [资源包管理](https://portal.qiniu.com/financial/orders/respack-mgr) 界面查询确认。 |

<br />

| Q21: 为什么会有2个账号？                                                               |
| ----------------------------------------------------------------------------- |
| 一般一个手机号可以注册认证三个账号，使用手机号登录的时候会选择登录哪个账号，这个时候需要指定选择登录哪个账号的，或者使用邮箱登录即可，邮箱是每个账号唯一的 |

<br />

| Q22: 账号认证主体变更影响产品使用吗？                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 不会，账号主体变更只是变更账号实名认证主体信息，不会影响产品使用和数据；主体变更操作参考：[如何进行企业认证变更？](/account/identity-verification/0-how-to-make-enterprise-certification-changes) <br /> `注意：仅支持企业实名认证账号进行主体变更，个人实名认证账号不支持变更认证信息` |

<br />

| Q23: 账号对公充值或进行企业认证银行转账认证没有对应的支行？ |
| -------------------------------- |
| `支行信息缺少需填写对应上级分行即可`              |

<br />

| Q24: 支持设置欠费超出多少金额后，自动关停账号吗？         |
| ----------------------------------- |
| 不支持，七牛是后付费计费模式，根据实际使用量计费，且计费更新延迟一天。 |

<br />

| Q25: 如何查询历史充值明细？                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 可以在七牛控制台 - 财务中心 - [收支明细](https://portal.qiniu.com/financial/cost/income-expenses) 选择流水类型为 `充值` 进行查询。![image.png](/docs-assets/faq/account-finance/account-problem-faq/index/Fir0nmqFpiIRU4B0kk1L4dOExpKd-c9404f1ec049.webp) |

<br />

| Q26: 不记得原来的账号了怎么办？                                       |
| -------------------------------------------------------- |
| 可以看下是否有原账号的相关资源信息、如手机号、邮箱、空间名称、域名、域名解析、资源访问链接等都可以用于账号查询。 |

<br />

| Q27: 海外账号是否可以购买中国大陆服务器、CDN或对象存储？              |
| --------------------------------------------- |
| 暂不支持；如需使用中国大陆服务器、CDN或对象存储，需要您注册中国大陆账号并完成实名认证。 |

<br />

| Q28: 退款提现审核已通过，但一直未收到打款？           |
| ---------------------------------- |
| 财务预计每周四左右会统一处理打款，节假日顺延，辛苦耐心等待打款即可。 |

<br />

| Q29: 对公转账时，收款账号输入错误，如何处理？                                               |
| ----------------------------------------------------------------------- |
| 账号输入错误，银行会原路退回，充值失败，您那边重新使用正确的收款账号打款即可。之前的充值打款状态可在您的银行账号 - 收支明细中自行查询确认。 |

<br />

| Q30: 有2个七牛账号，如何将A账号的余额转移至B账号？                     |
| ------------------------------------------------- |
| 2个七牛账号的实名认证主体一致，且打款主体一致（都是打款到上海七牛或嘉兴七牛），才可进行余额转移。 |

<br />

| Q31: 有微信或支付宝充值记录，但在提现时找不到对应充值记录，是什么原因？                                                                                  |
| ----------------------------------------------------------------------------------------------------------------------- |
| 一般是您的这笔充值费用已经被账户消费占用，只能提现剩余金额导致的，可在 [提现](https://portal.qiniu.com/financial/withdraw) 界面点击 `系统自动提现` 按钮后选择对应充值记录进行提现。    |
| ![image.png](/docs-assets/faq/account-finance/account-problem-faq/index/Fov3pIZ_lf5or5qQl6o_JzU0KXlZ-226071693fc4.webp) |

<br />

| Q32: 如何联系账号专属商务？                                                                                                              |
| ----------------------------------------------------------------------------------------------------------------------------- |
| 在 [工单系统](https://support.qiniu.com/tickets) 左下角可以看到您的七牛账号专属商务企业微信，账单、资源包购买、资源包订单退款、充值到账、价格和计费、发票申请或退票等可以直接添加专属商务微信，与商务沟通为您处理。 |

<br />

| Q33: 如何开启`资源包到期提醒`的短信通知？                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 在 [消息中心 - 财务消息](https://portal.qiniu.com/notification/user-setting/basic/finance) 选择 **资源包到期提醒** 勾选短信即可。![image.png](/docs-assets/faq/account-finance/account-problem-faq/index/FqmYlLEW6LICzbyJthSCU1Qc1BiJ-c9bf5c7cf345.webp) |

<br />

| Q34: 实名认证失败，没有认证次数了，如何处理？                                                |
| ------------------------------------------------------------------------ |
| 可以提交 [工单](https://support.qiniu.com/tickets) 反馈技术支持为您增加认证次数后，重新提交实名认证申请。 |

| Q35: 需要获取七牛产品资质，比如等保证书、CDN牌照、体系认证、营业执照、等保三级测评、数据安全合规认证等，在哪里获取  |
| -------------------------------------------------------------- |
| 可以在 [工单平台](https://support.qiniu.com/tickets) 左下角添加您的专属商务进行申请。 |

| Q36: 海外账户绑定 Visa 或 Mastercard 后，是否会给账户钱包充值？如何使用信用卡支付？                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------- |
| 不会。绑定 Visa 或 Mastercard 只是用于后付费按量计费账单的自动扣款，不会向账户钱包预存资金，也不会产生充值到账金额。若页面仅显示银行转账，说明账户钱包充值不支持通过该信用卡直接加款；请确保已成功绑定信用卡且额度充足，系统会在次日账单更新后自动扣费。 |

| Q37: 验证码发送超限了，限制是多少呢？ |
| --------------------- |
| 目前限制次数是5次，超限后禁15分钟    |

| Q38: 海外账号绑定+86手机号失败？                       |
| ------------------------------------------ |
| 目前暂不支持海外账号绑定国内手机号，可以与商务经理或工单技术支持沟通确认具体使用姿势 |


# 常用单位换算 (/faq/account-finance/traffic-stats/1592-commonly-used-unit-conversion)



最近更新时间: 2017-08-31 17:30:58

# 七牛的带宽和流量单位之间是如何转换的? [#七牛的带宽和流量单位之间是如何转换的]

以 1M 带宽为例,每天的流量为: `1Mbps = (1Mbpsx24x3600)/8 = 10800MB = 10.546875GB`

# 七牛的存储和流量单位之间是如何转换的? [#七牛的存储和流量单位之间是如何转换的]

| 以此类推           |
| -------------- |
| 1 PB = 1024 TB |
| 1 TB = 1024 GB |
| 1 GB = 1024 MB |
| 1 MB = 1024 KB |
| 1 KB = 1024 B  |


# Chrome 浏览器打印账单出现丢页 (/faq/account-finance/bill/1501-print)



最近更新时间: 2026-05-07 14:39:42

chrome 浏览器的打印功能，保存为 pdf 会有丢页的情况，如果发现打印出的账单有问题时，解决方案如下：

1，更换浏览器，如：火狐浏览器等

2，打印时边距设置为 无

![](/docs-assets/faq/account-finance/bill/1501-print/FkkOjFR2UNGPJ4aFeAI4Q4_TrJYq-b53f50509b56.webp)

参考链接：
[stackoverflow：https://stackoverflow.com/questions/22744141/printing-from-chrome-missing-lines](https://stackoverflow.com/questions/22744141/printing-from-chrome-missing-lines)


# 欠费须知 (/faq/account-finance/bill/1543-lack-of-information)



最近更新时间: 2026-05-07 13:08:51

> 欠费后对账户有哪些影响？

* 欠费后，用户将会收到七牛云存储发送的欠费通知邮件。

* 收到欠费通知后请及时完成现金充值。

* 自冻结之日起的第 31 个自然日，如现金账户仍然欠费，视作您默认放弃数据，七牛云存储将删除账户中的数据，并且不可恢复。

* 在冻结帐号期间，因保存数据而使用的存储功能仍将计算费用，每逢扣费日相应的存储费用会被扣除。

可在个人面板 > 财务中心查看[财务概览](https://portal.qiniu.com/financial/overview)：

![image.png](/docs-assets/faq/account-finance/bill/1543-lack-of-information/FmUFLEigZNTMAnZXepwD0hBxWYJO-2497de3bec13.webp)

用户可在[收支明细](https://portal.qiniu.com/financial/cost/income-expenses)知道自己的付款和消费情况。在[按量计费预估](https://portal.qiniu.com/financial/bills/estimated-consume)查看当月的消费情况。


# 免费额度须知 (/faq/account-finance/bill/1574-free-credit-information)



最近更新时间: 2026-05-07 12:10:04

七牛的实名认证用户享有的免费额度如下：

## 一、对象存储 [#一对象存储]

| 计费项目                 | 免费额度          |
| -------------------- | ------------- |
| 标准存储免费空间             | 0-10 GB       |
| 标准存储数据读取             | 无上限           |
| 标准存储 GET 请求          | 第 0 次至 100 万次 |
| 标准存储 Put / Delete 请求 | 0-10 万次       |
| 标准存储 CDN 回源流出流量      | 0GB - 10GB    |
| 上传流量                 | 无上限           |

## 二、融合CDN [#二融合cdn]

| 访问区域 | 计费项目      | 额度             |
| ---- | --------- | -------------- |
| 中国大陆 | HTTP 下载流量 | 第 0 GB 至 10 GB |
| 其他地区 | HTTP 下载流量 | 第 0 GB 至 10 GB |

注：中国大陆和其他区域独立享有 10G HTTP 免费额度，共 20 G。

## 三、智能多媒体服务 [#三智能多媒体服务]

<table>
  <tbody><tr><td>计费项目</td><td>免费额度</td></tr><tr><td>音视频处理</td><td>20元</td></tr><tr><td>C1M1 自定义数据处理服务</td><td>750 小时</td></tr><tr><td colspan="2">部分图片处理服务</td></tr><tr><td>imageView2（图片基本处理）</td><td rowspan="6"><br /><br /><br /><br />每月共享 10TB 免费额度</td></tr><tr><td>imageMogr2（图片高级处理）</td></tr><tr><td>imageInfo（图片基本信息）</td></tr><tr><td>exif（图片 EXIF 信息)</td></tr><tr><td>watermark（图片水印处理）</td></tr><tr><td>roundPic（图片圆角）</td></tr></tbody>
</table>

## Q：使用量超出免费额度怎么办？ [#q使用量超出免费额度怎么办]

\*\*A：\*\*超过免费额度的流量，进入标准阶梯计费模式，按照价格表计费。
如本月的存储量为 5GB，下载流量为 15GB，请求 PUT 1 万次，GET10 万次。那么本月 5GB 存储为免费，下载流量中 0-10GB（小于等于 10GB）为免费，10GB-15GB（大于 10GB）按照 10GB-1TB 的标准阶梯计费进行计费，PUT 和 GET 的请求均为免费额度。
七牛的计费模式为当月使用，下月初扣费，例如，在存储达到 10G 后无需额外开通，您可以直接使用无上限的存储空间，建议您的账户预留足够余额，防止因账户余额不足以抵扣本月消费而被提前冻结。


# 七牛发出账单的时间 (/faq/account-finance/bill/1580-seven-cattle-issue-invoice)



最近更新时间: 2026-08-27 16:14:14

# 什么时候可以收到账单？ [#什么时候可以收到账单]

* 七牛云存储在每月的 3日至 5日，发出上月的账单。如：2012 年 4 月的账单，你将在 2012 年 5 月 3 日至5日之间收到。

* 友情提示：账单邮件使用 [billing@qiniu.com](mailto:billing@qiniu.com) 进行发送，为保证账单接收正常，请将此邮件地址添加为联系人。

* 如遇到账单问题请联系销售 400-101-8589转 1 号线。


# 抵用券使用和扣费须知 (/faq/account-finance/bill/1633-the-vouchers-deduction-notice)



最近更新时间: 2017-08-31 16:52:09

## 抵用券使用: [#抵用券使用]

* 取得七牛云存储的抵用券/体验券的号码，在财务 -> 抵用券 中进行激活操作。
* 抵用券的充值计入抵用券账户，显示为抵用券余额。
* 每个账户仅可进行一次使用 抵用券/体验券 号码进行充值。
* 其他形式获得的抵用券将会由系统自动充值到您的账户中。

## 抵用券如何扣费？ [#抵用券如何扣费]

* 除快递费外，我们将会优先扣除您的抵用券账户中的金额，并且优先扣除近期将会过
  期的抵用券。
* 月度账单开具时，在扣费时间点之前过期的抵用券仍有效。如抵用券 7 月 18 日过期，
  7 月账单发出后，8 月 5 日完成扣费，此时 7 月 18 日过期的抵用券仍然为有效抵用
  券，可参与账单的扣费。
* 月度账单开具时，在账单月过期的抵用券仍有效。如抵用券 7 月 18 日过期，7 月账单发出后，8 月 10 日完成扣费，此时 7 月 18 日过期的抵用券仍然视为有效抵用券，可参与 7 月账单的扣费。


# 七牛kodo计量方法 (/faq/account-finance/bill/1634-seven-cattle-billing-method)



最近更新时间: 2026-05-07 11:24:15

> 七牛的存储费用是怎么计算的？

* 七牛对存储、下载流量、请求次数分别计费。最终支付款项为三项之和。

* 存储量取月度日均值，进行费用的结算。如存储量每日的绝对值为 D1、D2、D3...D31 ，则最终月度结算费用时为 (D1+D2+...+D31)/31。

* 下载流量和请求次数以新增的数量进行累积计算。


# 音视频处理收费标准 (/faq/account-finance/bill/2654-audio-and-video)



最近更新时间: 2026-05-07 12:13:55

#### 转码单价 [#转码单价]

音视频转码的收费标准可以参考[转码官网价格](https://www.qiniu.com/prices/dora)，计费时长以转码后文件播放时长为准，而非转码过程消耗的时间。

#### 转码后的视频分辨率如果介于两个规格之间，那么收费按照分辨率为左开右闭空间阶梯状。 [#转码后的视频分辨率如果介于两个规格之间那么收费按照分辨率为左开右闭空间阶梯状]

例：转码后分辨率为750x700

长边：640 \<750 \<=1080

短边：480 \< 700 \< =720

所以按照sd（1080x720）的收费标准收费


# 订阅管理积分相关FAQ (/faq/aitokenapi/aitoken-sub-mgmt/13459-sub-mgmt-faq)



最近更新时间: 2026-04-30 17:39:26

**Q1：我可以同时购买多个订阅吗？**
A1：单个用户当前仅支持同时拥有一个有效的 AI 订阅。如需提升服务，可以升级当前订阅等级。

**Q2：订阅内的模型是否会随时变动？**
A2：订阅内模型会根据市场与技术动态适时优化，重大调整将提前通知，保障用户体验连续性。

**Q3：如果我的积分用完了怎么办？**
A3：如果仅是当前每周窗口内的额度已耗尽，建议您耐心等待下一个刷新周期，届时额度将自动恢复；若当月订阅的全部额度均已用完，建议您通过按量付费模式的 API Key 继续使用服务，确保您的使用不受影响。

**Q4：API 访问权限如何保障安全？**
A4：订阅仅能通过订阅 API Key 访问，可以前往[【API Key 管理】](https://portal.qiniu.com/ai-inference/api-key)管理你的订阅访问。

**Q5：可以随时升级或取消计划吗？**
A5：可以，升级订阅计划，权益&#x2A;*立即生效（例如从包月升级到包季或包年）**；取消订阅后，当前订阅周期内服务不变，到期后自动终止。目前暂不支持降级。

**Q6：订阅的积分额度没用完会不会过期？**
A6：所有订阅计划的月度额度遵循"**订阅周期清零**"规则，不累计至下一周期。订阅周期分别为：一个月30天，一个季度90天，一年365天。请您合理规划用量。

**Q7："每周刷新额度"具体是什么意思？如果我每周额度不够用怎么办？**
A7：这意味着系统**每周**为您补充一次可用额度。如果您在某个刷新周期内提前用完额度，则需要等待下一个刷新周期开始才能获得新额度。建议您合理规划使用；或者您也可以随时用"按量模式"应急。且固定时间内，订阅范围中所有模型**共享同一额度限制**，不单独计算。

**Q8：升级订阅时费用如何计算？**
A8：升级时，系统会自动计算当前订阅剩余天数对应的差价，您只需支付差额即可。升级后新计划立即生效，下次续费将按新计划价格扣费。例如：您在包月计划使用一半时升级到包季，只需按照剩余天数补缴差价，无需重新支付全额。

**Q9：我该如何选择订阅计划？**
A9：您可以根据贵司主要的使用场景来预估大致的需求量。如果仍难以决定，欢迎随时联系我们的客服，将竭诚为您提供个性化的选择建议。

**Q10：购买或自动续费订阅计划后，是否支持退款？**
A10：用户通过购买或者自动续费完成的扣款，除法律法规另有规定、支付渠道另有规则或本平台另有明确承诺外，已生效周期的服务费用不予退还。[自动续费服务协议](https://www.qiniu.com/agreements/auto-renewal)。

#

我们致力于打造透明公平、灵活便捷的 AI 模型订阅服务，帮助您轻松体验最前沿、最丰富的人工智能能力。若您遇到问题，欢迎随时联系我们的客服支持，获取更多帮助与建议！

感谢您的支持与信赖，祝您使用愉快！


# 大模型接口调用FAQ (/faq/aitokenapi/other/13462-aitoken-use-faq)



最近更新时间: 2026-10-15 17:19:10

# API兼容性问题 [#api兼容性问题]

## Q: API兼容哪些协议和接口标准？ [#q-api兼容哪些协议和接口标准]

A: 兼容OpenAI接口(/v1/chat/completions) 和 Anthropic接口标准(/v1/messages); 同时兼容HTTP流式和非流式调用。

## Q: 是否兼容HTTP GET方法？ [#q-是否兼容http-get方法]

A: 只有查询模型列表接口(/v1/models)支持GET操作，其他接口均为POST操作。

# 模型资源问题 [#模型资源问题]

## Q: 支持哪些模型？ [#q-支持哪些模型]

A: 支持国产主流顶级和开源大模型，价格与模型参数请参考[模型广场](http://www.qiniu.com/ai/models)
同时支持大语言模型（LLM/LRM文本生成/代码生成）、多模态模型（图片生成、视频生成）。

# Token用量计费问题 [#token用量计费问题]

# 账号认证问题 [#账号认证问题]

## Q: 作为渠道商客户，如何进行大模型分销? [#q-作为渠道商客户如何进行大模型分销]

## Q: 注册账号后，是否需要实名认证？ [#q-注册账号后是否需要实名认证]

## Q: 大模型API Keys与账号AK/SK有什么区别？ [#q-大模型api-keys与账号aksk有什么区别]

# 价格折扣问题 [#价格折扣问题]

# 其他问题 [#其他问题]

| Q1：如何调用 API 以及部署？                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------- |
| 可参考此处文档：[https://www.qiniu.com/products/ai-token-api#document](https://www.qiniu.com/products/ai-token-api#document) |

<br />

| Q2：API 接口是什么风格？请求参数和响应参数是怎样的？                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 接口兼容 OpenAI 风格，参数也完全兼容 OpenAI 的 sdk，比如 maxtoken、tempeature 等常见参数可以直接使用 sdk 中的参数；常见容易搞错的是 OpenAI sdk 配的 baseurl 一般是域名 + /v1，比如：[https://api.qnaigc.com/v1，而不是（https://api.qnaigc.com/](https://api.qnaigc.com/v1，而不是（https://api.qnaigc.com/) 或者 [https://api.qnaigc.com/v1/chat/completions）](https://api.qnaigc.com/v1/chat/completions）) |

<br />

| Q3：API 支持哪些模型？                                                                     |
| ---------------------------------------------------------------------------------- |
| 除了 DeepSeek-R1、V3 模型，也支持 Qwen 模型，模型列表参考：[AI大模型广场](https://www.qiniu.com/ai/models) |

<br />

| Q4：各种 AI App 或大模型聚合平台（如 cherrystudio 等），如何接入七牛的 API ？                                                                                                                                           |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 可以选择 OpenAI 的接入方式进行接入，常见容易搞错的是 url 配置一般是域名，比如：[https://api.qnaigc.com，而不是](https://api.qnaigc.com，而不是) [https://api.qnaigc.com/v1/chat/completions](https://api.qnaigc.com/v1/chat/completions) |

<br />

| Q5：API 的回答为什么没有思考过程？                                                            |
| ------------------------------------------------------------------------------- |
| 只有 deepseek-r1 模型是默认有思考过程的，回答内容开头有 \<think> 标签。也有小概率遇到 \<think> 标签内容为空的情况，属正常情况 |

<br />

| Q6：API 调用报错：`openai.InternalServerError: Error code: 503 - {'error': {'message': 'the price of the model is not set (model: deepseek-r1:671b)', 'type': 'quota_exceeded_error'}}`，怎么解决？ |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| model 字段的值传错了，需要严格和 [AI大模型广场](https://www.qiniu.com/ai/models)里面的“API model参数“的值保持一致，否则找不到模型                                                                                            |

<br />

| Q7：API 调用报错包含 header 字段的，比如：`"error":"authorization header missing", "status": false`，怎么解决？ |
| ------------------------------------------------------------------------------------------- |
| 往往是请求 header 或请求字段有问题，建议对照教程文档检查下；如果还未解决，可以咨询我们的技术支持，**注意抹掉 api key 敏感信息**                  |

<br />

| Q8：API 如何调用 DeepSeek 671B 的模型？            |
| ----------------------------------------- |
| 当前支持的 deepseek-r1 就是 671B 的全参数模型，也是所谓的满血版 |

<br />

| Q9：七牛云有哪些 GPU 主机可用来私有部署？支持多少人并发使用？                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GPU 主机 A100、V100、A10、H20、4090 等都有，可以部署 671b 量化全参模型，也可以跑中小参的 DeepSeek-R1-Qwen、DeepSeek-R1-Llama 蒸馏模型；具体规格示例：6张 40G 的 A100 显卡可以满足 10 tokens/s；8张 32G 的 V100 显卡大概 5 tokens/s |

如需私有部署，可参考此文档：[DeepSeek R1 GPU 主机部署教程](https://developer.qiniu.com/aitokenapi/12885/host-deployment-tutorial)

<br />

| Q10：ollma 与 vllm 部署方式如何选择？                                |
| --------------------------------------------------------- |
| ollama 推荐个人开发者，高并发推荐 vllm 部署，目前全参数模型要求配置高，也可以使用 32b 的蒸馏模型 |

<br />

**vllm 部署 速度对比**

* 模型：DeepSeek-R1-Distill-Qwen-32B
* 环境：显卡 4 x 32G V100 CPU 48 x Intel(R) Xeon(R) Silver 4116 CPU @ 2.10 GHz

| GPU 显存、内存消耗                                  | 并发数 | 速度              |
| -------------------------------------------- | --- | --------------- |
| 显存 95.9 GB VIRT（虚拟内存）: 56.7G；RES（物理内存）: 5.8G | 1   | 13.848 tokens/s |
| 显存 95.9 GB VIRT（虚拟内存）: 56.7G；RES（物理内存）: 5.8G | 10  | 14.12 tokens/s  |
| 显存 95.9 GB VIRT（虚拟内存）: 56.7G；RES（物理内存）: 5.8G | 100 | 13.41 tokens/s  |

<br />

| Q11：使用 Token API 和购买 GPU 主机进行专属私有化部署有什么差别？                                                                                |
| ------------------------------------------------------------------------------------------------------------------------- |
| 差别1：数据安全隐私。API 背后的模型归属云厂商，客户的问题和答案都经过云厂商的模型处理；私有化部署的模型归属客户，客户的问题和答案数据有更好的隐私保护，尤其是如果客户场景是 RAG 应用，涉及客户的内部资料和数据，更建议用私有化部署的方式 |
| 差别2：灵活性。API 一般是按 token 计费，RPM/TPM 等指标并不明显；私有化部署则租期可长可短，token 数无限制，RPM/TPM 等通过扩容比较可控。                                      |

* [API 定价](/products/aitokenapi/0-ai-token-api-pricing)

<br />

| Q12：获取 API KEY 的 /llmapikey 的接口可以调用多次吗？API KEY 需要重新获取吗？API KEY 泄漏了怎么办？                                       |
| ------------------------------------------------------------------------------------------------------------ |
| 第一次调用 /llmapikey 接口获取 API KEY，保存下来可以一直用；如果泄漏或者单纯想要重置 API KEY，可以再次调用 /llmapikey 接口，获取新的 API KEY，旧的 API KEY失效。 |

<br />

| Q13：支持联网搜索吗？                                                         |
| -------------------------------------------------------------------- |
| 联网搜索需要单独配置对应的API,使用[全网搜索 API](/products/aitokenapi/1-web-search-api) |

<br />

| Q14：deepseek-v3.1模型是否有参数支持关闭推理？ |
| ------------------------------- |
| 不支持，只能在提示词引导关闭思考                |

<br />

| Q15：AI大模型API调用RPM是多少？          |
| ------------------------------ |
| 不同模型的RPM限制不一样，随资源调度策略动态优化，不固定。 |

<br />

| Q16：AI接口调用报402错误码？                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 402错误码是账号余额或资源包不足导致的，资源包、账单以及AI接口请求是15分钟的实时计量数据，提示402错误后您那边 [充值](https://portal.qiniu.com/financial/recharge) 或 [购买资源包](https://qmall.qiniu.com/template/MTMx?spec_combo=MzU4NQ\&ref=index) 即可，充值或购买资源包后，大约15分钟左右接口会恢复正常。 |

<br />

| Q17：API接口调用报ip in black list 错误？               |
| ---------------------------------------------- |
| 这是因为使用了错误的API-KEY频繁调用接口导致的，您修改使用正确的API-KEY调用即可 |

<br />

| Q18：如何查询某个API-KEY的用量和计费信息？                                                                                                                                                                                                                                                               |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1、用量可以在七牛控制台 - [用量统计](https://portal.qiniu.com/ai-inference/usage) 查看，支持按API-KEY查询；<br /> 2、计费信息可以在七牛控制台 - [计费预估](https://portal.qiniu.com/ai-inference/bill) 查看，支持按API-KEY查询。<br /> 3、资源包抵扣后的计费数据在 [按量计费预估](https://portal.qiniu.com/financial/bills/estimated-consume) 界面查看，数据更新有一定延迟。 |

<br />

| Q19：为什么无法创建API-KEY？                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 目前AI产品仅支持中国大陆账号使用，暂不支持海外账号。<br />1、如果您注册的是海外账号的话，无法创建API-KEY是预期的；<br />2、如果注册的是中国大陆区域账号，创建失败：<br />A、可以先检查下账号是否欠费？欠费后将限制API-KEY创建；<br />B、如果确认账号未欠费，可以提供下具体错误信息，然后 [提交工单](https://support.qiniu.com/tickets/new-for-person) 由技术人员排查确认。 |

<br />

| Q20：AI接口调用报403（invalid user v2或access denied for invalid user）错误，如何处理？                                                                                                                                                                                                                          |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 这种403错误一般是风控系统巡查判定认定为非法注册大量账号、恶意机刷AI推理活动资源包奖励，导致AI调用被封禁；<br /&#x3E; 对于系统自动触发封禁，如果认为存在误封情况，可在此提交申诉 &#x2A;*[解封申诉](https://jsj.top/f/VlBX1F)** 提交后系统会自动审核处理。<br /> 提交申诉时需要您提供不是机刷的证明，包括但不限于：<br /> 1. 公众号/视频号/B 站等公域平台的内容分享链接；<br /> 2. 微信群/Discord 等私域社群的转发分享截图；<br /> 3. 证明材料中均需显示完整的推广链接，或推广海报。 |

<br />

| Q21：api请求报错`502`，显示`stream canceled, context done`错误，如何处理？   |
| ------------------------------------------------------------ |
| 原因：一般是因为模型响应慢，客户端主动断开导致的报错，检查是否使用了非流式请求，建议调整为流式请求或调大客户端超时时间。 |

<br />

| Q22：api请求报错`429`，显示`UID rate limit reached for TPD (oversea) for UID`、`RPM`, `TPM`错误，如何处理？                                     |
| ------------------------------------------------------------------------------------------------------------------------------ |
| 原因：一般是因为模型请求限频导致的，TPD是每日TOKEN限制，RPM是每分钟请求数，TPM是每分钟 Token 数，请求触发这些限制就会导致请求报错，可以先降低调用频率或改用其他模型先使用，建议需要调整的话需通过工单平台添加左侧专属商务经理联系确认。 |

<br />

| Q23：api请求报错`400`，参数错误，如何处理？                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 原因：一般是因为客户端请求参数错误导致的，可以先参考 [AI接口文档](https://apidocs.qnaigc.com/) 检查下请求参数问题；如果自查后无法定位问题，可以在 [请求日志](https://portal.qiniu.com/ai-inference/request-log) 找到对应400错误的请求ID，提交 [工单](https://support.qiniu.com/tickets) 咨询技术支持，工单中提供下对应的请求ID内容。<br /> 控制台手动查询日志参考：[请求日志](/products/aitokenapi/2-request-log-api) 说明文档 |

<br />

| Q24：AI接口调用报`403 {"error":{"type":"forbidden","message":"Request not allowed"}} `错误，如何处理？                         |
| ---------------------------------------------------------------------------------------------------------------- |
| 一般是账号欠费或可用余额为负导致的，在七牛控制台 - 点击 [账户充值](https://portal.qiniu.com/financial/recharge) 补齐欠费，充值成功后，预计20min左右系统会自动解除限制。 |

<br />

| Q25：AI接口调用报错50MB限制，如何处理？                                                                                             |
| -------------------------------------------------------------------------------------------------------------------- |
| 目前相关模型单次消息体上限就是 50MB，超出大小会报错                                                                                         |
| ![image.png](/docs-assets/faq/aitokenapi/other/13462-aitoken-use-faq/FsVXmUU2Gewv6Yvbx1wG7EeTIpha-a2cdf59a92d3.webp) |

<br />

| Q26：AI接口调用响应慢，如何处理？                                            |
| -------------------------------------------------------------- |
| 如果模型响应耗时在秒级，是预期的；如果是非流式请求，可以在客户端修改stream为true，使用流式请求后再测试看看耗时情况 |

<br />

| Q27：AI接口调用报错`bad response status code 401, message: Invalid API Key, body: {"error":{"message":"Invalid API Key","type":"authentication_error"}}`，如何处理？ |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 是使用的API Key不对导致的，可以在[查看API Key](https://portal.qiniu.com/ai-inference/api-key)复制对应的API Key。                                                             |

<br />

| Q28：AI接口调用报错`Your request was rejected by the safety system`，如何处理？ |
| ------------------------------------------------------------------ |
| 是被模型安全检测拦截导致的，建议检查下请求内容是否存在违规内容？                                   |

<br />

| Q29：AI模型的上下文限制（比如：DeepSeek-V4-Pro模型上下文1000k）是如何计算的？                                                                                     |
| --------------------------------------------------------------------------------------------------------------------------------------- |
| 该限制是指模型发行商说的这个模型支持“1M 上下文”；所谓“1M 上下文”指的是它支持 1,000,000 个 token；关于 token（词元）的数量取决于分词器怎么分词，即一个汉字是几个 token，或者一段话是几个 token，都取决于这个模型的分词器如何处理。 |

<br />

| Q30：七牛AI推理模型调用接口返回数据结构与模型官网返回的结构有区别吗？                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------ |
| 七牛返回数据结构基本按OpenAI Chat Completions和Anthropic messages兼容，但不能保证与OpenAI和Anthropic官网同模型返回逐字段完全一致。如果是走七牛AI接口调用模型，返回数据以七牛接口为准。 |

<br />

| Q31：七牛控制台无法启用或创建API-KEY，操作按钮是灰色，是什么原因？                        |
| ------------------------------------------------------------- |
| 一般是账号欠费导致的，账号欠费后会限制七牛控制台API-KEY相关操作功能，您充值补齐欠费，账号解除欠费后会自动解除限制。 |

<br />

| Q32：七牛AI有文本向量、Embedding模型吗？                                |
| ---------------------------------------------------------- |
| 七牛暂时没有文本向量、Embedding模型，如果需要使用文本向量模型，建议您可以使用友商的Embedding模型。 |

<br />

| Q33：AI接口调用接口出现403 'apikey monthly quota exceeded'                                                    |
| ---------------------------------------------------------------------------------------------------- |
| 这个是由于API-KEY设置了日或者月使用额度的限制，关闭或者放大限制即可，在[API-KEY](https://portal.qiniu.com/ai-inference/api-key)管理中修改 |

<br />

| Q34：AI接口调用模型失败，报错示例：'model deepseek/deepseek-v4-pro is not available in your assigned model groups'，如何处理？                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 这个是由于API-KEY设置了模型范围限制导致的，如需对应api-key                                                                                                                                                                                           |
| api-key调用报错模型，可在 [API Key](https://portal.qiniu.com/ai-inference/api-key) 找到对应 api-key 点击 模型范围 添加对应模型ID即可。![image.png](/docs-assets/faq/aitokenapi/other/13462-aitoken-use-faq/Fmb0YcoL9bdmkJpAtm0bx-W80Q11-d09bdda94f9c.webp) |

<br />

| Q35：模型调用偶现超时失败？                                                                                               |
| ------------------------------------------------------------------------------------------------------------- |
| 一般是本地网络异常导致的，建议先确认下本地网络稳定性，确认本地网络正常，可以 [提交工单](https://support.qiniu.com/tickets/new-for-person) 由技术人员进一步排查确认。 |

<br />

| Q36：模型调用失败，报“No active subscription includes this model”错误？                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 使用订阅套餐的api-key调用非订阅套餐内的模型ID导致的，可以在 [https://portal.qiniu.com/ai-inference/subscription](https://portal.qiniu.com/ai-inference/subscription) 查询订阅套餐可用模型范围，修改套餐支持的模型ID即可。。 |

**附录：**

* API文档：[/products/aitokenapi/inference-api/1-real-time-ai-interface-api](/products/aitokenapi/inference-api/1-real-time-ai-interface-api)
* API定价：[/products/aitokenapi/0-ai-token-api-pricing](/products/aitokenapi/0-ai-token-api-pricing)
* 支持的模型列表：[https://www.qiniu.com/ai/models](https://www.qiniu.com/ai/models)
* 专属 GPU 主机购买：[https://marketing.qiniu.com/activity/2024-1111-act](https://marketing.qiniu.com/activity/2024-1111-act?ref=developer.qiniu.com\&s_path=%2Faitokenapi%2F12896%2Fdeploy-deepseek-r1-distilled-model-gpu)
* DeepSeek R1 GPU 主机部署教程：[https://developer.qiniu.com/aitokenapi/12885/host-deployment-tutorial](https://developer.qiniu.com/aitokenapi/12885/host-deployment-tutorial)
* 更多文档：[https://www.qiniu.com/products/ai-token-api#document](https://www.qiniu.com/products/ai-token-api#document)

<br />


# AI推理邀请、注册FAQ (/faq/aitokenapi/share-to-earn/13461-aitoken-Invite-registration-earn)



最近更新时间: 2026-04-30 17:48:19

### Q1:AI推理如何推广好友？ [#q1ai推理如何推广好友]

开通推广功能后，系统会为您生成专属的邀请链接。您可以直接复制链接分享，也可以生成微信海报或小程序二维码进行分享。
具体操作方式:
1：[推广页面](https://www.qiniu.com/ai/promotion/invite) [https://www.qiniu.com/ai/promotion/invite](https://www.qiniu.com/ai/promotion/invite) 登录账号
![image.png](/docs-assets/faq/aitokenapi/share-to-earn/13461-aitoken-Invite-registration-earn/FocVsSDDihuMeN0Dr8EcUW-ey6Tx-68d074d7b52a.webp)
2:登录完成后，点击 【立即推广拿百亿 Token】 奖励可以看到具体的推广链接
![image.png](/docs-assets/faq/aitokenapi/share-to-earn/13461-aitoken-Invite-registration-earn/FhdJqLYRbukFRacsJpcmjX2fqaCz-86bbed049133.webp)
3:将邀请链接复制给好友注册即可，只有通过专属链接注册的账号才可以获取邀请奖励


# DNS 服务器问题确认及修改 (/faq/cdn/basic-use-of/1438-the-dns-server-problem-identification-and-modification)



最近更新时间: 2026-05-08 16:22:08

## 一，确认是否是DNS问题。 [#一确认是否是dns问题]

用户出现上传下载慢的问题，可以使用dig命令来检测dns服务器地址是否设置正确。如下图所示，蓝色框中即为dns服务器地址。

![](/docs-assets/faq/cdn/basic-use-of/1438-the-dns-server-problem-identification-and-modification/d1879337a0222244cad8fee6e9149776-cd5daef58f8e.webp)

把蓝色框中的ip地址放入([https://www.ip138.com/](https://www.ip138.com/) )的搜索框，如下图。
![image.png](/docs-assets/faq/cdn/basic-use-of/1438-the-dns-server-problem-identification-and-modification/FuBfWBIa8ghUyoI7vx8HLa09HmId-9d9dc93e67cd.webp)
![image.png](/docs-assets/faq/cdn/basic-use-of/1438-the-dns-server-problem-identification-and-modification/FqqRSrwLSo5RI9CsvsKFwHSmrlvL-f99318d1247d.webp)

查询到的结果就是你的dns服务器所在的地理位置及运营商。

如果信息显示的城市结果离你很远，或者跨运营商了，就表明dns设置存在问题。

比如，dns 设置为8.8.8.8或114.114.114.114可能会导致cdn网络无法定位你的位置，从而无法选择最优节点。

## 二，修改DNS设置。 [#二修改dns设置]

确认dns出问题后，登录[http://www.ip.cn/dns.html](http://www.ip.cn/dns.html)

查找你所在地的DNS服务器地址,根据自己的系统参照下面的更改设置方法进行修改：

WIN XP：

[https://jingyan.baidu.com/article/d621e8da60d9bf2865913ffb.html](https://jingyan.baidu.com/article/d621e8da60d9bf2865913ffb.html)

Win7：

[https://jingyan.baidu.com/article/ca00d56c11d659e99eebcfdd.html](https://jingyan.baidu.com/article/ca00d56c11d659e99eebcfdd.html)

win8:

[https://jingyan.baidu.com/article/f71d603774ee781ab641d1d2.html](https://jingyan.baidu.com/article/f71d603774ee781ab641d1d2.html)

Windows 10:

[http://jingyan.baidu.com/article/1612d50058aa86e20e1eee96.html](http://jingyan.baidu.com/article/1612d50058aa86e20e1eee96.html)

MAC OS:

[https://jingyan.baidu.com/article/93f9803f3f6389e0e46f55b4.html](https://jingyan.baidu.com/article/93f9803f3f6389e0e46f55b4.html)

Unix:

[http://os.51cto.com/art/201004/194716.htm](http://os.51cto.com/art/201004/194716.htm)

linux:

[https://jingyan.baidu.com/article/ca41422f66beab1eae99edce.html](https://jingyan.baidu.com/article/ca41422f66beab1eae99edce.html)


# 视频播放卡顿、无法播放，应该怎么办？ (/faq/cdn/basic-use-of/4082-video-playback-caton-unable-to-play)



最近更新时间: 2017-09-30 17:28:45

# 视频播放卡顿 [#视频播放卡顿]

视频播放缓冲时间长，播放卡顿。

问题分析：

1：检查播放的域名是否是测试域名，比如 `*.bkt.clouddn.com`。测试域名访问有限制，不适合在正式环境中使用，建议绑定自定义域名：[/products/cdn/0-fusion-quick-start](/products/cdn/0-fusion-quick-start)

2：通过avinfo查看视频元信息的码率：`bit_rate`，avinfo使用详情参考：[/products/dora/audio-and-video-processing-api/2-audio-and-video-metadata-information-avinfo](/products/dora/audio-and-video-processing-api/2-audio-and-video-metadata-information-avinfo)

码率与带宽的换算：bit\_rate/1024/1024

再用 [http://www.speedtest.net/](http://www.speedtest.net/) 测试网络的下行带宽，然后与上面的码率换算后的带宽进行比较。

如果是码率过高造成的视频播放卡，可以使用多媒体处理的音视频转码，将码率设置低一点。音视频转码请参考：[/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb)

# 视频无法播放 [#视频无法播放]

问题分析：

1：最常见的就是的浏览器或者播放器不支持该视频的编码格式，例如谷歌浏览器不支持编码格式为mpeg4的视频，需要特定的播放器才能正常播放。编码格式可以通过avinfo查看视频元信息的编码格式(codec\_name)，avinfo详情参考：[/products/dora/audio-and-video-processing-api/2-audio-and-video-metadata-information-avinfo](/products/dora/audio-and-video-processing-api/2-audio-and-video-metadata-information-avinfo)

如果是编码格式造成的无法播放，可以使用多媒体处理的音视频转码，将音视频转成播放器或者浏览器支持的编码格式。音视频转码请参考：[/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb)

2：音视频本身文件损坏，你可以将上传之前的文件拿到播放器去播放，观察是否正常的播放。如果不能正常的播放，说明该音视频可能损坏。

3：如果上述的问题都是正常的，可以提交工单，需提供以下信息：

一：ping 自定义加速域名的截图；

二：完整的资源url链接

七牛工程师会在工单上帮你分析无法正常播放的原因。


# 七牛云对文本文件下载优化的支持 (/faq/cdn/download-problem/1571-seven-niuyun-support-for-text-file-download-optimization)



最近更新时间: 2017-09-19 17:18:19

**需求情景描述**

当你需要对上传完成的文件进行压缩，然后对压缩过的文件进行下载，来减少流量，七牛云提供了以下解决方案来帮助你节省流量

**解决方案**

首先七牛对用户的上传文件，原样上传（保存最原始的文件），其次当用户请求的时候，七牛自动会对文本文件进行压缩操作（gzip）。然后客户端（浏览器）如果支持gzip的话，会自动解压缩。这样会给用户省去很多流量费用。

七牛解决方案： 支持的文件类型：

text/plain
text/css
text/javascript
text/xml
application/x-javascript
application/json
application/xml
application/xml+rss
application/javascript


# 如何配置域名的 CNAME (/faq/cdn/domain-name-configuration-problem/1322-how-to-configure-cname-domain-name)



最近更新时间: 2026-04-29 17:50:41

# CNAME 简介<a id="conflict" /> [#cname-简介]

 CNAME 即指别名记录，也被称为规范名字。一般用来把域名解析到别的域名上，当需要将域名指向另一个域名，再由另一个域名提供 ip 地址，就需要添加 CNAME 记录。

***

# CNAME 配置 [#cname-配置]

 如果需要对七牛创建的加速域名进行 CNAME 配置，您可以在创建加速域名后，通过以下方式为您的加速域名添加解析。

<a id="cname" />

# 一. 获取CNAME值 [#一-获取cname值]

  在 **七牛管理控制台** 页面选择 [**CDN**](https://portal.qiniu.com/cdn/overview) ，选择 [**域名管理**](https://portal.qiniu.com/cdn/domain)，鼠标停留在域名下图红框的符号上即可点击复制 ，如下图所示。

<img src="/docs-assets/faq/cdn/domain-name-configuration-problem/1322-how-to-configure-cname-domain-name/Fjfbfu__LCJsAoXS2p15kfk7yb50-1f9f1b8f7a7b.webp" width="800" />

***

# 二. 添加CNAME记录 [#二-添加cname记录]

 添加CNAME记录需要在您的\*\*`域名厂商`**处配置，比如您在 阿里云 / 腾讯云 / 新网 等处购买的域名，您需要前往**`购买域名的厂商`\*\*相应管理控制台，添加域名解析。

1. 打开您购买域名的厂商官网，登陆后在页面右上角找到 &#x2A;*`控制台`** 或 相关管理后台入口。
    如果您不清楚域名解析的入口，建议查看您域名厂商的产品文档，或者寻求域名厂商的售后支持。

<br />

2. 在域名厂商的控制台中，找到您的域名解析添加页面，例如：
   a.  阿里云：在控制台页面的左侧，产品与服务栏中选择 **域名**。
   b.  腾讯云：在控制台的云产品中，搜索并选择 **云解析**。
   c.  DNSPOD：在控制台页面左侧，选择 **域名**。
   其他域名厂商请参考产品文档说明或咨询产品售后。

<br />

3. 在域名产品的列表中找到您加速域名对应的\*\*`主域名&#x60;，点击域名后面的 &#x2A;*`解析设置`** 或 \*\*`解析`，进入解析设置页。

<br />

4. 选择 `添加记录` ，依次填写 **主机记录**，**记录类型** 以及 **记录值**，其他可设为默认值。
   如果您不清楚如何填写主机记录，请参考下文第5步提供的示例。

   <img src="/docs-assets/faq/cdn/domain-name-configuration-problem/1322-how-to-configure-cname-domain-name/Fn5LvRsKMEUgBQM4PvvAccI-ISyO-fd142884247f.webp" width="1000" />

| 参数   | 填写说明                                                                    | 注意事项          |
| ---- | ----------------------------------------------------------------------- | ------------- |
| 主机记录 | 填写加速域名对应的主机前缀                                                           | 该参数唯一，请勿自定义   |
| 记录类型 | 选择 CNAME 类型                                                             | 该参数唯一，请勿自定义   |
| 线路类型 | 保持默认                                                                    | 该参数可以根据需求自行调整 |
| 记录值  | 域名创建后，七牛提供的 <font color="#4671D5"><a href="#cname">**CNAME**</a></font> | 该参数唯一，请勿自定义   |
| TTL  | 保持默认                                                                    | 该参数可以根据需求自行调整 |

<br />

5.解析示例：

假设您购买的一级域名为 qiniu.com
您需要先在七牛控制台创建加速域名，比如您创建了 cdn.qiniu.com 或 img.qiniu.com 之类的自定义二级域名。
创建完成后，在域名厂商后台添加解析记录时，您需要填写主机记录为加速域名对应的前缀，如 cdn 或 img 即可。
`注意：主机记录需要和加速前缀完全一致，请对应填写。`

常见的普通域名主机记录填写方式举例：

| 创建的加速域名                               | 域名类型 | 主机记录      |
| ------------------------------------- | ---- | --------- |
| qiniu.com                             | 普通域名 | @         |
| [www.qiniu.com](http://www.qiniu.com) | 普通域名 | www       |
| cdn.qiniu.com                         | 普通域名 | cdn       |
| video.cdn.qiniu.com                   | 普通域名 | video.cdn |

常见的泛域名主机记录填写方式举例：

| 创建的加速域名        | 域名类型 | 主机记录   |
| -------------- | ---- | ------ |
| .qiniu.com     | 泛域名  | \*     |
| .cdn.qiniu.com | 泛域名  | \*.cdn |

<font color="#4671D5">
  <a href="#check">配置完成，如何检查解析是否生效</a>
</font>

# 如何处理 CNAME 记录和 A 记录冲突？ [#如何处理-cname-记录和-a-记录冲突]

 同一个域名只能使用 A 记录解析，或者使用 CNAME 解析，如果您在添加域名的 CNAME 解析时提示存在冲突，请检查该主机记录是否已经存在 A 记录。

解决方案：

1. 如果您的域名用于绑定七牛云存储
   * 重新添加一个未在其他地方使用的二级加速域名，例如您原本在七牛绑定的是 qiniu.com 或 [www.qiniu.com](http://www.qiniu.com) ，建议您重新在空间绑定加速域名例如 cdn.qiniu.com 或者 xxx.qiniu.com ，然后针对新添加的加速域名，配置对应的解析即可。
   * 删除您原有的 A 记录就可做 CNAME 解析
     (**注**：A 记录删除会导致您的域名无法访问该域名的原有资源，谨慎操作)

2. 如果您的域名用于加速您的源站服务器站点
   * 在确认 CDN 配置无误情况下，可以删除A记录。
   * 通过配置 CNAME 解析，使得域名能够绑定到七牛的加速线路上。

 **注** ： 修改 CNAME 配置生效时间：新增 CNAME 记录会实时生效，而修改 CNAME 记录需要等待生效时间 TTL。

# 如何判断 CNAME 是否正确配置？<a id="check" /> [#如何判断-cname-是否正确配置]

 先在CDN 的 域名管理 中检查域名是否创建成功，如果已经创建成功，且已经按照步骤添加了 CNAME 解析，但是无法正常访问资源外链，或保持“等待 CNAME ”状态，可以通过以下方法检测本地的域名解析，如果域名长时间没有创建成功，您可以[提交工单](https://support.qiniu.com/tickets/new)处理。

 您可以通过 nslookup 您的加速域名，域名是否解析到 CNAME 值上。

* linux/mac系统您可以通过如图所示的命令 `dig 您的加速域名` 查看，第一条是否解析到您配置的CNAME值。
  <img src="/docs-assets/faq/cdn/domain-name-configuration-problem/1322-how-to-configure-cname-domain-name/FhZC_DzsNzPA6PzpD2ApNdy1udEE-780c5a91c6c6.webp" width="600" />

* windows系统可以通过Win+R 或 点击左下角的“开始”按钮打开“开始”菜单，打开“运行”，输入cmd回车。
  在命令行模式下输入`nslookup 您的加速域名`，例如 nslookup qn.vinchi.club,在结果中可以看到您复制的cname值即可。

  <img src="/docs-assets/faq/cdn/domain-name-configuration-problem/1322-how-to-configure-cname-domain-name/FpCsAmZwHyxWvWpIUSQE59GXgGpV-0d2580d32294.webp" width="400" />

 **注**：详细排查步骤请参考文档 [**检验域名创建是否成功**](/faq/cdn/domain-name-configuration-problem/5326-how-to-check-whether-the-configuration-is-successful)

***

# FAQ [#faq]

## 为什么使用 CDN 需要 CNAME 记录？ [#为什么使用-cdn-需要-cname-记录]

 在七牛云开发者平台创建加速域名后，会给域名分配一个 “CNAME域名”（例：cdn-example-com.qiniudns.com）。用户需要在域名服务商处，配置一条 CNAME 记录，将访问加速域名的请求指向这个 cdn-example-com.qiniudns.com 域名记录，生效后访问加速域名时解析将会正式指向七牛云 CDN ，之后由 CDN 完成调度，使得该域名所有的请求都开始享有 CDN 加速效果。

## CNAME 记录和 A 记录是什么关系？ [#cname-记录和-a-记录是什么关系]

* CNAME 记录和 A 记录都是在 DNS 解析过程中的一种记录值类型。
* A 记录会直接解析到某个 IP ，CNAME 会解析到另一个域名，之后再对另一个域名继续解析，直到解析出节点。
  所以，A 记录只能够实现域名解析到 IP ，七牛提供的 CDN 加速服务会根据用户所在位置选择并返回最优节点 IP 。


# 什么是防盗链设置中的空 Referer (/faq/cdn/domain-name-configuration-problem/1337-what-is-hotlinking-prevention-set-of-empty-referer)



最近更新时间: 2018-01-02 16:03:30

# 什么是 Referer？ [#什么是-referer]

这里的 Referer 指的是 HTTP 头部的一个字段，也称为 HTTP 来源地址（HTTP Referer），用来表示从哪儿链接到目前的网页，采用的格式是 URL。换句话说，借着 HTTP Referer 头部网页可以检查访客从哪里而来，这也常被用来对付伪造的跨网站请求。

Referer 的正确英语拼法是 referrer。由于早期 HTTP 规范的拼写错误，为了保持向后兼容就将错就错了。其它网络技术的规范企图修正此问题，使用正确拼法，所以目前拼法不统一。

比如，您如果点击下面资料来源后面维基百科的网址链接，那么浏览器会产生一个送到维基百科的 Web 服务器的 HTTP 请求，该请求中则会包含一个 Referer 字段（即本页面的地址）

资料来源：[http://zh.wikipedia.org/wiki/HTTP ](http://zh.wikipedia.org/wiki/HTTP%E5%8F%82%E7%85%A7%E4%BD%8D%E5%9D%80)

# 什么是空 Referer，什么时候会出现空 Referer？ [#什么是空-referer什么时候会出现空-referer]

首先，我们对空 Referer 的定义为，Referer 头部的内容为空，或者，一个 HTTP 请求中根本不包含 Referer 头部。

那么什么时候 HTTP 请求会不包含 Referer 字段呢？根据 Referer 的定义，它的作用是指示一个请求是从哪里链接过来，那么当一个请求并不是由链接触发产生的，那么自然也就不需要指定这个请求的链接来源。

比如，直接在浏览器的地址栏中输入一个资源的 URL 地址，那么这种请求是不会包含 Referer 字段的，因为这是一个 “凭空产生” 的 HTTP 请求，并不是从一个地方链接过去的。

# 那么在防盗链设置中，允许空 Referer 和不允许空 Referer 有什么区别？ [#那么在防盗链设置中允许空-referer-和不允许空-referer-有什么区别]

在防盗链的白名单设置中，如果指名白名单中包含空的 Referer，那么通过浏览器地址栏直接访问该资源 URL 是可以访问到的；

但如果不指名需要包含空的 Referer，那么通过浏览器直接访问也是被禁止的。


# 关于www域名加速的时候与主机A记录冲突策略 (/faq/cdn/domain-name-configuration-problem/1400-on-the-www-domain-acceleration-and-host-a-record-when-conflict-strategy)



最近更新时间: 2026-04-29 17:54:05

*

原理

空间配置图

## 原理 [#原理]

首先明白下 一个域名（例 ：[www.echohu.top）](http://www.echohu.top）) 若做了A 记录操作到ip 是不能在做cname的绑定到七牛
可以使用以下策略
[www.echohu.top这个域名请求的资源会先从你指向的七牛的空间去获取资源，当七牛的空间不存在这个资源他会从镜像源test.echohu.top获取资源](http://www.echohu.top这个域名请求的资源会先从你指向的七牛的空间去获取资源，当七牛的空间不存在这个资源他会从镜像源test.echohu.top获取资源) 而这个test.echohu.top有指向一个你的服务器ip 首先我们以echohu.top的域名为例 这是总体的图片

  ![](/docs-assets/faq/cdn/domain-name-configuration-problem/1400-on-the-www-domain-acceleration-and-host-a-record-when-conflict-strategy/Fo4b3I7KE4bLTFYp-jGztL3gNUll-c24fcd301835.webp)

## 空间配置图 [#空间配置图]

### [www.echohu.top的域名指向一个七牛空间这个七牛的空间test-wjw](http://www.echohu.top的域名指向一个七牛空间这个七牛的空间test-wjw) [#wwwechohutop的域名指向一个七牛空间这个七牛的空间test-wjw]

![](/docs-assets/faq/cdn/domain-name-configuration-problem/1400-on-the-www-domain-acceleration-and-host-a-record-when-conflict-strategy/Flc06vondYTYzZWS-DenfP64ZMsF-b528ec75ff4b.webp)

### 七牛的的存储空间设置镜像源为test.echohu.top的域名 [#七牛的的存储空间设置镜像源为testechohutop的域名]

![image.png](/docs-assets/faq/cdn/domain-name-configuration-problem/1400-on-the-www-domain-acceleration-and-host-a-record-when-conflict-strategy/Fn-2nF_Quwy67xrP0FaDcmJ-gvfv-f2a70cfdd4ab.webp)


# 为什么自定义域名的状态显示未生效? (/faq/cdn/domain-name-configuration-problem/1563-why-haven-t-state-of-the-custom-domain-name-suggest-take-effect)



最近更新时间: 2017-09-19 17:14:37

1. 访问 portal.qiniu.com 查看空间设置中的域名设置，在自定义域名栏目中可查看到自定义域名的审核状态。
2. 自定义域名的配置需要审核，当域名显示解析未生效时，请先将 cname 指向页面中提示的信息。
3. 当域名的 cname 配置完成时，查看自定义域名的配置详情，系统将检测是否已指向 CNAME 目标，检测成功的域名显示 “使用中”。


# 时间戳防盗链 (/faq/cdn/domain-name-configuration-problem/1670-timestamp-hotlinking-prevention)



最近更新时间: 2026-04-29 17:59:21

# <span id="1"> 1. 简介</span> [#-1-简介]

七牛 CDN 支持多种[访问控制](/products/cdn/configuration-management-fusion/access-control-configuration)方式；其中，时间戳防盗链可以通过对时间有关的字符串进行签名，将时间、签名信息通过一定的方式传递给 CDN 边缘节点服务器进行鉴权，从而正确响应合法请求、拒绝非法请求。相比于 referer 防盗链，时间戳防盗链的安全性更强。

## 1.1 原理说明 [#11-原理说明]

时间戳防盗链的目的是使得每个请求的 url 都具有一定的 &#x2A;*“时效性”**，所以 url 本身需要携带过期时间相关的信息，同时还需要确保这个过期时间不能被恶意修改，因此采用 md5 算法，将 **key、过期时间、文件路径**等信息进行加密得到签名加入 url，并在 CDN 节点进行验证。

## 1.2 鉴权过程 [#12-鉴权过程]

整个时间戳防盗链的实现需要以下几个部分配合：

* 客户端：负责发送原始请求给客业务服务器以及发送带时间戳加密的 url 给 CDN 节点进行验证；
* 源站业务服务器：根据约定的[算法](#3)生成带签名参数的 url 返回给客户端；
* CDN 节点：负责对客户端进行时间、签名校验。

主要分为以下几个步骤：

<img src="/docs-assets/faq/cdn/domain-name-configuration-problem/1670-timestamp-hotlinking-prevention/Fok2dfmFng4WcNvFMLO-ambBKP08-21ff6ee01673.webp" width="400" />

（1）用户管理员在七牛 [CDN 控制台](https://portal.qiniu.com/cdn/domain) 配置 key ，并将 key配置进业务服务器。
（2）当客户端请求资源时，将原始 url 发送至业务服务器。
（3）业务服务器根据[计算逻辑](#3)，将带有时间戳签名的 url 返回至客户端。
（4）客户端使用带有时间戳签名的 url 请求资源。
（5）CDN 检查 url 签名的合法性。

**注意：若同时配置了 referer 防盗链、IP 黑白名单、时间戳防盗链，有一项不满足条件，即为不通过，响应 403 。**

# <span id="2">2.配置步骤</span> [#2配置步骤]

## 2.1 开始配置 [#21-开始配置]

（1）登录七牛开发者平台后，进入[CDN 控制台](https://portal.qiniu.com/cdn/domain)，选择【域名管理】。
（2）进入域名配置界面，**访问控制**模块下的**时间戳防盗链**点击【修改配置】进行时间戳防盗链的配置。
![image.png](/docs-assets/faq/cdn/domain-name-configuration-problem/1670-timestamp-hotlinking-prevention/FviLGHjiNLPpxHNPk3qmMvzA8nEk-be9a745b7b36.webp)

## 2.2 配置 KEY [#22-配置-key]

key 即用于加密 url 的密文，需要填写主要和备用 key，两个 key 不能相等，一般来说使用其中一个即可。用户可以点击【随机生成】生成 key；也可以自行使用算法生成，如下方[生成实例](https://)中`gen_key（）`函数。

获取 key 以后，需要将 key 配置到业务服务器中，并实现相关签算逻辑。具体实现方式可参考[算法说明](#3)及代码[生成实例](#4)。
![image.png](/docs-assets/faq/cdn/domain-name-configuration-problem/1670-timestamp-hotlinking-prevention/FmZkTJ4aJjXoX1Mfwl4UjKR9gzvB-e677d5b61b29.webp)

## 2.3 校验时间戳 URL [#23-校验时间戳-url]

为保证服务器正确实现了签算逻辑，防止因签算逻辑错误导致 403 错误，在正式开启前必须进行 url 的正确性校验。

在业务服务器实现相关签算逻辑后，可获取一个生成的带有时间戳签名的 url 粘贴至下面输入框。

若提示错误，请仔细阅读[算法说明](#3)进行错误检查。

![image.png](/docs-assets/faq/cdn/domain-name-configuration-problem/1670-timestamp-hotlinking-prevention/FmZkTJ4aJjXoX1Mfwl4UjKR9gzvB-e677d5b61b29.webp)

> ### 时间戳 URL 计算器 [#时间戳-url-计算器]
>
> 为方便用户辅助检查，七牛提供一个 [URL 时间戳签名计算器](https://codesandbox.io/s/qiniu-time-referer-demo-trnw9)，请确保您的业务服务器可以与该时间戳计算器获得一致的结果。
> &#x2A;*但需注意：此计算器仅用于辅助检查，请勿为通过检验直接将计算粘贴至检验框中。**

## 2.4 确认开启时间戳防盗链 [#24-确认开启时间戳防盗链]

点击【确定】即可正式开启时间戳防盗链功能。
**在正式开启前，请务必确认业务服务器已经可以正确签算时间戳签名 url ，保证所有访问 url 都正确携带相关参数**，
![image.png](/docs-assets/faq/cdn/domain-name-configuration-problem/1670-timestamp-hotlinking-prevention/Fi1UDHO7dWQ4GVvWM-MVZVS_tvrb-a33269c11302.webp)

# <span id="3"> 3.算法说明 </span> [#-3算法说明-]

## 3.1 签名算法 [#31-签名算法]

* key：在开启时间戳防盗链时，可以在控制台上输入或随机生成。

* path：访问资源的 url 中的路径部分，例如：访问的 url 为 `http://xxx.yyy.com/DIR1/dir2/vodfile.mp4?v=1.1`，则 `path = /DIR1/dir2/vodfile.mp4`（注意不含 querystring 部分）。

* T：url 过期时间,当超过设置的过期时间时，该鉴权失效。按 unix\_time 的 16 进制小写形式表示。 如 `2015-08-01 00:00:00 –> 1438358400 –> 55bb9b80`。&#x2A;*注意，请务必使用 16 进制时间，若没有转化为 16 进制形式直接使用 unix\_time, 将会被 CDN 认为是一个很大的过期时间，导致无法起到时间戳鉴权的作用。**

签名原始字符串 `S = key + url_encode(path) + T` 。
签名 `SIGN = md5(S).to_lower()，to_lower` 指将字符串转换为小写；

\*\*	注：本文提到的 url\_encode 算法，都是斜线不参与编码的 utf-8 编码，下同。\*\*

## 3.2 签名参数传递方式 [#32-签名参数传递方式]

`<SIGN>`和`<T>`作为URL查询参数进行传递。

* 签名参数 sign、 t ，sign 在前，t 在后；
* `<SIGN>`、`<T>` 替换为对应的值， 实际url中不含\<> ；

例如:
原始访问的 url 为： `http://xxx.yyy.com/DIR1/dir2/vodfile.mp4?v=1.1`
最终形成的访问 url 为： `http://xxx.yyy.com/DIR1/dir2/vodfile.mp4?v=1.1&sign=<SIGN>&t=<T>`

## 3.3 访问 url [#33-访问-url]

访问 url 的 path 部分也需要 url\_encode，其算法与签名时使用 url\_encode 算法一致。斜线 / 不编码。

访问 url 为：

```
scheme + "://" + host + url_encode(path) + query_part
```

### 访问 url 生成示例 [#访问-url-生成示例]

下图给出了一个访问 url 的生成示例。

<img src="/docs-assets/faq/cdn/domain-name-configuration-problem/1670-timestamp-hotlinking-prevention/FjCSJ7lDkXbNJxrIyvkC8EE4zYBq-5aa2dd5fda21.webp" width="800" />

原始 url : [http://xxx.yyy.com/DIR1/中文/vodfile.mp4?v=1.2。](http://xxx.yyy.com/DIR1/中文/vodfile.mp4?v=1.2。)

资源过期时间为：2015年8月1日。

| 参数   | 值                                        |
| ---- | ---------------------------------------- |
| path | /DIR1/中文/vodfile.mp4                     |
| KEY  | 9388f4ba63b89bba5b9b84aa70a92eaac099d39b |
| T    | 55bb9b80                                 |

签名原始字符串 `S = key + url_encode(path) + T`

`S = 9388f4ba63b89bba5b9b84aa70a92eaac099d39b/DIR1/%E4%B8%AD%E6%96%87/vodfile.mp455bb9b80`

`SIGN = b4b7f94dd7817ce0283b5491861c3936`

`T=55bb9b80`

访问 url 为：

`http://xxx.yyy.com/DIR1/%E4%B8%AD%E6%96%87/vodfile.mp4?v=1.2&sign=b4b7f94dd7817ce0283b5491861c3936&t=55bb9b80`

# <span id="4"> 4. 生成实例 </span> [#-4-生成实例-]

python版

```python
#! /usr/bin/env python
#coding:utf-8

from hashlib import md5
import urllib
import sys
import time
from urlparse import urlparse, parse_qs
import traceback
import uuid
import base64

# 要求正确的 url_encode 编码，斜线 / 不编码；
# 井号 # 等在浏览器会直接识别为其它含义，若在 path 中必须编码；
# 问号 ? 等在 url 中有特殊含义，若在 path 中必须编码；
# 部分字符 "~!$&'()*+,:;=@[]" 不含双引号 "，虽有特殊含义，但在 path 部分，编码与否，都可以正常访问；
# 另一些，如 双引号 ", 空格 " ", 汉字等必须编码；
#
# 建议 url 的 path 中尽量不含上述部分，建议 url 中尽量不含上述部分。
#
# 参考
# https://www.wikiwand.com/zh-cn/%E7%99%BE%E5%88%86%E5%8F%B7%E7%BC%96%E7%A0%81
# https://www.wikiwand.com/en/Percent-encoding
# https://www.wikiwand.com/de/URL-Encoding
def url_encode(s):
    return urllib.quote(s.decode(sys.stdin.encoding).encode("utf8"), safe="/")

def to_deadline(rang):
    return int(time.time()) + rang

def t16(t):
    return hex(t)[2:].lower()   # 16 进制小写形式

def summd5(str):
    m = md5()
    m.update(str)
    return m.hexdigest()

def sign(key, t, path):
    a = key + url_encode(path) + t
    print("S: " + a)
    sign_s = summd5(a).lower()
    sign_part = "sign=" + sign_s + "&t=" + t
    return sign_part

def sign_url(key, t, p_url):
    url = urllib.unquote(p_url)
    up = urlparse(url)
    path = up.path
    sign_part = sign(key, t, path)
    p_query = up.query
    if p_query:
        query_part = "?" + p_query + "&"+ sign_part
    else:
        query_part = "?" + sign_part

    return up.scheme + "://" + up.netloc + url_encode(path) + query_part

def printurl_encode_help():
    print '''
# 要求正确的 url_encode 编码，斜线 / 不编码；
# 井号 # 等在浏览器会直接识别为其它含义，若在 path 中必须编码；
# 问号 ? 等在 url 中有特殊含义，若在 path 中必须编码；
# 部分字符 "~!$&'()*+,:;=@[]" 不含双引号 "，虽有特殊含义，但在 path 部分，编码与否，都可以正常访问；
# 另一些，如 双引号 ", 空格 " ", 汉字等必须编码；
#
# 建议 url 的 path 中尽量不含上述部分，建议 url 中尽量不含上述部分。
#
# 参考
# https://www.wikiwand.com/zh-cn/%E7%99%BE%E5%88%86%E5%8F%B7%E7%BC%96%E7%A0%81
# https://www.wikiwand.com/en/Percent-encoding
# https://www.wikiwand.com/de/URL-Encoding
    '''

def signt_help():
    print
    print "./signt.py time <key> <url> <t,eg: 3600>"
    print "./signt.py deadline <key> <url> <deadline>"
    print "./signt.py check <key> <signed_url>"
    print "./signt.py show <t, eg: 55bb9b80>"
    print "./signt.py genkey"
    print "\n"
    print '''
# example:

# url = "http://xxx.yyy.com/DIR1/中文/vodfile.mp4?sfdf=dfe"
# key = 12345678
# 过期时间点: Sat Aug  1 00:00:00 2015  ==> 1438358400

# 执行: signt.py deadline 12345678  http://xxx.yyy.com/DIR1/中文/vodfile.mp4?sfdf=dfe 1438358400
# 签名 url 为: http://xxx.yyy.com/DIR1/%E4%B8%AD%E6%96%87/vodfile.mp4?sfdf=dfe&sign=6356bca0d2aecf7211003e468861f5ea&t=55bb9b80

# 执行: signt.py check 12345678 "http://xxx.yyy.com/DIR1/%E4%B8%AD%E6%96%87/vodfile.mp4?sfdf=dfe&sign=6356bca0d2aecf7211003e468861f5ea&t=55bb9b80"
# 显示: True
    '''
    print "\n"
    printurl_encode_help()

def sign_time(key, url, rang):
    print("range: " + str(rang))
    deadline = to_deadline(rang)
    sign_deadline(key, url, deadline)

def sign_deadline(key, url, deadline):
    print("\nkey: " + key)
    print("\nurl: " + url)
    print("\ndeadline: " + t16(deadline) + ", " + str(deadline) + ", " + time.ctime(deadline))
    print
    t = t16(deadline)
    signed_url = sign_url(key, t, url)
    print "\nsigned_url:"
    print signed_url
    print

# signed_url 是正确 url_encode 编码后签出的 url
# 见 url_encode 方法注释
def sign_check(key, signed_url):
    print "\n 要求: 待检测的 url 是正确 url_encode 编码后签出的 url"
    printurl_encode_help()
    u = urlparse(signed_url)
    t = parse_qs(u.query)["t"][0]
    sign_s = summd5(key + u.path + t).lower()
    print
    print("deadline: " + str(int(t, 16)) + " , " + time.ctime(int(t, 16)))
    print(sign_s)
    print(parse_qs(u.query)["sign"][0] == sign_s)

def show_t(t):
    i_t = int(t, 16)
    s_t = time.ctime(i_t)
    print(t + " : " + str(i_t) + " : " + s_t)

# 仅用于测试
def gen_key():
    print base64.urlsafe_b64encode(str(uuid.uuid4()))[:40].lower()

try:
    type = sys.argv[1]

    if type == "time":
        sign_time(sys.argv[2], sys.argv[3], int(sys.argv[4]))
    elif type == "deadline":
        sign_deadline(sys.argv[2], sys.argv[3], int(sys.argv[4]))
    elif type == "check":
        sign_check(sys.argv[2], sys.argv[3])
    elif type == "show":
        show_t(sys.argv[2])
    elif type == "genkey":
        gen_key()
    else:
        signt_help()
except Exception as e:
    print traceback.format_exc()
    signt_help()
```


# 为什么做了 CNAME 解析还是显示请配置 CNAME (/faq/cdn/domain-name-configuration-problem/3884-why-did-the-cname-parsing-or-display-please-match-cname)



最近更新时间: 2018-01-02 15:49:20

通常有以下几种原因

# 场景一 [#场景一]

用户绑定的加速域名为正在使用的网站域名，如：[www.abc.com](http://www.abc.com)

## 问题原因 [#问题原因]

因为一个域名只能解析一次 A 记录或者 CNAME ，所以当用户在七牛绑定这种域名并增加一条解析是没效果的。

## 解决办法 [#解决办法]

起一个没用解析过的二级域名（可以根据业务命名），如 images.abc.com

# 场景二 [#场景二]

## 问题原因 [#问题原因-1]

用户在绑定加速域名后做 CNAME 解析，CNAME 记录值填写错误导致解析无效

举例说明：域名 images.abc.com

在域名服务商系统里解析的时候，主机记录为 images ，记录值为 七牛提供的 iduxxxx.qiniudns.com 这样的地址

## 解决办法 [#解决办法-1]

解析完成后一般1分钟后就可以通过外链访问资源了，解析之后可以通过命令行`dig`命令查看线路是否配置好了。

# 场景三 [#场景三]

## 问题原因 [#问题原因-2]

某些域名商（如百度、360）配置解析后，会自动开启域名商的 CDN 服务，此时用`dig`命令查询域名解析结果是 A 记录。

## 解决办法 [#解决办法-2]

如果可以正常访问文件，是可以忽略“等待 cname”的提示的。但更建议联系域名商，禁用域名商提供的 CDN 服务。

# 场景四 [#场景四]

解析配置正确，且用`dig`命令查询，域名已经正确解析到七牛提供的 cname 地址，但仍显示等待 cname 。

## 问题原因 [#问题原因-3]

部分地区的 LocalDNS 未更新解析结果。
域名解析记录的生存时间（TTL）一般为 10 分钟（如果修改过，可以手动修改回 10 分钟），所以解析修改后，需要等待 10 分钟左右， LocalDNS 的解析记录更新。但某些小运营商的 LocalDNS 服务器，不会严格遵守设置的 TTL 时间，即使解析时设置了 TTL 时间为 10 分钟，解析结果有可能会缓存数小时甚至数天。

## 解决方法 [#解决方法]

如果等待 10 分钟左右刷新页面，仍然显示等待 cname ，便可以确认是部分地区的 LocalDNS 未更新，此时只能等待解析结果更新。
不过，这种情况下仅是少数地区的某些小运营商解析结果不对，绝大部分地区的解析是没有问题的。

# 最后 [#最后]

如果都确认了不是以上问题，给我们提交工单，技术支持会为您尽快排查原因和解决问题。


# 常见问题 - CDN 回源配置相关问题 (/faq/cdn/domain-name-configuration-problem/4064-understanding-and-setting-up-the-way-back-to-the-source-host)



最近更新时间: 2026-05-28 10:30:42

# 简介 [#简介]

 CDN 加速支持指定不同的回源方式对源站进行加速，本文列出了部分关于 CDN 回源配置您可能需要了解的问题。
<font color="#4671D5"><a href="#Q0">Q：回源示意图</a></font>
<font color="#4671D5"><a href="#Q1">Q：回源流程说明</a></font>
<font color="#4671D5"><a href="#Q2">Q：什么是回源IP、回源域名 ？</a></font>
<font color="#4671D5"><a href="#Q3">Q：什么是回源 HOST ？</a></font>
<font color="#4671D5"><a href="#Q4">Q：回源 HOST 和源站域名有什么区别？</a></font>
<font color="#4671D5"><a href="#Q5">Q：如何填写测试资源？</a></font>
<font color="#4671D5"><a href="#Q6">Q：对网站 [http://www.a.com/](http://www.a.com/) 加速，回源配置应该如何填写？</a></font>
<font color="#4671D5"><a href="#Q7">Q：为什么加速域名和源站域名不能相同？</a></font>
<font color="#4671D5"><a href="#Q8">Q：为什么域名回源，域名测试不通过</a></font>
<font color="#4671D5"><a href="#Q9">Q：域名测试的作用是什么，测试资源可以删除吗</a></font>
<font color="#4671D5"><a href="#Q10">Q：有回源的固定IP列表么，需要回源IP加白名单</a></font>
<font color="#4671D5"><a href="#Q11">Q：访问CDN的客户端IP地址，到源站的请求头是什么？</a></font>

 
 如果本文仍然无法解决您的问题，您也可以通过 &#x2A;*[工单系统](https://support.qiniu.com/tickets/new)** 将您的问题反馈给我们。

***

<div id="Q0" />

# Q：回源示意图 [#q回源示意图]

![image](/docs-assets/faq/cdn/domain-name-configuration-problem/4064-understanding-and-setting-up-the-way-back-to-the-source-host/Fr7B98mKHHsq_5cV-itCjUgJ4K8x-80953e3c408b.webp)

<div id="Q1" />

# Q：回源流程说明 [#q回源流程说明]

### 1. 指定七牛云存储为源站 [#1-指定七牛云存储为源站]

 CDN 回源时，将根据您配置的源站存储空间名称，回源到存储机房对应空间中。

### 2. 指定源站域名回源 [#2-指定源站域名回源]

 CDN 回源时，先根据源站域名解析得到一个源站 IP ,然后向该 IP 发起请求，通过配置的回源 HOST 确定，需要访问该源站服务器上的哪一个站点。

 例如： 源站域名为 `www.a.com` ，回源 HOST 为 `www.b.com` 。

* 回源时，先解析到 `www.a.com` 解析到的 IP, 并向该 IP 发起回源请求，请求时 HTTP 数据包的 HOST 头部值为您配置的回源 HOST `www.b.com` ，代表访问源站服务器上的站点 `www.b.com` 。

### 3. 指定IP地址回源 [#3-指定ip地址回源]

 CDN 回源时，向该 源站IP 发起请求，通过配置的回源 HOST 确定，需要访问该源站服务器上的哪一个站点。

 例如： 源站 IP 为 1.1.1.1 ，回源 HOST 为 `www.b.com` 。

* 回源时，请求的是 1.1.1.1 对应的源站服务器上的站点 `www.b.com` 。

<br />

<div id="Q2" />

| Q2: 什么是回源IP、回源域名 ？                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------- |
| 参考 <font color="#4671D5"><a href="#Q0">回源示意图</a></font>，回源IP 和 回源域名，就是服务器的IP 和 服务器上绑定的域名，作用是通过IP 或者 域名直接找到对应的服务器，回源域名要求一定是可以访问的。 |

<br />

<div id="Q3" />

| Q3: 什么是 回源 HOST？                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------- |
| 参考 <font color="#4671D5"><a href="#Q0">回源示意图</a></font>，当服务器源站存在多个不同站点时，CDN 将根据您的回源 HOST 域名，决定 CDN 将从哪一个站点中获取资源。 |

<br />

<div id="Q4" />

| Q4: 回源 HOST 和源站域名有什么区别？                                                                                  |
| -------------------------------------------------------------------------------------------------------- |
| 参考 <font color="#4671D5"><a href="#Q0">回源示意图</a></font>，源站域名将会通过 DNS 解析，获取到源站的 IP，解析后的回源流程和 IP 回源方式没有区别。 |
| 源站域名：只决定回源的 IP ，不决定访问时的具体站点。                                                                             |
| 回源 HOST ：决定了访问到该 IP 上的具体站点名称。                                                                            |

<br />

<div id="Q5" />

| Q5: 如何填写测试资源？                                                    |
| ---------------------------------------------------------------- |
| 测试资源代表在您源站服务器上，回源 HOST 对应的站点中，一个可供访问的资源，将用于 CDN 在部分场景下的全链路访问性监测。 |

<br />

<div id="Q6" />

| Q6: 对网站 `http://www.a.com` 加速，回源配置应该如何填写？？                                                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `对域名www.a.com 加速,CDN域名与网站域名相同，此时只能设置IP回源。` <br /> 只可以使用IP地址回源，回源 HOST 设置自定义回源host,填写 `www.a.com` 即可,由于之前的www已存在A记录解析，域名绑定完成后，需要删除或者暂停www的A记录解析，添加www的七牛cname解析后，[www.a.com的CDN加速才能生效。](http://www.a.com的CDN加速才能生效。)                                                                                                    |
| `对域名qcdn.a.com 加速，CDN域名与网站域名不同。` <br />  如果源站服务器 IP 固定，您可以使用IP地址回源，回源 HOST 填写 [www.a.com](http://www.a.com) 即可。<br /> 如果源站服务器 IP 需要通过域名解析动态获取，您可以使用源站域名回源，回源 HOST 填写 [www.a.com](http://www.a.com) 即可。 <br /> 域名绑定完成后，www的解析保持不动，新增qcdn记录的cname解析，表示qcdn.a.com去wwww\.a.com所在服务器的www站点拉取资源，进行CDN加速。访问qcdn.a.com就有加速效果了。 |
| **`注意：`** 如果需要加速的域名为 HTTPS 域名，且源站强制 HTTP 访问时重定向到 HTTPS，您需要配置加速域名和回源协议为 HTTPS，或者关闭源站的重定向跳转。                                                                                                                                                                                                                             |

<br />

<div id="Q7" />

| Q7: 为什么加速域名和源站域名不能相同？为什么会出现解析冲突                                                                                  |
| ---------------------------------------------------------------------------------------------------------------- |
| 一个域名最终只解析到一个位置，A记录和cname解析共存会造成冲突，一个主机记录只能有一个A记录或者cname解析。即解析到 CDN 加速节点后，将无法用于获取源站的 IP 信息，所以加速域名和源站域名无法配置为同一个域名。 |

<br />

<div id="Q8" />

****Q8: 为什么域名回源，域名测试不通过****

域名测试需要源站支持Head请求，支持curl，&#x2A;***`源站测试需要响应200状态码，不能是其他状态码，不能出现301/302跳转到CDN域名的情况，否则会出现无限重定向死循环，CDN回源源站，源站出现强制HTTPS跳转CDN域名`**** <br />
1: HTTP协议回源

```bash
 curl -IL http://源站IP或者源站域名/测试资源 -H 'host:回源host'
```

2: HTTPS协议回源

```bash
 curl -IL https://回源Host/测试资源 -H 'host:回源host' --resolve 回源Host:443:服务器IP(域名回源的方式，需要填写源站域名配置A记录的IP)
```

3: 高级回源配置，指定端口号-HTTP回源

```bash
 curl -IL http://源站IP或者源站域名:回源端口号/测试资源 -H 'host:回源host'
```

4：高级回源配置，指定端口号-HTTPS回源

```bash
 curl -IL https://回源Host/测试资源 -H 'host:回源host' --resolve 回源Host:回源端口号:服务器IP(域名回源的方式，需要填写源站域名配置A记录的IP)
```

根据你们的回源配置，进行对应的测试，源站响应200后，测试即可通过

<br />

<div id="Q9" />

| Q9: 域名测试的作用是什么，测试资源可以删除吗                                                                         |
| ------------------------------------------------------------------------------------------------ |
| 域名测试的作用是检查源站是否可用，源站状态是否健康，防止域名创建后，源站异常导致网站崩溃，测试资源不能删除，删除后会导致后续源站测试和健康状态检查失败，导致域名处理缓慢，必须提交工单协助处理。 |

<br />

<div id="Q10" />

| Q10: 有回源的固定IP列表么，需要回源IP加白名单                                                              |
| ---------------------------------------------------------------------------------------- |
| 回源IP会不定期调整，所以如果需要回源IP，您可以通过 &#x2A;*[工单系统](https://support.qiniu.com/tickets/new)** 联系我们。 |

<br />

<div id="Q10" />

| Q11: 访问CDN的客户端IP地址，到源站的请求头是什么？                                                       |
| ------------------------------------------------------------------------------------ |
| 目前没有，用户客户端请求源站会请求到CDN节点的，CDN节点再去回源的，回源到您的源站的是我们回源节点IP地址的。您这边可以看下从CDN边缘日志查看一下的客户端IP地址 |

<br />

<div id="Q10" />

| Q12: 源站是海外，CDN选择国内线路，国内访问慢                         |
| -------------------------------------------------- |
| 存在跨境回源的问题，进行回源访问，因为属于跨境访问，比较慢是正常情况，再次访问，节点有缓存会快很多。 |

<br />

<div id="Q10" />

| Q13: CDN请求miss占比很高，请求慢                                                                                                                       |
| -------------------------------------------------------------------------------------------------------------------------------------------- |
| 可能是CDN缓存配置时间比较短，可以参考[缓存配置](/products/cdn/configuration-management-fusion/2-cache-configuration)将缓存时间设置长点；可能是因为链接后添加了随机参数，导致请求回源，可以去掉链接后面的参数。 |


# 如何验证域名已经配置成功 (/faq/cdn/domain-name-configuration-problem/5326-how-to-check-whether-the-configuration-is-successful)



最近更新时间: 2026-04-29 17:43:58

# 验证的使用场景 [#验证的使用场景]

1.您的域名创建后，无法访问资源，不返回状态码，请参考<font color="#4671D5"><a href="#state">步骤一</a></font>和<font color="#4671D5"><a href="#cname">步骤二</a></font>。
2.您的域名创建后，状态为 等待CNAME ，请参考<font color="#4671D5"><a href="#cname">步骤二</a></font>。<a id="state" />
3.您的域名创建后，自行检查CNAME解析，请参考<font color="#4671D5"><a href="#cname">步骤二</a></font>。
**不适用场景**：访问资源时已经返回了JSON格式信息或者HTTP状态码，请您根据相关信息排查。

# 第一步：检查域名是否已经创建成功 [#第一步检查域名是否已经创建成功]

在 **七牛管理控制台** 页面选择 [**CDN**](https://portal.qiniu.com/cdn/overview) ，选择 [**域名管理**](https://portal.qiniu.com/cdn/domain)，可以查看具体域名的状态。<a id="cname" />

* 处理中：创建域名处理中，通常情况下 10-30 分钟完成，若超过30分钟未配置完成，您可以[提交工单](https://support.qiniu.com/)反馈。
* 成功：当域名状态显示成功，表示您的域名已经创建成功，您可以参考<font color="#4671D5"><a href="#cname">步骤二</a></font>排查。

<img src="/docs-assets/faq/cdn/domain-name-configuration-problem/5326-how-to-check-whether-the-configuration-is-successful/Fn7kn9l6zD7CvMQVc1Wp7n9OEv2A-f4de80b06906.webp" width="800" />

# 第二步：检查域名的CNAME是否配置正确 [#第二步检查域名的cname是否配置正确]

在 **七牛开发者平台** 页面选择[**对象存储**](https://portal.qiniu.com/kodo/bucket)，点击具体的对象存储空间后，在空间概览中查看 CDN 加速域名 的状态。

* 成功：CNAME正确解析。
* 等待CNAME：CNAME未正确解析。
  <img src="/docs-assets/faq/cdn/domain-name-configuration-problem/5326-how-to-check-whether-the-configuration-is-successful/Fio5hI-PMw2j7oRDcgHlypBF2Emh-7335dec25f2c.webp" width="800" />

## 如果您在域名厂商处已经配置CNAME解析后，仍旧是“等待CNAME”状态。 [#如果您在域名厂商处已经配置cname解析后仍旧是等待cname状态]

您可以根据下面提供的方法进行测试，如果已经成功解析到您的CNAME，则可以忽略不计。
&#x2A;*注意：如果未成功解析到您的CNAME，请您重新检查您的解析记录，主机记录和记录值是否填写有误，请参考[如何配置域名的CNAME](/faq/cdn/domain-name-configuration-problem/1322-how-to-configure-cname-domain-name)。**

* linux/mac系统您可以通过如图所示的命令 `dig 您的加速域名` 查看，第一条是否解析到您配置的CNAME值。
  <img src="/docs-assets/faq/cdn/domain-name-configuration-problem/5326-how-to-check-whether-the-configuration-is-successful/FhZC_DzsNzPA6PzpD2ApNdy1udEE-780c5a91c6c6.webp" width="600" />

* windows系统可以通过Win+R 或 点击左下角的“开始”按钮打开“开始”菜单，打开“运行”，输入cmd回车。
  在命令行模式下输入`nslookup 您的加速域名`，在结果中可以看到您复制的cname值即可。

  <img src="/docs-assets/faq/cdn/domain-name-configuration-problem/5326-how-to-check-whether-the-configuration-is-successful/FpCsAmZwHyxWvWpIUSQE59GXgGpV-0d2580d32294.webp" width="400" />


# 资源访问有问题时提工单所需的信息 (/faq/cdn/download-problem-cdn/3866-could-not-access-to-resources-to-the-repair-order-the-required-information)



最近更新时间: 2017-12-01 12:54:04

当提工单给七牛技术支持的时候，应该提供哪些信息方便七牛的技术支持更快的解决问题。

# 1.链接 [#1链接]

提供资源的完整链接（以文本的形式），如[https://ymh.qiniuts.com/233.gif](https://ymh.qiniuts.com/233.gif) 包含域名和路径
如果url有parameters（参数）、query(查询)、fragment（信息片断）等也需要带上。

# 2.headers [#2headers]

一次连接的完整的普通头(general header)、响应头(response header)和请求头(request header)，可以用浏览器或其他工具抓包获取，以chrome浏览器为例：

### 普通头： [#普通头]

<img src="/docs-assets/faq/cdn/download-problem-cdn/3866-could-not-access-to-resources-to-the-repair-order-the-required-information/FmX5uVJmOCfruebD9gXLNhRnZuBH-4866d121bcc9.webp" width="300" />

<br />

### 响应头： [#响应头]

<img src="/docs-assets/faq/cdn/download-problem-cdn/3866-could-not-access-to-resources-to-the-repair-order-the-required-information/Fv1QpfbETYwLg1IubhsiqJuyjkC8-9d360b95cfd9.webp" width="200" />

<br />

### 请求头： [#请求头]

![](https://dn-odum9helk.qbox.me/FlgCEbCfTIOwgQRIKztVUpKGc9sL)

截取headers一定要清晰完整，最好复制下来，以\_文本的形式\_再发一份。

<br />

# 3.响应 [#3响应]

如果是七牛的报错，响应里会是一个josn的文件，如下图

<img src="/docs-assets/faq/cdn/download-problem-cdn/3866-could-not-access-to-resources-to-the-repair-order-the-required-information/FmxkFk3KQu6nf2JGnGHiJVH6pCbo-bf6c4167815c.webp" width="300" />

如果响应有内容，可以把图片或视频等截图发给我们，方便我们比对，如下图。

<img src="/docs-assets/faq/cdn/download-problem-cdn/3866-could-not-access-to-resources-to-the-repair-order-the-required-information/FttCcYyxz0LMBOW-n7hHyJn8cWQK-b14e6bc6d653.webp" width="500" />

<br />

# 4.ping和dig [#4ping和dig]

使用ping和dig命令，并把结果完整截图发给我们

<br />

# 5.本地网络情况 [#5本地网络情况]

包括带宽情况，是否是独占网络，本地的网络运营商和地区

<br />

# 6.其他 [#6其他]

如果有工具可以进行检测，也可以把结果发给我们，对于关键信息并且文本较多，最好复制粘贴再发给我们一份，以便更快解决问题。


# 计费流量与日志监控流量的区别 (/faq/cdn/flow-calculation-problem/4066-the-difference-between-the-billing-flow-and-log-monitor-flow)



最近更新时间: 2018-01-18 10:23:35

加速域名日志中记录的流量数据，是我们应用层日志统计出的流量，但是实际产生的网络流量却要比应用层统计到的流量要高出 &#x2A;*7%-15%** ；这个主要的原因有两个：

1.TCP/IP 包头的消耗：

* a. 由于HTTP请求是基于 TCP/IP 协议的，每个包大小最大为 1500 字节，1500 字节中含有 TCP 和 IP 插进来的 40 个字节的包头。
* b. 当前以太网帧格式采用的是 Etherent Ⅱ 格式：
  即： 前导码(8byte) | 目的 MAC(6byte) | 源 MAC(6byte) | 类型 (byte) | 数据 (46\~1500byte) | FCS(4byte)，除去数据，固定开销为 26byte
* c. IP 包头 20byte
* d. TCP 包头 20byte

因此，TCP 传输的数据分段大小为(6\~1460byte)，假设网络良好，没有丢包也没有重传，则包头固定开销为 26+20+20=66byte
计算时如果忽略 TCP 三次握手，忽略 TCP 四次挥手，按照如上计算出包头占比：\[66\*(日志数据量/1460)]/日志数据量 = 66/1460 = 4.52%

2.TCP 重传：
根据互联网物理网络的负载情况，正常情况下，我们所发送的包会有 3-10% 左右会被互联网丢弃掉。被丢弃掉之后，服务器会对丢弃的部分进行重传。重传动作是由内核层协议栈处理的，应用层也无法统计到，这部分流量占我们日志计算出流量的比例，根据网络的好坏而不等。在凌晨互联网轻载的情况下，重传率会较低；在晚高峰互联网重载的时候，重传会上升；一般情况下，在 3%-7% 之间。


# 如何申请并使用免费证书 (/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate)



最近更新时间: 2026-05-08 15:55:51

## 如何申请并使用免费证书 [#如何申请并使用免费证书]

* 本文档介绍如何申请并使用七牛免费证书，主要步骤有：

  * 1.证书申请
  * 2.免费证书使用
    * 2.1创建https加速域名时使用
    * 2.2http升级为https时使用

* 免费证书使用说明: 提供下载，在我的证书处下载

### 申请七牛免费证书 [#申请七牛免费证书]

* 1.登录七牛管理控制台，选择 [SSL 证书](https://portal.qiniu.com/certificate/ssl)，购买证书

<img src="/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/FkCqxG0_Ek9NwB_eh1D3UZFWyp1b-9965f5bead68.webp" width="800" />

* 2.选择 TrustAsia 免费证书

![image.png](/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/Fn1Dg27PNCws-_aYAbnqmIFcZO-P-e03ecb02df7f.webp)

* 3.点击「核对信息并支付」，补全域名信息

![image.png](/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/Fn3jhLq4XrTZr0wtlrvs1ucAAX5r-9da6f85563ca.webp)
![image.png](/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/FoXacu-i057-ZphN1gi7IQZifmoV-ecb8f94d33fa.webp)

* 4.选择验证方式，如果域名托管商 CNAME  解析和 TXT 有冲突，请选择文件验证

<img src="/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/FuWNDWLwldesjoegPsLjpj_aNmgm-27e736ed7081.webp" width="800" />

* 5.查看证书详情，根据选择的验证方式进行验证

<img src="/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/Fgf3BAjUkxRNMQzcmVvlVlY0azkr-b218b7f741a9.webp" width="800" />

![image.png](/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/FuyGYV1OSfEj7KIVt36tB8Ky-ZmZ-2dc4abe1ccb4.webp)

* 6.1 **选择dns验证** 需要到域名服务商 进行 cname 解析

<img src="/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/4A0C3418-9116-41D6-A2C6-6EFA0C693918-031ad2dd4b31.webp" width="800" />

* 6.2 使用dig命令查看TXT解析

<img src="/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/5FB9C228-C3C6-498B-807D-DF01AC570E5F-f8c5849f6c09.webp" width="800" />

* 7.1 **选择文件验证** 需要到 xuzhuo.support2technical.me 对应站点下上传文本文件，文件名为 `.well-known/pki-validation/fileauth.txt`， 文本文件内容为：`2018082806105747stl44uj6z707i7iqsv3b42v4cqkc1v86k4d7ujonr85yfvn7`

```
已绑定域名 xuzhuo.support2technical.me（通用名称)
域名所有权验证
验证类型：FILE
验证文件路径：/.well-known/pki-validation/fileauth.txt
验证文件值：2018082806105747stl44uj6z707i7iqsv3b42v4cqkc1v86k4d7ujonr85yfvn7

```

<img src="/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/FpZWLfCslEQ8OQC9RCycaXg1k9yT-b7aeb561d139.webp" width="800" />

* 7.2 文件验证校验, 访问 `http://xuzhuo.support2technical.me/.well-known/pki-validation/fileauth.txt`， 返回文本值为：`2018082806105747stl44uj6z707i7iqsv3b42v4cqkc1v86k4d7ujonr85yfvn7`

<img src="/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/FjPXbMpw3Rw0bQQj4ueApXWfpbrZ-9f4c0e9d312d.webp" width="800" />

* 8.**注意：如果DNS验证中的 txt记录 与 cname记录 冲突导致无法验证成功的话，请重新申请订单更换为文件验证的方式**

* 9.查看证书验证状态，当订单状态为已签发时，可以到我的证书处查看证书

<img src="/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/Foo2j9D8TCEeD97yC4PSpOXIXUtR-e1ddb7a1723f.webp" width="800" />

### 使用免费证书 [#使用免费证书]

* 1.创建加速域名时选择对应的证书

<img src="/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/FtJ2aQDgyWZpLct5KOGBy2hZnx4a-1104957629d7.webp" width="800" />

* 2.已经创建的域名，升级https时选择对应的证书

<img src="/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/Fres9NY6ha_0eEn6U3Tmv3vYoRrO-5d060075893a.webp" width="800" />

<img src="/docs-assets/faq/cdn/https-issues-related-to/3725-how-to-apply-for-and-use-free-certificate/FisiUJENadotb_u7WU8tdPSCLmNA-68b0f61e6803.webp" width="800" />

注：修改域名的https配置时，如果下拉框中没有可绑定的证书，请检查证书包含的域名和需要绑定的域名是否完全一致。


# 私有 M3U8 播放发生 ts 资源加载报401（Unauthorized）错误 (/faq/cdn/other-dora/4040-private-m3u8-play-ts-resource-loading-at-401-unauthorized-error)



最近更新时间: 2017-08-30 14:42:11

# 问题描述 [#问题描述]

私有空间的M3U8文件在调用pm3u8接口无法播放，提示下面的报错：

![](/docs-assets/faq/cdn/other-dora/4040-private-m3u8-play-ts-resource-loading-at-401-unauthorized-error/Ftc3UGvs0OkmCLvGN7nDWJKn5scL-dbea7fd132d4.webp)

# 问题原因 [#问题原因]

这样的报错原因基本有两种：

## 原因一 [#原因一]

pm3u8接口在设置 expires 或者 deadline 参数值过小，而视频播放时长较长，导致私有ts资源url下载凭证链接失效，致使视频无法播放。

## 原因二 [#原因二]

客户私有空间的缓存策略选择默认缓存，或者m3u8文件的缓存时间过长，并且开启了回源鉴权策略，导致客户在播放的时候命中的是之前的ts文件，而之前的ts文件已经失效，导致播放失败。

回源鉴权请参考：[/products/cdn/configuration-management-fusion/access-control-configuration/2-back-to-the-source-authentication](/products/cdn/configuration-management-fusion/access-control-configuration/2-back-to-the-source-authentication)

# 解决方法 [#解决方法]

## 原因一解决办法 [#原因一解决办法]

pm3u8接口在设置 expires 或者 deadline 参数值要比视频的播放总时长要大

## 原因二解决办法 [#原因二解决办法]

以下方法推荐选择第二种：

1：关闭回源鉴权策略（不推荐）

![](/docs-assets/faq/cdn/other-dora/4040-private-m3u8-play-ts-resource-loading-at-401-unauthorized-error/FvuL6HAwsQwhEDQls7P3E9jiWoqG-54ff38fa7b86.webp)

2：设置m3u8文件的缓存时间为0s;

![](/docs-assets/faq/cdn/other-dora/4040-private-m3u8-play-ts-resource-loading-at-401-unauthorized-error/FqjL6tzzLUNx9L1T_5vvnQ7tFZdw-0f0b4c6694fb.webp)


# 测试域名使用规范 (/faq/cdn/other-fusion/1319-test-domain-access-restriction-rules)



最近更新时间: 2026-06-09 19:00:04

**如果您正在使用或将要使用七牛测试域名，请务必仔细阅读本内容！**
    七牛云测试域名是用户在创建云存储空间时系统自动生成的七牛域名，以 clouddn.com / qiniucdn.com / qiniudn.com / qnssl.com / qbox.me 等结尾，此类域名仅供用户测试和体验七牛产品功能，不能用于正式生产环境。

    为了确保测试域名的规范使用，保障七牛云用户的权益，我们将对测试域名加强管理，具体措施如下：

1. 测试域名不得作为生产域名，如因不规范使用或被当作正式域名使用的，在使用期间导致的业务受损或其他类故障不在SLA保障范围内。
   （注意：域名类型是普通域名，不会受此限制）

2. 不得使用测试域名存储、发布、传播违法违规内容。当测试域名下有非法资源时，该域名将被直接冻结并不予解封。如对七牛云及其他用户造成损害，七牛云保留进一步追责的权利。

3. 自2020年2月14日起所有测试域名将禁止下载应用程序(**apk、ipa、exe、dmg等**)，如需使用请绑定自定义域名进行访问。

4. 流量限制：测试域名每个自然日访问回源总流量限10GB，当日回源流量达到10GB后，将会禁止对新文件访问。

5. 回收机制：
   a. 每个测试域名生命周期为30个自然日（已有测试域名自回收功能上线之日起算，新产生的测试域名自系统自动生成之日起算），超过30日系统将自动回收，回收即为域名删除。
   b. 在测试域名生命周期终结之前我们会邮件通知您，您也可以自行在 七牛云-管理控制台 的域名详情中查看测试域名剩余的回收时间。

6. 为了您的正常业务不受影响，请您规范使用测试域名，并尽快[绑定自定义域名](https://portal.qiniu.com/cdn/domain/create)进行访问（如已绑定，请忽略）。

7. 测试域名不支持续费续期等操作，30个自然日到期后自动回收，无法进行相关操作

8. 测试域名会忽略全部参数，所以测试域名访问链接是不支持进行添加参数处理操作的

因测试域名不服务于生产环境，所以测试域名不在SLA保障范围内。


# 判断丢包率及延时的趋势 (/faq/cdn/other-fusion/1628-judge-the-trend-of-packet-loss-rate-and-delay)



最近更新时间: 2017-08-21 10:32:51

在使用mtr检测连通性时，如果发现中间节点丢包率很高这是正常的事情，因为骨干路由器不一定会对所有的ping包做响应。

主要是查看最后一跳的丢包情况，以及丢包率是否在某个节点之后都有大幅度上升，只要中间节点丢包率有降低就可以忽略，延时情况也是同理。

总之判断丢包率及延时的趋势时，不是只看一个节点。另外还需要判断IP所在地，看是否有绕路，以及是否有路由回环等问题。


# 关于全站加速问题 (/faq/cdn/other-fusion/1632-questions-about-total-station-to-accelerate)



最近更新时间: 2020-02-14 16:59:04

问题：

网站采用xxx搭建，启用七牛cdn后，登录通过 `http://www.XXX.com/admin` 无法登录后台，输入正确用户名和密码后点击登录没有反应。

1. 没启用七牛cdn加速前的源站是没有这个问题的

2. 系统的缓存设置是默认设置，没有做任何更改

这里说的是全站直接使用cdn加速。请问这是什么问题？

原因：

你好， 我们的cdn这边默认是静态文件加速的，所以你全站加速时会将一些动态请求也缓存住。

所以再次请求就没法到你源站了， 就登录不上去了。建议你使用插件进行加速静态文件即可。


# 使用 curl 理解七牛请求 (/faq/cdn/other-fusion/2641-use-the-curl-seven-cows)



最近更新时间: 2018-11-21 18:52:43

使用七牛的 curl 实现表单上传

```
curl -v upload.qiniup.com -F'token=JOiPUijNB0t8vbNKIufpn5gDKmg0G-uFHBlrQoV2:rmU9wAEmrSV9FxPuD0V1Z1BgzKw=:eyJzY29wZSI6Impzc2RrIiwiZGVhZGxpbmUiOjE0ODQwMzY0NTJ9' -F'file=abc'
```

注释：其中参数 `-F/--form` 模拟http表单提交数据

使用 curl 模拟七牛的刷新接口

```
curl -i -X POST "http://fusion.qiniuapi.com/refresh" -H 'Content-Type: application/json' -H 'Authorization: QBox vI2xPIjOoh7udcRw4GdYNvf3o_gKsCx9wdZaC9u-:0KPRVoBiHR2c9K-t9bBr5DVDuUU=' -d '{"urls":["http://7xr0n9.com1.z0.glb.clouddn.com/3.txt.zip"]}'
```

注释：参数的 -H 其实就是 http 请求的头部   而七牛是靠这个签证头部 Authorization 来识别你的请求是否非法

-X POST 是以 post 的形式来请求 -d 就是 post 携带的数据

七牛的大部分接口其实用简单的 curl 理解起来就是  签算 Authorization 鉴权 post 请求数据

![](/docs-assets/faq/cdn/other-fusion/2641-use-the-curl-seven-cows/FpIElrLbI39iefxXUXL939s4hsQk-dea2e4707054.webp)

这个请求如果说你的已经签算好：

`Authorization QBox vI2xPIjOoh7udcRw4GdYNvf3o_gKsCx9wdZaC9u-:0KPRVoBiHR2c9K-t9bBr5DVDuUU=`
那么请求就如下

```
curl -i -X POST "http://fusion.qiniuapi.com/v2/tune/refresh" -H 'Content-Type: application/json' -H 'Authorization: QBox vI2xPIjOoh7udcRw4GdYNvf3o_gKsCx9wdZaC9u-:0KPRVoBiHR2c9K-t9bBr5DVDuUU=' -d '{"urls":["http://7xr0n9.com1.z0.glb.clouddn.com/3.txt.zip"],"dirs":["http://7xr0n9.com1.z0.glb.clouddn.com/*"]}'
```


# 运营商劫持反馈 (/faq/cdn/other-fusion/2755-operator)



最近更新时间: 2025-04-14 13:32:13

# 运营商劫持投诉 [#运营商劫持投诉]

首先需要确认是否被劫持了。
劫持一般分为 DNS 劫持和内容劫持。如果遇到以下两种现象：

1. 域名解析到七牛的 cname 地址，但是跟我们确认过，域名实际解析到的节点非七牛 CDN 节点；
2. 文件内容被篡改，加入了广告链接、跳转链接等。

投诉内容格式参考：

> 有客户反馈在北京移动被劫持了，访问到的节点不是七牛云存储公司的CDN节点（或者文件被篡改）。
>
> 测试链接如下：`<这里提供劫持链接>`，麻烦帮忙解决！

# 移动劫持 [#移动劫持]

[移动投诉网址](http://www.10086.cn/support/selfservice/suggest/)

# 联通劫持 [#联通劫持]

1、找到联通在本地的最高等级投诉热线；

2、确定投诉内容，投诉时，不要向接线员描述这些细节，而要告诉他们：当我访问某个域名时，经常跳到奇怪的站点；

3、收集证据，浏览器截图、录屏动画、网页源代码、Fiddler HttpWatch Wireshark等工具的抓包数据都可以作为证据；

4、拨打投诉热线，发送证据，并确认投诉的问题已经发送邮件，请检查是否收到。

# 电信劫持 [#电信劫持]

[电信投诉网址](https://www.189.cn/suggestions/)

# 工信部投诉 [#工信部投诉]

如果各个运营商没有及时解决或者解决比较慢，可以在工信部进行反馈投诉。

[工信部投诉网址](https://yhssglxt.miit.gov.cn/web/complaintChannel)


# 刷新缓存的方法 (/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time)



最近更新时间: 2026-04-29 18:02:26

# 主动提交刷新缓存请求 [#主动提交刷新缓存请求]

提交刷新请求的方法有三种：

1. 在 [七牛开发者中心](https://portal.qiniu.com) 左侧产品列表中找到 CDN ，进去后点击 [刷新预取](https://portal.qiniu.com/domain/refresh) 。
   按要求填写需要刷新的  URL，点击提交即可。
   ![image.png](/docs-assets/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time/FuDySDtG479dnYPuDNG2k_Jnegm9-7331774b6d4f.webp)
2. 工具刷新
   使用七牛云提供的 [qshell](/products/kodo/0-qshell) 命令行工具，参考使用文档，先设置密钥，然后执行  [cdnrefresh](https://github.com/qiniu/qshell/blob/master/docs/cdnrefresh.md) 命令来刷新缓存。
3. 通过API 接口提交刷新请求：
   七牛各服务端的 [SDK](/sdk-tools/sdk#official-sdk) 都提供了刷新缓存的方法。
   另附：[刷新接口文档](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time)

**注：** 如果使用了 **镜像存储** ，不能直接刷新，需要参考 [镜像存储刷新缓存方法](/faq/cdn/4215-image-storage-refresh-the-cache-method)
      提交刷新请求后 **10 分钟** 左右，刷新全网生效。
      刷新 **https** 域名下的链接，会同时刷新 **http** 和 **https**，占用两次刷新额度。

# 通过携带随机 URL 参数刷新 [#通过携带随机-url-参数刷新]

## 实现方法： [#实现方法]

例如，如果 [http://dn-odum9helk.qbox.me/resource/gogopher.jpg](http://dn-odum9helk.qbox.me/resource/gogopher.jpg) 这个图片资源没有更新，可以在该 URL 后面加上问号随机参数的形式来让 CDN 强制刷新：[http://dn-odum9helk.qbox.me/resource/gogopher.jpg?v=1234567](http://dn-odum9helk.qbox.me/resource/gogopher.jpg?v=1234567) ，CDN 拿到这个 URL 后会强制回源站中取回最新的资源。

## 实现原理： [#实现原理]

如果域名没有开启忽略 URL 参数，那么在 CDN 节点上，对于：
[http://dn-odum9helk.qbox.me/resource/gogopher.jpg](http://dn-odum9helk.qbox.me/resource/gogopher.jpg)
[http://dn-odum9helk.qbox.me/resource/gogopher.jpg?v=1](http://dn-odum9helk.qbox.me/resource/gogopher.jpg?v=1)
[http://dn-odum9helk.qbox.me/resource/gogopher.jpg?v=2](http://dn-odum9helk.qbox.me/resource/gogopher.jpg?v=2)
这三个 URL 是独立缓存的。所以，如果携带之前没用过的参数访问，CDN 会强制回源站中取回最新的资源。

## 注意事项： [#注意事项]

1. 关闭忽略 URL 缓存的域名，才可以使用这种方法刷新。
   ![](/docs-assets/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time/FrxsUkwOt1hqHl6ztT7GNFN_9NS3-fa6ca46e44ed.webp)
2. 若使用 [http://dn-odum9helk.qbox.me/resource/gogopher.jpg?v=1](http://dn-odum9helk.qbox.me/resource/gogopher.jpg?v=1) 访问一次，不会刷新 [http://dn-odum9helk.qbox.me/resource/gogopher.jpg](http://dn-odum9helk.qbox.me/resource/gogopher.jpg) 的缓存。所以如果要保证访问到最新的资源，需要携带之前没有使用过的参数。
3. 此方法适用于需要频繁更新的文件，为保证参数不重，可以在每次更新文件后，携带的参数 +1 ，或者取 unix 时间戳来作为参数。


# CDN 缓存常见问题 (/faq/cdn/refresh-the-cache-problem/1503-the-fusion)



最近更新时间: 2026-05-29 12:00:57

## 缓存刷新和文件预取有什么区别？ [#缓存刷新和文件预取有什么区别]

缓存刷新：是指通过管理控制台或者 API 接口的方式将缓存在 CDN 节点的资源文件删除或标记为过期，对于新的请求会回源站服务器获取新的文件。

文件预取：是提前将资源文件缓存在 CDN 节点，新的请求过来之后可以直接命中，无需回源服务器获取资源文件，以低源站压力，提升首次访问体验。

## 刷新缓存后要多久生效？ [#刷新缓存后要多久生效]

缓存刷新全网生效时间一般为 10 分钟。

## 使用七牛云对象存储服务，文件更新需要手动刷新吗？ [#使用七牛云对象存储服务文件更新需要手动刷新吗]

需要。使用了七牛云对象存储服务时，存储资源更新（替换或删除）后，需要手动刷新触发 CDN 节点刷新缓存，否则可能会导致依然能够访问到原文件的情况。

## 发现通过七牛云 CDN 访问的资源和源站资源不一致怎么办？ [#发现通过七牛云-cdn-访问的资源和源站资源不一致怎么办]

通过管理控制台或 API 接口进行缓存刷新。

## 刷新预取入口： [#刷新预取入口]

### 管理控制台： [#管理控制台]

在七牛控制台 产品列表 中点击 CDN ，进去后可以看到刷新预取功能

### API： [#api]

[/products/cdn/8-fusion-api-cache-management](/products/cdn/8-fusion-api-cache-management)

### 如何判断请求是否触发回源，没有请求到缓存 [#如何判断请求是否触发回源没有请求到缓存]

可以打开浏览器的开发者模式，network中查看对应的请求，如果请求中有Age这个响应头，就说明触发了缓存，单位是秒；没有这个响应头，说明请求进行了回源。日志中，hit是命中缓存，miss是触发了回源。


# CDN 缓存规则设置 (/faq/cdn/refresh-the-cache-problem/1680-cdn-cache-rule-set)



最近更新时间: 2026-04-29 18:07:30

# 一、背景介绍 [#一背景介绍]

1. 七牛提供的加速功能只针对静态文件
2. 动态文件使用了cdn缓存后影响访问效果，如，登录界面，使用缓存后会串号

# 二、解决方法 [#二解决方法]

## 场景1 [#场景1]

自定义域名绑定在七牛空间，建议空间中只存储静态文件，采用动静分离的模式。

示例：[www.qiniu.com](http://www.qiniu.com) 的域名A记录到源站 IP 123.123.123.123，绑定自定义域名为 img.qiniu.com，然后将域名 cname 到七牛提供的域名上。使用时将 img.qiniu.com 的资源链接嵌入到代码中即可。

## 场景2 [#场景2]

自定义域名回源到客户源站

## 示例１：在源站配置文件中设置缓存时间为 0，Nginx 为例 [#示例１在源站配置文件中设置缓存时间为-0nginx-为例]

```
server {
    listen       80;
    server_name  localhost;
    location ~* ^(.+\.php)(.*)$ {
        root     html;
        expires  -1;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME         $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
```

## 示例２：设置自定义域名的缓存时间 [#示例２设置自定义域名的缓存时间]

* ２.1. 找到缓存设置界面
  ![image.png](/docs-assets/faq/cdn/refresh-the-cache-problem/1680-cdn-cache-rule-set/FrmQho4hh_ihRn5jkXM2Bw9MAr02-83518fb5d44d.webp)
  ![image.png](/docs-assets/faq/cdn/refresh-the-cache-problem/1680-cdn-cache-rule-set/FgplC91JHnskaQAMwqZc9YJO6ULI-88aa6d7534ec.webp)

* ２.２ 设置的规则和按钮
  ![image.png](/docs-assets/faq/cdn/refresh-the-cache-problem/1680-cdn-cache-rule-set/FueFK0B2SxxWhk0Z_JbF57qDiA8G-3e5f709ff2e8.webp)

* ２.３.添加缓存设置

* ２.３.１ 推荐配置
  ![image.png](/docs-assets/faq/cdn/refresh-the-cache-problem/1680-cdn-cache-rule-set/FkY6tkGF37Zkh5oeAQfTKf9CewQn-61ebc13aa5ef.webp)

* ２.３.２ 添加后缀
  ![image.png](/docs-assets/faq/cdn/refresh-the-cache-problem/1680-cdn-cache-rule-set/Fkb3cOFHEmyUOQ3I2CJZb3KpFDK2-68a44f456fc2.webp)

* ２.３.３ 添加目录
  ![image.png](/docs-assets/faq/cdn/refresh-the-cache-problem/1680-cdn-cache-rule-set/Fock1hovLcwAcewdhG9yjQy-6qdH-1d764897ab64.webp)


# CDN 缓存配置建议 (/faq/cdn/refresh-the-cache-problem/1711-fusion-cdn-cache-configuration-recommendations)



最近更新时间: 2020-02-14 16:57:59

使用场景如下建议

小文件

| 优先级 | 网站元素 | 路径模板                                     | 缓存时间 | 忽略URL参数 |
| --- | ---- | ---------------------------------------- | ---- | ------- |
| 1   | 目录页  | /\*/                                     | 1h   | 否       |
| 2   | 常见文本 | /\*.(js\|css\|txt\|xml)                  | 1d   | 否       |
| 3   | 常见文件 | /\*.(shtml\|html\|htm)                   | 1h   | 否       |
| 4   | 常见图片 | /\*.(jpg\|jpeg\|png\|psd\|bmp\|gif\|ico) | 7d   | 否       |

流媒体

| 优先级 | 网站元素 | 路径模板                                                            | 缓存时间 | 忽略URL参数 |
| --- | ---- | --------------------------------------------------------------- | ---- | ------- |
| 1   | 媒体文件 | /\*.(mp3\|wav\|wmv\|mp4\|avi\|flv\|rmvb\|swf\|aif\|au\|dat\|rm) | 30d  | 否       |
| 2   | 媒体文件 | /\*.(m3u8)                                                      | 0s   | 否       |

下载分发

| 优先级 | 网站元素 | 路径模板                     | 缓存时间 | 忽略URL参数 |
| --- | ---- | ------------------------ | ---- | ------- |
| 1   | 下载文件 | /\*.(apk\|zip\|rar\|ipa) | 30d  | 是       |


# 刷新预取 FAQ (/faq/cdn/refresh-the-cache-problem/2501-refresh-the-prefetch)



最近更新时间: 2026-05-25 16:43:52

| Q1：删除/覆盖了七牛空间里的文件，为什么访问链接还能访问到旧文件？                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| 七牛空间里的文件，使用 CDN 来访问，而 CDN 是通过缓存来加速的。更新源站的文件后，需要 [刷新缓存](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time) ，才可以访问到新文件。 |

<br />

| Q2：我已经提交了刷新请求，为什么还没有刷新成功？                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 提交刷新后，全网生效需要 10 分钟左右，可以在 [七牛管理控制台](https://portal.qiniu.com) 的 [刷新预取](https://portal.qiniu.com/domain/refresh) 界面，点击操作记录，来查看刷新进度。<br />如果刷新状态异常，或者状态显示成功，但还是会访问到旧文件，请 [提交工单](https://support.qiniu.com/)。 |

<br />

| Q3：提交了 1 个刷新链接，为什么消耗了 2 个刷新额度？                   |
| ------------------------------------------------ |
| 刷新 https 域名下的链接，会同时刷新 http 和 https 的链接，消耗两次刷新额度。 |

<br />

| Q4：使用镜像存储，如何刷新缓存？                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------- |
| 参考 [刷新缓存方法](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time#3) 一文中的 “使用镜像存储刷新缓存方法”。 |

<br />

| Q5：刷新和预取有什么区别？                                                                |
| ----------------------------------------------------------------------------- |
| 刷新缓存：清除 CDN 节点缓存，从源站获取最新资源。<br />文件预取：是在 CDN 节点没有资源缓存时预下载（如果节点缓存已存在，预取时不会覆盖）。 |

<br />

| Q6：怎么刷新CDN缓存？有工具批量刷新缓存吗                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 刷新缓存方法请参考：<br /> [/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time) <br /> 方法1: portal.qiniu.com 控制台刷新缓存，点击左侧 cdn => 刷新预取<br />方法2: api 接口地址：[https://developer.qiniu.com/fusion/api/1229/cache-refresh](https://developer.qiniu.com/fusion/api/1229/cache-refresh) <br /> 方法3：使用[qshell](https://github.com/qiniu/qshell/blob/master/docs/cdnrefresh.md)工具[批量刷新缓存](https://github.com/qiniu/qshell/blob/master/docs/cdnrefresh.md) |

<br />

| Q7：刷新预取时，提示 `仅支持处理当前账号下的DCDN加速域名资源` ，怎么处理？                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 原因：域名不存在或刷新预取入口错误导致的。<br /> 1、CDN域名刷新预取提交入口：[CDN刷新预取](https://portal.qiniu.com/cdn/refresh-prefetch) <br /> 2、全站加速域名刷新预取提交入口：[全站加速域名刷新预取](https://portal.qiniu.com/dcdn/refresh-prefetch) |


# 源站更新源cdn如何同步 (/faq/cdn/refresh-the-cache-problem/2522-update-how-source-cdn-synchronization-source-stand)



最近更新时间: 2026-05-08 16:00:40

# 情景一 cdn的源站是七牛的情况下 [#情景一-cdn的源站是七牛的情况下]

模式是这样的

<img src="/docs-assets/faq/cdn/refresh-the-cache-problem/2522-update-how-source-cdn-synchronization-source-stand/FnluCu7R_kQ3mTvwAqAQyWVUxqrB-c88ff3811cab.webp" width="800" />

![image.png](/docs-assets/faq/cdn/refresh-the-cache-problem/2522-update-how-source-cdn-synchronization-source-stand/Fs24sXxwnPCugU0ki5Kw2PcQEbau-910451f98309.webp)

![image.png](/docs-assets/faq/cdn/refresh-the-cache-problem/2522-update-how-source-cdn-synchronization-source-stand/Flf9g9sux7tvKNv7_qxua1DDMXwT-8ec6d97d9ead.webp)

* 首先 资源的读取的情况是这样的  客户端访问时候先从 cdn 拉取资源 如果 cdn 存在缓存那么资源直接从 cdn 返回给客户端
* 其次 客户端从 cdn 没有拉到资源那么就会从七牛的存储空间拉取资源
* 最后 如果七牛空间和 cdn 都不存在资源那么 客户端就会从客户的源站拉取资源

这个是源站回源到七牛情况，所以客户源站资源的更新需要先把七牛空间的资源删除，七牛过滤控制台手动删除，参考 [删除文件](/products/kodo/kodo-console-guide/file-management/8-delete-the-file) 再刷新下[ cdn 缓存](https://portal.qiniu.com/cdn/refresh-prefetch)  这样客户端访问才会直接打回到客户的源站取最新资源。

# 情景二 cdn源站直接指向自己域名或ip [#情景二-cdn源站直接指向自己域名或ip]

<img src="/docs-assets/faq/cdn/refresh-the-cache-problem/2522-update-how-source-cdn-synchronization-source-stand/Fv_iROXoCJXp-y14zoF4lt6zh9tE-b5e7adce0160.webp" width="800" />

![image.png](/docs-assets/faq/cdn/refresh-the-cache-problem/2522-update-how-source-cdn-synchronization-source-stand/FuyQe-rQnb2MGdlqkU_ugnQECrhr-621f36ee3b6f.webp)

* 首先 资源的读取的情况是这样的  客户端访问时候先从cdn 拉取资源 如果cdn存在缓存那么资源直接从cdn返回给客户端
* 最后 如果七牛空间和cdn 都不存在资源那么 客户端就会从客户的源站拉取资源

这个是源站回源到客户自己域名或ip，所以客户源站资源的更新  刷新下 [cdn 缓存](https://portal.qiniu.com/cdn/refresh-prefetch)  这样客户端访问才会直接打回到客户的源站取最新资源


# 刷新缓存失败，验证文件一致性方法 (/faq/cdn/refresh-the-cache-problem/3644-refresh-the-cache-fails-consistency-method-validation-file)



最近更新时间: 2017-09-19 17:14:42

更新/删除文件后，遇到访问文件与上传的文件不一致时，需要刷新 CDN 缓存来解决。刷新方法参考：
[/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time)

刷新文件后，对于已知修改部分的文本文件，可用肉眼判断文件是否刷新成功。
对于其他文件，可以用对比文件 md5 的方法来进行验证。

1. 对于 MacOS、Linux  操作系统，可在终端用 md5 file\_name 命令计算文件 MD5 ：

![](/docs-assets/faq/cdn/refresh-the-cache-problem/3644-refresh-the-cache-fails-consistency-method-validation-file/FuNE04KWmeYTZVqSWVRRsuClm-hS-a171033047dd.webp)

1. 对于 Windows 系统，可借助第三方工具来计算 MD5 ，这里推荐一款免费、轻量的软件：Hash（MD5校验工具）


# 访问资源与上传资源不一致 (/faq/cdn/refresh-the-cache-problem/4078-access-to-resources-and-upload-resources)



最近更新时间: 2026-04-29 18:01:11

# 问题描述 [#问题描述]

访问的资源与上传的资源不一致

# 问题原因 [#问题原因]

## 原因一 [#原因一]

cdn 节点缓存了相同的 url 链接，但是资源不同，比如覆盖上传文件，因为 cdn 是按照资源的 url 进行缓存，如果访问的 url 相同，那么就会命中缓存，直接返回 cdn 中的资源，而不是去源站拉取最新的资源。您可以刷新 cdn 缓存解决此问题。
如何刷新请参考：
[/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time)

## 原因二 [#原因二]

在确保原因一描述的情况没有问题，访问的文档与上传的资源的确不一致，或者上传之前和上传之后文件的md5值不一样，建议您在上传的时候开启 crc32 校验策略（crc32 校验请参考：[https://developer.qiniu.com/search?keyword=crc32](https://developer.qiniu.com/search?keyword=crc32) ） ，上传前会先计算本地文件的 crc32，然后和上传到七牛后文件的 crc32 进行对比，如果两者不同的话就不会保存，并且会返回 406：上传的数据 crc32 校验错误。通过 crc32 校验确保上传之前与上传之后的文件一致。

## 原因三 [#原因三]

如果出现极少部分地区访问的资源不一致，比如内容被篡改，并且通过刷新 cdn 缓存的方式已无法解决此问题，这有可能是 cdn 节点或者用户的网络被劫持。可以提交工单并且提供以下信息，七牛工程师会帮您检查是否是 cdn 节点被劫持还是用户的自身网络被劫持。

需提供提供以下资源：

1：资源链接

2：ping下你的访问域名截图

3：dns 诊断截图([https://boce.aliyun.com/detect/dns](https://boce.aliyun.com/detect/dns))

如果是 cdn 的节点被劫持，我们会去运营商进行投诉，如果是用户自身的网络，需要用户自己去网络运营商进行投诉。运营商反馈劫持请参考：[/faq/cdn/other-fusion/2755-operator](/faq/cdn/other-fusion/2755-operator)


# postman 调试接口 (/faq/cdn/upload-download-problem/3752-no%20query)



最近更新时间: 2017-09-20 17:27:53

调试表单上传方法

1. [表单上传](/products/kodo/development-guidelines/upload-types/1-form-upload)

<br />

2. 表单上传必须的三个元素 上传 host 、文件本身以及上传 token

<br />

3. 不同区域存储空间对应的 host 不同，[参考文档](/products/kodo/2-region-endpoint-fq)

<br />

4. 上传 token 生成，[参考文档](/products/kodo/development-guidelines/security/2-upload-token)
5. 打开 postman ,输入下图中指定内容

![](/docs-assets/faq/cdn/upload-download-problem/3752-no%20query/FnXLVAL94YjZaYrmnIYyAoIHZ0sG-b9ee8a1b7e96.webp)


# gif 转 mp4 (/faq/dora/av-processing/1278-gif-to-mp4)



最近更新时间: 2021-07-21 15:11:11

使用[音视频转码 (avthumb)](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 进行转码

例子：

使用 php 进行转码操作：

```php
<?php
require_once '/---/--/php-sdk-7.0.8/autoload.php';

use Qiniu\Auth;
use Qiniu\Processing\PersistentFop;

//对已经上传到七牛的视频发起异步转码操作

$accessKey = ' ';
$secretKey = ' ';
$auth = new Auth($accessKey, $secretKey);

//要转码的文件所在的空间和文件名
$bucket = ' ';
$key = ' ';

//转码是使用的队列名称
$pipeline = ' ';
$pfop = new PersistentFop($auth, $bucket, $pipeline);
$fops = "avthumb/mp4/s/640x360/vb/1.25m";
$savekey = Qiniu\base64\_urlSafeEncode('目标空间:转码后文件名称');
$pfops = $fops.'|saveas/'.$savekey;

list($id, $err) = $pfop-\>execute($bucket, $key, $pfops);
echo "\n====\> pfop avthumb result: \n";
if ($err != null) {
var\_dump($err);
} else {
echo "PersistentFop Id: $id\n";
}

//查询转码的进度和状态
list($ret, $err) = $pfop-\>status($id);
echo "\n====\> pfop avthumb status: \n";
if ($err != null) {
var\_dump($err);
} else {
var\_dump($ret);
}
```

之后使用 `http://api.qiniu.com/status/get/prefop?id=<PersistentFop Id>` 查询转码状态

在空间中也能看到转码后的mp4


# avthumb参数formats格式及解释 (/faq/dora/av-processing/1320-avthumb-parameters-formats-format-and-explanation)



最近更新时间: 2023-12-11 14:47:15

[/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 

## 参数 `format`：目标音频（比如 mp3 m4a 等）或视频（比如 avi 、flv 、mp4等）格式。 [#参数-format目标音频比如-mp3-m4a-等或视频比如-avi-flv-mp4等格式]

该参数支持具体格式如下表：

| formats          | description                                                 |
| ---------------- | ----------------------------------------------------------- |
| 3g2              | 3GP2 (3GPP2 file format)                                    |
| 3gp              | 3GP (3GPP file format)                                      |
| a64              | a64 video for Commodore 64                                  |
| ac3              | raw AC-3                                                    |
| adts             | ADTS AAC (Advanced Audio Coding)                            |
| adx              | CRI ADX                                                     |
| aiff             | Audio IFF                                                   |
| alaw             | PCM A-law                                                   |
| amr              | 3GPP AMR                                                    |
| asf              | ASF (Advanced / Active Streaming Format)                    |
| asf\_stream      | ASF (Advanced / Active Streaming Format)                    |
| ass              | SSA (SubStation Alpha) subtitle                             |
| ast              | AST (Audio Stream)                                          |
| au               | Sun AU                                                      |
| avi              | AVI (Audio Video Interleaved)                               |
| avm2             | SWF (ShockWave Flash) (AVM2)                                |
| bit              | G.729 BIT file format                                       |
| caf              | Apple CAF (Core Audio Format)                               |
| cavsvideo        | raw Chinese AVS (Audio Video Standard) video                |
| crc              | CRC testing                                                 |
| data             | raw data                                                    |
| daud             | D-Cinema audio                                              |
| dirac            | raw Dirac                                                   |
| dnxhd            | raw DNxHD (SMPTE VC-3)                                      |
| dts              | raw DTS                                                     |
| dv               | DV (Digital Video)                                          |
| dvd              | MPEG-2 PS (DVD VOB)                                         |
| eac3             | raw E-AC-3                                                  |
| f32be            | PCM 32-bit floating-point big-endian                        |
| f32le            | PCM 32-bit floating-point little-endian                     |
| f4v              | F4V Adobe Flash Video                                       |
| f64be            | PCM 64-bit floating-point big-endian                        |
| f64le            | PCM 64-bit floating-point little-endian                     |
| ffm              | FFM (FFserver live feed)                                    |
| ffmetadata       | FFmpeg metadata in text                                     |
| filmstrip        | Adobe Filmstrip                                             |
| flac             | raw FLAC                                                    |
| flv              | FLV (Flash Video)                                           |
| framecrc         | framecrc testing                                            |
| framemd5         | Per-frame MD5 testing                                       |
| g722             | raw G.722                                                   |
| g723\_1          | raw G.723.1                                                 |
| gif              | GIF Animation                                               |
| gxf              | GXF (General eXchange Format)                               |
| h261             | raw H.261                                                   |
| h263             | raw H.263                                                   |
| h264             | raw H.264 video                                             |
| hls              | Apple HTTP Live Streaming                                   |
| ico              | Microsoft Windows ICO                                       |
| ilbc             | iLBC storage                                                |
| image2           | image2 sequence                                             |
| image2pipe       | piped image2 sequence                                       |
| ipod             | iPod H.264 MP4 (MPEG-4 Part 14)                             |
| ircam            | Berkeley/IRCAM/CARL Sound Format                            |
| ismv             | ISMV/ISMA (Smooth Streaming)                                |
| ivf              | On2 IVF                                                     |
| jacosub          | JACOsub subtitle format                                     |
| latm             | LOAS/LATM                                                   |
| m4v              | raw MPEG-4 video                                            |
| matroska         | Matroska                                                    |
| md5              | MD5 testing                                                 |
| microdvd         | MicroDVD subtitle format                                    |
| mjpeg            | raw MJPEG video                                             |
| mkvtimestamp\_v2 | extract pts as timecode v2 format, as defined by mkvtoolnix |
| mlp              | raw MLP                                                     |
| mmf              | Yamaha SMAF                                                 |
| mov              | QuickTime / MOV                                             |
| mp2              | MP2 (MPEG audio layer 2)                                    |
| mp3              | MP3 (MPEG audio layer 3)                                    |
| m4a              | M4A (MPEG-4 audio )                                         |
| mp4              | MP4 (MPEG-4 Part 14)                                        |
| mpeg             | MPEG-1 Systems / MPEG program stream                        |
| mpeg1video       | raw MPEG-1 video                                            |
| mpeg2video       | raw MPEG-2 video                                            |
| mpegts           | MPEG-TS (MPEG-2 Transport Stream)                           |
| mpjpeg           | MIME multipart JPEG                                         |
| mulaw            | PCM mu-law                                                  |
| mxf              | MXF (Material eXchange Format)                              |
| mxf\_d10         | MXF (Material eXchange Format) D-10 Mapping                 |
| nut              | NUT                                                         |
| ogg              | Ogg                                                         |
| oma              | Sony OpenMG audio                                           |
| psp              | PSP MP4 (MPEG-4 Part 14)                                    |
| rawvideo         | raw video                                                   |
| rm               | RealMedia                                                   |
| roq              | raw id RoQ                                                  |
| rso              | Lego Mindstorms RSO                                         |
| rtp              | RTP output                                                  |
| rtsp             | RTSP output                                                 |
| s16be            | PCM signed 16-bit big-endian                                |
| s16le            | PCM signed 16-bit little-endian                             |
| s24be            | PCM signed 24-bit big-endian                                |
| s24le            | PCM signed 24-bit little-endian                             |
| s32be            | tPCM signed 32-bit big-endian                               |
| s32le            | PCM signed 32-bit little-endian                             |
| s8               | PCM signed 8-bit                                            |
| sap              | SAP output                                                  |
| segment          | segment                                                     |
| smjpeg           | Loki SDL MJPEG                                              |
| smoothstreaming  | Smooth Streaming Muxer                                      |
| sox              | SoX native                                                  |
| spdif            | IEC 61937 (used on S/PDIF - IEC958)                         |
| srt              | SubRip subtitle                                             |
| stream\_segment  | streaming segment muxer                                     |
| ssegment         | streaming segment muxer                                     |
| svcd             | MPEG-2 PS (SVCD)                                            |
| swf              | SWF (ShockWave Flash)                                       |
| tee              | Multiple muxer tee                                          |
| truehd           | raw TrueHD                                                  |
| u16be            | PCM unsigned 16-bit big-endian                              |
| u16le            | PCM unsigned 16-bit little-endian                           |
| u24be            | PCM unsigned 24-bit big-endian                              |
| u24le            | PCM unsigned 24-bit little-endian                           |
| u32be            | PCM unsigned 32-bit big-endian                              |
| u32le            | PCM unsigned 32-bit little-endian                           |
| u8               | PCM unsigned 8-bit                                          |
| vc1              | raw VC-1 video                                              |
| vc1test          | VC-1 test bitstream                                         |
| vcd              | MPEG-1 Systems / MPEG program stream (VCD)                  |
| vob              | MPEG-2 PS (VOB)                                             |
| voc              | Creative Voice                                              |
| w64              | Sony Wave64                                                 |
| wav              | WAV / WAVE (Waveform Audio)                                 |
| webm             | Matroska / WebM                                             |
| webvtt           | WebVTT subtitle                                             |
| wtv              | Windows Television (WTV)                                    |
| wv               | raw WavPack                                                 |
| yuv4mpegpipe     | YUV4MPEG pipe                                               |


# 音视频转码请求的计费方法 (/faq/dora/av-processing/1331-the-charging-method-based-on-audio-and-video-transcoding-request)



最近更新时间: 2021-07-23 18:22:00

> 音视频转码是如何计费的？

# 音频转码 价格：0.0048 元 / min , 0.288 元 / hour [#音频转码-价格00048-元--min--0288-元--hour]

### 举例：用户将一段 3min45sec 的WAV，转换输出为 3min45sec 128 KHz 的MP3 [#举例用户将一段-3min45sec-的wav转换输出为-3min45sec-128-khz-的mp3]

转码计费的标准为输出的声音文件的时间长度，故本次转码的费用如下

3min45sec = 3.75 min
3.75 \* 0.0048 = 0.018 元

用户承担由此产生的转码结果的存储费用。

### 视频转码 sd240 价格: 0.0057 元 / min - 0.342 元 / hour [#视频转码-sd240-价格-00057-元--min---0342-元--hour]

按照用户的输出视频面积的"长边x短边"来判断规格
当输出的视频分辨率同时小于等于320x240，符合此规格的计费标准。
当输出的视频分辨率一边大于320或240 则不属于该规格，如321x240，321x239，320x241，319x241等不属于该规格。

举例：一段任意规格的60min钟原始视频，使用了七牛转码输出为319x240规格的60min视频，并保存在指定bucket中。
收费以输出的结果为计费标准，则本次收费的结果如下：
转码的费用 ： 60 \* 0.0057 = 0.342 元

用户承担由此产生的转码结果的存储费用。

### 视频转码 sd480 价格: 0.0072 元 / min - 0.432 元 / hour [#视频转码-sd480-价格-00072-元--min---0432-元--hour]

按照用户的输出视频面积的"长边x短边"来判断规格
当输出的视频分辨率同时小于等于640x480，符合此规格的计费标准。
当输出的视频分辨率一边大于640 或 480 则不属于该规格，如641x480,640x481,639x481,641x479, 等不属于该规格。

举例：一段任意规格的60min钟原始视频，使用了七牛转码输出为629x240规格的60min视频，并保存在指定bucket中。
收费以输出的结果为计费标准，则本次收费的结果如下：
转码的费用 ： 60 \* 0.0072 = 0.432 元

用户承担由此产生的转码结果的存储费用。

### 视频转码 sd 价格: 0.0189 元 / min, 1.134 元 / hour [#视频转码-sd-价格-00189-元--min-1134-元--hour]

规格说明：
按照用户的输出视频面积的"长边x短边"来判断规格
当输出的视频分辨率同时小于等于1080x720，符合此规格的计费标准。
当输出的视频分辨率一边大于1080 或 720 则不属于该规格，如1077x721,1081x719,1080x721,1081x719, 等不属于该规格。

举例：一段任意规格的60min钟原始视频，使用了七牛转码输出为1000x720 规格的60min视频，并保存在指定bucket中。
收费以输出的结果为计费标准，则本次收费的结果如下：
转码的费用 ： 60 \* 0.0189 = 1.134 元

用户承担由此产生的转码结果的存储费用。

### 视频转码 hd 价格: 0.0324 元 / min 1.944 元 / hour [#视频转码-hd-价格-00324-元--min-1944-元--hour]

按照用户的输出视频面积的"长边x短边"来判断规格
当输出的视频分辨率长短边中任一边大于1080x720，符合此规格的计费标准。
当输出的视频分辨率同时小于等于1080x720 则不属于该规格，
如1077x721,1081x719,1280x720,1081x480, 属于该规格。
如 1080x719，1080x240，等不属于该规格

举例：一段任意规格的60min钟原始视频，使用了七牛转码输出为1000x1000 规格的60min视频，并保存在指定bucket中。
收费以输出的结果为计费标准，本次收费的结果如下：
转码的费用：60 \* 0.0324 = 1.944 元

用户承担由此产生的转码结果的存储费用。

**注：如果使用管道功能对音视频文件进行多次转码，那么每次转码过程都会计费。**


# avthumb参数vcodec格式及解释 (/faq/dora/av-processing/1385-avthumb-parameter-vcodec-format-and-explanation)



最近更新时间: 2023-08-30 14:19:49

[http://developer.qiniu.com/code/v6/api/dora-api/av/avthumb.html](http://developer.qiniu.com/code/v6/api/dora-api/av/avthumb.html)

## 参数`/vcodec/<VideoCodec>`：视频编码方案，支持方案：libx264 ，libvpx ，libtheora ，libxvid ，libvpx-vp9 等。 [#参数vcodecvideocodec视频编码方案支持方案libx264-libvpx-libtheora-libxvid-libvpx-vp9-等]

| videoEncoders | description                                                                               |
| ------------- | ----------------------------------------------------------------------------------------- |
| a64multi      | Multicolor charset for Commodore 64 (codec a64\_multi)                                    |
| a64multi5     | Multicolor charset for Commodore 64, extended with 5th color (colram) (codec a64\_multi5) |
| amv           | AMV Video                                                                                 |
| asv1          | ASUS V1                                                                                   |
| asv2          | ASUS V2                                                                                   |
| avrp          | Avid 11 10-bit RGB Packer                                                                 |
| avui          | Avid Meridien Uncompressed                                                                |
| ayuv          | Uncompressed packed MS 4444                                                               |
| bmp           | BMP (Windows and OS/2 bitmap)                                                             |
| cljr          | Cirrus Logic AccuPak                                                                      |
| dnxhd         | VC3/DNxHD                                                                                 |
| dpx           | DPX image                                                                                 |
| dvvideo       | DV (Digital Video)                                                                        |
| ffv1          | FFmpeg video codec # 1                                                                    |
| ffvhuff       | Huffyuv FFmpeg variant                                                                    |
| flashsv       | Flash Screen Video                                                                        |
| flashsv2      | Flash Screen Video Version 2                                                              |
| flv           | FLV / Sorenson Spark / Sorenson H.263 (Flash Video) (codec flv1)                          |
| gif           | GIF (Graphics Interchange Format)                                                         |
| h261          | H.261                                                                                     |
| h263          | H.263 / H.263-1996                                                                        |
| h263p         | H.263+ / H.263-1998 / H.263 version 2                                                     |
| libx264       | libx264 H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10 RGB (codec h264)                        |
| libx265       | libx265 H.265 / AVC / MPEG-4 AVC / MPEG-4 part 10 RGB (codec h265)                        |
| libaom-av1    | Alliance for Open Media AV1                                                               |
| huffyuv       | Huffyuv / HuffYUV                                                                         |
| jpeg2000      | JPEG 2000,                                                                                |
| jpegls        | JPEG-LS                                                                                   |
| ljpeg         | Lossless JPEG                                                                             |
| mjpeg         | MJPEG (Motion JPEG)                                                                       |
| mpeg1video    | MPEG-1 video                                                                              |
| mpeg2video    | MPEG-2 video                                                                              |
| mpeg4         | MPEG-4 part 2                                                                             |
| libxvid       | libxvidcore MPEG-4 part 2 (codec mpeg4)                                                   |
| msmpeg4v2     | MPEG-4 part 2 Microsoft variant version 2                                                 |
| msmpeg4       | MPEG-4 part 2 Microsoft variant version 3 (codec msmpeg4v3)                               |
| msvideo1      | Microsoft Video-1                                                                         |
| pam           | PAM (Portable AnyMap) image                                                               |
| pbm           | PBM (Portable BitMap) image                                                               |
| pcx           | PC Paintbrush PCX image                                                                   |
| pgm           | PGM (Portable GrayMap) image                                                              |
| pgmyuv        | PGMYUV (Portable GrayMap YUV) image                                                       |
| png           | PNG (Portable Network Graphics) image                                                     |
| ppm           | PPM (Portable PixelMap) image                                                             |
| prores        | Apple ProRes                                                                              |
| prores\_aw    | Apple ProRes (codec prores)                                                               |
| prores\_ks    | Apple ProRes (iCodec Pro) (codec prores)                                                  |
| qtrle         | QuickTime Animation (RLE) video                                                           |
| r10k          | AJA Kona 10-bit RGB Codec                                                                 |
| r210          | Uncompressed RGB 10-bit                                                                   |
| rawvideo      | raw video                                                                                 |
| roqvideo      | id RoQ video (codec roq)                                                                  |
| rv10          | RealVideo 1.0                                                                             |
| rv20          | RealVideo 2.0                                                                             |
| sgi           | SGI image                                                                                 |
| snow          | Snow                                                                                      |
| sunrast       | Sun Rasterfile image                                                                      |
| svq1          | Sorenson Vector Quantizer 1 / Sorenson Video 1 / SVQ1                                     |
| targa         | Truevision Targa image                                                                    |
| libtheora     | libtheora Theora (codec theora)                                                           |
| tiff          | TIFF image                                                                                |
| utvideo       | Ut Video                                                                                  |
| v210          | Uncompressed 422 10-bit                                                                   |
| v308          | Uncompressed packed 444                                                                   |
| v408          | Uncompressed packed QT 4444                                                               |
| v410          | Uncompressed 444 10-bit                                                                   |
| libvpx        | libvpx VP8 (codec vp8)                                                                    |
| libvpx-vp9    | libvpx VP9                                                                                |
| wmv1          | Windows Media Video 7                                                                     |
| wmv2          | Windows Media Video 8                                                                     |
| xbm           | XBM (X BitMap) image                                                                      |
| xface         | X-face image                                                                              |
| xwd           | XWD (X Window Dump) image                                                                 |
| y41p          | Uncompressed YUV 411 12-bit                                                               |
| yuv4          | Uncompressed packed 420                                                                   |
| zlib          | LCL (LossLess Codec Library) ZLIB                                                         |
| zmbv          | Zip Motion Blocks Video                                                                   |
| copy          | 编码与同原始视频                                                                                  |


# 切片生成的ts文件只有一片的问题 (/faq/dora/av-processing/1413-slice-the-generated-ts-file-only-a-slice-of-the-problem)



最近更新时间: 2021-07-21 15:11:11

一般切片生成一片都是文件本身有问题，比如这个音频文件, 切片的时候可以指定参数/vn/1可修复，vn/1表示的是忽略视频流的信息。

比如这个mp3文件:

[http://dn-odum9helk.qbox.me/wjw/48min-66mb.mp3](http://dn-odum9helk.qbox.me/wjw/48min-66mb.mp3)

这样切片生成的文件是只有一片的:

avthumb/m3u8/segtime/10/ab/48k/ar/44100/acodec/libfaac/noDomain/1

加一个vn/1参数再次切片是正常的:

avthumb/m3u8/segtime/10/ab/48k/ar/44100/acodec/libfaac/noDomain/1/vn/1

原因如下:

Frame rate very high for a muxer not efficiently supporting it. 导致结果不符合预期

因为此音频实际含有视频流
index":1,"codec\_name":"mjpeg","codec\_type":"video","start\_time":"0.025056","duration":"2884.075100","bit\_rate":"","nb\_frames":"","width":420,"height":420,"pix\_fmt":"yuvj444p","r\_frame\_rate":"90000/1","avg\_frame\_rate":"0/0","sample\_aspect\_ratio":"1:1","display\_aspect\_ratio":"1:1","tags":\{},"Disposition":

\{"attached\_pic":1}


# avthumb参数acodec格式及解释 (/faq/dora/av-processing/1432-avthumb-parameter-acodec-format-and-explanation)



最近更新时间: 2022-09-02 10:16:37

[/faq/dora/av-processing/1432-avthumb-parameter-acodec-format-and-explanation](/faq/dora/av-processing/1432-avthumb-parameter-acodec-format-and-explanation)

## 参数 `/acodec/<AudioCodec>`：音频编码方案，支持方案：libmp3lame ， libfaac ， libvorbis ，libfdk\_aac 等。 [#参数-acodecaudiocodec音频编码方案支持方案libmp3lame--libfaac--libvorbis-libfdk_aac-等]

| audioEncoders      | description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| aac                | AAC (Advanced Audio Coding)                                       |
| libfaac            |                                                                   |
| ac3                | ATSC A/52A (AC-3)                                                 |
| ac3\_fixed         | ATSC A/52A (AC-3) (codec ac3)                                     |
| adpcm\_adx         | SEGA CRI ADX ADPCM                                                |
| g722               | G.722 ADPCM (codec adpcm\_g722)                                   |
| g726               | G.726 ADPCM (codec adpcm\_g726)                                   |
| adpcm\_ima\_qt     | ADPCM IMA QuickTime                                               |
| adpcm\_ima\_wav    | ADPCM IMA WAV                                                     |
| adpcm\_ms          | ADPCM Microsoft                                                   |
| adpcm\_swf         | ADPCM Shockwave Flash                                             |
| adpcm\_yamaha      | ADPCM Yamaha                                                      |
| alac               | ALAC (Apple Lossless Audio Codec)                                 |
| libopencore\_amrnb | OpenCORE AMR-NB (Adaptive Multi-Rate Narrow-Band) (codec amr\_nb) |
| comfortnoise       | RFC 3389 comfort noise generator                                  |
| dca                | DCA (DTS Coherent Acoustics) (codec dts)                          |
| eac3               | ATSC A/52 E-AC-3                                                  |
| flac               | FLAC (Free Lossless Audio Codec)                                  |
| g723\_1            | G.723.1                                                           |
| libilbc            | iLBC (Internet Low Bitrate Codec) (codec ilbc)                    |
| mp2                | MPEG audio layer 2 High Frequency                                 |
| libmp3lame         | libmp3lame MP3 (MPEG audio layer 3) (codec mp3)                   |
| nellymoser         | Nellymoser Asao                                                   |
| pcm\_alaw          | PCM A-law / G.711 A-law                                           |
| pcm\_f32be         | PCM 32-bit floating point big-endian                              |
| pcm\_f32le         | PCM 32-bit floating point little-endian                           |
| pcm\_f64be         | PCM 64-bit floating point big-endian                              |
| pcm\_f64le         | PCM 64-bit floating point little-endian                           |
| pcm\_mulaw         | PCM mu-law / G.711 mu-law                                         |
| pcm\_s16be         | PCM signed 16-bit big-endian                                      |
| pcm\_s16be\_planar | PCM signed 16-bit big-endian planar                               |
| pcm\_s16le         | PCM signed 16-bit little-endian                                   |
| pcm\_s16le\_planar | PCM signed 16-bit little-endian planar                            |
| pcm\_s24be         | PCM signed 24-bit big-endian                                      |
| pcm\_s24daud       | PCM D-Cinema audio signed 24-bit                                  |
| pcm\_s24le         | PCM signed 24-bit little-endian                                   |
| pcm\_s24le\_planar | PCM signed 24-bit little-endian planar                            |
| pcm\_s32be         | PCM signed 32-bit big-endian                                      |
| pcm\_s32le         | PCM signed 32-bit little-endian                                   |
| pcm\_s32le\_planar | PCM signed 32-bit little-endian planar                            |
| pcm\_s8            | CM signed 8-bit                                                   |
| pcm\_s8\_planar    | PCM signed 8-bit planar                                           |
| pcm\_u16be         | PCM unsigned 16-bit big-endian                                    |
| pcm\_u16le         | PCM unsigned 16-bit little-endian                                 |
| pcm\_u24be         | PCM unsigned 24-bit big-endian                                    |
| pcm\_u24le         | PCM unsigned 24-bit little-endian                                 |
| pcm\_u32be         | PCM unsigned 32-bit big-endian                                    |
| pcm\_u32le         | PCM unsigned 32-bit little-endian                                 |
| pcm\_u8            | PCM unsigned 8-bit                                                |
| real\_144          | RealAudio 1.0 (14.4K) (codec ra\_144)                             |
| roq\_dpcm          | id RoQ DPCM                                                       |
| s302m              | SMPTE 302M                                                        |
| sonic              | Sonic                                                             |
| sonicls            | Sonic lossless                                                    |
| tta                | TTA (True Audio)                                                  |
| vorbis             | Vorbis                                                            |
| libvorbis          | ibvorbis (codec vorbis)                                           |
| wavpack            | 无损音频压缩格式                                                          |
| wmav1              | Windows Media Audio 1                                             |
| wmav2              | Windows Media Audio 2                                             |
| copy               | 编码同原始音频                                                           |


# 视频支持格式 (/faq/dora/av-processing/1455-support-video-format)



最近更新时间: 2021-07-21 15:11:11

| 格式               | 是否支持 |
| ---------------- | ---- |
| g2               | true |
| 3gp              | true |
| a64              | true |
| ac3              | true |
| adts             | true |
| adx              | true |
| aiff             | true |
| alaw             | true |
| amr              | true |
| asf              | true |
| asf\_stream      | true |
| ass              | true |
| ast              | true |
| au               | true |
| avi              | true |
| avm2             | true |
| bit              | true |
| caf              | true |
| cavsvideo        | true |
| crc              | true |
| data             | true |
| daud             | true |
| dirac            | true |
| dnxhd            | true |
| dts              | true |
| dv               | true |
| dvd              | true |
| eac3             | true |
| f32be            | true |
| f32le            | true |
| f4v              | true |
| f64be            | true |
| f64le            | true |
| ffm              | true |
| ffmetadata       | true |
| filmstrip        | true |
| flac             | true |
| flv              | true |
| framecrc         | true |
| framemd5         | true |
| g722             | true |
| g723\_1          | true |
| gif              | true |
| gxf              | true |
| h261             | true |
| h263             | true |
| h264             | true |
| hls              | true |
| ico              | true |
| ilbc             | true |
| image2           | true |
| image2pipe       | true |
| ipod             | true |
| ircam            | true |
| ismv             | true |
| ivf              | true |
| jacosub          | true |
| latm             | true |
| m4v              | true |
| matroska         | true |
| md5              | true |
| microdvd         | true |
| mjpeg            | true |
| mkvtimestamp\_v2 | true |
| mlp              | true |
| mmf              | true |
| mov              | true |
| mp2              | true |
| mp3              | true |
| mp4              | true |
| mpeg             | true |
| mpeg1video       | true |
| mpeg2video       | true |
| mpegts           | true |
| mpjpeg           | true |
| mulaw            | true |
| mxf              | true |
| mxf\_d10         | true |
| null             | true |
| nut              | true |
| ogg              | true |
| oma              | true |
| psp              | true |
| rawvideo         | true |
| rm               | true |
| roq              | true |
| rso              | true |
| rtp              | true |
| rtsp             | true |
| s16be            | true |
| s16le            | true |
| s24be            | true |
| s24le            | true |
| s32be            | true |
| s32le            | true |
| s8               | true |
| sap              | true |
| segment          | true |
| smjpeg           | true |
| smoothstreaming  | true |
| sox              | true |
| spdif            | true |
| srt              | true |
| stream\_segment  | true |
| ssegment         | true |
| svcd             | true |
| swf              | true |
| tee              | true |
| truehd           | true |
| u16be            | true |
| u16le            | true |
| u24be            | true |
| u24le            | true |
| u32be            | true |
| u32le            | true |
| u8               | true |
| vc1              | true |
| vc1test          | true |
| vcd              | true |
| vob              | true |
| voc              | true |
| w64              | true |
| wav              | true |
| webm             | true |
| webvtt           | true |
| wtv              | true |
| wv               | true |
| yuv4mpegpipe     | true |


# 使用七牛进行视频的剪辑 (/faq/dora/av-processing/1620-using-seven-cows-for-video-clips)



最近更新时间: 2021-07-23 18:21:40

七牛提供了很丰富的一视频处理功能， 比如视频转码， 截图， 水印，旋转， 切片等， 这篇简单介绍下[视频剪辑](/faq/dora/av-processing/1620-using-seven-cows-for-video-clips)的简单操作。

比如我的七牛空间中有一个 MP4 文件：[http://dn-odum9helk.qbox.me/wangjiawei/1.mp4](http://dn-odum9helk.qbox.me/wangjiawei/1.mp4) 。 我们先来看下这个 MP4 的[视频信息](http://dn-odum9helk.qbox.me/wangjiawei/1.mp4?avinfo), 我们可以看到一个视频的时长信息`"duration": "239.285333"`表示 239 秒。现在我们打算做这样的截取`从第一分钟开始，截取时长为一分钟`。 我们来看下我们的[音视频处理接口](/faq/dora/av-processing/1620-using-seven-cows-for-video-clips), 其中有两个参数：

| 参数名称                    | 类别  | 必填 | 说明                                    |
| ----------------------- | --- | -- | ------------------------------------- |
| `&lt;Format&gt;`        | A/V | 是  | 目标视频的格式（比如 flv、mp4 等），参考 \[支持转换的视频格式] |
| `/ss/&lt;SeekStart&gt;` | A/V |    | 指定视频截取的开始时间，单位：秒。用于视频截取，从一段视频中截取一段视频。 |
| `/t/&lt;Duration&gt;`   | V   |    | 指定视频截取的长度，单位：秒。用于视频截取，从一段视频中截取一段视频。   |

可以用来做视频剪辑。

* 根据需求我们可以将开始时间 `ss` 设置为 `60`, 剪辑时长一分钟，可以将 `t` 设置为 `60`， 这样我们的处理规则就是：`avthumb/mp4/ss/60/t/60`。

* 然后使用我们的 [PFOP](/faq/dora/av-processing/1620-using-seven-cows-for-video-clips) 即可以将视频截取出来。

* 但是这样处理后的文件名是不规则的， 如果你想指定处理后的文件名可以参考我们的 [saveas 接口](/faq/dora/av-processing/1620-using-seven-cows-for-video-clips) 。 比如我们想处理后保存在空间`rwxf`, 文件名保存成`processed.mp4`。

  1. 我们首先需要对 `rwxf:processed.mp4` 进行[urlsafebase64编码](/faq/dora/av-processing/1620-using-seven-cows-for-video-clips)后得到 `cnd4Zjpwcm9jZXNzZWQubXA0`。
  2. 这样我们的处理命令就变成了：`avthumb/mp4/ss/60/t/60\|saveas/cnd4Zjpwcm9jZXNzZWQubXA0`。

* 进行 PFOP 处理后，如果想要查询处理的状态可以通过[持久化状态查询](/faq/dora/av-processing/1620-using-seven-cows-for-video-clips)接口来进行查询。

下面我们给一个简单的 php demo：

\<?php
require\_once **DIR**. '/../autoload.php';

use Qiniu\Auth;
use Qiniu\Processing\PersistentFop;

$accessKey = '\<your\_ak>';
$secretKey = '\<your\_sk>';
$auth = new Auth($accessKey, $secretKey);
$config = new \Qiniu\Config();

$bucket = 'rwxf';
$key = '1.mp4';
$pipeline = 'abc'; //队列名称，使用独立队列可以加快处理速度。
$pfop = new PersistentFop($auth, $config);
$savedkey = 'processed.mp4';
$entry = \Qiniu\base64\_urlSafeEncode("$bucket:$savedkey");
$fops = "avthumb/mp4/ss/60/t/60|saveas/$entry";
list($id, $err) = $pfop->execute($bucket, $key, $fops);
echo "\n====> pfop avthumb result: \n";
if ($err != null)
\{
var\_dump($err);
}
else
\{
echo "PersistentFop Id: $id\n";
}

以上代码要配合我们的 [phpsdk](https://github.com/qiniu/php-sdk) 才可以运行。


# 视频元信息响应内容的属性及说明 (/faq/dora/av-processing/1678-video-meta-information-response-content-properties-and-instructions)



最近更新时间: 2021-07-21 15:11:11

# streams 输出流信息 [#streams-输出流信息]

| 属性                 | 说明           | 属性                              | 说明                   |
| ------------------ | ------------ | ------------------------------- | -------------------- |
| index              | 流所在的索引区域     | r\_frame\_rate/avg\_frame\_rate | 实际帧率/平均帧率            |
| Codec\_name        | 编码名          | time\_base                      | 时间基数(用来做timestamp计算) |
| Codec\_long\_name; | 编码全名         | start\_time                     | 起始时间                 |
| Codec\_type        | 编码类型         | duration                        | 总时长                  |
| Codec\_time\_base  | 编码的时间戳计算基础单位 | n\_frames                       | 帧数                   |
| Codec\_tag\_string | 编码的标签数据      | handle\_name                    | 句柄名称                 |
| width/height       | 视频的宽和高       | sample\_fmt                     | 音频的原始采样格式            |
| pix\_fmt           | 图像显示图像色彩格式   | sample\_rate                    | 音频的采样率               |
| level              | 编码的level     | channels                        | 信道数目                 |

# format 输出封装格式信息 [#format-输出封装格式信息]

| 属性                 | 说明     | 属性           | 说明   |   |
| ------------------ | ------ | ------------ | ---- | - |
| nb\_streams        | 流通道数   | format\_name | 封装格式 |   |
| format\_long\_time | 封装格式全称 | start\_time  | 起始时间 |   |
| duration           | 总时长    | size         | 文件大小 |   |
| bit\_rate          | 码率     |              |      |   |


# 关于七牛音视频转码时长的说明 (/faq/dora/av-processing/1681-about-seven-cows-audio-video-transcoding-long-description)



最近更新时间: 2021-07-21 15:11:11

使用公有队列以及私有队列处理时间不同：

1.使用公有队列

使用公有队列的转码任务，由于使用共享资源，存在任务排队的可能，所以转码时长不能保证；

2.使用私有队列

当使用私有队列进行视频转码，如果转码耗时未超过视频长度三分之一(例如一个小时的视频，转码在20分钟内完成)，则属于正常范围；如果希望加快转码速度，则用户可以部署ufop（自定义数据处理），通过提高机器性能来缩短转码时长。

* [私有队列的创建和sdk使用](/faq/dora/other-dora/3853-how-to-create-audio-and-video-processing-private-queues)
* [自定义数据处理文档](/products/dora/processing-mechanism/1-directions-for-use-pfop)

注意：如果对于处理时长有要求的话，建议使用私有队列


# 点播如何保存，再进行视频格式（mp4）的转码 (/faq/dora/av-processing/1699-on-demand-how-saveas-again-the-transcoding-of-video-format-mp4)



最近更新时间: 2021-07-21 15:11:11

# 1.点播保存 [#1点播保存]

业务服务器有两个版本，v1和v2，下面分别介绍如何进行视频流的保存：

**v1：**

v1版本服务器是通过saveAs(saveAsName, saveAsFormat, saveAsStart, saveAsEnd)方法进行视频流的保存的，其中

saveAsName是保存的视频的名称。

saveAsFormat是目标视频的格式，指定format为null进行操作，立即生成m3u8。

saveAsStart, saveAsEnd分别为想保存视频的起止时间，以Unix时间戳的格式传入，这个时间可以通过segments方法获得。

**v2：**

v2版本服务器是通过save(long start, long end)方法进行视频流的保存的，默认只能保存成m3u8文件，其参数为想保存视频的起止时间，以Unix时间戳的格式传入，这个时间可以通过historyRecord方法获得。

【注意】

如果是转存mp4（或其他格式）,不建议在saveas的时候直接指定format为mp4，那样有些已知的问题，比如转出来的视频播放卡住，快进，无法拖动进度条等等。因此推荐用户指定format为null，先保存成m3u8文件再使用存储SDK的avthumb接口进行转码操作。

# 2.视频转码 [#2视频转码]

视频的转码可以使用存储SDK的avthumb接口来操作。下面是相关文档链接：

avthumb的接口文档：[/faq/dora/av-processing/1699-on-demand-how-saveas-again-the-transcoding-of-video-format-mp4](/faq/dora/av-processing/1699-on-demand-how-saveas-again-the-transcoding-of-video-format-mp4)

Java SDK相关：[/faq/dora/av-processing/1699-on-demand-how-saveas-again-the-transcoding-of-video-format-mp4](/faq/dora/av-processing/1699-on-demand-how-saveas-again-the-transcoding-of-video-format-mp4)


# 如何从视频中只抽离出音频文件？ (/faq/dora/av-processing/1701-how-to-only-smoke-from-the-audio-from-video-files)



最近更新时间: 2021-07-21 15:11:11

在 音视频转码（avthumb）中可以设置`/vn/<VideoNo>`参数。  有关视频转码（avthumb）文档链接：[音视频转码](/faq/dora/av-processing/1701-how-to-only-smoke-from-the-audio-from-video-files)

**参数设置**

| 参数名称                  | 类别 | 说明                      |
| --------------------- | -- | ----------------------- |
| `/vn/&lt;VideoNo&gt;` | V  | 是否去除视频流，0为保留，1为去除。默认值为0 |

**使用方法**

命令可以根据需要自定义，如：

avthumb/vn/1

命令的调用，可以在上传时指定[persistentOps](/products/kodo/development-guidelines/security/1-put-policy#3)参数（即 **预转持久化** ），或者调用[pfop](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)命令（即 **触发持久化** ）。

以 Python Sdk 为例，具体可以看下[音视频转码示例](/faq/dora/av-processing/1701-how-to-only-smoke-from-the-audio-from-video-files#avthumb-samples)。需要在[音视频转码示例](/faq/dora/av-processing/1701-how-to-only-smoke-from-the-audio-from-video-files#avthumb-samples)的基础修改数据处理命令 **fops** ，将其修改为：

fops = avthumb/mp4/vn/1

**注意**

其他语言 Sdk 可在[官方Sdks](/faq/dora/av-processing/1701-how-to-only-smoke-from-the-audio-from-video-files#sdk)下载，可以通过查看 Sdk 使用指南中 **触发持久化** ， **预转持久化** 使用。


# 关于七牛的流媒体队列 (/faq/dora/av-processing/2500-streaming-media-queue-about-seven-cows)



最近更新时间: 2021-07-21 15:11:11

七牛的流媒体队列 （英文简称 pipeline ）

七牛首创云端音视频、流媒体处理服务，依托高性能硬件及私有任务队列机制，保障任务高效完成。

# 共有队列 [#共有队列]

共有队列是所有的客户都在使用的队列, 所以如果任务量比较大需要排队比较久。这个共有队列就是不定状态的 如果需要快速处理需要使用私有队列。

问题1：怎么样查看自己提交的数据处理的情况呢？

答案：每个处理都会返回一个类似于 z0.58b5338645a2653715350b20  z0.开头得的 PersistentId
可以通过 get [请求这个接口查到](/products/dora/processing-mechanism/persist/1-persistent-processing-status-query-prefop) 处理的状态

```
{
    "code": 1,
    "desc": "The fop is waiting for execution",
    "id": "z0.58b5338645a2653715350b20",
    "inputBucket": "echohu",
    "inputKey": "./hh.wmv",
    "items": [
        {
            "cmd": "avthumb/mp4|saveas/dmlkZW86dGVzdDExMC5tcDQ=",
            "code": 1,
            "desc": "The fop is waiting for execution",
            "returnOld": 0
        }
    ],
    "pipeline": "0.default",
    "reqid": ""
}

```

参考：[处理化数据处理查询](/products/dora/processing-mechanism/persist/1-persistent-processing-status-query-prefop)

"pipeline": "0.default"如果是0.default 就是使用默认的共有队列

# 私有队列 [#私有队列]

创建私有队列

在七牛的 portal 平台的主界面,点击 多媒体处理 的“立即添加”。这个就是私有队列 pipeline
![](/docs-assets/faq/dora/av-processing/2500-streaming-media-queue-about-seven-cows/Fl1HWJAUBpOJC_mNI0epwfVIDQLw-b111310ac9d6.webp)

在代码处理时候传入这个得名字即是使用它下面给出php demo的使用私有队列 队列名是abc

```
  <?php
  require_once 'path_to_sdk/vendor/autoload.php';

  use Qiniu\Auth;
  use Qiniu\Storage\UploadManager;

  $accessKey = 'Access_Key';
  $secretKey = 'Secret_Key';
  $auth = new Auth($accessKey, $secretKey);

  $bucket = 'Bucket_Name';

  //转码时使用的队列名称
  $pipeline = 'abc';

  //要进行转码的转码操作
  $fops = "avthumb/mp4/s/640x360/vb/1.25m";

  //可以对转码后的文件进行使用saveas参数自定义命名，当然也可以不指定文件会默认命名并保存在当间
  $savekey = Qiniu\base64_urlSafeEncode('目标Bucket_Name:自定义文件key');
  $fops = $fops.'|saveas/'.$savekey;

  $policy = array(
    'persistentOps' => $fops,
    'persistentPipeline' => $pipeline
  );
  $uptoken = $auth->uploadToken($bucket, null, 3600, $policy);

  //上传文件的本地路径
  $filePath = './php-logo.png';

  $uploadMgr = new UploadManager();

  list($ret, $err) = $uploadMgr->putFile($uptoken, null, $filePath);
  echo "\n====> putFile result: \n";
  if ($err !== null) {
      var_dump($err);
  } else {
      var_dump($ret);
  }

```

还有关于价格私有队列收费价格看这里的多媒体处理  [价格](http://www.qiniu.com/pricing)


# 部分 mp4 在网页播放器兼容问题 (/faq/dora/av-processing/2637-some-customers-mp4-problems-in-distributed-web-page)



最近更新时间: 2021-07-23 18:21:51

浏览器web播放器支持的格式是比较标准的，所以部分的不是标准格式的视频会在 web 端播放不出来

# 解决方案 [#解决方案]

使用代码，调用七牛的接口转为标准的 MP4 。参考：[音视频转码](/products/dora/1-features_introduction)

`fops = 'avthumb/mp4'`  设置为标准的 mp4

python

```
from qiniu import Auth, put_file, etag, urlsafe_base64_encode
import qiniu.config

# access_key，secret_key在个人面板的密钥管理处获得，非个人账号密码
access_key = '...'
secret_key = '...'

# 初始化Auth状态
q = Auth(access_key, secret_key)

# 你要测试的空间， 并且这个key在你空间中存在
bucket_name = '...'
key = '...'

# 是使用的队列名称,不设置使用默认队列。
pipeline = 'your_pipeline'

# 设置转码参数
fops = 'avthumb/mp4'

# 通过添加'|saveas'参数，指定处理后的文件保存的bucket和key，不指定默认保存在当前空间，bucket_saved为目标bucket，bucket_saved为目标key
saveas_key = urlsafe_base64_encode('bucket_saved:bucket_saved')

fops = fops+'|saveas/'+saveas_key

# 在上传策略中指定fobs和pipeline
policy={
  'persistentOps':fops,
  'persistentPipeline':pipeline
 }

token = q.upload_token(bucket_name, key, 3600, policy)

# 视频所在的本地路径
localfile = './python_video.flv'

ret, info = put_file(token, key, localfile)
print(info)
assert ret['key'] == key
assert ret['hash'] == etag(localfile)

```

php

```
  <?php
  require_once 'path_to_sdk/vendor/autoload.php';

  use Qiniu\Auth;
  use Qiniu\Storage\UploadManager;

  $accessKey = 'Access_Key';
  $secretKey = 'Secret_Key';
  $auth = new Auth($accessKey, $secretKey);

  $bucket = 'Bucket_Name';

  //转码时使用的队列名称
  $pipeline = 'abc';

  //要进行转码的转码操作
  $fops = "avthumb/mp4";

  //可以对转码后的文件进行使用saveas参数自定义命名，当然也可以不指定文件会默认命名并保存在当间
  $savekey = Qiniu\base64_urlSafeEncode('目标Bucket_Name:自定义文件key');
  $fops = $fops.'|saveas/'.$savekey;

  $policy = array(
    'persistentOps' => $fops,
    'persistentPipeline' => $pipeline
  );
  $uptoken = $auth->uploadToken($bucket, null, 3600, $policy);

  //上传文件的本地路径
  $filePath = './php-logo.png';

  $uploadMgr = new UploadManager();

  list($ret, $err) = $uploadMgr->putFile($uptoken, null, $filePath);
  echo "\n====> putFile result: \n";
  if ($err !== null) {
      var_dump($err);
  } else {
      var_dump($ret);
  }

```


# avconcat报错mismatched sar of videos的解决方法 (/faq/dora/av-processing/3972-the-solution-to-the-avconcat-error-mismatched-sar-of-videos)



最近更新时间: 2021-07-21 15:11:11

# 问题原因 [#问题原因]

出现该错误的原因是要进行拼接的视频SAR不匹配，即`url?avinfo`信息中的`sample_aspect_ratio`不一致。

# 解决方式 [#解决方式]

通过`avthumb`[接口](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb)中的`aspect`字段转码下，将SAR转为一致即可，其中`aspect`字段控制的是DAR，即`url?avinfo`信息中的`display_aspect_ratio`参数。

如图所示的两个视频进行拼接就会出现上述错误，将视频一通过`avthumb/mp4/aspect/16:9`命令，将`display_aspect_ratio`转为16：9，则`sample_aspect_ratio`为1:1，此时再进行拼接，即可拼接成功。

![](/docs-assets/faq/dora/av-processing/3972-the-solution-to-the-avconcat-error-mismatched-sar-of-videos/FocwQRaXWpj3_5e0ZllwoLUTdHqZ-d0b76597576d.webp)

![](/docs-assets/faq/dora/av-processing/3972-the-solution-to-the-avconcat-error-mismatched-sar-of-videos/FsBINCEKAFUUaHSYPMC_go6oA_39-d1f421cbe61e.webp)

注：SAR \* PAR = DAR

* SAR —— Sample Aspect Ratio
* PAR —— Pixel Aspect Ratio
* DAR —— Display Aspect Ratio


# 提交了音视频转码，为什么长时间处于处理中？ (/faq/dora/av-processing/8320-submit-the-audio-and-video-transcoding-why-long-time-in-processing)



最近更新时间: 2021-11-05 09:52:04

* 如果希望加快转码速度，可以使用[倍速转码](/products/dora/audio-and-video-processing-api/9-avfast)，加速对视频资源进行编码。
* 除了以上方式，也可以通过部署[ufop（自定义数据处理)](/products/dora/processing-mechanism/1-directions-for-use-pfop)，通过提高机器性能来缩短转码时长。


# 音视频转码失败，是什么原因？ (/faq/dora/av-processing/8321-audio-and-video-transcoding-fails-what-reason-be)



最近更新时间: 2021-07-23 18:21:11

* 首先 [获取转码的 persistent ID](/faq/dora/other-dora/3643-how-to-acquire-persistent-id) ，然后通过 [持久化处理状态查询接口](/products/dora/processing-mechanism/persist/1-persistent-processing-status-query-prefop) ，查看简要的报错原因。
* 或者浏览器直接访问 `http://api.qiniu.com/status/get/prefop?id=` 后跟 persistent ID 。
* 如果对处理失败原因有疑问，可以带着 persistent ID ，提交工单咨询。


# 图片文字水印支持字体列表 (/faq/dora/other-dora/11230-image-text-watermarking-support-font-list)



最近更新时间: 2023-09-14 17:32:23

**支持字体列表如下：**

| 文字字体<br />（需经过URL安全的Base64编码） | 中文意思                | 支持语音 | 字体样式<br />（需经过URL安全的Base64编码）                                                               |
| :---------------------------- | :------------------ | :--- | :------------------------------------------------------------------------------------------ |
| WenQuanYi Zen Hei             | 文泉驿正黑               | 中/英文 | medium                                                                                      |
| WenQuanYi Zen Hei Mono        | 文泉驿等宽正黑             | 中/英文 | medium                                                                                      |
| WenQuanYi Micro Hei           | 文泉驿微米黑              | 中/英文 | regular                                                                                     |
| WenQuanYi Micro Hei Mono      | 文泉驿等宽微米黑            | 中/英文 | regular                                                                                     |
| Source Han Sans SC            | 思源黑体                | 中/英文 | normal、heavy、extralight、regular、bold、light、medium                                           |
| Source Han Serif SC           | 思源宋体                | 中/英文 | semibold、bold、extralight、regular、light、medium、heavy                                         |
| FZFangSong-Z02S               | 方正仿宋                | 中/英文 | regular                                                                                     |
| FZHei-B01S                    | 方正黑体                | 中/英  | regular                                                                                     |
| FZKai-Z03S                    | 方正楷体                | 中/英  | regular                                                                                     |
| FZShuSong-Z01S                | 方正书宋                | 中/英  | regular                                                                                     |
| Roboto                        | Roboto              | 英文   | Black、BlackItalic、Bold、Italic、Light、LightItalic、Medium、MediumItalic、Regular、Thin、ThinItalic |
| Marcellus                     | Marcellus           | 英文   | Regular                                                                                     |
| Lato                          | Lato                | 英文   | Black、BlackItalic、Bold、BoldItalic、Italic、Light、LightItalic、Regular、Thin、ThinItalic          |
| Montserrat                    | Montserrat          | 英文   | Black、Bold、ExtraBold、ExtraLight、Light、Medium、Regular、SemiBold、Thin                          |
| Poppins                       | Poppins             | 英文   | Bold、Light、Medium、Regular、SemiBold                                                          |
| Droid Sans Fallback           | Droid Sans Fallback | 中文   | Bold、Light、Medium、Regular、SemiBold                                                          |


# 视频文字水印支持字体列表 (/faq/dora/other-dora/1379-image-and-video-text-watermarking-support-font-list)



最近更新时间: 2023-09-14 17:32:12

**支持字体列表如下：**

| 文字字体<br />（需经过URL安全的Base64编码） | 中文意思                | 支持语音 | 字体样式<br />（需经过URL安全的Base64编码）                                                               |
| :---------------------------- | :------------------ | :--- | :------------------------------------------------------------------------------------------ |
| WenQuanYi Zen Hei             | 文泉驿正黑               | 中/英文 | medium                                                                                      |
| WenQuanYi Zen Hei Mono        | 文泉驿等宽正黑             | 中/英文 | medium                                                                                      |
| WenQuanYi Micro Hei           | 文泉驿微米黑              | 中/英文 | regular                                                                                     |
| WenQuanYi Micro Hei Mono      | 文泉驿等宽微米黑            | 中/英文 | regular                                                                                     |
| Source Han Sans SC            | 思源黑体                | 中/英文 | normal、heavy、extralight、regular、bold、light、medium                                           |
| Source Han Serif SC           | 思源宋体                | 中/英文 | semibold、bold、extralight、regular、light、medium、heavy                                         |
| FZFangSong-Z02S               | 方正仿宋                | 中/英文 | regular                                                                                     |
| FZHei-B01S                    | 方正黑体                | 中/英  | regular                                                                                     |
| FZKai-Z03S                    | 方正楷体                | 中/英  | regular                                                                                     |
| FZShuSong-Z01S                | 方正书宋                | 中/英  | regular                                                                                     |
| Roboto                        | Roboto              | 英文   | Black、BlackItalic、Bold、Italic、Light、LightItalic、Medium、MediumItalic、Regular、Thin、ThinItalic |
| Marcellus                     | Marcellus           | 英文   | Regular                                                                                     |
| Lato                          | Lato                | 英文   | Black、BlackItalic、Bold、BoldItalic、Italic、Light、LightItalic、Regular、Thin、ThinItalic          |
| Montserrat                    | Montserrat          | 英文   | Black、Bold、ExtraBold、ExtraLight、Light、Medium、Regular、SemiBold、Thin                          |
| Poppins                       | Poppins             | 英文   | Bold、Light、Medium、Regular、SemiBold                                                          |
| Droid Sans Fallback           | Droid Sans Fallback | 中文   | Bold、Light、Medium、Regular、SemiBold                                                          |


# ufop、刷新预取查询demo汇总 (/faq/dora/other-dora/1464-ufop-refresh-prefetching-query-demo-summary)



最近更新时间: 2019-01-04 16:29:49

# ufop java 示例 demo [#ufop-java-示例-demo]

* [ufop](https://github.com/liangchao07115/qiniu-java-simple/tree/master/src/com/test)

# fusion 刷新、预取、查询 demo [#fusion-刷新预取查询-demo]

* [刷新、预取、查询](https://github.com/liangchao07115/qiniu-java-simple/tree/master/src/com/qiniu/fusion)

# c#-sdk demo [#c-sdk-demo]

* [c# sdk](/products/kodo/csharp#8)

# node demo [#node-demo]

* [node](https://github.com/qiniu/nodejs-sdk.v6/pull/208/commits/8b05c7955177fedf652c238f4368af3b21ad10de)

# python demo [#python-demo]

* [python](https://github.com/qiniu/python-sdk/tree/master/examples)


# 七牛点播云设置CNAME解析的方法 (/faq/dora/other-dora/1704-seven-cattle-on-demand-cloud-set-cname-analytical-method)



最近更新时间: 2017-08-30 09:55:59

# 快速入门 [#快速入门]

举例说明：dianbo.qiniudemo.com

## 操作步骤： [#操作步骤]

## 1 在域名绑定页面，找到对应的域名，点击复制获取到 CNAME 的记录值 [#1-在域名绑定页面找到对应的域名点击复制获取到-cname-的记录值]

![](/docs-assets/faq/dora/other-dora/1704-seven-cattle-on-demand-cloud-set-cname-analytical-method/FohE2YMy0zeXipPsfTQKd6BbzTtx-88607e2874d8.webp)

## 2 登录域名管理中心，找到域名点击“解析” [#2-登录域名管理中心找到域名点击解析]

注意事项：

域名管理中心在购买域名的平台里。

![](/docs-assets/faq/dora/other-dora/1704-seven-cattle-on-demand-cloud-set-cname-analytical-method/FqkQHhzpDg4QR8JVJde22IIdod0k-18ec75f9985c.webp)

## 3 在记录管理页面，点击“添加纪录” [#3-在记录管理页面点击添加纪录]

![](/docs-assets/faq/dora/other-dora/1704-seven-cattle-on-demand-cloud-set-cname-analytical-method/FgOGLgKWxfpy_94d8GIg1MFyOd60-df03a73d5389.webp)

## 4 按照提示输入内容，点击“确认”保存 [#4-按照提示输入内容点击确认保存]

注意事项：

*

记录类型： CNAME

*

主机记录：dianbo （dianbo.qiniudemo.com 主域名前面部分）

*

记录值：test-idox821.qiniudns.com（步骤1中复制获取到的内容）

*

其它：默认即可

![](/docs-assets/faq/dora/other-dora/1704-seven-cattle-on-demand-cloud-set-cname-analytical-method/FigWo10NS9i2iB8cwCUxbkaIjC5M-09af90c799db.webp)

## 5 检查解析进度 [#5-检查解析进度]

注意事项：

需要linux终端，使用dig命令检查解析内容，下图中为解析完成后的正确结果（解析时间一般是10分钟左右生效，如果没有找到解析内容代表还没有解析成功或解析错误）

![](/docs-assets/faq/dora/other-dora/1704-seven-cattle-on-demand-cloud-set-cname-analytical-method/Fug8P5J0qdbi0KSKAFGMRhZclr21-8795976a6bca.webp)

## 6 设置为默认域名 [#6-设置为默认域名]

![](/docs-assets/faq/dora/other-dora/1704-seven-cattle-on-demand-cloud-set-cname-analytical-method/FkW4nHKl2IvELRMBexM-OR3IFboV-80f9989ebc70.webp)


# persistent ID 的常见问题 (/faq/dora/other-dora/3643-how-to-acquire-persistent-id)



最近更新时间: 2023-09-01 16:05:24

# **什么是 persistent ID？** [#什么是-persistent-id]

七牛给每个 持久化处理 作业，都会分配一个唯一的 ID ，用来记录和查询。

# **如何获取 persistent ID？** [#如何获取-persistent-id]

使用 [持久化处理 API 接口](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 提交请求，可以在返回信息中得到 persistent ID 。

# **任务查询方式** [#任务查询方式]

通过【API创建的任务】，用户可以使用以下3种方式进行查询：

1. 通过任务查询接口，发起查询请求。

2. 登录 proral ，在任务列表中进行查询。

3. 创建任务时，设置回调地址，七牛将会向你设置的 URL 发起 `Content-Type: application/json` 的 POST 请求。请参考[持久化处理结果通知](/products/dora/processing-mechanism/persist/1-persistent-processing-status-query-prefop)。

# **任务查询API** [#任务查询api]

## 接口规格 [#接口规格]

```
<persistentId>
```

| 参数名称            | 必填 | 说明                                      |
| --------------- | -- | --------------------------------------- |
| \<persistentId> | 是  | 上传预处理或持久化处理接口返回的`&lt;persistentId&gt;`。 |

使用 [持久化处理作业查询](/products/dora/processing-mechanism/persist/1-persistent-processing-status-query-prefop) 服务，具体方法是浏览器地址栏输入 [https://api.qiniu.com/status/get/prefop?id=](https://api.qiniu.com/status/get/prefop?id=) 后跟 persistent ID 。

# **控制台查询** [#控制台查询]

登录【智能多媒体控制台】，进入【导航栏->任务】页面，进入 [任务列表](https://portal.qiniu.com/dora/media-gate/task) 页面。

![img](/docs-assets/faq/dora/other-dora/3643-how-to-acquire-persistent-id/WX20201208-154524-f1cba687bdef.webp)

> **查询条件说明：**
>
> * 切换区域
>
>   * 任务资源所属区域：**华东、华北、华南、东南亚、北美**
> * 按时间查询
>
>   * 当前支持查询 **近7天** 的任务
>
>   * 选择队列：任务执行的队列
>
>   * 选择区域：任务资源所属区域
>
>   * 选择任务状态：
>
>     **全部、成功、失败、处理中、已提交、已取消**（当用户删除pipeline时，并且有任务还在等待中）
> * 按任务ID查询
>
>   * 输入任务ID，进行精确匹配查询
>
> **搜索结果说明：**
>
> * 对应查询条件以列表形式展示任务信息：任务ID、资源名称、状态、队列。
> * 点击【加载更多】，展示更多任务。


# 保存处理后的图片 (/faq/dora/other-dora/3751-save-the-processed-image)



最近更新时间: 2017-08-30 09:55:59

## 保存处理后的图片生成url 然后使用get请求即可 [#保存处理后的图片生成url-然后使用get请求即可]

## 公有空间 [#公有空间]

### java [#java]

```
public class imageSaveas {

    public static void main(String args[]) throws Exception{
        String ACCESS_KEY = "FMVCRs2-LvRNi4l7mEZE6ZDvPv-519D1ZCO";
        String SECRET_KEY = "InOXBls8acFn002XsoXKFw1iFJZxcoOvAeY";

        Auth auth = Auth.create(ACCESS_KEY, SECRET_KEY);

        //需要存储的空间名和文件名
        String scope = "picture:test.jpg";

        String urlbase64 = UrlSafeBase64.encodeToString(scope);

        //空间domain, 比如 orf68lb7.bkt.clouddn.com
        String domain = "orf68lb7.bkt.clouddn.com";

        //需要处理的文件名
        String key = "测试";

        //处理操作
        String cmd = "imageView2/2/w/200/h/200";

        String encodedFileKey = URLEncoder.encode(key, "utf-8");

        String DownloadUrl  = domain + "/" + encodedFileKey + "?" + cmd + "|saveas/" + urlbase64;
        Mac mac = javax.crypto.Mac.getInstance("HmacSHA1");
        mac.init(new SecretKeySpec(StringUtils.utf8Bytes(SECRET_KEY),"HmacSHA1"));
        String sign = UrlSafeBase64.encodeToString(mac.doFinal(StringUtils.utf8Bytes(DownloadUrl)));

        String URL = "http://"+DownloadUrl+"/sign/"+ACCESS_KEY+":"+sign;

        System.out.println(auth.privateDownloadUrl(URL, 36000));
    }
}
```

<br />

<br />

### python [#python]

```
def __token( data):
    data = b(data)
    hashed = hmac.new(secret_key, data, sha1)
    return urlsafe_base64_encode(hashed.digest())

access_key = 'oPQDbCnHhXjZtGZk6ysNYDMrcs7a8Puy_e0mcaL_'
secret_key = 'DzQHHAizEpsr3LqiIfjF8-p2cBi406nR44CYasBx'

#需要处理的url
url_op = "oa1azzrgm.bkt.clouddn.com/test.jpg?imageInfo"

#处理后另存的空间文件名
save_bucket = 'test'
save_key = 'ttt.mp4'
savekey = "saveas/"+ entry(save_bucket, save_key)
url = '{0}%7C{1}'.format(url_op,savekey)

#签名
q = Auth(access_key, secret_key)
sign_url = 'http://{0}/sign/{1}:{2}'.format(url, access_key, __token(url))
print(sign_url)
```

<br />

<br />

## 私有空间 [#私有空间]

### java [#java-1]

```
public class imageSaveasForPrivate {
    public static void main(String args[]) throws Exception {
        String ACCESS_KEY = "FMVCRs2-LO1ivRNi7mEZE6ZDvPv-519D12kZCO";
        String SECRET_KEY = "InOXBls8alaPiRc02XsoXKFw1iFJZxcoOvAeY";

        Auth auth = Auth.create(ACCESS_KEY, SECRET_KEY);

        //需要存储的空间名和文件名
        String scope = "qiniu:test.jpg";

        String urlbase64 = UrlSafeBase64.encodeToString(scope);

        //空间domain, 比如 orf68lb7.bkt.clouddn.com
        String domain = "oq2z5wvba.bkt.clouddn.com";

        //需要处理的文件名
        String key = "测试.png";

        //处理操作
        String cmd = "imageView2/2/w/200/h/200";

        String encodedFileKey = URLEncoder.encode(key, "utf-8");

        String signUrl  = domain + "/" + encodedFileKey + "?" + cmd + "|saveas/" + urlbase64;

        Mac mac = Mac.getInstance("HmacSHA1");
        mac.init(new SecretKeySpec(StringUtils.utf8Bytes(SECRET_KEY),"HmacSHA1"));
        String sign = UrlSafeBase64.encodeToString(mac.doFinal(StringUtils.utf8Bytes(signUrl)));

        String finalUrl = "http://" + signUrl + "/sign/" + ACCESS_KEY + ":" + sign;

        String url = auth.privateDownloadUrl(finalUrl, 36000);

        System.out.println(url);
    }

}
```

<br />

<br />

### python [#python-1]

```
def __token( data):
    data = b(data)
    hashed = hmac.new(secret_key, data, sha1)
    return urlsafe_base64_encode(hashed.digest())

access_key = 'oPQDbCnHhXjZtGZk6ysNYDMrcs7a8Puy_e0mcaL_'
secret_key = 'DzQHHAizEpsr3LqiIfjF8-p2cBi406nR44CYasBx'

#需要处理的url
url_op = "oa1azzrgm.bkt.clouddn.com/test.jpg?imageInfo"

#处理后另存的空间文件名
save_bucket = 'test'
save_key = 'ttt.mp4'
savekey = "saveas/"+ entry(save_bucket, save_key)
url = '{0}%7C{1}'.format(url_op,savekey)

#签名
q = Auth(access_key, secret_key)
sign_url = 'http://{0}/sign/{1}:{2}'.format(url, access_key, __token(url))
print(sign_url)

#私有空间签名
private_url = q.private_download_url(sign_url, expires=3600*24*4)
print(private_url)
```


# 如何创建音视频处理私有队列 (/faq/dora/other-dora/3853-how-to-create-audio-and-video-processing-private-queues)



最近更新时间: 2021-07-23 18:21:23

在七牛进行音视频处理，推荐使用私有队列（pipeline）。 创建私有队列方法如下：

# 第一步 [#第一步]

登录[七牛云智能多媒体平台](https://portal.qiniu.com/dora/media-gate/pipeline)，切换到【队列】页面，点击图片红点所示处 “新建队列”

![](/docs-assets/faq/dora/other-dora/3853-how-to-create-audio-and-video-processing-private-queues/WX20210721-142015-944fc1e7e835.webp)

# 第二步 [#第二步]

填写队列名称，点击 "确定创建”
![](/docs-assets/faq/dora/other-dora/3853-how-to-create-audio-and-video-processing-private-queues/WX20210721-142105-3b0c08ebed71.webp)


# 图片处理水印不居中显示处理方法 (/faq/dora/the-image-processing/1377-image-watermarking-is-not-centered-processing-method)



最近更新时间: 2021-07-21 15:14:32

关于图片大水印操作，比如只指定[gravity/South](http://dn-odum9helk.qbox.me/wjw/testpicture?imageView2/2/w/728/q/100%7Cwatermark/1/image/aHR0cDovL29kdW05aGVsay5xbnNzbC5jb20vd2p3L3dhdGVybWFyay5wbmc=/gravity/South/dy/5/dx/0)，理论上来说水印会出现在最下方中间，但是其实不是，是会有一些像素偏移的，这个时候可以加上[/dx/0](http://dn-odum9helk.qbox.me/wjw/testpicture?imageView2/2/w/728/q/100%7Cwatermark/1/image/aHR0cDovL29kdW05aGVsay5xbnNzbC5jb20vd2p3L3dhdGVybWFyay5wbmc=/gravity/South/dy/5/dx/0)参数表示水印处于水平方向最中间，如果加上/dy/0表示在垂直方向中间位置,以下为对比的情况:

不加/dx/0

[http://dn-odum9helk.qbox.me/wjw/testpicture?imageView2/2/w/728/q/100|watermark/1/image/aHR0cDovL29kdW05aGVsay5xbnNzbC5jb20vd2p3L3dhdGVybWFyay5wbmc=/gravity/South/dy/5](http://dn-odum9helk.qbox.me/wjw/testpicture?imageView2/2/w/728/q/100%7Cwatermark/1/image/aHR0cDovL29kdW05aGVsay5xbnNzbC5jb20vd2p3L3dhdGVybWFyay5wbmc=/gravity/South/dy/5)

加/dx/0

[http://dn-odum9helk.qbox.me/wjw/testpicture?imageView2/2/w/728/q/100|watermark/1/image/aHR0cDovL29kdW05aGVsay5xbnNzbC5jb20vd2p3L3dhdGVybWFyay5wbmc=/gravity/South/dy/5/dx/0](http://dn-odum9helk.qbox.me/wjw/testpicture?imageView2/2/w/728/q/100%7Cwatermark/1/image/aHR0cDovL29kdW05aGVsay5xbnNzbC5jb20vd2p3L3dhdGVybWFyay5wbmc=/gravity/South/dy/5/dx/0)


# imageMogr2对gif转成webp格式并缩放报错解决方法 (/faq/dora/the-image-processing/1452-imagemogr2-to-gif-into-the-webp-and-zoom-error-solution)



最近更新时间: 2021-07-21 15:14:32

#### 报错：error: "The original image abnormal" [#报错error-the-original-image-abnormal]

> imageMogr2将gif转为web并且缩放时，使用imageMogr2/format/webp|imageMogr2/thumbnail/100x报错

**报错链接** ：[https://dn-odum9helk.qbox.me/test.gif?imageMogr2/format/webp|imageMogr2/thumbnail/100x](https://dn-odum9helk.qbox.me/test.gif?imageMogr2/format/webp%7CimageMogr2/thumbnail/100x)

![blob.png](/docs-assets/faq/dora/the-image-processing/1452-imagemogr2-to-gif-into-the-webp-and-zoom-error-solution/Fl5eNfaKeFhQ2Wvh6jnRWfeAE-Sn-877c09f7de64.webp)

**报错原因** ：imageMogr2参考工具[imageMagick](http://www.imagemagick.com.cn/ "imagemagick")，由于 imageMagick 对 animated webp 进行缩放处理不支持，导致在imageMogr2将.gif转成.webp格式的文件时缩放报错

**解决方法** ：2种。

1）使用管道符，使用imageMogr2缩放.gif图片后再转成.webp格式文件

如：[https://dn-odum9helk.qbox.me/test.gif?imageMogr2/thumbnail/100x|imageMogr2/format/webp](https://dn-odum9helk.qbox.me/test.gif?imageMogr2/thumbnail/100x%7CimageMogr2/format/webp)

![blob.png](/docs-assets/faq/dora/the-image-processing/1452-imagemogr2-to-gif-into-the-webp-and-zoom-error-solution/FspfjQHf8LQW0XPCyHD77KEB_7UA-675a6f606ce0.webp)

2）不使用管道符，在缩放.gif图片时直接指定目标格式为.webp，

如：[https://dn-odum9helk.qbox.me/test.gif?imageMogr2/thumbnail/100x/format/webp](https://dn-odum9helk.qbox.me/test.gif?imageMogr2/thumbnail/100x/format/webp)

![blob.png](/docs-assets/faq/dora/the-image-processing/1452-imagemogr2-to-gif-into-the-webp-and-zoom-error-solution/FnTR-neYs6nvRC6qbwIfU_uq7on0-7e6a7092ad37.webp)

**参考** ：

[高级图片处理imageMogr2](/faq/dora/the-image-processing/1452-imagemogr2-to-gif-into-the-webp-and-zoom-error-solution)


# 关于图片 EXIF 信息中旋转参数 Orientation 的理解 (/faq/dora/the-image-processing/1560-information-about-photo-exif-rotation-parameters-in-the-understanding-of-orientation)



最近更新时间: 2021-07-21 15:14:32

EXIF（Exchangeable Image File）是 “可交换图像文件” 的缩写，当中包含了专门为数码相机的照片而定制的元数据，可以记录数码照片的拍摄参数、缩略图及其他属性信息，简单来说，Exif 信息是镶嵌在 JPEG/TIFF 图像文件格式内的一组拍摄参数，需要注意的是 EXIF 信息是不支持 png,webp 等图片格式的。 对于七牛，可以在图片后面加? exif 参数来获取图片的 exif 信息。

对于 Orientation 参数，简单的说是记录图片拍摄的相机的旋转信息，浏览器 (需要浏览器支持) 可以根据这个参数中的 val 信息自动旋转图片到正确的方向。

**eg：**

* 在浏览器中输入以下图片链接，由于浏览器自动旋转了，我们可以看到一个显示正常的图片：

[http://dn-odum9helk.qbox.me/exif.png](http://dn-odum9helk.qbox.me/exif.png)

* 其实这张图片拍摄的时候相机是有旋转的，我们可以去掉图片的 exif 信息显示如下：

[http://dn-odum9helk.qbox.me/exif.png?imageMogr2/strip](http://dn-odum9helk.qbox.me/exif.png?imageMogr2/strip)

*

可以查询到图片的 exif 信息如下：

[http://dn-odum9helk.qbox.me/exif.png?exif](http://dn-odum9helk.qbox.me/exif.png?exif)

\{"ColorSpace":\{"val":"sRGB","type":3},"ExifVersion":\{"val":"Exif Version 2.1","type":7},"FlashPixVersion":\{"val":"FlashPix Version 1.0","type":7},"Orientation":\{"val":"Right-top","type":3},"PixelXDimension":\{"val":"3264","type":4},"PixelYDimension":\{"val":"2448","type":4},"ResolutionUnit":\{"val":"Inch","type":3},"XResolution":\{"val":"72","type":5},"YResolution":\{"val":"72","type":5}}

由以上我们可以得到图片拍摄时的 val 信息得到图片拍摄时相机的旋转信息是 Right-top 信息，我们可以由以下文档得到相机拍摄时应该是在逆时针选择了 90 度的基础上拍摄的：
[http://sylvana.net/jpegcrop/exif\_orientation.html](http://sylvana.net/jpegcrop/exif_orientation.html)
[http://www.impulseadventure.com/photo/exif-orientation.html](http://www.impulseadventure.com/photo/exif-orientation.html)

![111](/docs-assets/faq/dora/the-image-processing/1560-information-about-photo-exif-rotation-parameters-in-the-understanding-of-orientation/71a7c382de4df5315df4c71614f9fdcf-8326b41df01e.webp)

![222](/docs-assets/faq/dora/the-image-processing/1560-information-about-photo-exif-rotation-parameters-in-the-understanding-of-orientation/8942949faa9b806a94e86406472323fc-4a2cb594d8ab.webp)

需要注意的是，七牛显示的 exif 信息 Orientation":\{"val":"Right-top","type":3}，其中 type 信息是可以忽略，以 value 信息为准


# 如何知道缩略图是否已经成功生成 (/faq/dora/the-image-processing/1570-how-to-know-whether-the-thumbnail-has-been-successfully-generated)



最近更新时间: 2021-07-21 15:14:32

> 在上传图片 API 中使用预处理指令生成缩略图之后，如何知道缩略图是否已经成功生成？

可以通过持久化处理返回的persistenId查询，可以看到处理后的key值，通过拼接到下述链接获取
[http://api.qiniu.com/status/get/prefop?id=](http://api.qiniu.com/status/get/prefop?id=)
具体文档参考
[/faq/dora/the-image-processing/1570-how-to-know-whether-the-thumbnail-has-been-successfully-generated](/faq/dora/the-image-processing/1570-how-to-know-whether-the-thumbnail-has-been-successfully-generated)

但是不建议大家使用pfop生成缩略图，因为缩略图生成过程通常比较快，而且缩略图有缓存机制（但不是存到你的存储空间），用户下次访问的时候，会直接访问上次已经生成好的缩略图。因此可以直接在线生成缩略图即可


# 图片缩放后size比原图大 (/faq/dora/the-image-processing/1625-sizelarge)



最近更新时间: 2022-05-23 14:25:57

用户调用我们的imageView2或者imagemogr2接口实现图片缩放但是设置了图片质量参数 `/quality/`，发现图片的size比压缩之前大。

* 原图（63 KB）

  ```
  http://7xt44n.com2.z0.glb.qiniucdn.com/%E5%8E%9F%E5%9B%BE.jpg
  ```

* 处理后（ 87 KB）

  ```
  http://7xkt2b.com1.z0.glb.clouddn.com/原图.jpg?imageView2/2/w/308/h/308/q/100
  ```

  ​

## **问题分析** [#问题分析]

影响图片的因素如下:

1. 图片尺寸（像素）：同样的一张图，尺寸做得越大，图片就越大，打开就越慢； 注：尺寸和像素，都是表达图片长和宽的单位。

2. 图片的色彩丰富程度：色彩越丰富，颜色越多样，在同样尺寸大小时，图片越大；

3. 图片的清晰度：高清，高饱和度的图片，在同样尺寸大小时，图片越大；

4. 图片的格式：由于压缩比不同，图片大小与图片格式.jpg .png .webp等也有关系

其中，图片的色彩丰富程度和图片的清晰度和图片的质量因素相关。

**图片分辨率对比：**

* 原图分辨率：

  \{"format":"jpeg","width":580,"height":580,"colorModel":"ycbcr"}

* 压缩图分辨率：

  \{"format":"jpeg","width":308,"height":308,"colorModel":"ycbcr"}

**图片质量因素对比**

可以安装ImageMagick查看图片大小色度等信息的命令

* 原图的质量因素为90：

  C:\Demo>identify -verbose [http://7xkt2b.com1.z0.glb.clouddn.com/原图.jpg](http://7xkt2b.com1.z0.glb.clouddn.com/原图.jpg) | grep Quality
  Quality: 90

* 处理后图片质量因素为100：

  C:\Demo>identify -verbose [http://7xkt2b.com1.z0.glb.clouddn.com/原图.jpg?imageView2/2/w/308/h/308/q/100](http://7xkt2b.com1.z0.glb.clouddn.com/原图.jpg?imageView2/2/w/308/h/308/q/100) | grep Quality
  Quality: 100

**很明显，用户增加图片的质量因素比缩小图片分辨率影响图片的size要大，关于图片质量可以参考如下：**

```
保存为jpg格式为有损压缩，通俗来讲，即通过一定算法减少像素携带色彩数据的总量（注意，不是减少像素点数量）来达到压缩图片大小的效果。

比方10x10像素的图片，如果每个像素携带了1种颜色数据，则最大包含了100种不同的颜色。图片无损存储时，数据是这样记录的：x排+X列像素+颜色信息/组+下一组，共100种。当使用jpg压缩时，如果压缩比选8，通过其标准算法选取其中约20%与相邻像素数据一致，这20个像素数据只需要一个同前或同后或同上或同下的一个标记，从而减少了数据记录的长度，再读取图片时这些像素点原本的颜色数据依据算法被周围某个像素数据覆盖或差值替换了，这样就实现了压缩的效果。（以上描述仅为打比方来说明原理）。rar类压缩工具的基本原理也可以这么理解，rar是把同化数据根据算法进行归纳，并不是减少而已。所以对jpg类已经有损压缩过的图片，经过专门针对图片的优化算法，同化数据很少了，再用rar，基本没什么效果。

图像分辨率的减少，等于直接减少了像素的数量，当然就减少了数据的数量。

通过原理来看，由于涉及到像素大小，携带颜色信息量多少，压缩比等等影响的因素很多，很难说到底哪个损失大。需要具体图片具体处理。例如纯色图片，都是一个颜色，因为颜色信息一致，都是一样的，修改像素为1x1，100x100都一样，当然用1x1就可以了。比jpg效果好太多。

一般来说，日常的照片，色彩越丰富，直接减少像素对图片质量的损失比压缩成jpg要大，越简单，损失越小。另外，使用ps压缩还有一个很实用得技巧，在压缩图片时，直接修改像素大小命令尽量不用，而是通过图片变形缩小，然后裁切画布来减少像素，每个像素可保存的颜色信息远比前者要多。(可以找一张照片，直接改小像素，再改回，反复几次，然后用第二种方式反复几次，结 果第一种可能三五次图片就完全模糊了，后者虽然也模糊但效果好的多。然后再用jpg保存时，压缩比越大，获得的压缩率越低，所以一般 为8，几乎不影响，尽量不要低于6。这样尽可能保存更多的颜色信息也实现了对图片的压缩。

```


# 图片流量优化压缩策略 (/faq/dora/the-image-processing/1627-flow-optimization-compression-of-images)



最近更新时间: 2021-07-23 18:20:21

**我们通常都希望使用七牛提供的服务对自己的图片进行压缩，这样可以在加载图片的时候减少下载流量，下面介绍一些常见的对图片进行压缩的方法:**

可以使用我们的图片处理接口：
[/faq/dora/the-image-processing/1627-flow-optimization-compression-of-images](/faq/dora/the-image-processing/1627-flow-optimization-compression-of-images)
[/faq/dora/the-image-processing/1627-flow-optimization-compression-of-images](/faq/dora/the-image-processing/1627-flow-optimization-compression-of-images)

本例中用到的测试图片是：
[http://7xkr3o.com1.z0.glb.clouddn.com/testdemo.jpg](http://7xt44n.com2.z0.glb.qiniucdn.com/testdemo.jpg)
大小：1.7 MB 分辨率：width: 790,height: 2682

**1.使用我们的 imageView2 或者 imageMogr2 接口改变图片的分辨率：**

[http://7xkr3o.com1.z0.glb.clouddn.com/testdemo.jpg?imageMogr2/thumbnail/500x](http://7xt44n.com2.z0.glb.qiniucdn.com/testdemo.jpg?imageMogr2/thumbnail/500x)
大小：168 KB 分辨率: width: 500,height: 1697

**2.如果视频有 exif 信息的话用 strip 去除视频元信息图片 size 会降低不少：**
可以查看图片的元信息：
[http://7xkr3o.com1.z0.glb.clouddn.com/testdemo.jpg?exif](http://7xkr3o.com1.z0.glb.clouddn.com/testdemo.jpg?exif)
[http://7xkr3o.com1.z0.glb.clouddn.com/testdemo.jpg?imageMogr2/strip](http://7xt44n.com2.z0.glb.qiniucdn.com/testdemo.jpg?imageMogr2/strip)
大小：360 KB 分辨率：width: 790,height: 2682

**3.如果是 jpg 图片格式的话是可以通过降低图片的 quality 来改变图片的大小:**

[http://7xkr3o.com1.z0.glb.clouddn.com/testdemo.jpg?imageMogr2/quality/50](http://7xt44n.com2.z0.glb.qiniucdn.com/testdemo.jpg?imageMogr2/quality/50)
大小：233 KB 分辨率：width: 790,height: 2682

**4.可以通过转换图片的格式来达到改变图片的大小：**

bmp 格式比 png 要大得多，而 png 可能比 jpg 又大得多，而 jpg 又可能比 google 最新推出的 webp 格式大得多
可以参考：
[http://blog.csdn.net/guoer9973/article/details/44345451](http://blog.csdn.net/guoer9973/article/details/44345451)

**5.以上几种方式集成在一起效果会更好：**

[http://7xkr3o.com1.z0.glb.clouddn.com/testdemo.jpg?imageMogr2/thumbnail/500x/strip/quality/50/format/webp](http://7xt44n.com2.z0.glb.qiniucdn.com/testdemo.jpg?imageMogr2/thumbnail/500x/strip/quality/50/format/webp)
大小：69 KB 分辨率：width: 790,height: 2682


# 新版本Chrome浏览器不支持渐进显示问题 (/faq/dora/the-image-processing/1675-a-new-version-of-the-chrome-browser-does-not-support-incremental-display-problems)



最近更新时间: 2021-07-21 15:14:32

为提高弱网条件下web端用户访问图片的体验，七牛提供了渐进显示图片的功能，来达到网速慢时，图片可以从模糊到清晰显示的效果。

渐进显示功能支持jpg格式的图片，显示方法是在图片url后拼接  `?imageView2/<mode>/interlace/1` 字段，其中`<mode>`值可取0-5。

渐进显示图片功能是通过修改rgb的排序，达到在web端显示的效果渐进。这一效果需要客户端支持。

主流浏览器如：IE，Safari，Mozilla Firefox 均支持这一功能。

Chrome浏览器稳定版51.0.2704.106及以下的版本也支持渐进显示，但2016年7月21日发布的Chrome稳定版52.02743.82更改了图片加载方式，自此，Chrome浏览器52.02743.82及以上的版本不再支持渐进显示的功能。


# 图片瘦身无效 (/faq/dora/the-image-processing/4077-image-thin-body-is-invalid)



最近更新时间: 2021-07-23 18:20:34

# 问题描述 [#问题描述]

开启图片瘦身策略或者在图片资源 url 后添加`imageslim`并未发现图片有瘦身的效果

# 问题原因 [#问题原因]

可以参考如下几种原因排查问题

## 原因一 [#原因一]

查看自定义加速域名是否开启了忽略 url 参数？如果开启了，请关闭忽略 url 参数以及刷新文件后在查看访问的效果。

![](/docs-assets/faq/dora/the-image-processing/4077-image-thin-body-is-invalid/FpbzlU251Xn9GkAqF3fs0m39qB3D-fdafa6d202ae.webp)

## 原因二 [#原因二]

如果你是开启了图片瘦身策略，只能对文件名带有显著.jpg，.png 的后缀的文件有瘦身的效果。

例如：
[https://url/b](https://url/b)  这个图片瘦身是无效的，
[https://url/b.jpg](https://url/b.jpg) 这个是图片瘦身有效的。

## 原因三 [#原因三]

这个资源本身不是图片格式，无法进行图片瘦身。您可以通过在文件名后添加`imageInfo`查看图片的元信息，如果不是图片格式，会提醒`"error": "unsupported format"`。如果是图片格式，则会返回正常的图片元信息。例如：[https://url/b.jpg?imageInfo](https://url/b.jpg?imageInfo)

## 原因四 [#原因四]

图片资源体积过大，导致图片处理超时，则返回原图。
返回原图时，可以打开浏览器的开发者模式，查看响应头，带有 response header「X-Slim-Origin」有2种取值："0": 表征内部处理正常，"1": 表征内部处理异常，返回原图

## 原因五 [#原因五]

图片资源已损坏，这种情况一般是对象存储空间中的其他资源的图片瘦身正常，只有单独的一张或者几张图片瘦身无效。建议你更换未损坏的图片资源。

## 原因六 [#原因六]

私有bucket 不支持 CDN中间源的图片瘦身处理。


# 图片处理报错"invalid text color"是什么原因？ (/faq/dora/the-image-processing/8318-image-processing-error-invalid-text-color-what-reason-be)



最近更新时间: 2021-07-23 18:20:49

**问题分析**：文字水印颜色编码不正确。

**处理方案**：水印文字颜色，RGB格式，可以是颜色名称（例如 red）或十六进制（例如 #FF0000），参考RGB颜色编码表，默认为黑色。经过URL安全的Base64编码。


# 使用图片水印 watermark/1 没有打上水印 (/faq/dora/the-image-processing/8319-using-image-watermark-watermark-watermark-1-no)



最近更新时间: 2021-07-23 18:20:56

**问题分析**：我们默认偏移为 10，超过偏移 watermark/1 就会返回原图

```
http://oepw6i5pr.qnssl.com/10221446?watermark/1/image/aHR0cDovL29lcHc2aTVwci5xbnNzbC5jb20vMTAyMjE0NDc=
```

* 原图

  "width": 4654,"height": 2362

* 水印图
  "width": 2327,"height": 2362

**处理方案**：重新设置dx、dy偏移量，如下：

```
http://oepw6i5pr.qnssl.com/10221446?watermark/1/image/aHR0cDovL29lcHc2aTVwci5xbnNzbC5jb20vMTAyMjE0NDc=/dx/0/dy/0
```


# 批量下载 (/faq/kodo/download-problem/12955-kodo-batch-download)



最近更新时间: 2025-04-10 15:17:00

# 关于下载 [#关于下载]

目前存储控制台不支持下载大量文件或者整个空间文件。

## 七牛提供如下解决方案： [#七牛提供如下解决方案]

* 调用各个语言SDK或者API获取文件列表，然后通过各个语言的HTTP client 发起get 请求，每个文件都有对应的URL，基于URL进行下载。
* 使用七牛提供的官方工具 [qshell](/products/kodo/0-qshell) 或者 [kodo-browser](/products/kodo/1-kodo-browser) 进行下载

## 批量下载工具 [#批量下载工具]

快速上手的工具推荐下面两个

* [图形界面化工具](/products/kodo/1-kodo-browser)，适合少量文件下载，文件量过多不建议使用,勾选想要下载的文件/目录后点击【下载】即可。

* [命令行工具](/products/kodo/0-qshell)，利用qshell的qdownload或者qdownload2命令批量上传，优先推荐使用qdownload2下载,具体参数说明参考[**qdownload2说明文档**](https://github.com/qiniu/qshell/blob/master/docs/qdownload2.md)。
  `使用qdownload2前，必须先登录账号`，使用qshell account 进行登录，如果已经登陆过，那么无需重复登录。ak sk 空间名称如果不了解是什么，可以阅读[常见的关键参数](/faq/kodo/7450-the-third-party-plug-in-key-parameters)

```bash
  qshell account 您的ak 您的sk 空间名称
  qshell qdownload2 --dest-dir=本地文件夹相对路径或者绝对路径 --bucket=空间名称
```

> **注意**
> 如果需要批量下载公开空间的资源，使用qshell 的 qdownload 或者 qdownload2 命令时，如果指定使用CDN域名下载时，建议将 public 参数置为true，下载时击中CDN缓存时产生CDN流量费用，未击中CDN缓存回源下载资源时会产生额外的CDN回源流量费用，不指定public 为ture , 有可能导致CDN标准回源流量费用增长

### 使用经验 [#使用经验]

* 没有域名，或者域名没有备案无法访问，但是需要下载文件到本地。这种情况下，直接用外链是无法下载的，只能使用S3域名的方式进行，如果对SDK不太熟悉，那么只能使用 `kodo-browser` 下载

* 由于qshell是一个脚本命令行工具，所以需要在cmd或者终端中运行，mac与linux系统会经常使用到终端，下载合适版本到本地解压，直接chmod +x qshell 即可执行命令行。
  `但是如果您需要使用windows操作系统的话，可能您对cmd不是那么熟悉，强列推荐参考这里`
  [**windows环境下安装qshell教程**](/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial#2)


# 断点续传下载功能说明 (/faq/kodo/download-problem/1568-breakpoint-continuingly-download-function)



最近更新时间: 2017-09-19 17:18:19

### 1. 接口说明 [#1-接口说明]

七牛云断点续传下载功能，其实是通过对标准的`HTTP`头部`Range`字段设置来实现的。具体设置方式请参考以下文档：

[下载过程说明](/products/kodo/development-guidelines/download-process#download-mechanism)

### 2. Demo演示 [#2-demo演示]

liuhanlindemac:Downloads yishiyaonie$ curl -I -H "Range:bytes=1024-2048" [http://liuhanlin-work.qiniudn.com/ceshimp4](http://liuhanlin-work.qiniudn.com/ceshimp4)
HTTP/1.1 206 Partial Content
Date: Mon, 03 Aug 2015 03:29:49 GMT
Server: nginx/1.4.4
Content-Type: video/mp4
Content-Length: 1025
Accept-Ranges: bytes
Access-Control-Allow-Origin: \*
Access-Control-Max-Age: 2592000
Cache-Control: public, max-age=31536000
Content-Disposition: inline; filename="ceshimp4"
Content-Range: bytes 1024-2048/36650496
Content-Transfer-Encoding: binary
ETag: "lrMxbjcfPyC7F1siA6tF78B1IMAq"
Last-Modified: Thu, 04 Jun 2015 06:37:13 GMT
X-Log: mc.g;IO:1
X-Reqid: QwIAAMDQ\_OYl1vYT
X-Qiniu-Zone: 0
X-Via: 1.1 yangzhou150:8080 (Cdn Cache Server V2.0), 1.1 lsh200:10 (Cdn Cache Server V2.0)
Connection: keep-alive

看一看下 “HTTP/1.1 206 Partial Content” 这个字段和 “Content-Length: 1025”。


# 为何没有“复制外链”的选项 (/faq/kodo/download-problem/5052-why-not-outside-chain-copy-option)



最近更新时间: 2019-01-07 17:14:43

# 问题描述 [#问题描述]

没有复制外链选项的情况，如下图所示：

![pic1](/docs-assets/faq/kodo/download-problem/5052-why-not-outside-chain-copy-option/Fn76ShJZKCamQZv8h4crSI-UrP8Q-1271f4e7fe96.webp)

# 原因分析 [#原因分析]

## 第一种情况： [#第一种情况]

![pic2](/docs-assets/faq/kodo/download-problem/5052-why-not-outside-chain-copy-option/FlBVsPVds-QkqV_lPYMnNTxPP6j8-17a7040b3bb7.webp)
当空间为\*\*`私有空间`\*\*的时候，下载链接是需要加上临时的 [下载凭证](/products/kodo/development-guidelines/security/0-download-token) 进行下载，所以不提供复制外链的选项，需要自行生成，形式如下：

```
[GET] http://<domain>/<key>?e=<deadline>&token=<downloadToken>
```

## 第二种情况： [#第二种情况]

![pic3](/docs-assets/faq/kodo/download-problem/5052-why-not-outside-chain-copy-option/FnliJ7JLWxqCMnySsNhpfoJAQNna-0b8854c6c921.webp)
当空间设置中开启了 [**`原图保护`**](/faq/kodo/basic-use-of/1359-what-is-the-original-protection) 的时候，也不会提供复制外链的选项


# 存储常见问题FAQ答疑 (/faq/kodo/basic-use-of/12957-kodo-nomarl-faq)



最近更新时间: 2026-08-21 10:24:25

# 简介 [#简介]

 如果您正在使用 存储 产品，本文列出了部分您可能需要了解的问题列表。
<font color="#4671D5"><a href="#Q1">Q1：存储赠送的 50GB 资源包到期后可以续费吗？</a></font>
<font color="#4671D5"><a href="#Q2">Q2：海外有存储资源包售卖吗？</a></font>
<font color="#4671D5"><a href="#Q3">Q3：我买了500GB资源包，为什么只抵扣了400多GB的流量？</a></font>
<font color="#4671D5"><a href="#Q4">Q4：【标准存储空间国内通用计费项】用完会自动用【标准存储空间国内通用计费项(v2)】资源包吗？</a></font>
<font color="#4671D5"><a href="#Q5">Q5：存储有文件版本控制的功能吗，类似于git那种文件版本管理？</a></font>
<font color="#4671D5"><a href="#Q6">Q6：已删除的文件能恢复吗？</a></font>
<font color="#4671D5"><a href="#Q7">Q7：可以获取文件最后访问时间吗？？</a></font>
<font color="#4671D5"><a href="#Q8">Q8：没有域名，测试域名回收了，域名没有备案，还有办法下载空间资源吗？</a></font>
<font color="#4671D5"><a href="#Q9">Q9：访问出现referer forbidden？</a></font>
<font color="#4671D5"><a href="#Q10">Q10：怎么删除空间？</a></font>
<font color="#4671D5"><a href="#Q11">Q11：可以给空间不同的文件设置不同的权限吗？只想让部分文件是私有访问的。</a></font>
<font color="#4671D5"><a href="#Q12">Q12：访问空间的访问记录是否可以查询</a></font>
<font color="#4671D5"><a href="#Q13">Q13：有什么办法可以快速扫描全盘，搜索包含指定内容的文件有哪些?</a></font>
<font color="#4671D5"><a href="#Q14">Q14：CDN回源流量资源包在哪里购买?</a></font>
<font color="#4671D5"><a href="#Q15">Q15：如何根据 文件后缀或文件类型 查询文件? 比如 &#x2A;.js，*.xml 后缀的文件 </a></font>
<font color="#4671D5"><a href="#Q16">Q16: 为什么上传的视频无法在七牛控制台预览和下载？</a></font>
<font color="#4671D5"><a href="#Q17">Q17: 将文件转换为 深度归档存储 类型后，为什么还能访问？</a></font>
<font color="#4671D5"><a href="#Q18">Q18: 上传失败，报579？</a></font>
<font color="#4671D5"><a href="#Q19">Q19: 对象存储空间是否有大小限制？</a></font>
<font color="#4671D5"><a href="#Q20">Q20: 创建空间提示空间名称已被占用，如何处理？</a></font>
<font color="#4671D5"><a href="#Q21">Q21: 空间数量是否有限制？</a></font>
<font color="#4671D5"><a href="#Q22">Q22: 如何查询文件上传日志？</a></font>
<font color="#4671D5"><a href="#Q23">Q23: 空间为什么存在空文件？</a></font>
<font color="#4671D5"><a href="#Q24">Q24: 空间文件被删除，如何查询删除记录？</a></font>
<font color="#4671D5"><a href="#Q25">Q25: 为什么使用空间自带s3域名或已绑定域名无法访问？</a></font>
<font color="#4671D5"><a href="#Q26">Q26: S3域名上传报跨域错误，如何处理？</a></font>
<font color="#4671D5"><a href="#Q27">Q27: 如何对存储空间视频进行转码处理？</a></font>
<font color="#4671D5"><a href="#Q28">Q28: 已备案域名接入对象存储空间，需要做备案变更或接入操作吗？</a></font>
<font color="#4671D5"><a href="#Q29">Q29: 文件存储类型转换会影响文件访问吗？</a></font>
<font color="#4671D5"><a href="#Q30">Q30: 批量提交了大量转码任务，如何取消未执行的任务？</a></font>
<font color="#4671D5"><a href="#Q31">Q31: 退订服务器是否会影响对象存储使用？</a></font>
<font color="#4671D5"><a href="#Q32">Q32: 对象存储如何开通使用？</a></font>
<font color="#4671D5"><a href="#Q33">Q33: 对象存储怎么上传文件到指定目录？</a></font>
<font color="#4671D5"><a href="#Q34">Q34: 存储空间绑定的自定义源站域名修改配置后，多久生效？</a></font>
<font color="#4671D5"><a href="#Q35">Q35: SDK支持根据文件类型或存储方式列举文件吗？</a></font>
<font color="#4671D5"><a href="#Q36">Q36: 存储空间控制台的域名管理按钮灰色无法点击，是什么原因？</a></font>
<font color="#4671D5"><a href="#Q37">Q37: 对象存储提供永久使用的域名吗？</a></font>
<font color="#4671D5"><a href="#Q38">Q38: 对象存储自定义源站域名配置HTTPS证书失败，报406错误，怎么处理？</a></font>
<font color="#4671D5"><a href="#Q39">Q39: 对象存储可以绑定多个域名和证书吗？</a></font>
<font color="#4671D5"><a href="#Q40">Q40: 对象存储文件如何禁用或启用？</a></font>

 
 如果本文仍然无法解决您的问题，您也可以通过 &#x2A;*[工单系统](https://support.qiniu.com/tickets/new)** 将您的问题反馈给我们。

<div id="Q1" />

| Q1: 存储赠送的 50GB 资源包到期后可以续费吗？                                                                               |
| --------------------------------------------------------------------------------------------------------- |
| 资源包到期后，无需续费，直接在[云商城](https://qmall.qiniu.com/template/MTEy?spec_combo=MzA0Ng\&ref=index)重新购买标准存储中国大陆通用资源包 |

<br />

<div id="Q2" />

| Q2: 海外有存储资源包售卖吗？           |
| -------------------------- |
| 存储海外目前没有资源包售卖，只有国内存储有资源包兜售 |

<br />

<div id="Q3" />

| Q3: 我买了500GB资源包，为什么只抵扣了400多GB的流量？                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------------- |
| 存储通用资源包存在抵扣系数，如果您的存储空间是华东存储空间，那么华东存储空间的抵扣系数是1.2 , 500GB的资源包只能抵扣华东存储空间 416GB 左右的容量计费                                                |
| `标准存储空间国内通用资源包，支持抵扣标准存储-华东-浙江、标准存储-华北-河北、标准存储-华南-广东、标准存储-华东-浙江2的存储容量，抵扣系数为 1.2:1.2:1:1。如实际使用标准存储-华东的存储容量 100 GB，相当于抵扣本资源包 120 GB。` |

<br />

<div id="Q4" />

| Q4: 【标准存储空间国内通用计费项】用完会自动用【标准存储空间国内通用计费项(v2)】资源包吗？ |
| ------------------------------------------------- |
| 是的，会自动生效抵扣                                        |

<br />

<div id="Q5" />

| Q5: 存储有文件版本控制的功能吗，类似于git那种文件版本管理？ |
| --------------------------------- |
| 存储是不支持文件版本管理的                     |

<br />

<div id="Q6" />

| Q6: 已删除的文件能恢复吗？ |
| --------------- |
| 已删除的文件是不能恢复的    |

<br />

<div id="Q7" />

| Q7: 可以获取文件最后访问时间吗？                                      |
| ------------------------------------------------------- |
| 文件不支持获取最后访问时间，只有智能分层类型的文件才可以通过list功能获取最后访问时间，其他类型存储都不支持 |

<br />

<div id="Q8" />

| Q8: 没有域名，测试域名回收了，域名没有备案，还有办法下载空间资源吗                                                            |
| ---------------------------------------------------------------------------------------------- |
| 没有域名，默认无法直接通过外链访问下载空间资源，如果需要将资源下载到本地，只能使用[kodo-browser](/products/kodo/1-kodo-browser)将文件下载到本地 |

<br />

<div id="Q9" />

| Q9: 访问出现referer forbidden                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 出现referer forbidden是由于在空间设置里面设置了对应的referer防盗链，需要检查下HTTP请求是否有携带正确的referer , 或者将空间设置中的referer防盗链关闭, <br /> `注意：是关闭存储空间，空间设置中的referer防盗链，不是CDN配置的referer防盗链` |

<br />

<div id="Q10" />

| Q10: 怎么删除空间                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------- |
| 空间删除必须是在文件全部删除的情况下，才可以在控制台 -- 空间设置中删除空间，删除文件可以参考[批量删除](/faq/kodo/basic-use-of/data-migration-issues/12959-kodo-batch-delete) |

<br />

<div id="Q11" />

| Q11: 可以给空间不同的文件设置不同的权限吗，只想让部分文件是私有访问的                                           |
| ------------------------------------------------------------------------------- |
| 同一个空间内的文件权限都是一样的，不能设置部分文件为私有，部分公开，这种场景，只能创建两个空间，将公开的文件放在公有空间，需要有私有权限的文件放在私有空间中。 |

<br />

<div id="Q12" />

| Q12: 访问空间的访问记录是否可以查询                                                                                                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 如果对应存储空间绑定的是CDN加速域名，空间资源访问日志可以在 [https://portal.qiniu.com/cdn/log](https://portal.qiniu.com/cdn/log) 下载CDN域名日志查看。top url、ip、ua、referer等信息，可以在 [https://portal.qiniu.com/cdn/statistics/log/top](https://portal.qiniu.com/cdn/statistics/log/top) 查看 |
| 如果对应存储空间绑定的是源站域名，空间访问日志可以参考 [/products/kodo/development-guidelines/management-of-storage-space/11-space-access-log](/products/kodo/development-guidelines/management-of-storage-space/11-space-access-log)                                          |

<br />

<div id="Q13" />

| Q13: 有什么办法可以快速扫描全盘，搜索包含指定内容的文件有哪些? |
| ---------------------------------- |
| 存储无法扫描文件内容的，只能您将文件下载逐个读取的          |

<br />

<div id="Q14" />

| Q14: CDN回源流量资源包在哪里购买?                                                                 |
| ------------------------------------------------------------------------------------- |
| 您可以在 [云商城](https://qmall.qiniu.com/template/MTEy?spec_combo=MzE3OA\&ref=index) 界面点击购买 |

<br />

<div id="Q15" />

| Q15: 如何根据 文件后缀或文件类型 查询文件? 比如 &#x2A;.js，*.xml 后缀的文件                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| 可以使用 qshell 工具的 [listbucket2](http://github.com/qiniu/qshell/blob/master/docs/listbucket2.md) 命令实现，qshell工具安装与使用参考 [qshell](/products/kodo/0-qshell) |
| A、比如列举 .js和.xml 后缀的文件：qshell listbucket2 --suffixes js,xml 空间名称 -o 列表存放的本地文件名.txt                                                                    |
| B、比如列举 js和 xml 类型的文件：qshell listbucket2 --mimetypes application/xml,application/javascript,text/xml,text/javascript 空间名称 -o 列表存放的本地文件名.txt           |

<br />

<div id="Q16" />

| Q16: 为什么上传的视频无法在七牛控制台预览和下载？                                                                                                                                                                                                                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是您在CDN加速域名或存储空间配置了referer防盗链策略导致的，可以参考 [Referer防盗链](/products/cdn/configuration-management-fusion/access-control-configuration/0-domain-name-hotlinking-prevention) 和 [设置Referer防盗链](/products/kodo/kodo-console-guide/bucket-management/space-settings/4-set-the-referer-hotlinking-prevention) 检查CDN加速域名或存储空间配置的referer防盗链策略是否拉黑或没有加白七牛控制台访问域名：portal.qiniu.com ？ |

<br />

<div id="Q17" />

| Q17: 将文件转换为 归档存储或深度归档存储 类型后，为什么还能访问？                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1、如果调用过 [解冻](/products/kodo/rs/12-restore-archive) 接口，解冻完成后可以访问是正常的；<br />2、如果没有进行过文件 [解冻](/products/kodo/rs/12-restore-archive) 操作，一般是CDN缓存导致的，刷新下对应文件的CDN缓存即可，CDN缓存刷新操作参考 [刷新预取](/products/cdn/2-refresh-the-prefetch-fusion) 说明文档。 |

<br />

<div id="Q18" />

| Q18: 上传失败，报579？                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 579是上传成功，回调失败；需要确认回调服务器接受 POST 请求，并可以给出 200 的响应。其他上传失败错误码说明参考 [上传失败常见状态码](/faq/kodo/upload-download-problem/3881-upload-the-common-failure-status-code-and-solve-method) |

<br />

<div id="Q19" />

| Q19: 对象存储空间是否有大小限制？               |
| --------------------------------- |
| 对象存储空间没有存储上限限制，根据您的实际存储文件量计算存储费用的 |

<br />

<div id="Q20" />

| Q20: 创建空间提示空间名称已被占用，如何处理？                          |
| -------------------------------------------------- |
| 七牛存储空间名称全局唯一，提示空间名称已被占用，说明已被其他用户创建使用，需要您更换其他空间名称创建 |

<br />

<div id="Q21" />

| Q21: 空间数量是否有限制？                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 每个存储区域空间数量限制默认20个，如需提升空间数量限制，可以 [提交工单](https://support.qiniu.com/tickets/new-for-person/form?category=%E5%85%B6%E4%BB%96%E7%B1%BB%E5%92%A8%E8%AF%A2\&space=%E5%AF%B9%E8%B1%A1%E5%AD%98%E5%82%A8) 申请 |

<br />

<div id="Q22" />

| Q22: 如何查询文件上传日志？                                                                                                  |
| ----------------------------------------------------------------------------------------------------------------- |
| 存储空间文件上传日志您无法自行查询，如需查询，可以 [提交工单](https://support.qiniu.com/tickets/create) 提供需要查询的文件名、上传时间、上传空间名称等信息，由技术支持人员为您查询。 |

<br />

<div id="Q23" />

| Q23: 空间为什么存在0字节大小的空文件？                                |
| ----------------------------------------------------- |
| 如果空文件的名称是类似 test/ 或 123/ 以 / 结尾的，是您创建了文件夹或目录产生的，可以忽略。 |

<br />

<div id="Q24" />

| Q24: 空间文件被删除，如何查询删除记录？                                                                                                |
| --------------------------------------------------------------------------------------------------------------------- |
| 文件删除日志您无法自行查询，可以提供删除文件名、空间名、文件删除时间，需要的信息（比如ip、ua等），然后 [提交工单](https://support.qiniu.com/tickets/create) 由技术支持人员为您查询提供。 |

<br />

<div id="Q25" />

| Q25: 为什么使用空间自带S3域名或已绑定域名无法访问？                                                                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1、S3协议域名需要走AWS S3协议生成下载凭证后，才能请求访问，具体参考：[AWS S3 兼容](/products/kodo/development-guidelines/aws-s3-compatible) 说明文档；<br /> 2、如果是通过绑定自定义域名访问失败，建议先确认下域名是否使用正确？必须使用绑定的自定义域名访问，不能使用七牛提供的CNAME地址访问；且绑定域名是否已经在域名购买商平台或DNS托管商平台添加了CNAME解析配置？ |

<br />

<div id="Q26" />

| Q26: S3协议域名上传报跨域错误，如何处理？                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------------------- |
| S3协议域名支持配置跨域策略，配置操作参考：[设置跨域资源共享](/products/kodo/kodo-console-guide/bucket-management/space-settings/5-set-the-cross-domain-resource-sharing) |

<br />

<div id="Q27" />

| Q27: 如何对存储空间视频进行转码处理？                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **1、上传时自动对视频进行转码处理：**<br /> A、上传token中添加转码参数来实现，上传token策略参数说明：[上传策略](/products/kodo/development-guidelines/security/1-put-policy)                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ![image.png](/docs-assets/faq/kodo/basic-use-of/12957-kodo-nomarl-faq/FjwvbgViXW-Rj29hZcz1KV1jXs_P-80500cf495b8.webp) <br /> B、不需要修改上传代码的情况下，可以在七牛控制台 [创建任务触发器](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/1-tigger) 来实现自动对新增视频文件进行转码处理。<br /> &#x2A;*2、对存储空间已存在的资源进行转码处理：**<br /> A、控制台手动 [创建转码任务](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/2-task#3) 处理；<br /> B、通过代码调用 [转码接口](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop#3) 提交处理 |

<br />

<div id="Q28" />

| Q28: 已备案域名接入对象存储空间，需要做备案变更或接入操作吗？                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 不需要，只要您的域名有ICP备案，且可以在 [工信部官网](https://beian.miit.gov.cn/#/Integrated/recordQuery) 可以查询到备案信息即可。![image.png](/docs-assets/faq/kodo/basic-use-of/12957-kodo-nomarl-faq/FteMsBharukCrcmQ8kAfuyEQnIgs-7cd15757072e.webp) |

<div id="Q29" />

| Q29: 文件存储类型转换会影响文件访问吗？                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1、标准存储、低频存储、智能分层存储、归档直读 这4种存储类型相互转换：不会影响文件访问，但计费会有差异，计费说明参考 [计量项与计费项](/products/kodo/1-metering-and-billing) <br /> 2、如果是其他存储类型转换为归档存储或深度归档存储：转换后，无法直接访问，需要先做文件解冻，解冻成功后才可以访问，接口文档参考：[解冻归档/深度归档存储文件](/products/kodo/rs/12-restore-archive)，另外，计费也会有差异，计费说明参考 [计量项与计费项](/products/kodo/1-metering-and-billing) <br /> 3、归档存储或深度归档转换为其他存储类型：无法直接转换，需要先将文件解冻成功后，才可以进行存储类型转换，解冻接口文档参考：[解冻归档/深度归档存储文件](/products/kodo/rs/12-restore-archive)，文件存储类型转换接口参考 [修改文件存储类型](/products/kodo/rs/9-modify-the-file-storage-type)，计费说明参考 [计量项与计费项](/products/kodo/1-metering-and-billing) |

<br />

<div id="Q30" />

| Q30: 批量提交了大量转码任务，如何取消未执行的任务？                                                                                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1、指定pipeline为私有队列名称提交的任务：可以在七牛控制台 - [队列](https://portal.qiniu.com/dora/media-gate/pipeline) 删除对应私有队列名称取消未执行任务；<br /&#x3E; &#x2A;*`注意：队列删除后不能创建同名队列，否则还是会导致未处理任务被继续执行`** <br /> 2、没有指定私有队列名称，使用默认队列提交的任务：需要您 [提交工单](https://support.qiniu.com/tickets) 由技术支持为您处理取消未执行任务&#x3002;<br />&#x2A;*`注意：只能取消还在排队且未开始执行的转码任务，已经在执行中或执行完成的任务无法取消`** |

<br />

<div id="Q31" />

| Q31: 退订服务器是否会影响对象存储使用？                                      |
| ----------------------------------------------------------- |
| 是否影响，取决于您的服务器是否有对象存储相关的上传、下载、回调、转码触发、镜像回源或中转服务部署，如果没有，不会影响。 |

<br />

<div id="Q32" />

| Q32: 对象存储如何开通使用？                                                                 |
| -------------------------------------------------------------------------------- |
| 注册七牛账号并完成实名认证后即可使用，无需开通。对象存储使用参考文档：[快速入门文档](/products/kodo/0-console-quickstart) |

<br />

<div id="Q33" />

| Q32: 对象存储怎么上传文件到指定目录？                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 上传到哪个“目录”不是单独设置目录参数，而是直接在上传时把目标路径写进文件名 key 里；控制台看到的目录是虚拟目录，/ 前面的前缀会自动显示成文件夹。比如图片传到 1 文件夹就把 key 设为 1/图片名.jpg，压缩包传到 2 文件夹就把 key 设为 2/压缩包名.zip；如果要更深层目录，就继续写成 1/a/xxx.jpg 这种格式。 |

<br />

<div id="Q34" />

| Q34: 存储空间绑定的自定义源站域名修改配置后，多久生效？ |
| ------------------------------ |
| 配置修改完成后，全网生效一般需要5-15min左右。     |

<br />

<div id="Q35" />

| Q35: SDK支持根据文件类型或存储方式列举文件吗？                                                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 不支持，[资源列举](/products/kodo/rs/4-list) 接口仅支持根据空间和统一前缀列举获取；<br />如需根据文件类型或存储类型等更多条件列举，<br /> 1、推荐使用 [qshell工具](/products/kodo/0-qshell) 的listbucket2命令列举获取，Windows使用qshell参考文档：[windows环境下安装qshell与使用](/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial#3) <br /> 2、或者调用 [资源列举](/products/kodo/rs/4-list) 接口，根据接口返回字段内容自行筛选记录需要的文件列表信息。 |

<br />

<div id="Q36" />

| Q36: 存储空间控制台的域名管理按钮灰色无法点击，是什么原因？                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是您查看的空间是其他七牛账号授权给您的，授权空间只能进行文件上传和下载，没有其他操作权限，说明参考：[设置空间授权](/products/kodo/kodo-console-guide/bucket-management/space-settings/3-set-the-space-authorization) 说明文档 |

<br />

<div id="Q36" />

| Q37: 对象存储提供永久使用的域名吗？                                                                                                                                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 不提供，创建空间时默认分配的测试域名只有30天有效期，到期后系统会自动回收且无法恢复，需要绑定您自己的域名来访问空间资源。<br /> 1、测试域名限制说明：[测试域名使用规范](/faq/cdn/other-fusion/1319-test-domain-access-restriction-rules) <br /> 2、存储空间绑定域名参考：[域名管理](/products/kodo/kodo-console-guide/bucket-management/kodo-domain-name-management)，中国大陆区域存储空间绑定的自定义域名必须有ICP备案。 |

<br />

<div id="Q38" />

| Q38: 对象存储自定义源站域名配置HTTPS证书失败，报406错误，怎么处理？                                                                                                                                                                                                                                                                             |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般是您上传的自有证书不支持导致的，HTTPS配置证书不支持 `自签证书`或`Cloudflare平台签发证书`，只支持CA签发证书。七牛支持申请免费证书，可在 [证书管理 - 购买证书](https://portal.qiniu.com/certificate/apply) 选择 【TrustAsia限免】 - 【DV免费域名型】进行购买。SSL证书入门说明文档参考：[/products/ssl/quick-start/13469-ssl-certificate-quick-start](/products/ssl/quick-start/13469-ssl-certificate-quick-start) |
| ![image.png](/docs-assets/faq/kodo/basic-use-of/12957-kodo-nomarl-faq/FuH_dOukoIkiz3nwgZ6IqjevM7zs-47ac408dcf3a.webp)                                                                                                                                                                                                |

<br />

<div id="Q39" />

| Q39: 对象存储可以绑定多个域名，并每个域名绑定证书吗？                                                                             |
| --------------------------------------------------------------------------------------------------------- |
| 支持，对象存储空间绑定域名操作参考：[域名管理](/products/kodo/kodo-console-guide/bucket-management/kodo-domain-name-management) |

<br />

<div id="Q40" />

| Q40: 对象存储文件如何禁用或启用？                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 方式1：可通过调用 [修改文件状态](/products/kodo/rs/11-modify-the-file-status) 接口启用或禁用文件；                                                                                                                                                                                                                                                                     |
| 方式2：可使用 [qshell](/products/kodo/0-qshell) 命令行工具的 [forbidden](http://github.com/qiniu/qshell/blob/master/docs/forbidden.md) 命令处理，<br /> 启用文件命令：`qshell forbidden 空间名 文件名 -r` <br /> 禁用文件命令：`qshell forbidden 空间名 文件名` <br /> 如果需要批量处理文件，可使用qshell工具的 [batchforbidden](http://github.com/qiniu/qshell/blob/master/docs/batchforbidden.md) 命令批量处理 |


# 批量获取文件列表 (/faq/kodo/basic-use-of/12958-kodo-batch-keylist)



最近更新时间: 2025-04-10 15:16:23

目前存储控制台不支持直接获获取文件列表

## 七牛提供如下解决方案： [#七牛提供如下解决方案]

* [官方服务端SDK](/sdk-tools/sdk#official-sdk)，调用各个语言SDK或者API获取文件列表，

* [命令行工具](/products/kodo/0-qshell)，利用qshell的listbucket或者listbucket2命令批量获取，优先推荐使用listbucket2获取列表,具体参数说明参考[**listbucket2说明文档**](https://github.com/qiniu/qshell/blob/master/docs/listbucket2.md)。

## 使用经验 [#使用经验]

### qshell 获取文件列表 [#qshell-获取文件列表]

由于qshell是一个脚本命令行工具，所以需要在cmd或者终端中运行，mac与linux系统会经常使用到终端，下载合适版本到本地解压，直接chmod +x qshell 即可执行命令行。
`但是如果您需要使用windows操作系统的话，可能您对cmd不是那么熟悉，强列推荐参考这里`[**windows环境下安装qshell教程**](/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial#2)

linux 和 mac 的话，直接在终端中执行

`listbucket2` 命令用于获取文件列表，可以根据不同的需求拉取不同的文件列表
这里只列举几种常见的获取文件列表的需求，更多参数叠加使用，参考[**listbucket2参数文档**](https://github.com/qiniu/qshell/blob/master/docs/listbucket2.md)
使用listbucket2前，必须先登录账号，使用qshell account 进行登录，如果已经登陆过，那么无需重复登录。ak sk 空间名称如果不了解是什么，可以阅读[常见的关键参数](/faq/kodo/7450-the-third-party-plug-in-key-parameters)

```bash
  qshell account 您的ak 您的sk 空间名称
```

1.获取全部文件列表

```bash
    qshell listbucket2 空间名称 -o 列表存放的本地文件名.txt
```

2.只获取文件名

```bash
    qshell listbucket2 空间名称 --show-fields Key -o 列表存放的本地文件名.txt
```

3.获取指定前缀文件列表
比如想要获取前缀为 image文件夹的文件，通过 prefix

```bash
     qshell listbucket2 空间名称 --prefix "iamge/" -o 列表存放的本地文件名.txt
```

4.获取指定时间范围内的文件列表
比如想要获取 2018-10-30 \~ 2018-11-03 之间上传的文件列表

```bash
     qshell listbucket2 --start 2018-10-30 --end 2018-11-03 空间名称  -o 列表存放的本地文件名.txt
```

5.获取指定文件类型的文件列表
比如想要获取 空间内的低频文件列表
file-types参上个月：根据列举前缀列举整个空间，然后从中筛选出满足七牛存储类型的文件；配置多个存储类型时中间用逗号隔开（eg: 1,2,3）；0：普通存储，1：低频存储，2：归档存储，3：深度归档存储，4：归档直读存储。

```bash
     qshell listbucket2  空间名称 --file-types 2  -o 列表存放的本地文件名.txt
```

### SDK [#sdk]

以java
java为列，参考 [https://developer.qiniu.com/kodo/1239/java#rs-list](https://developer.qiniu.com/kodo/1239/java#rs-list) ，可以将列表信息根据需求自定义捕获输出即可


# 什么是样式以及样式分隔符？ (/faq/kodo/basic-use-of/1327-what-is-the-style-and-the-style-separators)



最近更新时间: 2021-06-22 16:15:38

# 什么是样式 [#什么是样式]

样式是将冗长的数据处理重新定义的一个友好别名，其本质仍然是对图片的处理模式，

可以参考图片处理的相关文档:

[样式](/faq/kodo/basic-use-of/1327-what-is-the-style-and-the-style-separators#3)

[图片处理参数](/products/dora/image-processing-api/6-img-directions-for-use)

# 设置图片样式 [#设置图片样式]

可以在 [控制台](https://portal.qiniu.com/) - 对象存储 中选择需要配置的存储空间，在图片样式标签配置

![图片样式](/docs-assets/faq/kodo/basic-use-of/1327-what-is-the-style-and-the-style-separators/FuXGqOGi88Dl6ekcGfXX3e3r2h0k-8064cb3b2756.webp)

# 什么是样式分隔符 [#什么是样式分隔符]

样式分隔符是用于连接资源链接和图片样式的特殊符号，为防止访问出错，样式名中不可出现当前所启用的识别符

# 设置样式分隔符 [#设置样式分隔符]

可以在 [控制台](https://portal.qiniu.com/) - 对象存储 中选择需要配置的存储空间，在图片样式-样式分隔符设置中做分隔符配置

![样式分隔符设置](/docs-assets/faq/kodo/basic-use-of/1327-what-is-the-style-and-the-style-separators/FjZI9eYPo2VBnSlFN6XyhFKiV6Jn-a7f8e7f6f782.webp)

# 示例 [#示例]

样式名称为imageFop，样式内容为：imageView2/0/w/48/h/48，样式分隔符为 -

原始图片链接[http://dn-odum9helk.qbox.me/qiniu-picture1.jpg](http://dn-odum9helk.qbox.me/qiniu-picture1.jpg)

通过访问[http://dn-odum9helk.qbox.me/qiniu-picture1.jpg-imageFop](http://dn-odum9helk.qbox.me/qiniu-picture1.jpg-imageFop)  即可获得效果缩放效果

注意事项：

1、创建分隔符时，不建议使用在样式名称中出现的符号作为分隔符。

2、修改分隔符是个危险操作，全网生效须24小时。


# 在七牛云存储上播放 HLS (/faq/kodo/basic-use-of/1339-in-seven-niuyun-stored-in-hls)



最近更新时间: 2020-05-15 16:34:16

# 在七牛云存储上播放 HLS [#在七牛云存储上播放-hls]

HLS 是在移动端使用广泛的播放协议，可以用于直播，也可以用于点播。七牛云存储提供多种类型的视频文件向 HLS 的转换功能：[音视频切片](/faq/kodo/basic-use-of/1339-in-seven-niuyun-stored-in-hls)。同时，也提供了 m3u8 和 ts 文件的分发下载功能。

用户有两种方式使用七牛云存储提供的 HLS 功能。如果用户已经有视频的 m3u8 文件和相应的 ts 文件，那么只需上传到七牛云存储中即可。播放时将 m3u8 文件的[下载 url](/faq/kodo/basic-use-of/1339-in-seven-niuyun-stored-in-hls) 作为播放地址，便可以播放 HLS 视频。但有两点需要注意：

1,m3u8 文件中，必须指向 ts 文件所在的位置。包括两种形态：相对引用和绝对引用。相对引用就是当 m3u8 文件同 ts 文件在同一 bucket 中时，可以直接将 ts 文件名放在 m3u8 文件中，不需要额外的前缀：

\#EXTM3U
\#EXT-X-VERSION:3
\#EXT-X-MEDIA-SEQUENCE:0
\#EXT-X-ALLOW-CACHE:NO
\#EXT-X-TARGETDURATION:300
\#EXTINF:300.000,
seg00000.ts
\#EXTINF:300.000,
seg00001.ts
\#EXTINF:300.000,
seg00002.ts
\#EXTINF:300.000,
seg00003.ts
\#EXTINF:300.000,
seg00004.ts
\#EXT-X-ENDLIST

对于 m3u8 文件同 ts 文件放在不同的 bucket 的情况，需要在 ts 文件名之前增加域名前缀：

\#EXTM3U
\#EXT-X-VERSION:3
\#EXT-X-MEDIA-SEQUENCE:0
\#EXT-X-ALLOW-CACHE:NO
\#EXT-X-TARGETDURATION:300
\#EXTINF:300.000,
[http://test-hls.u.qiniudn.com/seg00000.ts](http://test-hls.u.qiniudn.com/seg00000.ts)
\#EXTINF:300.000,
[http://test-hls.u.qiniudn.com/seg00001.ts](http://test-hls.u.qiniudn.com/seg00001.ts)
\#EXTINF:300.000,
[http://test-hls.u.qiniudn.com/seg00002.ts](http://test-hls.u.qiniudn.com/seg00002.ts)
\#EXTINF:300.000,
[http://test-hls.u.qiniudn.com/seg00003.ts](http://test-hls.u.qiniudn.com/seg00003.ts)
\#EXTINF:300.000,
[http://test-hls.u.qiniudn.com/seg00004.ts](http://test-hls.u.qiniudn.com/seg00004.ts)
\#EXT-X-ENDLIST

2,为了保证 flash 播放器能够正确播放 HLS 视频，必须在 m3u8 和 ts 文件所在的 bucket 中放置 crossdomain.xml 文件。

如果用户所用的是其他类型的视频格式，比如 MP4、FLV 等，可以上传至七牛云存储，然后使用七牛云存储的[音视频切片](/faq/kodo/basic-use-of/1339-in-seven-niuyun-stored-in-hls)功能，将其转化成 HLS 视频。用户可以在视频上传的同时启动转换操作：[数据预处理](/faq/kodo/basic-use-of/1339-in-seven-niuyun-stored-in-hls#put-policy-persistent-ops-explanation)，也可以对已经上传的视频文件进行转换：[触发持久化处理](/faq/kodo/basic-use-of/1339-in-seven-niuyun-stored-in-hls)。

在启动 HLS 转换操作时，需要指定视频切片的长度。这个值过长会造成拖放响应降低，废流量增加；这个值过短，会造成 ts 文件过多，管理不便。通常，ts 文件片的长度取 5 分钟到 10 分钟比较合适。

有的用户希望将 m3u8 和 ts 文件所在的 bucket 置为私有，以保护视频内容。但是，一旦 bucket 置为私有，那么对 ts 文件的访问必须每次都进行授权，从而导致每次访问的 url 都不一样，进而使得每次播放都需要生成不同的 m3u8 文件。为解决这个问题，七牛云存储提供了[私有 m3u8 功能](/faq/kodo/basic-use-of/1339-in-seven-niuyun-stored-in-hls)。用户借助此功能，可以直接访问一个私有 bucket 中的 HLS 视频。


# 什么是原图保护？ (/faq/kodo/basic-use-of/1359-what-is-the-original-protection)



最近更新时间: 2026-04-30 17:27:12

# 概述 [#概述]

原图保护是七牛云存储针对媒体类源文件的保护措施。

对整个存储空间内`所有的资源`生效，开启后，空间内的文件无法直接通过url进行访问，需要配合[样式分隔符](/faq/kodo/basic-use-of/1327-what-is-the-style-and-the-style-separators)和[图片样式](/faq/kodo/basic-use-of/1359-what-is-the-original-protection#3)才能访问

# 使用场景 [#使用场景]

用于控制客户只能访问处理后的资源，如：

1. 对于存储在七牛上的图片资源，只希望客户访问携带水印的图片
2. 对于存储在七牛上的图片资源，进行统一的规格化处理

特别需要注意的是，原图保护是一种空间属性，对整个空间的资源都会生效，因此强烈建议对于开启原图保护的空间只存储需要保护原图的图片文件，其他文件使用其他空间存放。

# 访问方式 [#访问方式]

开启原图(或源文件)保护后，不能通过如下方式访问:

* `http://绑定域名/文件key或相对路径`
* `http://绑定域名/文件key或相对路径?操作符/操作符参数`

可以通过如下方式进行公开访问（其中加号“+”忽略）：

* `http://绑定域名/文件key或相对路径 + 已设定的样式分隔符 + 已设定的图片样式`

如配置分隔符为"-",图片样式名称为"watermarked.jpg"，则以下形式的链接可以访问

* `http://(Domain)/(Key)-watermarked.jpg`

如果希望对源文件进行访问，可以通过[私有链接签名](/products/kodo/development-guidelines/download-process/1-download-private)的方式，携带鉴权参数访问，但不建议这样使用。

# 设置方法 [#设置方法]

1. 设置样式分隔符，可以在 [控制台](https://portal.qiniu.com/) - 对象存储 中选择需要配置的存储空间，在样式分隔符设置标签配置

![样式分隔符设置](/docs-assets/faq/kodo/basic-use-of/1359-what-is-the-original-protection/FiQMOFBsJnJc7HodoMQdc2g513jt-c329e5ea3483.webp)

2. 设置图片样式，可以在 [控制台](https://portal.qiniu.com/) - 对象存储 中选择需要配置的存储空间，在图片样式标签配置

![image.png](/docs-assets/faq/kodo/basic-use-of/1359-what-is-the-original-protection/FjHv4D2jKY_DSOEK5vZoS4XRPwqt-00266a4c2ab8.webp)
3\. 设置原图保护

在 [控制台](https://portal.qiniu.com/) 的 对象存储中选择需要配置的存储空间，在访问设置下选择开启或关闭原图保护功能

![image.png](/docs-assets/faq/kodo/basic-use-of/1359-what-is-the-original-protection/FjATeRQOkxbkEr5Ri78lANRxso-3655cd5ef908.webp)


# 公开空间和私有空间介绍 (/faq/kodo/basic-use-of/1363-public-space-and-private-space-is-introduced)



最近更新时间: 2020-05-15 16:34:16

创建空间时，可设置为公开空间或私有空间。

公开空间，可通过文件对象的 URL 直接访问。如果要使用七牛云存储的镜像存储功能，请设置空间的属性为公有。

私有空间，文件对象的访问则必须获得拥有者的授权才能访问。

公开和私有仅对空间的读文件生效，修改、删除、写入等对空间的操作均需要拥有者的授权才能进行操作。


# 关于 list 超时及规避方式 (/faq/kodo/basic-use-of/1443-on-the-list-and-avoid-overtime)



最近更新时间: 2020-05-15 16:34:16

一个空间存放了大量的文件，这个数量很大，用户 list 出一部分文件批量删除空间的大量文件，然后再次调用 list 接口整个空间的文件名，list 失败并报超时错误。

**问题截图（Java版本）：**

![blob.png](/docs-assets/faq/kodo/basic-use-of/1443-on-the-list-and-avoid-overtime/001577618de0aef5121b9e4463de8a1-bba9aadd952b.webp)

遇到这个问题时，请修改如下配置文件的超时时间，改到 200s；或者使用 [qshell](/faq/kodo/basic-use-of/1443-on-the-list-and-avoid-overtime) 工具，使用 [listbucket](https://github.com/qiniu/qshell/wiki/listbucket) 命令对空间文件名打印输出。

![blob.png](/docs-assets/faq/kodo/basic-use-of/1443-on-the-list-and-avoid-overtime/0015776180fdf67e8fae770f8799c3b-5c61bad0a34f.webp)

如果依然显示超时，原因如下：

在七牛的存储系统中，当用户调用 list 接口时，系统程序会先查看 marker 参数是否为空，如果为空，则起点位置设为整个空间的第一个文件，然后过滤整个空间的所有文件名并返回。

每当用户删除了大量文件，这时用户调用 list 接口，系统还是先查看 marker 字段是否为空，如果为空，则开始过滤已经被标记删除文件的信息， **如果删除的文件很多，系统会过滤很长时间，list等待时间过长，导致list失败** 。

**规避方式：**

调用 list 接口时，设置 marker 参数，指定 list 标记位置，如此系统不会过滤之前被删除的文件，而之间从标记位置遍历下去。

**本文涉及接口：**

* [资源列举(list)](/products/kodo/rs/4-list)

* [资源删除(delete)](/products/kodo/rs/3-delete)


# 统计日志 (/faq/kodo/basic-use-of/1451-how-to-own-space-ip-access-number)



最近更新时间: 2026-04-29 17:34:49

# 1 首先要有 linux 系统或者 mac 系统 [#1-首先要有-linux-系统或者-mac-系统]

# 2 下载日志到本地 [#2-下载日志到本地]

# 3 统计最热资源的访问次数排名前 20 [#3-统计最热资源的访问次数排名前-20]

$ zcat qwe.gz | awk '\{a\[$7]+=1} END\{for (i in a) print a\[i] " ==> " i}' | sort -rn | head -20

# 4 统计访问 ip 的前 20 [#4-统计访问-ip-的前-20]

$ cat part01.txt | awk '\{a\[$1]+=1} END\{for (i in a) print a\[i] " ==> " i}' | sort -rn | head -20

# 5 查看某个文件的 ip 访问次数统计（例如文件名字叫 windows） [#5-查看某个文件的-ip-访问次数统计例如文件名字叫-windows]

$ cat part01 |grep Windows| awk '\{a\[$1]+=1} END\{for (i in a) print a\[i] " ==> " i}' | sort -rn | head -20

# 6 cdn 下载统计访问错误码分布 [#6-cdn-下载统计访问错误码分布]

$ cat install.banban.im.cn.log |awk '\{if ($10!=20000) \{a\[$10]++;s=NR}} END \{for (i in a) \{print a\[i],i,a\[i]/s\*100 "%"}}'|sort -rn

# 7 IO 下载统计访问错误码分布 [#7-io-下载统计访问错误码分布]

$ cat 14.215.165.50.log |awk -F '\t' '\{if ($8!\~/20000/) \{a\[$8]++}} END \{for (i in a) \{print a\[i],i,a\[i]/NR\*100 "%"}}'|sort -rn


# 空间属性maxAge实现对缓存控制 (/faq/kodo/basic-use-of/1475-space-maxage-attribute-to-the-cache-control)



最近更新时间: 2026-04-30 17:19:28

# 使用空间属性maxAge实现对缓存的控制 [#使用空间属性maxage实现对缓存的控制]

* 通过配置七牛的空间（如下图）属性中 maxAge, 达到配置 HTTP header 中 Cache-Control:max-age的目的。

![image.png](/docs-assets/faq/kodo/basic-use-of/1475-space-maxage-attribute-to-the-cache-control/Fknf48Fhg1sp6DUN2JAlzUqiU9z3-2c14d63ecc91.webp)

# 什么是Cache-Control？ [#什么是cache-control]

* Cache-Control 通用消息头被用于在http 请求和响应中通过指定指令来实现缓存机制,是一种缓存控制的方法。 HTTP header中，服务器可以通过对Cache-Control的设置来指定在文档过期之前将其缓存多长时间。
* 例如，七牛控制台可以通过配置Cache-Control: max-age的时间表示从服务器传来文档之时起，认为此文档处于新鲜状态的秒数。

# maxAge值和CDN缓存时间的区别？ [#maxage值和cdn缓存时间的区别]

访问资源链接时，缓存通常分为浏览器缓存和CDN节点缓存。
用户在浏览器中输入资源链接访问时，优先使用浏览器缓存，缓存失效或禁用本地缓存后，会向CDN节点请求资源，当CDN缓存时间超时后，会向源站发起资源请求。

* Cache-Control:max-age:设置缓存存储的最大周期，超过这个时间缓存被认为过期(单位秒)，控制用户浏览器端的缓存。
* CDN缓存：当CDN缓存超时后，节点认为缓存失效，会向源站重新请求资源。

# 如何查看Cache-Control的maxAge值？ [#如何查看cache-control的maxage值]

* 以chrome控制台为例，打开 开发者工具 或 检查，在network标签页下查看。

<img src="/docs-assets/faq/kodo/basic-use-of/1475-space-maxage-attribute-to-the-cache-control/FmFP1Yf577R9H32p6lDhG-4-apiy-2497b11244b0.webp" width="700" />


# 设置  robots.txt 文件 (/faq/kodo/basic-use-of/1540-set-the-robots-txt-file)



最近更新时间: 2020-05-15 16:34:16

下面是设置robots.txt文件的地方和具体操作

请参考图片：

![blob.png](/docs-assets/faq/kodo/basic-use-of/1540-set-the-robots-txt-file/00156efb948266be0399bae328da35e-18f2f2bf879e.webp)

![blob.png](/docs-assets/faq/kodo/basic-use-of/1540-set-the-robots-txt-file/00156efb96170057045679f9c74a96b-23c48c7c4988.webp)


# 浏览器对 MP4 的支持 (/faq/kodo/basic-use-of/1561-various-browsers-support-for-mp4)



最近更新时间: 2020-05-15 16:34:16

# 浏览器的支持表 [#浏览器的支持表]

[参照如下文档](https://en.wikipedia.org/wiki/HTML5_video)

# MP4 视频格式解释 [#mp4-视频格式解释]

MP4有非常复杂的含义（ 见 [http://en.wikipedia.org/wiki/Mp4](http://en.wikipedia.org/wiki/Mp4) ），普通人对MP4的理解是后缀为 `.mp4` 的文件。但 MP4 本身不是一种简单的视频格式，它是一个包装了视频和音频格式的容器。至于里面的视频和音频使用什么编码是可选的。MP4的视频格式可以使用 DivX 也可使用 H264，vp8，vp9，theora。

# 推荐浏览器 [#推荐浏览器]

Chrome浏览器支持 HTML5 ，它支持原生播放部分的 MP4 格式（不用通过 Flash 等插件）

# 遇到的问题 [#遇到的问题]

为什么是部分MP4呢？是因为 Chrome 只支持 H264。为什么 Chrome 不支持所有的视频编码格式？绝大部份的视频编码格式都是要付专利费的，Google 已经为 H264 买了单，Firefox 没有 Google 那么有钱不愿意买。

# 查看视频格式 [#查看视频格式]

在外链地址后面加上 `?avinfo`，如： [http://dn-odum9helk.qbox.me/mp4-v1?avinfo](http://dn-odum9helk.qbox.me/mp4-v1?avinfo)

这是可以在chrome中正常播放的：

"streams": \[
\{
"index": 0,
"codec\_name": "h264",
"codec\_long\_name": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",

这个格式就是不OK的：

"streams": \[
\{
"index": 0,
"codec\_name": "mpeg4",
"codec\_long\_name": "MPEG-4 part 2",

# 播放效果 [#播放效果]

[可以播放的视频演示](http://dn-odum9helk.qbox.me/@/test/mp4-test1%20-%20%E5%89%AF%E6%9C%AC.html)

[不可以播放的视频效果](http://dn-odum9helk.qbox.me/@/test/mp4-test1.html)

# 解决方案 [#解决方案]

1. 使用js或者flash播放器来播放 针对部分格式，即使是播放器也不行。还是建议使用七牛的转码。
2. 使用七牛的异步转码服务。
3. 转码前，利用部分的播放器也播放不了。原视频：[http://dn-odum9helk.qbox.me/mpeg4.mp4](http://dn-odum9helk.qbox.me/mpeg4.mp4)
4. 转码后：[http://dn-odum9helk.qbox.me/mpeg4-zhuanma.mp4](http://dn-odum9helk.qbox.me/mpeg4-zhuanma.mp4)


# 如何利用七牛云存储实现 HLS 的多码率播放 (/faq/kodo/basic-use-of/1618-how-to-make-use-of-more-than-seven-niuyun-storage-of-hls-rate-play)



最近更新时间: 2020-05-15 16:34:16

当前的音视频应用必须面对各种不同的播放客户端，从 PC 端（Web）开始，到智能手机。这些播放客户端有不同的尺寸，因而需要不同的分辨率。视频不同的客户端也会有不同的网络环境，比如 PC 上通常都有 WiFi 或有线网络，有较高的带宽保证，而手机、平板电脑在室外时，使用 2G/3G 网络，往往带宽不足，或者不稳定。因而需要针对不同的网络环境采用不同的码率。

HLS 本身所具备的的多码率播放能力对于音视频应用而言，提供了很大的方便。

用户首先根据需要生成不同分辨率和码率的 HLS 视频，（生成的方法参考[在七牛云存储上播放 HLS](/faq/kodo/basic-use-of/1339-in-seven-niuyun-stored-in-hls)）。这些不同分辨率的 HLS 视频都应当存放在同一个 bucket 中。然后构造出多码率的 m3u8 文件：

\#EXTM3U
\#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=15000000
[http://test-hls.u.qiniudn.com/ultra-high.m3u8](http://test-hls.u.qiniudn.com/ultra-high.m3u8)
\#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=10000000
[http://test-hls.u.qiniudn.com/high.m3u8](http://test-hls.u.qiniudn.com/high.m3u8)
\#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=5000000
[http://test-hls.u.qiniudn.com/standard.m3u8](http://test-hls.u.qiniudn.com/standard.m3u8)
\#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=2500000
[http://test-hls.u.qiniudn.com/low.m3u8](http://test-hls.u.qiniudn.com/low.m3u8)

其中，ultra-high.m3u8、high.m3u8、standard.m3u8、low\.m3u8 分别是已经生成的各种分辨率和码率的 HLS 视频。

用户生成这个文件后，可以将其上传至 bucket，供以后使用。


# 列举条目时 delimiter 参数问题 (/faq/kodo/basic-use-of/1698-java-lists-delimiter-parameter-problem)



最近更新时间: 2020-05-15 16:34:16

## 列举文件时delimiter参数问题 [#列举文件时delimiter参数问题]

#### 参数描述： [#参数描述]

调用listFiles方法列举指定空间的指定文件 

//参数一：bucket 空间名;
//参数二：prefix 文件名前缀
//参数三：marker 上一次获取文件列表时返回的marker 
//参数四：limit 每次迭代的长度限制，最大1000，推荐值100 
//参数五：delimiter 以指定参数为分隔符的所有公共前缀（模拟列出目录效果）。缺省值为空字符串

以 python 为例：

```
# -*- coding: utf-8 -*-
# flake8: noqa
from qiniu import Auth
from qiniu import BucketManager
import json

access_key = '...'
secret_key = '...'

q = Auth(access_key, secret_key)
bucket = BucketManager(q)

bucket_name = '...'
#前缀
prefix = None
#列举条目
limit = 10
#列举'/'为分隔的所有前缀
delimiter = '/'
#标识
marker ='eyJjIjowLCJrIjoibGludXjlhoXmoLgvbGludXgtMy4xMC4xMDQudGFyLnh6In0='
ret, eof, info = bucket.list(bucket_name, prefix, marker, limit, delimiter)
print(info)
assert len(info.text_body) is not None

```

#### 输出结果： [#输出结果]

【注】：输出结果包括不含delimiter中指定参数的key，以及delemiter指定参数为分隔符的公共前缀

#### 例： [#例]

```
"{
    "marker": "eyJjIjowLCJrIjoicHl0aG9uL3RpbWVzaWduLnB5In0=",
    "items": [
        {
            "mimeType": "image/jpeg",
            "fsize": 66441,
            "hash": "Fme36Zks7NJVopii5OPfZ2PwHE8o",
            "key": "mtr.jpg",
            "putTime": 14563802730506377
        }
    ],
    "commonPrefixes": [
        "o1-vkxcxP1-28U_lCDR4OFOYDdc=/",
        "php/",
        "pili/",
        "python/"
    ]
}
```


# 特殊key资源的访问 (/faq/kodo/basic-use-of/2636-special-access-to-key-resources)



最近更新时间: 2020-05-15 16:34:16

> 文件key为`/log.jpg`,为什么访问不了？

## 概要 [#概要]

一般情况下，访问公有资源可以通过以下形式的url:

```
http://<domain>/<key>
```

例如:

```
http://qiniuphotos.qiniudn.com/gogopher.jpg
```

基于此种简单规则的url在实际应用中非常方便。七牛云存储对key的格式几乎没有限制，因此任何可打印字符皆可作为资源的key。但是,如果key中包含特殊字符，如首字符为`/`、两个连接以上的`/`、以及`?`等，则无法通过上面形式的url在浏览器中进行访问。产生此类key的来源主要有：

1. 使用 sdk 上传文件
2. 使用 qboxrsctl put 上传

> **注：采用qrsync工具时不会产生此类key**

这里强调了两点，一是key中包含了特殊字符，二是通过浏览器访问文件。 这是因为浏览器对这些符号是保留使用的，例如：`/`用于分隔目录，`?`用于分隔Url和查询，多个连续的`/`会被处理为一个等等。 对于这类key,需要对其进行转义，其方法为：

将特殊字符转换成 ASCII码，格式为：%加字符的 ASCII码，即一个百分号 %，后面跟对应字符的 ASCII（16进制）码值。例如 空格的编码值是 %20。

## 示例 [#示例]

下面4个资源：

* 资源1，`key:hello%2Fqiniu.jpg`
* 资源2，`key:hello/qiniu.jpg`
* 资源3，`key:hello?qiniu.jpg`
* 资源4，`key:/hello/qiniu2.jpg`

对于资源 1 和 2，无论在浏览器中输入下面的哪种形式的 url，最终访问到的是资源 2

```
http://test.qiniudn.com/hello%2Fqiniu.jpg
```

或

```
http://test.qiniudn.com/hello/qiniu.jpg
```

对于资源4，如果在浏览器中输入`http://test.qiniudn.com//hello/qiniu2.jpg`，浏览器中将会显示: `{"error":"E404"}`，说明这个资源不存在

## 解决方案 [#解决方案]

对于示例中的资源 1 和 3，可分别通过下面的 url 进行访问：

```
http://test.qiniudn.com/hello%252Fqiniu.jpg

http://test.qiniudn.com/hello%3Fqiniu.jpg
```

多数情况下不需要手工对 url 进行转换，例如php语言，可以调用 urlencode 方法对 key 进行编码，其它语言类似。

```
<?php
    echo "http://test.qiniudn.com/".urlencode("hello%2Fqiniu.jpg")
    echo "http://test.qiniudn.com/".urlencode("hello?qiniu.jpg")
?>

```

对于示例中的资源4，上面的解决方法失效。需要通过下面的url访问：

```
http://test.qiniudn.com/@/hello/qiniu2.jpg
```

具体的编码算法如下：

```
func qiniuescape(key string) string
{
   needesc := true
   for i, ch := range key {
       if ch == '/' && needesc {
         //转义为 "@/"
       } else if ch == '@' && needesc {
         //转义为 "@@"
       }
       needesc = (ch == '/')
   }
}
```

> **如无特殊需求，建议开发者避免使用以上提到的特殊key**


# 私有空间的注意事项 (/faq/kodo/basic-use-of/4054-matters-needing-attention-of-private-space)



最近更新时间: 2020-05-15 16:34:16

公有空间与私有空间的区别，在于 [下载私有资源](/products/kodo/development-guidelines/download-process/1-download-private) ，需要带有 [下载凭证](/products/kodo/development-guidelines/security/0-download-token) 。
在七牛服务端 SDK 中，均有生成私有链接的 demo 。
另外，访问时，还需注意以下几点：

1. **测试域名不能用于私有空间。**
   测试域名的缓存时间不能更改，只能是默认的 1 个月。因此，即使签出的私有链接过期时间短于 1 个月，也有可能在链接第一次访问过了 1 个月后才会过期。
2. **自定义域名必须开启回源鉴权。**
   私有空间的自定义域名必须开启 [回源鉴权](/products/cdn/configuration-management-fusion/access-control-configuration/2-back-to-the-source-authentication)(私有空间的域名，开启回源鉴权将自动填充成私有空间的规则，无需手动输入)。这是因为，自定义域名的缓存过期时间也有可能和私有链接的过期时间有矛盾，且默认的缓存策略是带问号参数缓存。
   如果**不**开启，可能会带来以下问题：

* CDN 缓存时间长于私有链接过期时间，导致私有签名过期后仍可访问。
* 访问时如果每次访问签出的链接不同，由于默认的缓存策略是带问号参数缓存，于是每次访问都回源，不会命中缓存，严重影响访问性能。

3. **播放 hls 文件需要使用 pm3u8 服务。**
   播放 hls 文件时，需要用 [pm3u8](/products/dora/audio-and-video-processing-api/4-private-m3u8-pm3u8) 服务，对 m3u8 文件列表里的 ts 链接做签名。


# 带图片样式的私有空间文件授权 (/faq/kodo/basic-use-of/4069-take-pictures-style-file-authorization-private-space)



最近更新时间: 2020-05-15 16:34:16

# 带图片样式的私有空间授权 [#带图片样式的私有空间授权]

本文介绍了当使用了拼接了数据处理或者图片样式如何进行签名授权。

私有资源下载是通过 <span>HTTP GET</span> 的方式访问特定的    URL。私有资源 URL 与公开资源 URL 相比只是增加了两个参数 `e` 和 `token`，分别表示过期时间和[下载凭证](/products/kodo/development-guidelines/security/0-download-token)。一个完整的私有资源 URL 如下所示：

```
http://<domain>/<key>?e=<deadline>&token=<downloadToken>

```

当使用了七牛的实时数据处理功能或者拼接了图片样式时在 sdk 中进行签名授权时需要带拼接参数进行一起进行签名授权。不能在原文件签名后进行拼接参数。

如 私用空间中的文件为

原文件：    [http://xxx.qiniu.xxx/qiniu.jpg](http://xxx.qiniu.xxx/qiniu.jpg)

<br />

数据处理：  [http://xxx.qiniu.xxx/qiniu.jpg?imageslim](http://xxx.qiniu.xxx/qiniu.jpg?imageslim)

<br />

图片样式：  [http://xxx.qiniu.xxx/qiniu.jpg-style](http://xxx.qiniu.xxx/qiniu.jpg-style)

<br />

文件另存下载  [http://xxx.qiniu.xxx/qiniu.jpg?attname=lhs.jpg](http://xxx.qiniu.xxx/qiniu.jpg?attname=lhs.jpg)

<br />

\*\* 正确的使用：&#x2A;*[http://xxx.qiniu.xxx/qiniu.jpg?imageslim\&e=xxxx\&token=xxxx](http://xxx.qiniu.xxx/qiniu.jpg?imageslim\&e=xxxx\&token=xxxx)**\*\*

\*\* 错误的使用： &#x2A;*[http://xxx.qiniu.xxx/qiniu.jpg?e=xxxx\&token=xxxxx?imageslim](http://xxx.qiniu.xxx/qiniu.jpg?e=xxxx\&token=xxxxx?imageslim)**\*\*

<br />

\*\* 以 php-sdk 为例，其中的 `baseUrl` 需要为拼接参数后的 url \*\*

```
<?php
require_once __DIR__ . '/../autoload.php';
use Qiniu\Auth;
$accessKey = getenv('QINIU_ACCESS_KEY');
$secretKey = getenv('QINIU_SECRET_KEY');
// 构建Auth对象
$auth = new Auth($accessKey, $secretKey);
// 私有空间中的外链 http://<domain>/<file_key>

$baseUrl = 'http://xxx.qiniu.xxx/qiniu.jpg';
//签名时的Url需要为拼接参数后的url后进行签名
//$baseUrl= 'http://xxx.qiniu.xxx/qiniu.jpg?imageslim';
//$baseUrl = 'http://xxx.qiniu.xxx/qiniu.jpg-style';
//$baseUrl = 'http://xxx.qiniu.xxx/qiniu.jpg?attname=lhs.jpg';

// 对链接进行签名
$signedUrl = $auth->privateDownloadUrl($baseUrl);
echo $signedUrl;

```


# 存储空间的转码样式使用说明 (/faq/kodo/basic-use-of/5858-the-instructions-on-the-storage-space-of-transcoding-style)



最近更新时间: 2020-05-15 16:34:16

<a id="Parameter" />

# **转码命令参数详解** [#转码命令参数详解]

| 转码命令                    | 完整命令                                                                                                         | 命令参数                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| audio-AAC-64K           | avthumb/mp4/ab/64k/ar/44100/acodec/libfaac                                                                   | 封装：MP4，音频码率：64Kbps，音频采样率：44100Hz，音频编码格式：libfaac                                                                               |
| audio-AAC-128K          | avthumb/mp4/ab/128k/ar/44100/acodec/libfaac                                                                  | 封装：MP4，音频码率：128Kbps，音频采样率：44100Hz，音频编码格式：libfaac                                                                              |
| audio-AAC-256K          | avthumb/mp4/ab/256k/ar/44100/acodec/libfaac                                                                  | 封装：MP4，音频码率：256Kbps，音频采样率：44100Hz，音频编码格式：libfaac                                                                              |
| audio-HLS-32k           | avthumb/m3u8/segtime/10/ab/32k/ar/44100/acodec/libfaac                                                       | 封装：m3u8，切片时长：10s，音频码率：32Kbps，音频采样率：44100Hz，音频编码格式：libfaac                                                                     |
| audio-HLS-48k           | avthumb/m3u8/segtime/10/ab/48k/ar/44100/acodec/libfaac                                                       | 封装：m3u8，切片时长：10s，音频码率：48Kbps，音频采样率：44100Hz，音频编码格式：libfaac                                                                     |
| audio-HLS-64k           | avthumb/m3u8/segtime/10/ab/64k/ar/44100/acodec/libfaac                                                       | 封装：m3u8，切片时长：10s，音频码率：64Kbps，音频采样率：44100Hz，音频编码格式：libfaac                                                                     |
| audio-MP3-128K          | avthumb/mp3/ab/128k/ar/44100/acodec/libmp3lame                                                               | 封装：MP3，音频码率：128Kbps，音频采样率：44100Hz，音频编码格式：MP3 (MPEG audio layer 3)                                                             |
| audio-MP3-160K          | avthumb/mp3/ab/160k/ar/44100/acodec/libmp3lame                                                               | 封装：MP3，音频码率：160Kbps，音频采样率：44100Hz，音频编码格式：MP3 (MPEG audio layer 3)                                                             |
| audio-MP3-192K          | avthumb/mp3/ab/192k/ar/44100/acodec/libmp3lame                                                               | 封装：MP3，音频码率：192Kbps，音频采样率：44100Hz，音频编码格式：MP3 (MPEG audio layer 3)                                                             |
| audio-MP3-320K          | avthumb/mp3/ab/320k/ar/44100/acodec/libmp3lame                                                               | 封装：MP3，音频码率：320Kbps，音频采样率：44100Hz，音频编码格式：MP3 (MPEG audio layer 3)                                                             |
| video-Generic-320x240   | avthumb/mp4/ab/128k/ar/22050/acodec/libfaac/r/30/vb/300k/vcodec/libx264/s/320x240/autoscale/1/stripmeta/0    | 封装：MP4，音频码率：128Kbps，音频采样率：22050Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：300Kbps，视频编码：H.264，视频分辨率：320x240，视频按原比例缩放至分辨率，清除文件metadata    |
| video-Generic-360p-16:9 | avthumb/mp4/ab/128k/ar/44100/acodec/libfaac/r/30/vb/720k/vcodec/libx264/s/640x360/autoscale/1/stripmeta/0    | 封装：MP4，音频码率：128Kbps，音频采样率：44100Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：720Kbps，视频编码：H.264，视频分辨率：640x360，视频按原比例缩放至分辨率，清除文件metadata    |
| video-Generic-360p-4:3  | avthumb/mp4/ab/128k/ar/44100/acodec/libfaac/r/30/vb/600k/vcodec/libx264/s/480x360/autoscale/1/stripmeta/0    | 封装：MP4，音频码率：128Kbps，音频采样率：44100Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：600Kbps，视频编码：H.264，视频分辨率：480x360，视频按原比例缩放至分辨率，清除文件metadata    |
| video-Generic-480p-16:9 | avthumb/mp4/ab/128k/ar/44100/acodec/libfaac/r/30/vb/1200k/vcodec/libx264/s/854x480/autoscale/1/stripmeta/0   | 封装：MP4，音频码率：128Kbps，音频采样率：44100Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：1200Kbps，视频编码：H.264，视频分辨率：854x480，视频按原比例缩放至分辨率，清除文件metadata   |
| video-Generic-480p-4:3  | avthumb/mp4/ab/128k/ar/44100/acodec/libfaac/r/30/vb/900k/vcodec/libx264/s/640x480/autoscale/1/stripmeta/0    | 封装：MP4，音频码率：128Kbps，音频采样率：44100Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：900Kbps，视频编码：H.264，视频分辨率：640x480，视频按原比例缩放至分辨率，清除文件metadata    |
| video-Generic-720P      | avthumb/mp4/ab/160k/ar/44100/acodec/libfaac/r/30/vb/2400k/vcodec/libx264/s/1280x720/autoscale/1/stripmeta/0  | 封装：MP4，音频码率：160Kbps，音频采样率：44100Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：2400Kbps，视频编码：H.264，视频分辨率：1280x720，视频按原比例缩放至分辨率，清除文件metadata  |
| video-Generic-1080P     | avthumb/mp4/ab/160k/ar/44100/acodec/libfaac/r/30/vb/5400k/vcodec/libx264/s/1920x1080/autoscale/1/strpmeta/0  | 封装：MP4，音频码率：160Kbps，音频采样率：44100Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：5400Kbps，视频编码：H.264，视频分辨率：1920x1080，视频按原比例缩放至分辨率，清除文件metadata |
| video-HLS-150k          | avthumb/m3u8/segtime/10/ab/128k/ar/44100/acodec/libfaac/r/30/vb/150k/vcodec/libx264/stripmeta/0              | 封装：m3u8，切片时长：10s，音频码率：128Kbps，音频采样率：44100Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：150Kbps，视频编码：H.264，清除文件metadata                     |
| video-HLS-240k          | avthumb/m3u8/segtime/10/ab/128k/ar/44100/acodec/libfaac/r/30/vb/240k/vcodec/libx264/stripmeta/0              | 封装：m3u8，切片时长：10s，音频码率：128Kbps，音频采样率：44100Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：240Kbps，视频编码：H.264，清除文件metadata                     |
| video-HLS-640k          | avthumb/m3u8/segtime/10/ab/128k/ar/44100/acodec/libfaac/r/30/vb/640k/vcodec/libx264/stripmeta/0              | 封装：m3u8，切片时长：10s，音频码率：128Kbps，音频采样率：44100Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：640Kbps，视频编码：H.264，清除文件metadata                     |
| video-HLS-1000k         | avthumb/m3u8/segtime/10/ab/128k/ar/44100/acodec/libfaac/r/30/vb/1000k/vcodec/libx264/stripmeta/0             | 封装：m3u8，切片时长：10s，音频码率：128Kbps，音频采样率：44100Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：1000Kbps，视频编码：H.264，清除文件metadata                    |
| video-Web               | avthumb/mp4/ab/160k/ar/44100/acodec/libfaac/r/30/vb/2200k/vcodec/libx264/s/1280x720/autoscale/1/stripmeta/0  | 封装：MP4，音频码率：160Kbps，音频采样率：44100Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：2200Kbps，视频分辨率：1280x720，视频按原比例缩放至分辨率，视频编码：H.264，清除文件metadata  |
| video-iPhone4           | avthumb/mp4/ab/160k/ar/48000/acodec/libfaac/r/30/vb/2200k/vcodec/libx264/s/1280x720/autoscale/1/stripmeta/0  | 封装：MP4，音频码率：160Kbps，音频采样率：48000Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：2200Kbps，视频分辨率：1280x720，视频按原比例缩放至分辨率，视频编码：H.264，清除文件metadata  |
| video-iPhone4s          | avthumb/mp4/ab/160k/ar/48000/acodec/libfaac/r/30/vb/5000k/vcodec/libx264/s/1920x1080/autoscale/1/stripmeta/0 | 封装：MP4，音频码率：160Kbps，音频采样率：48000Hz，音频编码格式：libfaac，视频帧率：30Hz，视频码率：5000Kbps，视频分辨率：1920x1080，视频按原比例缩放至分辨率，视频编码：H.264，清除文件metadata |

<a id="Filename" />

# **目标文件名设置** [#目标文件名设置]

目标文件名指转码后的文件名，设置时支持使用[魔法变量](/products/kodo/development-guidelines/upload-types/0-vars#magicvar)，魔法变量引用格式为$\{var}，$(var)。

特别的，魔法变量仅支持：bucket、key、etag、fsize、mimeType、endUser、fname、ext、fprefix、keybase

举例：

1.目标文件名设置为$(fprefix)-transcode.$(ext)

2.上传文件名为butterfly.mp4，则转码后文件名为butterfly-transcode.mp4；上传文件名newcity.flv，则转码后文件名为newcity-transcode.flv


# 存储空间域名管理 (/faq/kodo/basic-use-of/5859-domain-name-to-access-the-storage-space)



最近更新时间: 2023-05-10 12:12:18

用户可以绑定自定义域名到存储空间，添加 CNAME 记录指向相应域名，然后通过自定义域名来访问存储空间里的文件。

* 自定义 CDN 加速域名：为空间绑定自定义 CDN 加速域名，可以通过 CDN 边缘节点缓存数据，提高存储空间内的文件访问响应速度。
* 自定义源站域名：绑定自定义域名为空间的源站域名，即可通过该域名直接访问存储空间内的文件。

**注意：按照中华人民共和国《互联网管理条例》的要求，所有需要绑定自定义域名的用户，必须提前将域名在工信部备案。**

<a id="CDNDomain" />

# **自定义 CDN 加速域名** [#自定义-cdn-加速域名]

Bucket 可以绑定 CDN 加速域名，利用 CDN 节点缓存数据，来实现存储空间内文件的加速访问。

* 从空间列表点击任一空间名，进入空间管理界面。
* 点击「域名管理」，在「自定义 CDN 加速域名」设置卡片单击「绑定域名」，即可打开空间的 CDN 加速域名绑定界面。

![](/docs-assets/faq/kodo/basic-use-of/5859-domain-name-to-access-the-storage-space/FlbOmcInXftkuh4NEEhW8bOGzYfp-e0ce7529eee9.webp)

* 域名需要能通过 ICP 备案检测，然后按需设置域名的通信协议、使用范围、应用场景和缓存策略即可。域名需要添加 CNAME 记录解析到指定的域名。

![](/docs-assets/faq/kodo/basic-use-of/5859-domain-name-to-access-the-storage-space/Fg-tpNBrUyaT2PZV7QntfvkjlPyB-47d50781b603.webp)

* 绑定好的域名，会在空间的自定义 CDN 加速域名列表中展示。

<a id="SrcDomain" />

# **自定义源站域名** [#自定义源站域名]

Bucket创建后，用户可以绑定自定义域名为其源站域名，然后使用自定义域名直接访问存储空间内的文件。

* 从空间列表点击任一空间名，进入空间管理界面。
* 点击「域名管理」，在「自定义源站域名」设置卡片单击「绑定域名」，即可打开空间的源站域名绑定界面。

![](/docs-assets/faq/kodo/basic-use-of/5859-domain-name-to-access-the-storage-space/Fuzeg8miehYnbruL8TSB4eDq8PAY-f30f32184d75.webp)

* 域名通过 ICP 备案检测后即可绑定成功。域名需要添加 CNAME 记录指向存储空间所在区域对应的 CNAME 域名，才能通过自定义域名访问存储空间，各区域 CNAME 域名如下：
  * 华东-浙江  iovip.qiniuio.com
  * 华东-浙江2 iovip-cn-east-2.qiniuio.com
  * 华北-河北  iovip-z1.qiniuio.com
  * 华南-广东  iovip-z2.qiniuio.com
  * 北美-洛杉矶  iovip-na0.qiniuio.com
  * 亚太-新加坡  iovip-as0.qiniuio.com
* 绑定好的域名，会在空间的自定义源站域名列表中展示。

## **开启HTTPS访问** [#开启https访问]

用户可以为源站域名开通HTTPS访问并绑定SSL证书，证书需要先行托管至七牛云的 [SSL证书服务](https://portal.qiniu.com/certificate/ssl)

![](/docs-assets/faq/kodo/basic-use-of/5859-domain-name-to-access-the-storage-space/FmwnXgR37Hiy11vy9B93iAo0ENyG-a4c8e6b2abfe.webp)

## **设置防盗链** [#设置防盗链]

为了防止数据被其他人盗链，可以设置空间防盗链功能：

* Referer白名单，仅允许指定的域名访问资源；或黑名单，指定域名禁止访问资源。
* 是否允许空Referer。如果不允许空Referer，则只有HTTP或HTTPS header中包含Referer字段的请求才能访问资源。

![](/docs-assets/faq/kodo/basic-use-of/5859-domain-name-to-access-the-storage-space/FjJxOebNeTaahmRGeNZA0N-6KLVs-52b12333272d.webp)

## **验证域名所有权** [#验证域名所有权]

当您的域名被其他用户绑定时，可以通过验证域名所有权，强制解绑此域名。
&#x2A;*说明：此步骤仅在绑定自定义源站域名提示域名冲突时可查看和操作。**

1、域名绑定冲突时，界面会提示系统依据域名信息生成的 TXT 记录。
![](/docs-assets/faq/kodo/basic-use-of/5859-domain-name-to-access-the-storage-space/Ftrx0QPKNYd3S-pPxpKWGp-NTfl0-9d16bff4c962.webp)
2、在域名解析商处添加对应的 TXT 记录，信息如下：
![](/docs-assets/faq/kodo/basic-use-of/5859-domain-name-to-access-the-storage-space/FtfgdMD5mahs2U_96SNwUuPNs-Jd-0bae839fd3bf.webp)

* 记录类型：TXT
* 主机记录：填写步骤1中显示的主机记录。
* 记录值：填写步骤1中显示的值
* 其他值保持默认
  3、在**绑定域名**弹窗中，单击**我已添加TXT验证记录，提交**，若系统验证检测信息通过，则会执行解绑。


# 如何在 Xcode 导入七牛 objc-sdk (/faq/kodo/the-common-problems-in-the-sdk/1328-how-in-the-xcode-import-seven-cows-objc-sdk)



最近更新时间: 2025-04-09 21:45:25

## 一、 使用 pod 包管理工具导入（推荐方式）。 [#一-使用-pod-包管理工具导入推荐方式]

在项目跟目录创建 PodFile 文件，输入：

platform :ios, "8.0" # 第一行指定平台和版本
pod 'AFNetworking', '~~> 3.0'
pod "Qiniu", :git => '[https://github.com/qiniu/objc-sdk.git](https://github.com/qiniu/objc-sdk.git)', :branch => 'AFNetworking-3.x'
pod 'HappyDNS', '~~> 0.2'

项目跟目录下执行 `pod install` ，成功后使用 xcode 打开新生成的 `Project.xcworkspace` 文件。
参考：
[http://www.yeolar.com/note/2015/01/02/cocoapods/](http://www.yeolar.com/note/2015/01/02/cocoapods/)
[http://guides.cocoapods.org/using/getting-started.html](http://guides.cocoapods.org/using/getting-started.html)

## 二、直接复制源码到项目 [#二直接复制源码到项目]

源码地址： [https://github.com/qiniu/objc-sdk](https://github.com/qiniu/objc-sdk)

* 右键，选择添加文件到项目

![image](/docs-assets/faq/kodo/the-common-problems-in-the-sdk/1328-how-in-the-xcode-import-seven-cows-objc-sdk/objc_to_add-7643d4b35778.webp)

* 选择文件`Added folders` 选择 `Create groups`

![image](/docs-assets/faq/kodo/the-common-problems-in-the-sdk/1328-how-in-the-xcode-import-seven-cows-objc-sdk/objc_s_add-c6c028e0cd2d.webp)

完成后：

![image](/docs-assets/faq/kodo/the-common-problems-in-the-sdk/1328-how-in-the-xcode-import-seven-cows-objc-sdk/objc_page-3955ec88255b.webp)

在 `Build Phases` --- `Compile Sources` 中已自动添加了`*.m`文件

![image](/docs-assets/faq/kodo/the-common-problems-in-the-sdk/1328-how-in-the-xcode-import-seven-cows-objc-sdk/objc_compile-f9d90619cfc1.webp)

## 导入依赖（源码导入参考） [#导入依赖源码导入参考]

7.0.12 后依赖 `HappyDNS`: [https://github.com/qiniu/happy-dns-objc](https://github.com/qiniu/happy-dns-objc) 以上面相同方式导入`HappyDNS`的源码。

至此，可正常编译、运行项目。

**注意** ：

* 若报 `Undefined symbols for architecture x86_64: "_crc32", referenced from:` ，项目中需导入 `libz.dylib`。(`Build Phases` ---`Link Binary With Libraries`)

* 若报`"_res_9_ninit", referenced from: _setup_dns_server in QNResolver.o` 等，

1. 项目中需导入 `libresolv.dylib`或`libresolv.9.dylib`。(`Build Phases` --- `Link Binary With Libraries`)；
2. 或 (`Build Settings` --- `Linking` --- `Other Linker Flags`) 添加 `-lresolv` 选项

* 报 `Thread 1: EXC_BAD_ACCESS(code=1,address=0x180f4beb8)`类似错误，将 `QN` 打头的都设置 `arc` (`Build Phases` --- `Compile Sources`)
  ![image](/docs-assets/faq/kodo/the-common-problems-in-the-sdk/1328-how-in-the-xcode-import-seven-cows-objc-sdk/objc_arc-af7eb944e040.webp)

## 链接错误 [#链接错误]

有客户导入sdk后会报链接错误 (linker command failed with exit code 1)，可以下载下这个打包好的文件，解压后直接导入工程使用

[点击下载zip](http://dn-odum9helk.qbox.me/QiniuStorageLibrary.zip)


# js sdk 使用常见问题 (/faq/kodo/the-common-problems-in-the-sdk/1329-js-sdk-using-common-problems)



最近更新时间: 2018-01-19 00:54:01

## 案例1： [#案例1]

Q：如何在文件上传后，删除上传成功的文件记录UI，只保留正在上传，和报错的文件UI。
A：要在FileUploaded方法中调用UI逻辑来实现。不要使用RemoveFile方法因为：这个方法是删除文件，终止上传的，跟UI没关系。具体的业务代码需要客户自己实现。

***

## 案例2: [#案例2]

Q：上传文件时，出现400:\{"error":"read exceed block size"} 报错

A：首先更换最新的qiniu.js,然后清除掉本地浏览器中的localstory，然后重试文件上传，如果还有错误，请用我们官方提供的默认main.js.如果成功说明是你们main.js修改的不正确导致。

***

## 案例3: [#案例3]

Q：上传的时候，如何初始化多个按钮绑定多个事件来上传？ A：可以参照[https://github.com/qiniu/js-sdk/blob/master/src/qiniu.js#L278-L293](https://github.com/qiniu/js-sdk/blob/master/src/qiniu.js#L278-L293)
中var Qiniu = new QiniuJsSDK();这是每次初始化一个对象来上传，你可以新建多个对象来上传就可以了。你新建多个对象，每次新建一个对象就可以重新获取一次token。

***

## 案例4: [#案例4]

不设置 chunk\_size 、或 chunk\_size: 0、或 chunk\_size: '0'、或 chunk\_size: '0mb' ，在html5下也是使用直传

## 案例5: [#案例5]

报错信息：

![js](/docs-assets/faq/kodo/the-common-problems-in-the-sdk/1329-js-sdk-using-common-problems/fa5deb1d04b47953870a8cf29e947c9d-f8130e8c39fd.webp)

解决方法：

![js－02](/docs-assets/faq/kodo/the-common-problems-in-the-sdk/1329-js-sdk-using-common-problems/dcf17708efef427b2fab2ad01681a83c-d0ff898a7532.webp)

将箭头的代码注释掉。

***

## 案例5: [#案例5-1]

Q：JS上传报 400，token is not spcified

A：在上传时指定upload\_url上传，需要明确在服务端生成的token的地址返回给客户端时需要返回的token是JSON格式。

***

## 案例6： [#案例6]

Q: 400 incorrect region

A: 使用静态服务器来运行demo,否则无法调用获取上传host的接口。或者更改qiniu.js中uploadhost为错误提示中的host
![](/docs-assets/faq/kodo/the-common-problems-in-the-sdk/1329-js-sdk-using-common-problems/Fvnh9Ig7XRImHhrP8ptOeHzj8n8s-7f3b3515836a.webp)

***

## 案例7： [#案例7]

Q: Moxie not defined

A: 使用2.1.1 \~ 2.1.9 版本的plupload

***

## 案例8： [#案例8]

Q: Filters在部分安卓机型微信浏览器中无法生效

A: 建议取消filters参数，直接在FileAdded里做判断，参考[http://jsdemo.gugaobai.top/scripts/main.js](http://jsdemo.gugaobai.top/scripts/main.js)


# 七牛鉴权QiniuToken (/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken)



最近更新时间: 2024-01-29 10:32:19

本文解释了生成七牛鉴权管理凭证的字符串(QiniuToken)的详细过程，共三步。

* 参考[管理凭证](/products/kodo/development-guidelines/security/access-token)，直接使用七牛支持的服务端语言 SDK 管理凭证
* 参考[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)、[下载凭证](/products/kodo/development-guidelines/security/0-download-token)，了解相关凭证的构造

# 准备工作：获取密钥（AK／SK） [#准备工作获取密钥aksk]

生成七牛鉴权凭证信息的字符串，需要用到[密钥](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken#aksk)，密钥包含AccessKey/SecretKey。第一次使用七牛的API之前，用户需要在七牛开发者平台的密钥管理中取得密钥。

**注意：** 密钥（AccessKey/SecretKey）是非常重要且隐私的信息，泄露可能会造成严重的后果，请不要直接放在客户端。

具体步骤如下：

1）登录[七牛开发者平台](https://portal.qiniu.com/signin),

2）点击［个人面板］，选择密钥管理，进入七牛的密钥管理页面,
![https://dn-odum9helk.qbox.me/2a083e0d2ef9a3c5cd59e3aa5c76e7f5](/docs-assets/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken/2a083e0d2ef9a3c5cd59e3aa5c76e7f5-f350f6dbd69f.webp)

3）在七牛的[密钥管理页面](https://portal.qiniu.com/user/key),获取一对AccessKey/SecretKey。

# Step1. 构造待签名的 Data [#step1-构造待签名的-data]

待签名的data字符串由以下几个参数构成，拼接规则为:

```
data = <Method> + " " + <Path> + "?<RawQuery>" + "\nHost: " + <Host> + "\nContent-Type: " + <contentType> + "\n\n" + <bodyStr>
```

注：\<>里面的内容需替换成相应的变量。

| 参数          | 必选 | 说明                                                                                                                         |
| :---------- | :- | :------------------------------------------------------------------------------------------------------------------------- |
| Method      | Y  | 支持 POST、PUT 和 GET 方式, 注意方法为全大写                                                                                             |
| Path        | Y  | 请求路径。实际的请求路径详见各接口说明的请求包                                                                                                    |
| RawQuery    | N  | 如不存在则不用添加 ?\<RawQuery>                                                                                                     |
| Host        | Y  | 请求域名，例如：atlab.ai                                                                                                           |
| contentType | N  | 请求内容类型，如果参数为空，则不用加 "\nContent-Type: " + \<contentType >                                                                    |
| bodyStr     | N  | 请求Body\<bodyStr>: 如果 \<Content-Length> 存在且 Body 不为空，同时 \<Content-Type> 存在且不为空也不等于 "application/octet-stream"，才加上\<bodyStr> |

**注意：无论\<Content-Length>和 \<bodyStr> 是否为空，中间的 "\n\n" 都一定要加。**

示例代码为：

```
data= <Method> + " " + <Path>

if "<RawQuery>" != "" {
        data += "?<RawQuery>"

}

data += "\nHost: " + <Host>

if "<Content-Type>" != "" {
        data += "\nContent-Type: <Content-Type>"
}

data += "\n\n"

if "<bodyStr>" != "" and
   "<Content-Type>" != "" and
   "<Content-Type>" != "application/octet-stream" {
          data += "<bodyStr>"

}

```

人脸识别的待签名字符串示例为：

```
POST /v1/face/detect
Host: argus.atlab.ai
Content-Type: application/json

{"data": {"uri":"http://img3.redocn.com/20120528/Redocn_2012052817213559.jpg"}}

```

# Step2.计算 HMAC-SHA1 签名，并对签名结果做 URL 安全的 Base64 编码 [#step2计算-hmac-sha1-签名并对签名结果做-url-安全的-base64-编码]

```
import hmac
import base64
import hashlib

sign = hmac.new("<Your_Secret_Key>", data, hashlib.sha1).digest()

encodedSign = base64.urlsafe_b64encode(sign)

```

# Step3.将 Qiniu 标识与 AccessKey、encodedSign 拼接得到管理凭证 [#step3将-qiniu-标识与-accesskeyencodedsign-拼接得到管理凭证]

```
<QiniuToken> = "Qiniu " + "<Your_Access_Key>" + ":" + encodedSign
```


# 镜像存储功能在源站 URL 含有问号时的抓取资源规则 (/faq/kodo/image-storage-common-problems/1358-image-storage-function-in-the-source-station-to-grab-resources-rules-in-effect-at-the-time-of-the-url-contains-a-question-mark)



最近更新时间: 2018-01-05 10:02:16

镜像存储功能在 [镜像存储与qrsync数据同步的使用](/faq/kodo/tools-common-problems/1345-the-combination-of-image-storage-and-qrsync-tool-data-migration-plan) 中已有介绍。在使用镜像存储的时候，七牛会回源站拉取文件，如果源 URL 中带有问号，资源会按照如下规则来抓取和存储：

1，
如果源站的 URL 是类似这样的：`http://example.com/a/b/c/d.txt?version=20130807`，那么镜像存储会将文件 `d.txt` 抓取过来，并在七牛保存为`a/b/c/d.txt` (在七牛云存储中称为 `key`)，忽略问号后面的参数。

2，如果源站的 URL 是类似这样的：`http://example.com/?version=20130807`，那么镜像存储会将访问该 URL 得到的结果保存在七牛云存储，但是保存的 key 为空的 key 值（不是不存在）。

3，如果源站的url是这样：`http://example.com/xxx.js?v=12222333332`，如果存在xxx.js这个文件，并且问号后面不同的版本号对应不同的文件，那么在抓取文件时，需要将？进行url编码后才可以正常拉取


# 七牛镜像存储使用手册 (/faq/kodo/image-storage-common-problems/1376-seven-cattle-image-storage-instruction-manuals)



最近更新时间: 2019-10-17 20:35:36

<a id="image-instruction-description" />

# **简介** [#简介]

七牛的镜像存储服务是一种快速的数据迁移和加速服务。可以帮助用户实现无缝数据迁移，迁移过程中并不影响原有业务系统的访问。镜像存储适用于迁移原有业务系统的已有数据。七牛提供分布式存储和加速分发服务，以分布式存储为核心服务。客户在准备接入七牛的时候一般有两种场景：

场景一

客户业务从设计开发的时候就采用七牛的云存储服务，这种情况下直接将文件上传到七牛，然后再使用七牛的加速分发服务即可。

场景二

客户业务已经建立起来后才准备接入七牛。这种情况下会遇到两个问题，第一个是需要修改上传的业务逻辑，第二个是如何迁移已有的数据。修改上传的业务逻辑，可能涉及到很多项目代码的修改，持续时间可能比较长。已有的数据可以使用七牛提供的同步工具[qshell](/products/kodo/0-qshell)上传到七牛，但是在上传之后由业务系统产生的新数据总不能每次都找出增量来上传，所以这个时候就可以用到镜像存储了。

<br />

<a id="image-business-model" />

# **业务模型** [#业务模型]

在镜像存储的业务模型里面，原来的图片或者视频访问域名将被配置为七牛的源站，而页面里面引用图片或视频链接的地方必须使用新的访问域名。然后将新的访问域名绑定 (CNAME) 到七牛空间对应的域名。在这些操作完成之后，终端用户就可以通过七牛访问图片或者视频等非结构化资源了。在每个访问请求到七牛的时候，如果七牛空间中不存在这个资源，那么七牛将主动回客户源站抓取资源并存储在空间里面，这样七牛就不需要再次回源客户的资源站点了。镜像存储业务模型如下:

![镜像存储业务模型](/docs-assets/faq/kodo/image-storage-common-problems/1376-seven-cattle-image-storage-instruction-manuals/FmgYGQnovQoMisC1icVwkVwQh5ih-d32ee8185891.webp)

<br />

<a id="image-configuration-steps" />

# **配置步骤** [#配置步骤]

### Step 1 [#step-1]

将非结构化数据的源站配置为七牛空间的镜像源站。选择空间，然后在空间的概览页面里，找到镜像存储，然后在镜像源对话框内填入用于回源抓取资源的源站域名。比如将空间 image1 的镜像源站配置为`http://image1.abc.com`。

### Step 2 [#step-2]

为空间申请自定义域名，该域名将是新的资源外链的域名。注意加速域名的填写，比如为空间 image1 申请自定义域名`image11.abc.com`，该域名必须是当前业务系统里面没有使用的子域名。

### Step 3 [#step-3]

自定义域名审核通过之后，在客户的DNS服务设置那里,就可以根据审核通过后提示的CNAME目标来将自定义域名绑 定到七牛的空间域名。

### Step 4 [#step-4]

修改页面中的资源引用域名为新的自定义域名。比如，将新的图片资源外链域名改为`http://image11.abc.com`。

<br />

<a id="image-faq" />

# **常见问题** [#常见问题]

Q1. 七牛的镜像存储和传统的 CDN 区别是什么？

七牛镜像存储是一种数据迁移的方式，其回源客户的源站也仅仅回源一次，成功抓取资源到七牛的空间之后，不再回源。七牛的存储外面还有一层 CDN 分发网络，这一层的 CDN 分发网络才和传统的 CDN 具有相同的功能。

<br />

Q2. 七牛的镜像存储的情况下，如何将源站更新的内容同步更新到七牛的空间？

七牛镜像存储的回源操作对相同的文件只抓取一次，后面如果客户的源站更新了文件内容，需要手动调用[镜像资源更新](/products/kodo/rs/6-prefetch)接口来更新七牛空间中的文件，保持内容和客户源站内容相同。另外七牛外围的 CDN 如果需要及时更新缓存的话，也需要利用七牛后台提供的[刷新预取](https://portal.qiniu.com/domain/refresh)功能来刷新 CDN 的缓存。如果不需要及时更新，那么等待 CDN 自动更新即可。

<br />

Q3. 七牛的镜像存储是否需要永久保留？

七牛的镜像存储是数据迁移的一种方式，之所以提供这种数据迁移方式是为了方便客户修改上传的业务逻辑。在上传的逻辑改为直传七牛之后，后续产生的新的数据将直接存储在七牛的空间。这样在镜像存储保留一段时间之后，源站的回源流量将逐渐趋于 0，这个时候就可以将镜像功能删除了。

<br />

Q4. 七牛的镜像存储需要修改资源的访问外链域名，如何使用和原有的资源域名相同的域名？

七牛的镜像存储会将原始的资源访问域名设置为源站，而新的资源访问域名必须采用和原始资源访问域名不同的域名。如果需要使用和原有资源域名相同的域名的话，首先需要将镜像源站的域名替换为一个新的子域名或者直接使用 IP 地址，然后将原有的资源域名申请配置为七牛空间的自定义域名，配置成功之后，进行 CNAME 操作，这样原有的页面里面的资源就不需要更改外链域名了。

<br />

Q4. 七牛的镜像存储回源源站时，User-Agent是什么？

七牛云镜像存储回源源站时，请求会携带固定的User-Agent信息：`<RegionID>-qiniu-imgstg-spider-1.0`，RegionID为华东z0、华南z1、华北z2、北美na0、东南亚as0。


# 使用镜像存储注意事项 (/faq/kodo/image-storage-common-problems/4067-using-image-storage-considerations)



最近更新时间: 2019-10-17 20:31:24

# 使用镜像存储，更新源站文件后，如何访问最新文件？ [#使用镜像存储更新源站文件后如何访问最新文件]

参考 [镜像存储刷新缓存方法](/faq/cdn/4215-image-storage-refresh-the-cache-method)

# 镜像源地址设置和拉取资源链接形式 [#镜像源地址设置和拉取资源链接形式]

   拉取资源链接为：镜像空间绑定的加速域名 +（源站链接-镜像源地址设置部分）

   例如：

   源站资源链接：http(s)://sourceDomain/image/123.jpg

   加速域名：a.b.com

<br />

   若镜像源地址设置为：http(s)://sourceDomain/

   则拉取资源链接：http(s)://a.b.com/image/123.jpg

<br />

   若镜像源地址设置为：http(s)://sourceDomain/image

   则拉取资源链接：http(s)://a.b.com/123.jpg

# 回源请求的User-Agent [#回源请求的user-agent]

回源源站时，请求会携带固定的User-Agent信息：`<RegionID>-qiniu-imgstg-spider-1.0`，RegionID为华东z0、华南z1、华北z2、北美na0、东南亚as0。


# windows环境下安装qshell与使用 (/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial)



最近更新时间: 2026-05-28 20:39:45

# 教程简介 [#教程简介]

本教程用于命令行初学者下载使用，且能够运行简单的命令测试能否正常使用。

本教程仅供示范，其他命令及详细操作请参考命令的 [**说明文档**](/products/kodo/0-qshell#9)。

# 安装操作步骤 [#安装操作步骤]

1. 在七牛开发者中心的 SDK & 工具中，选择合适的版本，下载到本地并解压 [**qshell文档**](/products/kodo/0-qshell)。

   <img src="/docs-assets/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial/FuG_5gO61zOJMg9UpU5BEbobZMsF-7efd44ed979e.webp" width="800" />

2. 为了方便文件的使用，可以对解压后的文件重命名为 `qshell.exe`（如果显示时隐藏了后缀，修改为 `qshell` 即可），如果解压后的文件名已经是qshell，那么忽略此步骤，参考上图

3. 将qshell复制存放入D盘，或者其他的非系统盘

4. widowns通过菜单栏搜索cmd，单击打开cmd窗口

<img src="/docs-assets/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial/FvjpJHxQQJYDSlBUg7nzYYvf_NRA-791f259f1628.webp" width="800" />

5. 由于此处我们的qshell存在在D盘，cmd进入D盘，输入 D: 切换D盘，切换后输入 qshell -v 有版本号输出后，表示qshell已经可用
   <img src="/docs-assets/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial/FmQBJZUj1cL6AiUtHw6HDLQO-Tm8-82e4b7de3139.webp" width="800" /> <br /> **注意**：如果没有对文件进行重命名，需要完整输入 `qshell文件名 -v`。如果报错无法识别的命令，请重新检查是否已经使用cmd进入了qshell.exe存放的真实目录

6. 使用 qshell 命令操作对应账号前需要进行登陆操作，登陆时需要 AK、SK 信息，获取密钥对 AK SK 可以在控制台复制，在个人中心 -  [**密钥管理**](https://portal.qiniu.com/developer/user/key)中查看。

   <img src="/docs-assets/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial/FuBPUTm5aw6rfdjLWTnApyOdDflc-4f7a650334f1.webp" width="800" />

7. 登陆时使用命令(见下图)：

   ```bash
   qshell account 填写您的ak 填写您的sk name
   ```

8. 登录后，通过 qshell account 可以展示出账号信息，表示已经登录成功
   ![37d6846b2c56c10d0c15061140202398.png](/docs-assets/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial/FuHi04mErfvV8LIBqerCURaHquJg-a0b89b0f86d7.webp)
   到此时，表示qshell已经可以正式使用，下面可以在此目录执行qshell的各种命令
   > **注意**：
   >
   > 1. 如果 AK，SK，name 首字母是 "-"，需要使用命令 `qshell account -- 填写您的ak填写您的sk name`（如图），可以避免把该项识别成命令行选项。
   > 2. qshell account 登录只需要登录一次，会记住账号，无需每次使用重复登录

<br />

<div id="L" />

# 文件列表 [#文件列表]

`listbucket2` 命令用于获取文件列表，可以根据不同的需求拉取不同的文件列表
`使用该命令行前需要先进行登陆，登陆命令参考本教程第二部分安装操作步骤。`
这里只列举几种常见的获取文件列表的需求，更多参数叠加使用，参考[**listbucket2参数文档**](https://github.com/qiniu/qshell/blob/master/docs/listbucket2.md&#x29;
&#x2A;*`注意：如果出现列举超时失败，建议先确认下本地网络情况，然后使用返回的marker标记重新执行列举命令即可。`**

**`marker的使用示例：`** 假如要列举的 bucket 名字为 "test-marker", marker 为"eyJjIjowLCJrIjoiMDkzOWM1ODU4ZmI1NGZiNzk3NTJmNjVkN2U4MWY4MmVfMTUzNTM3NzI2MDMxNV8xNTM1MzgwMjYyNDYxXzgzMjgyODAzOC0wMDAwMS5tcDQifQ=", 如果要接着这个 marker 位置继续列举，可以使用如下命令：
`qshell listbucket2 -m eyJjIjowLCJrIjoiMDkzOWM1ODU4ZmI1NGZiNzk3NTJmNjVkN2U4MWY4MmVfMTUzNTM3NzI2MDMxNV8xNTM1MzgwMjYyNDYxXzgzMjgyODAzOC0wMDAwMS5tcDQifQ= test-marker`

* <font color="#4671D5">
    <a href="#L1">获取全部文件列表</a>
  </font>
* <font color="#4671D5">
    <a href="#L2">只获取文件名</a>
  </font>
* <font color="#4671D5">
    <a href="#L3">获取指定前缀文件列表</a>
  </font>
* <font color="#4671D5">
    <a href="#L4">获取指定时间范围内的文件列表</a>
  </font>
* <font color="#4671D5">
    <a href="#L5">获取指定文件类型的文件列表</a>
  </font>

<div id="L1" />

## 获取全部文件列表 [#获取全部文件列表]

```bash
    qshell listbucket2 空间名称 -o 列表存放的本地文件名.txt
```

<div id="L2" />

## 只获取文件名 [#只获取文件名]

```bash
    qshell listbucket2 空间名称 --show-fields Key -o 列表存放的本地文件名.txt
```

<div id="L3" />

## 获取指定前缀文件列表 [#获取指定前缀文件列表]

比如想要获取前缀为 image文件夹的文件，通过 prefix

```bash
     qshell listbucket2 空间名称 --prefix "iamge/" -o 列表存放的本地文件名.txt
```

<div id="L4" />

## 获取指定时间范围内的文件列表 [#获取指定时间范围内的文件列表]

比如想要获取 2018-10-30 \~ 2018-11-03 之间上传的文件列表

```bash
     qshell listbucket2 --start 2018-10-30 --end 2018-11-03 空间名称  -o 列表存放的本地文件名.txt
```

<div id="L5" />

## 获取指定文件类型的文件列表 [#获取指定文件类型的文件列表]

比如想要获取 空间内的低频文件列表
file-types参上个月：根据列举前缀列举整个空间，然后从中筛选出满足七牛存储类型的文件；配置多个存储类型时中间用逗号隔开（eg: 1,2,3）；0：普通存储，1：低频存储，2：归档存储，3：深度归档存储，4：归档直读存储。

```bash
     qshell listbucket2  空间名称 --file-types 2  -o 列表存放的本地文件名.txt
```

# 单文件上传 [#单文件上传]

`rput` 命令用于上传大文件，命令参数详解参考 [**rput说明文档**](https://github.com/qiniu/qshell/blob/master/docs/rput.md)。

1. 使用该命令行前需要先进行登陆，登陆命令参考本教程第二部分安装操作步骤。
2. 执行命令：
   ```bash
   qshell rput bucket名 上传后文件名 本地文件的绝对路径或者相对路径(更简单的方式直接拖拽文件到cmd中)
   ```
   <img src="/docs-assets/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial/Fm5bt8cFDvq-IyjDOZEnmjarIAXu-76716d5760f3.webp" width="500" />

# 批量上传 [#批量上传]

`qupload2` 命令用于批量上传本地或者主机服务器某个文件夹下的文件全部上传到存储，命令参数详解参考 [**qupload2说明文档**](https://github.com/qiniu/qshell/blob/master/docs/qupload2.md)。
`使用该命令行前需要先进行登陆，登陆命令参考本教程第二部分安装操作步骤。`

```bash
    qshell qupload2 --src-dir=本地文件夹相对路径或者绝对路径 --bucket=空间名称
```

# 批量下载 [#批量下载]

`qdownload2` 用于批量下载空间内文件，命令参数详解参考 [**qdownload2说明文档**](https://github.com/qiniu/qshell/blob/master/docs/qdownload2.md)。
使用该命令行前需要先进行登陆，登陆命令参考本教程第二部分安装操作步骤。

## 批量下载空间内全部文件 [#批量下载空间内全部文件]

1. 执行命令：

   ```bash
   qshell qdownload2 --dest-dir=本地文件夹相对路径或者绝对路径 --bucket=空间名称
   ```

   > 注意：配置文件参数在当前 cmd 命令行所在目录下时，可以直接输入文件名。如果非本目录下，需要输入完整路径，如 `qshell qdownload2 --dest-dir=E:\qiniu-data\ --bucket=空间名称`。

   <img src="/docs-assets/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial/FgqR4D7v9hAHbQhfHK_kKSNUvtki-8a1f05c1c3d9.webp" width="500" />

2. 运行结果，保存路径不变的情况下会进行增量下载，详细日志信息可以在输出的 log 路径查看。

   <img src="/docs-assets/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial/FlGpwxmQ0lvojtb-U27UWGO7XWeF-a381c0ee9f4e.webp" width="500" />

## 批量下载空间内指定目录的文件 [#批量下载空间内指定目录的文件]

比如想要下载 image 目录的文件, 通过设置 prefix 内容即可

```bash
 qshell qdownload2 --dest-dir=本地文件夹相对路径或者绝对路径 --bucket=空间名称 --prefix="image/"
```

# 批量删除 [#批量删除]

`文件一旦删除，无法恢复，请务必慎重处理！`
`batchdelete` 用于批量下删除空间内的文件，需要先获对应的<font color="#4671D5"><a href="#L">文件列表</a></font>，然后基于列表删除，[batchdelete**说明文档**](https://github.com/qiniu/qshell/blob/master/docs/batchdelete.md)。
`使用该命令行前需要先进行登陆，登陆命令参考本教程第二部分安装操作步骤。`

## 批量删除空间内全部文件 [#批量删除空间内全部文件]

1. 执行命令，获取空间内全部文件：
   ```bash
   qshell listbucket2 空间名称 --show-fields Key -o todelete.txt
   ```

2. 等待1执行完毕后，基于1的todelete.txt做文件批量删除
   ```bash
   qshell batchdelete 空间名称 -i todelete.txt
   ```

## 批量删除指定时间内的文件 [#批量删除指定时间内的文件]

比如想要删除2024年6月之前上传的文件

1. 执行命令，获取指定时间内的文件列表名称：
   ```bash
   qshell listbucket2 空间名称 --show-fields Key --start 2010-01-01 --end 2024-05-31 -o todelete.txt
   ```

2. 等待1执行完毕后，基于1的todelete.txt做文件批量删除
   ```bash
   qshell batchdelete 空间名称 -i todelete.txt
   ```

# 批量修改历史文件生成周期 [#批量修改历史文件生成周期]

`空间的生命周期删除后，删除后上传的文件没有生命周期，但是删除前上传的生命周期默认不会消失！`
`batchchlifecycle` 用于批量修改文件生命周期，需要先获对应的<font color="#4671D5"><a href="#L">文件列表</a></font>，然后基于列表批量修改，[batchchlifecycle**说明文档**](https://github.com/qiniu/qshell/blob/master/docs/batchchlifecycle.md)。
`使用该命令行前需要先进行登陆，登陆命令参考本教程第二部分安装操作步骤。`

\--to-ia-after-days：指定文件上传后并在设置的时间后转换到 低频存储类型；值范围为 -1 或者大于 0，设置为 -1 表示取消已设置的转 低频存储 的生命周期规则，单位：天【可选】

\--to-archive-ir-after-days：指定文件上传后并在设置的时间后转换到 归档直读存储类型；值范围为 -1 或者大于 0，设置为 -1 表示取消已设置的转 归档直读存储 的生命周期规则，单位：天【可选】

\--to-archive-after-days：指定文件上传后并在设置的时间后转换到 归档存储类型；值范围为 -1 或者大于 0，设置为 -1 表示取消已设置的转 归档存储 的生命周期规则，单位：天【可选】

\--to-deep-archive-after-days：指定文件上传后并在设置的时间后转换到 深度归档存储类型；值范围为 -1 或者大于 0，设置为 -1 表示取消已设置的转 深度归档存储 的生命周期规则，单位：天【可选】

\--delete-after-days：指定文件上传后并在设置的时间后进行 过期删除，删除后不可恢复；值范围为 -1 或者大于 0，设置为 -1 表示取消已设置的 过期删除 的生命周期规则，单位：天【可选】

## 取消历史文件全部的生成周期 [#取消历史文件全部的生成周期]

1. 执行命令，获取空间内全部文件：
   ```bash
   qshell listbucket2 空间名称 --show-fields Key -o releaselifecycle.txt
   ```

2. 等待1执行完毕后，基于1的releaselifecycle.txt，批量取消生命周期
   ```bash
   qshell batchchlifecycle if-pbl -i releaselifecycle.txt
   --to-ia-after-days -1 \
   --to-archive-ir-after-days -1 \
   --to-archive-after-days -1 \
   --to-deep-archive-after-days -1 \
   --delete-after-days -1
   ```

## 对历史文件设置生成周期，30天后自动删除 [#对历史文件设置生成周期30天后自动删除]

1. 执行命令，获取空间内全部文件：
   ```bash
   qshell listbucket2 空间名称 --show-fields Key -o releaselifecycle.txt
   ```

2. 等待1执行完毕后，基于1的releaselifecycle.txt做文件批量修改生命周期
   ```bash
   qshell batchchlifecycle 空间名称 -i releaselifecycle.txt --delete-after-days 30
   ```

# 批量解冻归档文件 [#批量解冻归档文件]

1. 执行命令，获取空间内的归档文件列表
   `qshell listbucket2 空间名称 --file-types 2 --show-fields Key -o releaselifecycle.txt`

2. 等待1执行完毕后，基于1的releaselifecycle.txt做归档文件批量解冻操作，比如解冻5天
   `qshell batchrestorear 空间名称 5 -i releaselifecycle.txt`

# 批量解冻深度归档文件 [#批量解冻深度归档文件]

1. 执行命令，获取空间内的深度归档文件列表
   `qshell listbucket2 空间名称 --file-types 3 --show-fields Key -o releaselifecycle.txt`

2. 等待1执行完毕后，基于1的releaselifecycle.txt做深度归档文件批量解冻操作，比如解冻5天
   `qshell batchrestorear 空间名称 5 -i releaselifecycle.txt`

# 批量修改存储类型 [#批量修改存储类型]

1. 归档或深度归档存储文件，转换前需要先做解冻操作，解冻完成后才能进行存储类型修改，解冻参考上述【批量解冻深度归档文件】和【批量解冻归档文件】步骤
2. 标准存储、归档直读、低频存储和智能分层存储类型可以直接转换
3. 转换命令示例
   A、先列举出需要转换的文件名列表，参考上述【文件列表】步骤
   B、在 列表存放的本地文件名.txt 文件中添加目标存储类型，0:标准存储 1:低频存储 2:归档存储 3:深度归档 4:归档直读存储 5:智能分层存储；处理命令示例
   `awk '{print $1"\t0"}' 列表存放的本地文件名.txt > 新的列表存放的本地文件名.txt`
   C、批量修改存储类型
   `qshell batchchtype 空间名 新的列表存放的本地文件名.txt`


# 批量修改生命周期 (/faq/kodo/tools-common-problems/12969-kodo-batch-alt-lifecycle)



最近更新时间: 2026-08-18 11:55:55

## 关于生命周期 [#关于生命周期]

空间的生命周期删除后，删除后上传的文件没有生命周期，但是删除前上传的生命周期默认不会消失！

## 取消/修改文件生命周期 [#取消修改文件生命周期]

七牛提供如下解决方案：

* 七牛工具 [qshell](/products/kodo/0-qshell) 进行批量修改，`适用于大量文件、没有目录结构文件`，优先推荐使用qshell,,windows使用参考这里，[windows安装使用教程](/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial#2)

* [官方服务端SDK](/sdk-tools/sdk#official-sdk)，使用SDK方法和API修改文件生命周期，不推荐

## 使用经验 [#使用经验]

### qshell 修改生命周期 [#qshell-修改生命周期]

<br />

`使用batchchlifecycle 和 listbucket2 前，必须先登录账号，使用qshell account 进行登录，如果已经登陆过，那么无需重复登录`。ak sk 空间名称如果不了解是什么，可以阅读[常见的关键参数](/faq/kodo/7450-the-third-party-plug-in-key-parameters) , 想要获取指定的文件列表，可以参考[批量获取文件列表](/faq/kodo/basic-use-of/12958-kodo-batch-keylist),listbucket2的参数不同，就会获取不同的待修改的文件列表。

```bash
  qshell account 您的ak 您的sk 账号邮箱(名称)
```

\--to-ia-after-days：指定文件上传后并在设置的时间后转换到 低频存储类型；值范围为 -1 或者大于 0，设置为 -1 表示取消已设置的转 低频存储 的生命周期规则，单位：天【可选】

\--to-archive-ir-after-days：指定文件上传后并在设置的时间后转换到 归档直读存储类型；值范围为 -1 或者大于 0，设置为 -1 表示取消已设置的转 归档直读存储 的生命周期规则，单位：天【可选】

\--to-archive-after-days：指定文件上传后并在设置的时间后转换到 归档存储类型；值范围为 -1 或者大于 0，设置为 -1 表示取消已设置的转 归档存储 的生命周期规则，单位：天【可选】

\--to-deep-archive-after-days：指定文件上传后并在设置的时间后转换到 深度归档存储类型；值范围为 -1 或者大于 0，设置为 -1 表示取消已设置的转 深度归档存储 的生命周期规则，单位：天【可选】

\--delete-after-days：指定文件上传后并在设置的时间后进行 过期删除，删除后不可恢复；值范围为 -1 或者大于 0，设置为 -1 表示取消已设置的 过期删除 的生命周期规则，单位：天【可选】

### 取消历史文件全部的生成周期 [#取消历史文件全部的生成周期]

1. 执行命令，获取空间内全部文件：

```bash
qshell listbucket2 空间名称 --show-fields Key -o releaselifecycle.txt
```

2. 等待1执行完毕后，基于1的releaselifecycle.txt，批量取消生命周期

```bash
qshell batchchlifecycle if-pbl -i releaselifecycle.txt
   --to-ia-after-days -1 \
   --to-archive-ir-after-days -1 \
   --to-archive-after-days -1 \
   --to-deep-archive-after-days -1 \
   --delete-after-days -1
```

### 对历史文件设置生成周期，30天后自动删除，注意，文件一旦删除，不可恢复！ [#对历史文件设置生成周期30天后自动删除注意文件一旦删除不可恢复]

1. 执行命令，获取空间内全部文件：

```bash
qshell listbucket2 空间名称 --show-fields Key -o releaselifecycle.txt
```

2. 等待1执行完毕后，基于1的releaselifecycle.txt做文件批量修改生命周期

```bash
qshell batchchlifecycle if-pbl -i releaselifecycle.txt --delete-after-days 30
```

### SDK删除 [#sdk删除]

以java为列：
参考
1：获取文件名称
/products/kodo#rs-list
2：基于list获取的文件名称，调用API进行处理
/products/kodo/rs/8062-modify-object-life-cycle
其他SDK类似，可参考[官方服务端SDK](/sdk-tools/sdk#official-sdk)


# 镜像存储与qshell工具相结合的数据迁移方案 (/faq/kodo/tools-common-problems/1345-the-combination-of-image-storage-and-qrsync-tool-data-migration-plan)



最近更新时间: 2025-04-09 15:28:15

>

传统的数据迁移方案是：关掉网站原来的数据上传通道，所有数据变成只读，然后将所有数据上传到新的存储节点，再将上传入口改为新的存储节点，之后开放网站的上传功能。这样带来的问题是，数据迁移过程中，用户长时间不能进行上传操作，用户体验非常差。如何解决这个问题呢？

七牛云提供一套结合镜像存储和[qshell工具](/products/kodo/0-qshell)的数据迁移方案，这套方案很好地绕开了传统迁移方案所带来的问题。先通过七牛的数据上传工具 qshell 将大量冷数据传到七牛平台上，并将数据访问地址切换成七牛的域名。由于用户生成的大量热数据还在自己的平台上，为了不出现数据丢失的情况，保证用户访问的流畅性，那就选用七牛的镜像存储服务吧。

七牛的镜像存储为整个数据迁移过程提供良好的过渡支持作用。当用户访问的数据不在七牛平台上时，镜像存储服务将回客户源站抓取数据，并保存在七牛平台上。故此，镜像存储对每个资源只需回源一次，后续访问的时候就不再回源了。另外，镜像存储与 qshell 数据同步工具一起使用，可以很好地将你的网站数据在无需中断服务的情况下迁移到七牛云。下面介绍一下具体数据迁移的步骤：

**假设源站所有的图片，放在一个叫 img.example.com 子域里。那么迁移的方式如下：**

1. 在七牛上建立一个镜像 bucket，设定源站为 img.example.com。假设镜像 bucket 是 example-img，镜像 bucket 对应的域名为 example-img.qiniudn.com。

2. 将所有对外使用的图片的域名改为 example-img.qiniudn.com。

3. 如果网站数据是 UGC（用户产生内容）的，调整上传流程，传到七牛的镜像 bucket。这样源站就变成只读。

4. 使用 qshell 同步工具将历史数据全部同步到七牛的镜像 bucket。

如此就完成整个迁移过程。此时 img.example.com 这个源站就可以废弃不用了。

你可能会问：如果我希望保留 img.example.com 这个对外的域名，而不是用 example-img.qiniudn.com，可以么？答案是肯定的，不过会相对麻烦点，额外的操作如下：

1. 您的源站需要指定为另一个域名（不能是 img.example.com 了），比如是 img-src.example.com，或者直接用 IP。

2. 将 img.example.com 作为自定义域名绑定到七牛的镜像 bucket，此时 img.example.com上没有进行解析操作。自定义域名的生效时间最长为12小时左右。

3. 测试镜像存储如你所愿正常工作后，将 img.example.com CNAME 到返回的地址上。这一步务必小心不要做错，因为这之后你的网站就通过七牛的镜像存储进行服务了。出于谨慎，建议先在本地修改 hosts 文件，将 img.example.com 指向 example-img.qiniudn.com 的 IP 地址进行测试。


# 使用 qshell 同步目录 (/faq/kodo/tools-common-problems/1685-using-qshell-synchronize-directories)



最近更新时间: 2018-12-06 15:26:25

# 简介 [#简介]

该文档主要介绍使用 qshell 如何同步本地文件目录到存储空间并体现出层级结构。

<br />

# 环境 [#环境]

系统介绍：Linux（ ubuntu16.04 ）

要上传的资源目录：

![](/docs-assets/faq/kodo/tools-common-problems/1685-using-qshell-synchronize-directories/Fuz2M1jqyfuonqSaFoYzUv6JVSS5-c50fe99044b3.webp)

<br />

# 配置 [#配置]

<br />

## 第一步：工具下载 [#第一步工具下载]

命令行工具 qshell [传送门](/products/kodo/0-qshell)

本例下载工具版本如下：

| 文件名                | 描述          |
| ------------------ | ----------- |
| qshell\_linux\_x64 | Linux 64位系统 |

文件下载后重命名并赋予qshell执行权限，命令行操作如下：

```
$ mv qshell-linux-x64 qshell
$ chmod +x qshell
```

<br />

## 第二步：配置环境变量 [#第二步配置环境变量]

本例使用最简便的方法，直接放到环境变量。命令行操作如下：

```
$ sudo mv qshell /usr/bin/
```

<br />

操作完成后再重新开启一个终端既可运行 qshell，如下：

```
$ qshell
Use help or help [cmd1 [cmd2 [cmd3 ...]]] to see supported commands.
```

<br />

## 第三步：配置账户 [#第三步配置账户]

需要鉴权的命令都需要依赖七牛账号下的 AccessKey 和 SecretKey 。[传送门](https://portal.qiniu.com/user/key)

```
$ qshell account <Your AccessKey> <Your SecretKey>
```

操作完成后可以使用命令 `qshell account` 查看当前用户设置的 AccessKey 和 SecretKey 。

<br />

此处操作后在当前用户主目录中生成 qshell 目录：

```
$ ls ~/.qshell/
account.json
```

<br />

## 第四步：编写同步目录文件 [#第四步编写同步目录文件]

在上文提到的 qshell 目录中创建配置文件，文件内容如下：

```
$ cat upload.conf
{
    "src_dir" : "/home/boponik/XBOX",
    "bucket" : "xbox"
}
```

<br />

注意：

如果想要忽略本地文件的相对路径，比如本地存在一些层级；
但是层级里面的文件和外面的文件名称和内容都相同的情况下，为了避免重复上传不需要的文件，可以使用忽略本地文件的相对路径的方法。

则配置文件为：

```
$ cat upload.conf
{
    "src_dir" : "/home/boponik/XBOX",
    "ignore_dir" : true,
    "bucket" : "xbox"
}
```

<br />

## 第五步：同步资源 [#第五步同步资源]

详细参数说明：[https://github.com/qiniu/qshell/blob/master/docs/qupload.md](https://github.com/qiniu/qshell/blob/master/docs/qupload.md)

```
qshell qupload <LocalUploadConfig> [flags]
```

<br />

### 同步资源 [#同步资源]

![](/docs-assets/faq/kodo/tools-common-problems/1685-using-qshell-synchronize-directories/FpVk2u7wYkPHWfptBAjxogkiozgA-6fc7d549b57c.webp)

<br />

### 查看同步日志 [#查看同步日志]

![](/docs-assets/faq/kodo/tools-common-problems/1685-using-qshell-synchronize-directories/FiUi2VTmVENCIrIlO7l1vEyiKV-E-3220f4bed037.webp)

<br />

### 控制台查看资源 [#控制台查看资源]

到七牛云控制台进入空间 xbox

![](/docs-assets/faq/kodo/tools-common-problems/1685-using-qshell-synchronize-directories/FghHOFh-P9-aQ56fASm3vxmWyalu-da0a28e0135d.webp)


# 视频教程--命令行工具使用 (/faq/kodo/tools-common-problems/3858-video-of-how-to-use-qrs-tools)



最近更新时间: 2021-02-22 17:05:28

### qshell 工具使用教程 [#qshell-工具使用教程]

[qshell mac & linux](https://dn-odum9helk.qbox.me/spjc/7.mp4)

[qshell windows](https://dn-odum9helk.qbox.me/spjc/qshell-win.mp4)

<br />

<br />

### qrsctl 工具使用教程 [#qrsctl-工具使用教程]

[qrsctl mac & linux](https://dn-odum9helk.qbox.me/spjc/avthumb/qrsctl.mov.mp4)

[qrsctl windows](https://dn-odum9helk.qbox.me/spjc/qrsctl-win.mp4)

<br />

<br />

### qfetch 工具使用教程 [#qfetch-工具使用教程]

[qfetch mac & linux](https://dn-odum9helk.qbox.me/spjc/avthumb/qfetch.mov.mp4)


# 批量上传 (/faq/kodo/upload-download-problem/12950-kodo-batch-upload)



最近更新时间: 2026-05-26 13:55:51

# 关于上传 [#关于上传]

目前存储控制台不支持批量上传文件，存储这边也不支持上传压缩包在空间内解压；上传API都是单文件上传的API，每个API一次只能上传1个文件，如果需要批量上传文件到存储空间，只能使用工具或者SDK才可以

## 七牛提供如下解决方案： [#七牛提供如下解决方案]

* 服务端，在上传的业务逻辑里加个循环，或者开启多线程、多协程实现并发上传
* 客户端，使用多线程或多协程的方式，发送多个上传请求，每个请求各自上传各自的文件

### 服务端SDK [#服务端sdk]

七牛提供的SDK 默认都是使用单API上传文件，如果需要并发，建议在此基础上，创建线程池管理每个上传，服务端SDK可以参考[官方SDK](/sdk-tools/sdk#official-sdk)

## 批量上传工具 [#批量上传工具]

快速上手的工具推荐下面两个

* [图形界面化工具](/products/kodo/1-kodo-browser)，可拖拽本地目录上传，适合少量文件上传，文件量过多不建议使用
* [命令行工具](/products/kodo/0-qshell)，利用qshell的qupload或者qupload2命令批量上传，优先推荐使用qupload2上传

使用quload2前，必须先登录账号，使用qshell account 进行登录，如果已经登陆过，那么无需重复登录。ak sk 空间名称如果不了解是什么，可以阅读[常见的关键参数](/faq/kodo/7450-the-third-party-plug-in-key-parameters)

```bash
  qshell account 您的ak 您的sk 空间名称
  qshell qupload2 --src-dir=本地文件夹相对路径或者绝对路径 --bucket=空间名称

```

### 使用经验 [#使用经验]

由于qshell是一个脚本命令行工具，所以需要在cmd或者终端中运行，mac与linux系统会经常使用到终端，下载合适版本到本地解压，直接chmod +x qshell 即可执行命令行。
`但是如果您需要使用windows操作系统的话，可能您对cmd不是那么熟悉，推荐参考这里`
[**windows环境下安装qshell教程**](/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial#2)


# 如何上传base64编码图片到七牛云 (/faq/kodo/upload-download-problem/1326-how-to-upload-photos-to-seven-niuyun-base64-code)



最近更新时间: 2023-05-08 10:15:37

## 接口说明 [#接口说明]

POST /putb64/\<Fsize>/key/\<EncodedKey>/mimeType/\<EncodedMimeType>/crc32/\<Crc32>/x:user-var/\<EncodedUserVarVal>
Host: upload.qiniup.com
Authorization: UpToken \<UpToken>
Content-Type: application/octet-stream

\<Base64EncodedFileContent>

| 参数名称                       | 必填 | 说明                                                                                                                                                                                     |
| -------------------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/&lt;Fsize&gt;`           | 是  | 文件大小。支持传入 -1 表示文件大小以 http request body 为准。                                                                                                                                             |
| `/&lt;EncodedKey&gt;`      | 否  | 如果没有指定则：如果 uptoken.SaveKey 存在则基于 SaveKey 生产 key，否则用 hash 值作 key。EncodedKey 需要经过 base64 编码。具体可以参照：[URL 安全的 Base64 编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。 |
| `/&lt;EncodedMimeType&gt;` | 否  | 文件的 MIME 类型，默认是 application/octet-stream。EncodedMimeType 需要经过 base64 编码。具体可以参照：[URL 安全的 Base64 编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。                   |
| `/&lt;Crc32&gt;`           | 否  | 文件内容的 crc32 校验值，不指定则不进行校验。                                                                                                                                                             |
| `Host`                     |    | upload.qiniup.com(华东区域加速上传域名) ，不同区域的http 和 https 域名详见[不同存储区域对应的上传域名](/products/kodo/2-region-endpoint-fq)                                                                              |
| `UpToken`                  | 是  | 上传凭证，需要自行使用七牛算法单独构造生成，具体参考文档[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)                                                                                      |

返回包：

200 OK \{
  hash: \<ETag>
}

### 通过javascript方式上传 [#通过javascript方式上传]

javascript代码：

function putb64()\{
  var pic = "填写你的base64后的字符串";
  var url = "[http://upload.qiniup.com/putb64/20264](http://upload.qiniup.com/putb64/20264)"; //非华东空间需要根据注意事项 1 修改上传域名
  var xhr = new XMLHttpRequest();
  xhr.onreadystatechange=function()\{
    if (xhr.readyState==4)\{
      document.getElementById("myDiv").innerHTML=xhr.responseText;
    }
  }
  xhr.open("POST", url, true);
  xhr.setRequestHeader("Content-Type", "application/octet-stream");
  xhr.setRequestHeader("Authorization", "UpToken 填写你从服务端获取的上传token");
  xhr.send(pic);
}

**注意事项：**

* upload.qiniup.com 上传域名适用于华东空间。华北空间使用 upload-z1.qiniup.com，华南空间使用 upload-z2.qiniup.com，北美空间使用 upload-na0.qiniup.com。
* `var url = "http://upload.qiniup.com/putb64/20264";`这里的 20264 是图片没经过 base64 处理的原图字节大小。
* `xhr.setRequestHeader("Authorization", "UpToken 填写你从服务端获取的上传token");`这里的 UpToken 与后面的字符串保留一个空格。后面跟上服务端请求的 token 字符串。
* 获取文件大小的时候，切记要通过文件流的方式获取。而不是通过图片标签然后转换后获取。
* `var url = "http://upload.qiniup.com/putb64/20264";`中可以扩展为以下方式：`http://upload.qiniup.com/putb64/Fsize/key/EncodedKey/mimeType/EncodedMimeType/x:user-var/EncodedUserVarVal`。

举例：

上传后并指定自定义的 key：`http://upload.qiniup.com/putb64/12345/key/usxxeigng=`

### 通过java后台方式上传 [#通过java后台方式上传]

import java.io.File;
import java.io.FileInputStream;
import com.qiniu.util.&#x2A;;
import okhttp3.*;
public class put64 \{
    String ak = "";
    String sk = "";    // 密钥配置
    Auth auth = Auth.create(ak, sk);    // TODO Auto-generated constructor stub 
    String bucketname = "";    //空间名
    String key = "";    //上传的图片名

    public String getUpToken() \{        
        return auth.uploadToken(bucketname, null, 3600, new StringMap().put("insertOnly", 1));
    }    
    public void put64image() throws Exception \{
        String file = "D:\Documents\Pictures\1.png";//图片路径
        FileInputStream fis = null;        
        int l = (int) (new File(file).length());        
        byte\[] src = new byte\[l];
        fis = new FileInputStream(new File(file));
        fis.read(src);
        String file64 = Base64.encodeToString(src, 0);
        String url = "[http://upload.qiniup.com/putb64/](http://upload.qiniup.com/putb64/)" + l+"/key/"+ UrlSafeBase64.encodeToString(key);
//非华东空间需要根据注意事项 1 修改上传域名
        RequestBody rb = RequestBody.create(null, file64);
        Request request = new Request.Builder().
                url(url).
                addHeader("Content-Type", "application/octet-stream")
                .addHeader("Authorization", "UpToken " + getUpToken())
                .post(rb).build();
        System.out.println(request.headers());

        OkHttpClient client = new OkHttpClient();
        okhttp3.Response response = client.newCall(request).execute();
        System.out.println(response);
    }   
     public static void main(String\[] args) throws Exception \{   
          new put64().put64image();
    }
}

demo：
[http://dn-odum9helk.qbox.me/base64-demo.html](http://dn-odum9helk.qbox.me/base64-demo.html)


# 上传 401 错误码 (/faq/kodo/upload-download-problem/1330-upload-error-code-401)



最近更新时间: 2025-04-10 15:38:53

## 一、报错：`{"error":"expired token"}，{“error”:”token out of date”}` [#一报错errorexpired-tokenerrortoken-out-of-date]

### 处理方法： [#处理方法]

1、将token的有效期设置的长一些。对于比较大的文件，可以适当加长有效期（默认是3600秒）

2、看下自己的服务器时间是否是联网时间。如果时间不准，导致签名后的结果可能已经是过期的了

3、建议客户每次上传都重新请求一次上传token。或者设置的时间长些

## 二、报错：`{"error":"bad token","reqid":"t1wAAHuwANZHl9YT","details":["UP:4/401"],"code":401}` [#二报错errorbad-tokenreqidt1waahuwanzhl9ytdetailsup4401code401]

### 处理方法： [#处理方法-1]

1、检查密钥（ak，sk复制黏贴有误）信息是否正确。

2、数字签名错误（签名方法是自己写的）， 建议使用sdk中封装的方法。

3、检查上传参数，上传token由三部分组成（由冒号隔开），最后一段，用base64解码，可以看到你的上传策略中的参数，如果参数有问题也会报401。

4、如果使用我们的sdk生成的token出现的问题，把token给我们（七牛后台耳机图标：提交工单）， 如果是自己写的，请检查token生成的相关代码。

## 三、使用七牛sdk生成的token还是报错401 [#三使用七牛sdk生成的token还是报错401]

如果客户端获取到从服务端生成的token上传报错401，在确认ak和sk没有问题的情况下，则可以使用curl工具模拟上传一下。

curl -v -F 'key=1111' -F 'token=g8D\_Ledyo2iocGucAXSMEJqPFDly70AaHKCpQznb:5-oM4A7Hv8DTS1DVwBjE56x85sw=:eyJzY29wZSI6Inpob3VjaHVhbmciLCJkZWFkbGluZSI6MTQyNjc0NjY0Mn0=' -F 'file=/usr/local/test.txt' upload.qiniup.com

其中key为上传文件名，file为本地文件路径;

如果可以正常响应hash和key则说明token是没有问题，客户端获取token出现了问题。


# 七牛云上传下载操作指南 (/faq/kodo/upload-download-problem/1336-upload-download-instructions)



最近更新时间: 2022-02-17 12:06:53

# **上传方式** [#上传方式]

七牛云提供多种上传方式，包括命令行，及 11 种语言 SDK，都可以在我们的[七牛开发者中心](/faq/kodo/upload-download-problem/1336-upload-download-instructions)找到。

## **准备工作** [#准备工作]

在上传之前，你需要在 portal.qiniu.com 注册并激活成功，创建了一个 bucket，并且根据自己的情况将 bucket 设置为公开或者私有。

## **生成上传 token** [#生成上传-token]

为了安全起见，我们所有上传操作都是要有 token 的，各种 SDK 都有 token 生成函数。 生成 token 的必备要素:

* bucket，准备工作完成后已经创建了 bucket

* access key, secret key，我们的 SDK 验证都是通过这个进行验证，而不是账号密码，请到 portal 的账户设置中去查看

* 过期时间，各 SDK 默认是一小时的，您可以加长这个时间

* 上传策略，将 bucket，和过期时间放入上传策略的参数中，就可以生成最简单的策略，为了满足用户的不同需要具体策略还有很多配置，这里我们先不管。

根据上传策略，我们就可以利用 SDK 生成 token 了。从安全的角度考虑，我们不推荐在客户端直接用 access key 和 secret key 直接生成 token 的。您可以根据自己的情况，从我们的服务端 SDK 进行选择，来生成 token。

package util;
import com.qiniu.api.rs.\*;
import com.qiniu.api.config.Config;
import com.qiniu.api.auth.digest.Mac;
import com.qiniu.api.net.CallRet;
public class Qiniu \{
public static String uploadToken(String bucket, String accessKey, String secretKey)\{
PutPolicy upPolicy = new PutPolicy(bucket);
upPolicy.endUser = user;
upPolicy.callbackUrl = callbackUrl;
upPolicy.callbackBody = "key=$(key)\&hash=$(etag)\&width=$(imageInfo.width)\&height=$(imageInfo.height)\&user=$(endUser)\&size=$(fsize)\&mime=$(mimeType)";
String token = null;
Mac mac = new Mac(accessKey, secretKey);
try\{
token = upPolicy.token(mac);
}catch (Exception e)\{
e.printStackTrace();
}
return token;
}
}

## **开始上传** [#开始上传]

我们有两类上传 API，一种是简便的直接上传，另一种是加入断点续传及重传的 API，我们先从直传上手。如果没有任何报错，证明已经上传成功了。

PutPolicy putPolicy = new PutPolicy(bucketName);
Mac mac = new Mac(accessKey, secretKey);
String uptoken = putPolicy.token(mac);
String localFile = "test.png";
PutExtra extra = new PutExtra();
PutRet ret = IoApi.putFile(uptoken, key, localFile, extra);

## **浏览已经上传的文件** [#浏览已经上传的文件]

可以到 portal 中查看，或者使用列表 API 去下载，使用 stat API 去查看文件

## **如何实现客户服务器能够及时同步文件信息** [#如何实现客户服务器能够及时同步文件信息]

使用 callback, 或者 return url 的方式把文件信息通知到自己的服务器，因为七牛云讲究一个快字，所以如果用户上传到您那里，再从您那里上传到七牛就太慢了。所以我们提供了这样一种方式去同步信息，您只要按格式去填写关心的信息字段，生成 token 就好了，简单的说有 4 类字段

1. 文件信息字段
2. 文件内容信息字段，我们支持将图片文件的元信息传给您，比如宽，高
3. 自定义字段，上传时使用 x:custorm\_param 就可以传自己的字段。
4. 进行其他操作的预置字段，比如 endUser。

```
package util;
import com.qiniu.api.rs.*;
import com.qiniu.api.config.Config;
import com.qiniu.api.auth.digest.Mac;
import com.qiniu.api.net.CallRet;
public class Qiniu {
    public static String uploadToken(String bucket, String user, String callbackUrl){
        PutPolicy upPolicy = new PutPolicy(bucket);
        upPolicy.endUser = user;
        upPolicy.callbackUrl = callbackUrl;
        upPolicy.callbackBody = "key=$(key)&hash=$(etag)&width=$(imageInfo.width)&height=$(imageInfo.height)&user=$(endUser)&size=$(fsize)&mime=$(mimeType)";
        String token = null;
        Mac mac = new Mac(Config.ACCESS_KEY, Config.SECRET_KEY);
        try{
            token = upPolicy.token(mac);
        }catch (Exception e){
            e.printStackTrace();
        }
        return token;
    }
}

```

<br />

<a id="downloadintro" />

# **下载方式** [#下载方式]

## **公开下载** [#公开下载]

对于大部分空间公开用户来说，上传完后，通过通常的 http 直接访问就可以享受到我们的下载加速了。
具体可以参考：[公开资源下载](/products/kodo/development-guidelines/download-process/0-download-public)

## **私有下载** [#私有下载]

对于 bucket 内容不方便开放给所有用户的人来说，我们提供了下载鉴权机制。 生成一段时间内有效的下载 token ， 用户可以下载在下载token有效期内的七牛文件资源。
具体可以参考：[私有资源下载](/products/kodo/development-guidelines/download-process/1-download-private)

<a id="batchdownload" />

## **批量下载** [#批量下载]

可以在 portal 上批量下载文件，但是需要在浏览器设置 **允许显示弹出式窗口**

![](/docs-assets/faq/kodo/upload-download-problem/1336-upload-download-instructions/Fvzr5I55m4wJYsXkTrUlqXIyhdl0-7e6e4c3f26e0.webp)

点击上图中所示的浏览器拦截按钮，在弹窗中勾选 **始终允许显示弹出式窗口** 即可。

![](/docs-assets/faq/kodo/upload-download-problem/1336-upload-download-instructions/FhU433IIhY94Vu2W5Jr7erM4ctmD-e1b60ac9f902.webp)


# 上传 403 错误码 (/faq/kodo/upload-download-problem/1348-upload-error-code-403)



最近更新时间: 2020-05-15 16:33:22

#### 1.putPolicy中bucket:key与上传方法中的key不同，报错： [#1putpolicy中bucketkey与上传方法中的key不同报错]

`{"error":"key doesn't match with scope"}`

Example：

java-sdk为例:

```
String token = auth.uploadToken("qiniu-java-demo", "test",3600,null,true);//（生成token代码）
Response r = uploadManager.put(file, "test.txt", token,null,null, true);//（上传代码段）
```

因为test和test.txt不匹配，所以报错。auth.uploadToken中指定的key和uploadManager.put中设置的key值不同导致403

#### 2.putPolicy中设置了limited mimeType,报错： [#2putpolicy中设置了limited-mimetype报错]

`{"error":"limited mimeType: this file type is forbidden to upload"}`

#### Example： [#example]

java-sdk:

```
String token = auth.uploadToken("qiniu-java-demo", "test",3600,new StringMap().put("mimeLimit", "image/*"),true);
Response r = uploadManager.put(file, "test.txt", token,null,null, true);
```


# 如何进行同名文件覆盖上传 (/faq/kodo/upload-download-problem/13491-overwrite-upload)



最近更新时间: 2026-07-15 17:46:11

1、控制台覆盖上传，参考文档[上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file)
![image.png](/docs-assets/faq/kodo/upload-download-problem/13491-overwrite-upload/FnAdPPuV-g-95taAgInmgJ9dPRsT-ce10cad49b48.webp)
2、api覆盖上传
上传token明确指定insertOnly: 0 和 bucket:key，并保持上传时传入的 key 与它完全一致就可以完成覆盖上传。
![image.png](/docs-assets/faq/kodo/upload-download-problem/13491-overwrite-upload/FqjLzzb0CyFJwqr6BR4PSz1xoqWz-12d2dcbbca06.webp)![image.png](/docs-assets/faq/kodo/upload-download-problem/13491-overwrite-upload/FqjLzzb0CyFJwqr6BR4PSz1xoqWz-12d2dcbbca06.webp)


# 如何避免用户上传同名文件 (/faq/kodo/upload-download-problem/1365-how-to-avoid-the-users-to-upload-files-with-the-same-key)



最近更新时间: 2022-05-19 17:00:54

# 问题概述 [#问题概述]

## 标题： 如果避免用户上传同名文件呢（即相同key值的文件）？ [#标题-如果避免用户上传同名文件呢即相同key值的文件]

以前自己做存储的时候，是自己计算文件 hash，上传时查询如果存在的就不保存了。

现在改用七牛做存储了，看七牛上传返回的有文件 hash，但是不知道七牛的是如何计算出来的。

有没有办法在上传之前就可以知道七牛的存储空间里有没有相同的 hash 已经存在了，这样就不用向七牛上传相同的文件了，还是仍然需要自己实现这种排重计算？

## 答： [#答]

上传到七牛云存储的时候，key 是可选的。如果你不指定 key，则自动以 hash 值作为 key，此时自动带了消重能力。两个用户用同样的上传姿势上传相同的文件，最终的 key 是一样的。


# 七牛回调及回调鉴权 (/faq/kodo/upload-download-problem/1409-seven-cattle-callback-and-callback-authentication)



最近更新时间: 2020-09-11 17:52:55

# 概述 [#概述]

客户上传文件到<label id="Productname">七牛</label>后，<label id="Productname">七牛</label>服务器会响应 200 状态码，响应内容包括 hash 和 key 。但是如果客户需要自定义响应内容，则可以通过设置回调来实现。

# 回调实现 [#回调实现]

客户端需要在上传 token 中设置 `callbackurl` 和 `callbody`

1、`callbackurl` 必须是公网上可正常进行 POST 请求并能正常响应的 url，并且业务服务器返回给<label id="Productname">七牛</label>的内容必须是 json 串.

这里给一个最简单的能响应200的php代码(获取 `callbackbody` 并打印一个字符串给客户端)

```
<?php
$notifyBody = file_get_contents('php://input');
file_put_contents("test.txt",$notifyBody);
$arr=array("date"=>"test");
echo json_ encode($arr);
?>
```

2、`callbackbody` 是需要向业务服务器发送的回调内容，需使用<label id="Productname">七牛</label>的魔法变量或自定义变量来填充。
但是格式一定要正确，否则会报400格式错误.

例如 java 中正确的格式：

```
auth.uploadToken(bucket,key,3600,new StringMap()
.put("callbackUrl","callbackurl")
.put("callbackBody", "{"filename":$(fname),"filesize":$(fsize),"width":$(imageInfo.width)}") );
```

3、`callbodytype` 默认是 `application/x-www-form-urlencoded`, 也可在上传策略中设置为 `application/json`

# 回调鉴权 [#回调鉴权]

因为回调地址是公网可访问的，任何一台服务器都可以对其发起回调，如何确认回调是来自<label id="Productname">七牛</label>的呢？

<label id="Productname">七牛</label>在发起回调请求时会在请求头中带上 `Authorization` 字段，

```
Authorization:QBox iN7NgwM31j4-BZacMjPrOQBs34UG1maYCAQmhdCV:tDK-3f5xF3SJYEAwsll5g=
```

其中 QBox 为固定值，iN7Ngw\...dCV 为用户的 Accesskey，tDK-3f...5g= 为签名结果  encoded\_data。

业务服务器可以通过多种方法来对其进行验证， 例如如下面的代码php来进行验证：

```
    <?php
      require_once __DIR__ . '/../autoload.php';
      use Qiniu\Auth;
      $accessKey = getenv('QINIU_ACCESS_KEY');
      $secretKey = getenv('QINIU_SECRET_KEY');
      $bucket = getenv('QINIU_TEST_BUCKET');
      $auth = new Auth($accessKey, $secretKey);
      //获取回调的body信息
      $callbackBody = file_get_contents('php://input');
      //回调的contentType
      $contentType = 'application/x-www-form-urlencoded';
      //回调的签名信息，可以验证该回调是否来自存储服务
      $authorization = $_SERVER['HTTP_AUTHORIZATION'];
      //回调url
      $url = 'http://172.30.251.210/upload_verify_callback.php';
      $isQiniuCallback = $auth->verifyCallback($contentType, $authorization, $url, $callbackBody);
      if ($isQiniuCallback) {
          $resp = array('ret' => 'success');
      } else {
          $resp = array('ret' => 'failed');
      }
      echo json_encode($resp);
```

# 回调常见错误 [#回调常见错误]

## 1、400错误 [#1400错误]

这个是上传时表单格式错误，例如 `callbackbody` 设置的格式有问题等

## 2、579错误 [#2579错误]

1、上传成功回调失败，可以自己先用curl来验证callbackurl是否能成功响应200

```
curl -X POST -d "name=123.jpg" http://url
```

2、业务服务器返回给<label id="Productname">七牛</label>的 body 不是合法的 json 串
报错信息：`{"error":"unexcepted response"}`
这时可通过抓包，获取<label id="Productname">七牛</label>返回给客户端的 body ，通过 [http://jsonlint.com](http://jsonlint.com) 验证是否回调的 body 为合法的 json 串

3、业务服务器拒绝<label id="Productname">七牛</label>的回调请求
解决方案是配置允许<label id="Productname">七牛</label>的回调UA的访问。 <label id="Productname">七牛</label>回调UA：qiniu-callback/1.0


# 上传过程中，在使用魔法变量的情况下验证 app callback token (/faq/kodo/upload-download-problem/1428-upload-process-in-the-case-of-using-magic-variable-authentication-app-callback-token)



最近更新时间: 2020-05-15 16:33:22

上传过程中，在使用[魔法变量](/products/kodo/development-guidelines/upload-types/0-vars#1)的情况下验证 [callback token](/products/kodo/development-guidelines/upload-types/5-callback) ，此时签名的内容应该以魔法变量被替换前为准还是以魔法变量被替换后为准？

七牛的上传服务器 callback 客户的 app 服务器时会带有一个 `hmac_sha1` 签名，签名是针对最终请求来做的。

所以对于上面的问题，七牛的上传服务器先替换魔法变量的值，再对 callback 请求做签名。

可以参考：

* [上传策略](/products/kodo/development-guidelines/security/1-put-policy)


# webp 和 webm 格式图片上传后无法正常显示 (/faq/kodo/upload-download-problem/1434-webp-and-webm-format-to-upload-file-can-t-display-properly)



最近更新时间: 2020-05-15 16:33:22

如果webp和webm格式文件上传后无法正常显示，可能是由以下原因导致：

```
由于 webp 和 webm 都是由 Google 提出的图片和视频的编码格式，所以在 Chrome 浏览器上能得到很好的支持，其他浏览器不一定支持。
```

如果Chrome浏览器无法正常打开webp或者webm文件，可以去七牛开发者平台[https://portal.qiniu.com](https://portal.qiniu.com/)
通过前缀搜索资源，检查资源的mimeType，若不正确则手动将其修改为`image/webp`或者`video/webm`


# 从生成的 token 解析上传策略 (/faq/kodo/upload-download-problem/1488-from-the-generated-token-parsing-upload-strategy)



最近更新时间: 2020-05-15 16:33:22

**token 示例：**

```
JmTcjiVWsoRxql3OA2krgoW-Fu9bzBZZGCd2lXem:hnuOE5rHuQjyfTIBTH06IaFY0ME=:eyJzY29wZSI6ImF0ZXN0IiwiZGVhZGxpbmUiOjE1MDY5Mzg5NDF9
```

**token 字符串分为三段，以“：”分割，base64解码第二个”：“后的字符串，可以查看设置的上传策略，如下：**

```
 base64 -D <<< eyJzY29wZSI6ImF0ZXN0IiwiZGVhZGxpbmUiOjE1MDY5Mzg5NDF9
{"scope":"atest","deadline":1506938941}
```


# 七牛上传 crc32 校检说明与用法 (/faq/kodo/upload-download-problem/1593-seven-cattle-upload-crc32-check-and-usage)



最近更新时间: 2020-05-15 16:33:22

首先关于 crc32 的相关概念可以参考这个文章详细介绍：[CRC32](https://en.wikipedia.org/wiki/Cyclic_redundancy_check)

七牛这边上传设置 crc32 之后，上传前会先计算本地文件的 crc32，然后和上传到七牛后文件的 crc32 进行对比，如果两者不同的话就不会保存并且会返回 406：上传的数据 CRC32 校验错误。

我们不同的 SDK 用法都是类似的，就是在上传的时候设置 checkCrc 参数为 true 就可以了。
比如 java sdk 里面上传的 put 方法里面将 checkCrc 设置为 true 就可以了：
public Response put(XXXX data, String key, String token, StringMap params, String mime, **boolean checkCrc** ) throws QiniuException

具体可以参考七牛这边关于设定 crc32 之后计算 crc32 以及参数传递的方法： [https://github.com/qiniu/java-sdk/blob/43713ccf93cf17fd21ddd919434e1df96d291ead/src/main/java/com/qiniu/storage/FormUploader.java#L78-L99](https://github.com/qiniu/java-sdk/blob/43713ccf93cf17fd21ddd919434e1df96d291ead/src/main/java/com/qiniu/storage/FormUploader.java#L78-L99)

private void buildParams() throws QiniuException \{
params.put("token", token);
if (key == null) \{
fileName = "filename";
} else \{
fileName = key;
params.put("key", key);
}
if (checkCrc) \{
long crc32 = 0;
if (file != null) \{
try \{
crc32 = Crc32.file(file);
} catch (IOException e) \{
throw new QiniuException(e);
}
} else \{
crc32 = Crc32.bytes(data);
}
params.put("crc32", "" + crc32);
}
}

下面是关于 java sdk 的简单的 demo：

public class UploadWithCrc32 \{

String ACCESS\_KEY = "AK";
String SECRET\_KEY = "SK";
Auth auth = Auth.create(ACCESS\_KEY, SECRET\_KEY);
UploadManager uploadManager = new UploadManager();

// 设置指定上传策略
public String getUpToken()\{
return auth.uploadToken("phpdemo", null, 3600,null);
}

public void upload() throws IOException\{
String FilePath = "/Users/dxy/sync/aaa.jpg";
try \{
//设置验证crc32
Response res = uploadManager.put(FilePath, null, getUpToken(), null, null, true);
System.out.println(res.bodyString());
} catch (QiniuException e) \{
Response r = e.response;
// 请求失败时简单状态信息
System.out.println(r.toString());
}
}

public static void main(String args\[]) throws IOException\{
// //可以根据七牛的计算crc32算法打印出crc32的值
// File f=new File("/Users/dxy/sync/aaa.jpg");
// System.out.println(Crc32.file(f));

new UploadWithCrc32().upload();

}


# 上传下载及管理凭证的生命周期 (/faq/kodo/upload-download-problem/1598-upload-the-token-download-token-and-token-of-the-life-cycle-management)



最近更新时间: 2020-05-15 16:33:22

七牛目前有三种凭证：[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)、[下载凭证](/products/kodo/development-guidelines/security/0-download-token)、[管理凭证](/products/kodo/development-guidelines/security/access-token)。

其中：

* 上传凭证和下载凭证的算法均包含过期时间，过期时间在签名时指定。
* 管理凭证是根据请求内容签出的，没有过期时间。
* 服务端验证过期时间使用的是[Unix时间戳](/products/kodo/3-u#unixtime)。如果出现 token 意外超时，优先确认是不是过期时间使用了 Unix 时间戳造成的。


# 上传慢如何诊断？ (/faq/kodo/upload-download-problem/2516-slowly-upload)



最近更新时间: 2022-11-29 15:45:24

# 解决思路 [#解决思路]

为了可以快速定位问题，需要用提供有问题用户的网络信息或截图 通过 [提交工单](https://support.qiniu.com/question) 发给我们 来帮助排查。

# 解决方法 [#解决方法]

需要提供问题用户提供如下内容

### 1. 上传下载带宽信息 [#1-上传下载带宽信息]

打开 [本地网络带宽测试](http://www.bandwidthplace.com/) 点击 start 获取

### 2. 用户本地网络信息 [#2-用户本地网络信息]

打开 [问题诊断系统](http://ping.huatuo.qq.com) 稍等片刻后会显示诊断结果

### 3. 用户上传速度检测 [#3-用户上传速度检测]

打开 [七牛云上传速度检测](https://kodo-utils.qiniu.com/upload-test) 根据不同的上传空间区域选择指定的区域测试

注:

* 服务端上传测试 `up`
* 客户端上传测试 `upload`
* https 上传测试 `qiniup.com` 的域名

例如：上传空间为华东，协议为https，点击开始测试

<br />

![image.png](/docs-assets/faq/kodo/upload-download-problem/2516-slowly-upload/FrG3WpfnXEBPpUSJJDIA-k9Xpn5m-5ba3717c89b2.webp)


# 上传报400：incorrect region, please use xxxx.qiniu.com (/faq/kodo/upload-download-problem/3742-upload-to-400:-incorrect-region-both-please-use-xxxx-qiniu-com)



最近更新时间: 2020-05-15 16:33:22

上传的时候，如果遇到类似400：incorrect region, please use xxx.qiniu.com的错误，说明是上传域名和空间所在的区域不匹配，多发生在旧的sdk、工具和插件上。后面的 xxx.qiniu.com是正确的上传域名。

存储区域和上传域名的对应关系见[/products/kodo/2-region-endpoint-fq](/products/kodo/2-region-endpoint-fq)

出现这种情况，如果是使用的第三方插件，需要更新插件或询问第三方开发人员；如果是使用sdk，可以更新成最新的sdk，如果是使用七牛提供的工具，需要你更新为最新版本的qshell工具


# base64 上传自定义回调 (/faq/kodo/upload-download-problem/3821-base64-upload-custom-callback)



最近更新时间: 2020-05-15 16:33:22

#### Base64 上传自定义回调数据 [#base64-上传自定义回调数据]

Base64上传详见[/faq/kodo/upload-download-problem/1326-how-to-upload-photos-to-seven-niuyun-base64-code](/faq/kodo/upload-download-problem/1326-how-to-upload-photos-to-seven-niuyun-base64-code)。 <br />
这里讲一下x:user-var这个参数的使用<br />
首先需要在生成上传token时指定 saveKey 或者 callbackBody 这类支持自定义变量或者魔法变量的参数，一般通过服务器端生成。以在生成token是指定上传策略时，指定saveKey:name=$(x:extension)。<br />生成的token为<br />FMVCRs2-LO1ivRNi4l7mEZE6ZDvPv-519D12kZCO:RbsOpgGA6p\_aJlXHYOvAuBt2fvc=:eyJzYXZlS2V5IjoibmFtZVx1MDAzZCQoeDpleHRlbnNpb24pIiwic2NvcGUiOiJodG1sIiwiZGVhZGxpbmUiOjE0OTg0NDE1NDl9\<br>

#### 通过base64解码上传策略部分 [#通过base64解码上传策略部分]

eyJzYXZlS2V5IjoibmFtZVx1MDAzZCQoeDpleHRlbnNpb24pIiwic2NvcGUiOiJodG1sIiwiZGVhZGxpbmUiOjE0OTg0NDE1NDl9\<br>
\{"saveKey":"name\u003d$(x:extension)","scope":"html","deadline":1498441549}

#### 在上传url中指定x:extension参数 [#在上传url中指定xextension参数]

上传url: [http://up-z2.qiniup.com/putb64/-1/x:extension/dGVzdA==](http://up-z2.qiniup.com/putb64/-1/x:extension/dGVzdA==)
![](/docs-assets/faq/kodo/upload-download-problem/3821-base64-upload-custom-callback/FmFKB0XUTqSVP3CO-7GVbSYnOROS-7a045cd134a6.webp)


# 上传失败常见状态码 (/faq/kodo/upload-download-problem/3881-upload-the-common-failure-status-code-and-solve-method)



最近更新时间: 2026-04-30 17:34:33

在上传失败返回信息中，可以看到 http 状态码，几种常见错误如下：

| 状态码     | 说明                                                                                                                                                                                                                                             |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400     | 请求报文格式错误。<br />`incorrect region` 表示上传域名与上传空间的区域不符，此时需要升级 SDK 版本。                                                                                                                                                                              |
| 401     | 鉴权失败。<br />`token not specified` 表示上传请求中没有带 token ，可以抓包验证后排查代码逻辑。<br />`bad token` 表示 token 错误，说明生成 token 的算法有问题，建议直接使用七牛的服务端 SDK 生成 token。<br />`token out of date` 表示 token 过期，推荐 token 过期时间设置为 3600 秒（1 小时），如果是客户端上传，建议每次上传从服务端获取新的 token 。 |
| 403     | 权限不足。<br />`key doesn't match scope` 表示上传文件指定的 key 和上传 token 中，putPolicy 的 scope 字段不符。上传指定的 key 必须跟 scope 里的 key 完全匹配或者前缀匹配。<br />`ExpUser can only upload image/audio/video/plaintext` 表示账号是体验用户，体验用户只能上传文本、图片、音频、视频类型的文件，完成实名认证即可解决。         |
| 579     | 上传成功，回调失败。<br />需要确认回调服务器接受 POST 请求，并可以给出 200 的响应。                                                                                                                                                                                             |
| 612     | 指定文件或资源不存在的。                                                                                                                                                                                                                                   |
| 614     | 指定文件名称已存在，表示该key名称的文件已经存在了，无法覆盖上传                                                                                                                                                                                                              |
| 大文件上传失败 | 大文件上传容易受到网络波动影响，推荐使用分片上传。如果使用上传工具，推荐使用 [qshell](/products/kodo/0-qshell) 工具。                                                                                                                                                                   |


# 上传慢、上传失败等常见FAQ (/faq/kodo/upload-download-problem/3882-upload-problem-faq)



最近更新时间: 2026-09-16 15:29:15

| Q1：ak sk 空间名称 和 默认域名是什么？                                                |
| ----------------------------------------------------------------------- |
| 参考文档：[存储常见的关键参数](/faq/kodo/7450-the-third-party-plug-in-key-parameters) |

<br />

| Q2：上传失败，响应非 200 状态码，我应该怎么处理？                                                                                         |
| -------------------------------------------------------------------------------------------------------------------- |
| 参考文档：[上传失败常见状态码及解决方法](/faq/kodo/upload-download-problem/3881-upload-the-common-failure-status-code-and-solve-method) |

<br />

| Q3：上传报错 incorrect region Please use up-z(x).qiniu.com ，应该怎么办？                                                                                                    |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 报错原因是上传域名与空间所属区域不匹配，目前最新版 SDK 均已支持自动切换区域，所以一般更新 SDK 版本到最新版即可解决。<br />如果不方便更新版本，可以参照 [存储区域和域名的对应关系](/products/kodo/2-region-endpoint-fq) ，修改上传域名，或者换一个默认的华东区域的空间。 |

<br />

| Q4：上传报错，找不到上传域名，应该怎么办？                                                                                                                                                                                                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 找不到上传域名，一般来说，是使用的SDK客户端网络异常，不能根据上传token中的ak和bucket信息，调用[https://uc.qbox.me/query](https://uc.qbox.me/query) 和 [http://api.qiniu.com/query,去获取空间所在区域的上传域名,从而引发上传慢，耗时长，上传失败找不到上传域名的情况，这种情况，建议SDK直接指定上传域名](http://api.qiniu.com/query,去获取空间所在区域的上传域名,从而引发上传慢，耗时长，上传失败找不到上传域名的情况，这种情况，建议SDK直接指定上传域名) 或者 region即可,以java为例，其他各个版本SDK参考[官方SDK](/sdk-tools/sdk#official-sdk) |

```
//构造一个带指定Region对象的配置类 华东region0，华北region1，华南region2
Configuration cfg = new Configuration(Region.region0());
cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;// 指定分片上传版本
//...其他参数参考类注释
UploadManager uploadManager = new UploadManager(cfg);
//...生成上传凭证，然后准备上传

```

<br />

| Q5：上传报错，qiniup.com域名请求超时ping不通 ，应该怎么办？                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 正常来说，七牛的上传域名 up-z(x).qiniup.com都可以正常ping通，无法ping通的情况，大部分情况下都是客户端网络异常导致，可以常识上传端切换网络，比如从手机网络切换到家庭、公司wifi,看下是否可以；如果还是不可以，常识修改下本地网络的DNS解析服务器，将解析指向114.114.114.114或者8.8.8.8公共DNS，如果不知道怎么修改的话，可以百度下即可，确认网络是否有开启代理，关闭代理后再次测试；在更换网络，关闭代理，修改DNS都无法正常上传的情况下，需要您提供下您的客户端IP 和 ping 的上传节点ip给到工单，然后进行详细排查 |

<br />

| Q6：我的客户反馈上传速度慢，我应该提供哪些诊断信息给七牛？                                                                      |
| --------------------------------------------------------------------------------------------------- |
| 1：确认上传端和存储区域是否都在同一区域，如果是国内传海外，或者海外传国内，出现慢的情况符合预期，建议国内传国内，海外传海外                                      |
| 2：确认下上传端的网络带宽，上行带宽越高，上传速度越快，如果是主机上传，推荐使用客户端上传，客户端的上行带宽一把是远大于服务器代带宽的，可以百度下网络测速，测试上行带宽，上线带宽越高，上传速度越快。 |
| 3：确认网络是否有开代理，如果有开，关闭代理试试                                                                            |
| 4：直接在上传代码中，指定上传域名，不使用 autoregion ,减少获取上传域名的耗时                                                       |
| 5：如果以上都不行 参考文档：[上传慢如何诊断？](/faq/kodo/upload-download-problem/2516-slowly-upload)                     |

<br />

| Q7：我上传的文件与预期的不符，有图片变大变小、实际大小不符、图片被压缩、文件不完整等情况。                                                                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 首先 [刷新CDN 缓存](/faq/cdn/refresh-the-cache-problem/1325-refresh-the-cache-and-the-effect-of-time)，刷新完成后，[验证文件一致性](/faq/cdn/refresh-the-cache-problem/3644-refresh-the-cache-fails-consistency-method-validation-file) 。 |

<br />

| Q8: 我使用第三方插件，确定填写的参数都是对的，但是一直上传不了文件。                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 七牛官方没有提供过任何插件。官方社区收录的 [插件](/sdk-tools/sdk#community-plugin) ，经过验证都是可以使用的，但一般更新不太及时，不会支持七牛的最新功能或产品。<br />上传报错，常见的问题是因为上传指定的空间不是华东的存储空间，换成华东的空间一般可以解决。<br /> 如果确认配置正确，但还是上传失败，建议咨询 【插件供应商】那边技术人员，插件底层实现逻辑只有他们最清楚。 |

<br />

| Q9: 七牛对象存储是否可以搭建网站？                                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 对象存储只能用于文件存储，无法用来部署web网站或博客并运行。如果需要部署web网站或博客，建议购买 [云主机](/products/qvm/0-qvm-linux-quickstart) 或 [轻量应用服务器](/products/las/cloud-server/0-las-create-server) 来部署服务，web网站或博客中的静态资源(比如：图片、js、html、视频等)可以上传至七牛对象存储空间，然后通过外链来调用加载，对象存储使用参考 [对象存储快速入门文档](/products/kodo/0-console-quickstart) |

<br />

| Q10: 对象存储的文件大小是否有限制？ |
| -------------------- |
| 存储空间的单个文件大小没有限制。     |

<br />

| Q11: 存储空间最大支持预览的视频或图片是多大？ |
| ------------------------- |
| 视频或图片大小没有限制。              |

<br />

| Q12: 上传慢，上传速度怎么进一步提升                                                                                                                                                                                                                                                                                                  |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 上传速度主要取决于上传端的网络，客户端上行带宽越高，上传速度越快，理论上1Mbps的上行带宽理论峰值上传速度 = 1 / 8 = 0.125MB/s ，也就是125KB/s 。另外就是可以考虑使用加大并发上传，将有限的带宽更充分利用。<br />如果加大并发并且网络上行带宽充足的情况下，上传速度始终在200KB/s左右，那么有可能是本地网络的限制，可以考虑使用自定义上传加速域名上传，[传输加速](/products/kodo/development-guidelines/1-transfer-acceleration)。<br />`注意：自定义上传加速域名，需要配置cname解析，且上行流量是需要额外计费的` |

<br />

| Q13: 为什么存储空间的资源在七牛控制台无法预览查看？                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1：是否可以预览查看取决于资源格式在对应浏览器是否支持？浏览器支持的格式可以在控制台预览查看。                                                                                                                                                                                                                                                                                                                                                                              |
| 2：存储空间或CDN域名开启了referer防盗链功能，也会影响在线预览功能，开启空间referer防盗链或CDN域名referer防盗链的空间资源需要在七牛控制台预览查看的话，需要将 portal.qiniu.com 域名也加入referer白名单。空间referer防盗链配置文档参考：[设置Referer防盗链](/products/kodo/kodo-console-guide/bucket-management/space-settings/4-set-the-referer-hotlinking-prevention),CDN域名的referer配置文档参考：[Referer防盗链](/products/cdn/configuration-management-fusion/access-control-configuration/0-domain-name-hotlinking-prevention) |

<br />

| Q14: 如何使用七牛内网上传下载空间资源？                                                         |
| ------------------------------------------------------------------------------ |
| 目前仅支持【华东区域】存储空间与七牛云主机进行内网上传和下载，具体参考 [云主机和对象存储内网互通实践](/products/qvm/0-qvm-kodo) |

<br />

| Q15: 如何下载【违规邮件通知】中的违规资源？ |
| ------------------------ |
| 违规资源禁止下载                 |

<br />

| Q16: 控制台-敏感词问题                                                                                                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Q：为什么会有敏感词检查？哪些环节会有敏感词检查？                                                                                                                                                                                                                     |
| A：应网安管理部门要求，开发者平台 Portal 上不能展示包含有敏感词的文件，所以在 Portal 会过滤不展示包含敏感词的文件、并禁止上传名字包含敏感词的文件名；公司合规部门明确，国内和海外区域都需执行敏感词检查。名字包含敏感词的文件即便上传成功之后 Portal 也不会展示该文件。<br /> 如需查询或删除对应文件，可通过 [/products/kodo/1-kodo-browser](/products/kodo/1-kodo-browser) 图形化工具操作 |

<br />

| Q17: 控制台-未命名文件夹问题                                                                    |
| ------------------------------------------------------------------------------------ |
| Q：为什么会有未命名的文件夹？                                                                      |
| A：文件名称不能使用/开头，不然会判断为文件夹的，例如上传文件后将文件名称设置为：/ABC，那么这个文件会被识别为ABC文件夹的，设置为：/，就会生成一个未命名的文件夹 |

<br />

| Q18: 小文件可以正常上传，大文件上传报413错误，是什么原因？                                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 原因：一般是您在上传token中通过fsizeLimit限制了上传文件大小导致。<br /> 处理方式：<br />1、如果需要大文件上传，可以在生成上传token代码中调大fsizeLimit限制大小；<br />2、如果不需要限制，可以在生成上传token代码中去除fsizeLimit参数 |

<br />

| Q19: 文件上传失败，报401\{ error: user disabled }，是什么原因？                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 一般是您的账号欠费冻结或账号异常导致的，可以先登录 [七牛控制台](https://portal.qiniu.com/home) 确认下对应账号状态；如果确认账号状态正常，但上传还是报401，获取到上传失败的上传token后 [提交工单](https://support.qiniu.com/tickets) 反馈技术支持进一步核实确认 |

<br />

| Q20: 如何删除未命名文件夹？                        |
| --------------------------------------- |
| 以 / 开头的文件即未命名文件夹 ，切换到 非目录格式即可删除这个未命名文件夹 |


# 上传报文组装 (/faq/kodo/upload-download-problem/3971-upload-a-message-assembly)



最近更新时间: 2020-05-15 16:33:22

本文介绍一些因特殊情况需要自行组装上传报文时遇到的问题

### 正确的报文 [#正确的报文]

```
POST  HTTP/1.1
Host: up.qiniup.com
Cache-Control: no-cache
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename=""
Content-Type:


------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="token"

FMVCRs2-LO1ivRNi4l7mEZE6ZDvPv-519D12kZCO:TMxdqAM3QilkUuZu6pIfoHa5Y2A=:eyJzY29wZSI6InJ0Y3Rlc3QiLCJkZWFkbGluZSI6MjUwMzI3NDkyOX0=
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```

<br />

### 错误一 [#错误一]

invalid media parameter

### 可能原因 [#可能原因]

1. boundary之间有换行符
2. boundary中有“=”

### 解决方法 [#解决方法]

建议在boundary中不要采用特殊字符

<br />

### 错误二 [#错误二]

body/mutipart: NextPart: EOF;UP/400

### 可能原因 [#可能原因-1]

报文中指定的Content-Length值有误

### 解决方法 [#解决方法-1]

取消报文中的这个字段


# 云服务器QVM的入网带宽和出网带宽 (/faq/qvm/disk-cpu-memory-bandwidth/7061-cloud-server-qvm-network-bandwidth-and-network-bandwidth)



最近更新时间: 2026-05-07 15:38:15

# 概述 [#概述]

本文主要介绍云服务器QVM的入网带宽和出网带宽。

# 详细信息 [#详细信息]

> 七牛云提醒您：
>
> * 如果您对实例或数据有修改、变更等风险操作，务必注意实例的容灾、容错能力，确保数据安全。
> * 如果您对实例（包括但不限于QVM、RDS）等进行配置与数据修改，建议提前创建快照或开启RDS日志备份等功能。
> * 如果您在七牛云平台授权或者提交过登录账号、密码等安全信息，建议您及时修改。

本文从服务器角度出发，对入网带宽和出网带宽进行说明。下表给出了入网带宽和出网带宽的具体内容。

<table class="lake-table">
  <colgroup><col /><col /></colgroup>

  <tbody><tr><th>带宽类别 （Mbit/s）</th><th>描述</th></tr></tbody>

  <tbody><tr><td>入网带宽</td><td>流入云服务器QVM的带宽。<br />从云服务器QVM内部下载外部网络资源，或者以FTP客户端等方式上传资源到云服务器QVM的都是入网带宽。</td></tr><tr><td>出网带宽</td><td>流出云服务器QVM的带宽。<br />从云服务器QVM对外提供访问，或者以FTP客户端等方式下载云服务器QVM内部资源的都是出网带宽。云服务器QVM出网带宽就是购买的带宽值。</td></tr></tbody>
</table>

下图为数据流的方向说明。

![](/docs-assets/faq/qvm/disk-cpu-memory-bandwidth/7061-cloud-server-qvm-network-bandwidth-and-network-bandwidth/FgoGQ5o6HGqSGjY4-E0c7T31EJSy-b529b8e4615d.webp)

# 相关文档 [#相关文档]

* Windows实例带宽和CPU跑满或跑高排查

* Linux实例带宽和CPU跑满或跑高排查

# 适用于 [#适用于]

* 云服务器 QVM


# 监控CPU和内存的日志工具 (/faq/qvm/disk-cpu-memory-bandwidth/7062-monitor-the-log-tool-of-cpu-and-memory)



最近更新时间: 2020-08-13 19:24:48

# 概述 [#概述]

本文主要介绍监控CPU和内存的日志工具。

# 详细信息 [#详细信息]

> 七牛云提醒您：
>
> * 如果您对实例或数据有修改、变更等风险操作，务必注意实例的容灾、容错能力，确保数据安全。
> * 如果您对实例（包括但不限于QVM、RDS）等进行配置与数据修改，建议提前创建快照或开启RDS日志备份等功能。
> * 如果您在七牛云平台授权或者提交过登录账号、密码等安全信息，建议您及时修改。

以下分别在Linux和Windows系统中，介绍监控CPU和内存的日志工具。

## Linux工具 [#linux工具]

1. 下载如下工具。
   * [get\_cpu\_mem\_info\_sh.rar](http://img01.taobaocdn.com/tfscom/TB1qE_WHFXXXXbuaXXXXXXXXXXX.rar)

2. 下载该文件并且解压后，上传到`/tmp`目录中。

3. 执行如下命令，进入指定目录。

   cd /tmp

4. 执行如下命令，后台运行脚本。

   nohup bash get\_cpu\_mem\_info.sh &

5. 该工具会在`/tmp`目录下生成一个日志文件，实时记录系统的CPU、内存的使用情况，等到系统异常时可以用于分析日志。

## Windows工具 [#windows工具]

1. 下载如下工具。
   * [get\_cpu\_mem\_info\_bat.rar](http://img01.taobaocdn.com/tfscom/TB1G2AAHFXXXXXBXXXXXXXXXXXX.rar)
2. 下载该文件并解压后，上传到`c:\`目录中。
3. 打开文件运行后，请勿关闭，最小化即可。
4. 该工具会在`C:\`目录下生成一个日志文件，实时记录系统的性能状态，等到系统异常时可以用于分析日志。

# 适用于 [#适用于]

* 云服务器 QVM


# Linux实例磁盘空间满和inode满的问题排查方法 (/faq/qvm/disk-cpu-memory-bandwidth/7063-linux-instance-disk-space-and-full-inode-full-screen-problem)



最近更新时间: 2026-05-07 15:43:57

> \*\*免责声明：\*\*本文可能由社区贡献或涉及第三方产品信息，建议您访问社区或第三方产品的官方网站获取帮助与支持。第三方产品不在七牛云售后支持范围。本文仅供参考，七牛云不做任何暗示或其他形式的承诺。

# 问题描述 [#问题描述]

在Linux系统的云服务器QVM实例内创建文件时，出现类似如下空间不足的提示。

No space left on device …

# 问题原因 [#问题原因]

导致该问题的可能原因如下所示：

* 磁盘分区空间使用率达到百分之百。
* 磁盘分区inode使用率达到百分之百。
* 存在僵尸文件。

> **说明**：已删除文件因句柄被占用未释放，导致相应空间未释放的文件。

* 挂载点覆盖。

> **说明**：在原有文件系统的相应目录下已经存在大量文件。挂载新磁盘后，导致使用`df`命令能统计到相关空间使用，而使用`su`命令统计不到。

# 解决方案 [#解决方案]

> 七牛云提醒您：
>
> * 如果您对实例或数据有修改、变更等风险操作，务必注意实例的容灾、容错能力，确保数据安全。
> * 如果您对实例（包括但不限于QVM、RDS）等进行配置与数据修改，建议提前创建快照或开启RDS日志备份等功能。
> * 如果您在七牛云平台授权或者提交过登录账号、密码等安全信息，建议您及时修改。

要解决该问题，请根据不同的问题原因，通过以下方式进行处理：

* [分区容量满](#adPCB)
* [inode容量满](#ejmcJ)
* [修改inode数量](#jQPCQ)
* [僵尸文件分析删除](#HNddz)
* [挂载点覆盖](#h3-u6302u8F7Du70B9u8986u76D6)

## 分区容量满的处理 [#分区容量满的处理]

* 登录服务器，使用`df -h`命令查看磁盘使用率，其中的**Mounted on**指挂载的目录。
  ![](/docs-assets/faq/qvm/disk-cpu-memory-bandwidth/7063-linux-instance-disk-space-and-full-inode-full-screen-problem/Fu56AImgZiSNbCoSd2xr3CkjxDKH-df9dbc7d71c2.webp)
* 进入根目录，执行以下指令，逐级查看哪个目录占用磁盘空间较大，进入相应的目录，直到找到最精确的的文件或目录。

du -sh \*

系统显示类似如下。
![](/docs-assets/faq/qvm/disk-cpu-memory-bandwidth/7063-linux-instance-disk-space-and-full-inode-full-screen-problem/FhU62cph0t9lWFh0LWzPvK8Z46S3-3f8aa6a37722.webp)

* 最后，结合业务情况等判断对相关文件或目录进行删除，或者购买更大的数据盘分担处理。

## inode容量满的处理 [#inode容量满的处理]

通过如下操作，解决inode容量满的问题。

### **查询inode使用情况** [#查询inode使用情况]

Linux的inode节点中，记录了文件的类型、大小、权限、所有者、文件连接的数目、创建时间与更新时间等重要的信息，还有一个比较重要的内容就是指向数据块的指针。一般情况不需要特殊配置，如果存放文件很多，则需要配置。有时磁盘空间有剩余但是不能存放文件，可能是由于inode耗尽所致。

* 执行`df -i`命令，可以查询inode的使用情况。
  ![](/docs-assets/faq/qvm/disk-cpu-memory-bandwidth/7063-linux-instance-disk-space-and-full-inode-full-screen-problem/Fs-hl7upitLFBOolrwQPeNakABhk-2b2c37708bcc.webp)
* 如果inode使用率达到或者接近100%，可以通过以下两种方式进行处理：
* [清除inode占用高的文件或者目录](#trBFk)。
* [修改inode数量](#jQPCQ)。

### **清除inode占用高的文件或者目录** [#清除inode占用高的文件或者目录]

如果不方便格式化磁盘以增加inode数量，可以参考以下步骤，清理inode占用量高的文件或者目录。

* 登录服务器，执行以下命令，分析根目录下的每个二级目录下有多少个文件。

for i in /\*; do echo $i; find $i | wc -l; done

系统显示类似如下。
![](/docs-assets/faq/qvm/disk-cpu-memory-bandwidth/7063-linux-instance-disk-space-and-full-inode-full-screen-problem/FnwDxXAEgEH6FSMxyWQZJ72lwTwH-86718551c436.webp)

* 然后，逐层进入inode占用最高的目录，继续执行上述指令，逐步定位占用过高空间的文件或目录，最后进行相应清理。

### **修改inode数量** [#修改inode数量]

如果不允许清理磁盘中的文件，或者清理后inode使用率仍然较高，则需要通过以下步骤，增加inode节点数量。

> **说明**：inode的调整需要重新格式化磁盘，请确保数据已经得到有效备份后，再进行以下操作。

* 执行以下命令，卸载系统文件。

umount /home

* 执行以下命令，重新建立文件系统，指定inode节点数。

mkfs.ext3 /dev/xvdb -N 1638400

> **说明**：本文指定inode节点数1638400，现场实际环境请以实际为准。

* 执行以下命令，修改fstab文件。

vim /etc/fstab

* 执行以下命令，查看修改后的inode节点数。

dumpe2fs -h /dev/xvdb | grep node

系统显示类似如下。
![](/docs-assets/faq/qvm/disk-cpu-memory-bandwidth/7063-linux-instance-disk-space-and-full-inode-full-screen-problem/Fug4rUmE0s8ETDul8n5B4Z7bDbqH-d6443947a2d0.webp)

## 僵尸文件分析与删除 [#僵尸文件分析与删除]

如果磁盘和inode都没有问题，则需要查看是否存在未被清除句柄的僵尸文件。这些文件实际上已经被删除，但是有服务程序在使用这些文件，导致这些文件一直被占用，无法释放磁盘空间。如果这些文件过多，会占用很大的磁盘空间。参考以下步骤查看并删除僵尸文件。

* 远程登录服务器。
* 执行以下命令，安装lsof。

yum install lsof -y

* 执行以下命令，查看僵尸文件占用情况。

lsof |grep delete | more

系统显示类似如下。
![](/docs-assets/faq/qvm/disk-cpu-memory-bandwidth/7063-linux-instance-disk-space-and-full-inode-full-screen-problem/FhJBTuszh5LNLSixKYFt_poAMWDN-5d2421518e99.webp)

* 如果僵尸文件过多，会占用很大的磁盘空间。可以通过以下方法释放句柄，以清除僵尸文件。
* 重启服务器，验证效果。重启服务器，系统会退出现有的进程，开机后重新加载。该过程会释放调用的deleted文件的句柄。
* 根据`lsof`命令列出的pid进程号，使用`kill`命令正常停止或结束占用这些文件的服务进程。

> **说明**：如果服务器正在运行业务，可能会影响到业务，请慎重操作。

## 挂载点覆盖 [#挂载点覆盖]

先取消磁盘挂载，再检查原挂载目录下的空间占用情况。

# 适用于 [#适用于]

* 云服务器 QVM

如果您的问题仍未解决，您可以[提交工单](https://support.qiniu.com/tickets/new/?ref=developer.qiniu.com)联系七牛云技术支持。


# 使用ping命令丢包或不通时的链路测试方法 (/faq/qvm/qvm-network/7055-use-the-ping-command-packet-loss-or-not-the-link-test-method)



最近更新时间: 2026-05-07 16:21:04

> **免责声明：** 本文档可能包含第三方产品信息，该信息仅供参考。七牛云对第三方产品的性能、可靠性以及操作可能带来的潜在影响，不做任何暗示或其他形式的承诺。

# 概述 [#概述]

当客户端访问目标服务器出现ping丢包或ping不通时，可以通过tracert或mtr等工具进行链路测试来判断问题根源。本文介绍如何通过工具进行链路测试和分析。

# 详细信息 [#详细信息]

> 七牛云提醒您：
>
> * 如果您对实例或数据有修改、变更等风险操作，务必注意实例的容灾、容错能力，确保数据安全。
> * 如果您对实例（包括但不限于QVM、RDS）等进行配置与数据修改，建议提前创建快照或开启RDS日志备份等功能。
> * 如果您在七牛云平台授权或者提交过登录账号、密码等安全信息，建议您及时修改。

本文分别介绍如下链路测试方法。

* [链路测试工具](#Pxedd)
* [测试结果的简要分析](#eMWjW)
* [常见的链路异常场景](#ynsSx)
* [链路测试步骤](#nhPtf)
* [测试完成后的解决方法](#QGnym)

## 链路测试工具 [#链路测试工具]

操作系统类型不同，链路测试所使用的工具也有所不同。简要介绍如下。

### Linux系统 [#linux系统]

此处简单介绍两个链路测试工具。

##### 工具一：mtr命令 [#工具一mtr命令]

mtr（My traceroute）几乎是所有Linux发行版本预装的网络测试工具。其将ping和traceroute的功能合并，所以功能更强大。mtr默认发送ICMP数据包进行链路探测。您也可以通过“-u”参数来指定使用UDP数据包进行探测。相对于traceroute只会做一次链路跟踪测试，mtr会对链路上的相关节点做持续探测并给出相应的统计信息。所以，mtr能避免节点波动对测试结果的影响，所以其测试结果更正确，建议优先使用。

**用法说明**

mtr \[-BfhvrwctglxspQomniuT46] \[--help] \[--version] \[--report]
\[--report-wide] \[--report-cycles=COUNT] \[--curses] \[--gtk]
\[--csv|-C] \[--raw] \[--xml] \[--split] \[--mpls] \[--no-dns] \[--show-ips]
\[--address interface] \[--filename=FILE|-F]
\[--ipinfo=item\_no|-y item\_no]
\[--aslookup|-z]
\[--psize=bytes/-s bytes] \[--order fields]
\[--report-wide|-w] \[--inet] \[--inet6] \[--max-ttl=NUM] \[--first-ttl=NUM]
\[--bitpattern=NUM] \[--tos=NUM] \[--udp] \[--tcp] \[--port=PORT] \[--timeout=SECONDS]
\[--interval=SECONDS] HOSTNAME

**常见可选参数说明**

* \--report：以报告模式显示输出。
* \--split：将每次追踪的结果分别列出来，而非统计整个结果。
* \--psize：指定ping数据包的大小。
* \--no-dns：不对IP地址做域名反解析。
* \--address：主机有多个IP地址时，设置发送数据包的IP地址。
* -4：只使用IPv4协议。
* -6：只使用IPv6协议。

另外，也可以在mtr运行过程中，输入类似如下的字母来快速切换模式。

* ？或h：显示帮助菜单。
* d：切换显示模式。
* n：启用或禁用DNS域名解析。
* u：切换使用ICMP或UDP数据包进行探测。

**命令输出示例**\*\*
![](/docs-assets/faq/qvm/qvm-network/7055-use-the-ping-command-packet-loss-or-not-the-link-test-method/Fle3GEMrqEaNPc5Dlfu7aHwdOK9o-c7c051eb3d02.webp)\*\*

**返回结果说明**

默认配置下，返回结果中各数据列的说明如下。

* 第一列（Host）：节点IP地址和域名。按 **n** 键可切换显示。
* 第二列（Loss%）：节点丢包率。
* 第三列（Snt）：每秒发送数据包数。默认值是10，可以通过“-c”参数指定。
* 第四列（Last）：最近一次的探测延迟。
* 第五、六、七列（Avg、Best、Worst）：分别是探测延迟的平均值、最小值和最大值。
* 第八列（StDev）：标准偏差。越大说明相应节点越不稳定。

##### 工具二：traceroute命令 [#工具二traceroute命令]

traceroute也是几乎所有Linux发行版本预装的网络测试工具，用于跟踪Internet协议（IP）数据包传送到目标地址时经过的路径。traceroute先发送小的具有最大存活时间值（Max\_TTL）的UDP探测数据包，然后侦听从网关开始的整个链路上的ICMP TIME\_EXCEEDED响应。探测从TTL=1开始，TTL值逐步增加，直至接收到ICMP PORT\_UNREACHABLE消息。ICMP PORT\_UNREACHABLE消息用于标识目标主机已经被定位，或命令已经达到允许跟踪的最大TTL值。traceroute默认发送UDP数据包进行链路探测。可以通过“-I”参数来指定使用ICMP数据包进行探测。

**用法说明**

traceroute \[-I] \[ -m Max\_ttl ] \[ -n ] \[ -p Port ] \[ -q Nqueries ] \[ -r ] \[ -s SRC\_Addr ] \[ -t TypeOfService ] \[ -f flow ] \[ -v ] \[ -w WaitTime ] Host \[ PacketSize ]

**常见可选参数说明**

* -d：使用Socket层级的排错功能。
* -f：设置第一个检测数据包的存活数值TTL的大小。
* -F：设置不要分段标识。
* -g：设置来源路由网关，最多可设置8个。
* -i：主机有多个网卡时，使用指定的网卡发送数据包。
* -I：使用ICMP数据包替代UDP数据包进行探测。
* -m：设置检测数据包的最大存活数值TTL的大小。
* -n：直接使用IP地址而非主机名称（禁用DNS反查）。
* -p：设置UDP传输协议的通信端口。
* -r：忽略普通的Routing Table，直接将数据包发送到目标主机上。
* -s：设置本地主机发送数据包的IP地址。
* -t：设置检测数据包的TOS数值。
* -v：详细显示指令的执行过程。
* -w：设置等待远端主机回包时间。
* -x：开启或关闭数据包的正确性检验。

**命令输出示例**

**![](/docs-assets/faq/qvm/qvm-network/7055-use-the-ping-command-packet-loss-or-not-the-link-test-method/Fg9lIY2jB30JEKxlazbAHtlFv7Ov-983717d12c7d.webp)**

### Windows系统 [#windows系统]

此处简单介绍两个链路测试工具。

##### 工具一：WinMTR（建议优先使用） [#工具一winmtr建议优先使用]

WinMTR是mtr工具在Windows环境下的图形化实现，但进行了功能简化，只支持部分mtr的参数。WinMTR默认发送ICMP数据包进行探测，无法切换。和mtr一样，相比tracert，WinMTR能避免节点波动对测试结果的影响，所以测试结果更正确。所以在WinMTR可用的情况下，建议优先使用WinMTR进行链路测试。

**用法说明**

WinMTR无需安装，直接解压运行即可。操作方法非常简单，说明如下。

* 如下图所示，运行程序后，在 **Host** 字段输入目标服务器域名或IP，注意不要包含空格。
  ![](/docs-assets/faq/qvm/qvm-network/7055-use-the-ping-command-packet-loss-or-not-the-link-test-method/FgG9nR2BuDLjI6v4iHBsE1u4jNkq-67f0b5b18907.webp)
* 单击 **Start** 开始测试。开始测试后，相应按钮变成了 **Stop**。
* 运行一段时间后，单击 **Stop** 停止测试。
* 其它选项说明如下。
* Copy Text to clipboard：将测试结果以文本格式复制到粘贴板。
* Copy HTML to clipboard：将测试结果以HTML格式复制到粘贴板。
* Export TEXT：将测试结果以文本格式导出到指定文件。
* Export HTML：将测试结果以HTML格式导出到指定文件。
* Options：可选参数，包括的可选参数如下。
* Interval（sec）：每次探测的间隔（过期）时间。默认为1秒。
* ping size(bytes)：ping探测所使用的数据包大小，默认为64字节。
* Max hosts in LRU list：LRU列表支持的最大主机数，默认值为128。
* Resolve names：通过反查IP地址，以域名显示相关节点。

**返回结果说明**

默认配置下，返回结果中各数据列的说明如下。

* 第一列（Hostname）：节点的IP或域名。
* 第二列（Nr）：节点编号。
* 第三列（Loss%）：节点丢包率。
* 第四列（Sent）：已发送的数据包数量。
* 第五列（Recv）：已成功接收的数据包数量。
* 第六、七、八、九列（Best 、Avg、Worst、Last）：分别是到相应节点延迟的最小值、平均值、最大值和最后一次值。

##### 工具二：tracert命令行工具 [#工具二tracert命令行工具]

tracert（Trace Route）是Windows自带的网络诊断命令行程序，用于跟踪Internet协议（IP）数据包传送到目标地址时经过的路径。 tracert通过向目标地址发送 ICMP 数据包来确定到目标地址的路由。在这些数据包中，tracert使用了不同的IP“生存期”，即TTL值。由于要求沿途的路由器在转发数据包前必须至少将TTL减少1，因此TTL实际上相当于一个跃点计数器（hop counter）。当某个数据包的TTL达到0时，相应节点就会向源计算机发送一个ICMP超时的消息。 

tracert第一次发送TTL为1的数据包，并在每次后续传输时将TTL增加1，直到目标地址响应或达到TTL的最大值。中间路由器发送回来的ICMP超时消息中包含了相应节点的信息。

**用法说明**

tracert \[-d] \[-h maximum\_hops] \[-j host-list] \[-w timeout] \[-R] \[-S srcaddr] \[-4] \[-6] target\_name

**常见可选参数说明**

* -d：不要将地址解析为主机名（禁用DNS反解）。
* -h：maximum\_hops，指定搜索目标地址时的最大跃点数。
* -j： host-list，指定沿主机列表的松散源路由。
* -w：timeout，等待每个回复的超时时间（以毫秒为单位）。
* -R：跟踪往返行程路径（仅适用于IPv6）。
* -S：srcaddr，要使用的源地址（仅适用于IPv6）。
* -4：强制使用IPv4。
* -6：强制使用IPv6。
* target\_host：目标主机域名或IP地址。

**命令输出示例**

C:\\> tracert -d 223.5.5.5
通过最多 30 个跃点跟踪到 223.5.5.5 的路由
1                          请求超时。
2     9 ms     3 ms    12 ms  192.168.X.X
3     4 ms     9 ms     2 ms  X.X.X.X
4     9 ms     2 ms     1 ms  XX.XX.XX.XX
5    11 ms                  211.XX.X.XX
6     3 ms     2 ms     2 ms  2XX.XX.1XX.XX
7     2 ms     2 ms     1 ms  42.XX.2XX.1XX
8    32 ms     4 ms     3 ms  42.XX.2XX.2XX
9                          请求超时。
10     3 ms     2 ms     2 ms  223.5.5.5
跟踪完成。

## 测试结果的简要分析 [#测试结果的简要分析]

由于mtr（WinMTR）有更高的准确性，本文以其测试结果为例，参考如下要点进行分析。此处分析时以如下示例图为基础。

![](/docs-assets/faq/qvm/qvm-network/7055-use-the-ping-command-packet-loss-or-not-the-link-test-method/FsUX_KaKi7ZJT9-_xt1A1uv05o-p-fa6e38eab39f.webp)

### 要点一：网络区域 [#要点一网络区域]

正常情况下，从客户端到目标服务器的整个链路中会包含如下区域。

* 客户端本地网络，即本地局域网和本地网络提供商网络。如上图中的区域A。如果该区域出现异常，并且是客户端本地网络中的节点出现异常，则需要对本地网络进行相应的排查分析。如果是本地网络提供商网络出现异常，则需要向当地运营商反馈问题。
* 运营商骨干网络。如上图中的区域B。如果该区域出现异常，可以根据异常节点的IP查询其所属的运营商，直接向对应运营商进行反馈，或者通过[七牛云技术支持](https://account.alibabacloud.com/login/login.htm)，向运营商进行反馈。
* 目标服务器本地网络，即目标服务器所属提供商的网络。如上图中的区域C。如果该区域出现异常，需要向目标服务器所属的网络运营商反馈问题。

### 要点二：链路负载均衡 [#要点二链路负载均衡]

如上图中的区域D。如果中间链路某些部分启用了链路负载均衡，则mtr只会对首尾节点进行编号和探测统计。中间节点只会显示相应的IP或域名信息。

### 要点三：结合Avg（平均值）和StDev（标准偏差）综合判断 [#要点三结合avg平均值和stdev标准偏差综合判断]

由于链路抖动或其它因素的影响，节点的Best和Worst值可能相差很大。Avg统计了自链路测试以来所有探测的平均值，所以能更好的反应出相应节点的网络质量。而StDev越高，则说明数据包在相应节点的延时值越不相同，即越离散。所以标准偏差值可用于协助判断Avg是否真实反应了相应节点的网络质量。例如，如果标准偏差很大，说明数据包的延迟是不确定的。可能某些数据包延迟很小，例如25ms，而另一些延迟却很大，例如350ms，但最终得到的平均延迟反而可能是正常的。所以，此时Avg并不能很好的反应出实际的网络质量情况。

综上，建议的分析标准如下。

* 如果StDev很高，则同步观察相应节点的Best和Worst，来判断相应节点是否存在异常。
* 如果StDev不高，则通过Avg来判断相应节点是否存在异常。

> \*\*注：\*\*上述StDev高或者不高，并没有具体的时间范围标准。而需要根据同一节点其它列的延迟值大小来进行相对评估。比如，如果Avg为30ms，那么，当StDev为25ms，则认为是很高的偏差。而如果Avg为325ms，则StDev同样为25ms，反而认为是不高的偏差。

### 要点四：Loss%（丢包率）的判断 [#要点四loss丢包率的判断]

任一节点的Loss%（丢包率）如果不为零，则说明这一跳网络可能存在问题。导致相应节点丢包的原因通常有如下两种。

* 运营商基于安全或性能需求，限制了节点的ICMP发送速率，导致丢包。
* 节点确实存在异常，导致丢包。

结合异常节点及其后续节点的丢包情况，并参考如下内容，判定丢包原因。

* 如果随后节点均没有丢包，则通常表示异常节点丢包是由于运营商策略限制所致。可以忽略相关丢包。如上图中的第2跳所示。
* 如果随后节点也出现丢包，则通常说明异常节点确实存在网络异常，导致丢包。如上图中的第5跳所示。

 另外，上述两种情况可能同时发生，即相应节点既存在策略限速，又存在网络异常。对于这种情况，如果异常节点及其后续节点连续出现丢包，而且各节点的丢包率不同，则通常以最后几跳的丢包率为准。如上图所示，在第 5、6、7跳均出现了丢包。所以，最终丢包情况，以第7跳的40%作为参考。

### 要点五：关于延迟 [#要点五关于延迟]

关于延迟，有如下两种场景。

##### 场景一：延迟跳变 [#场景一延迟跳变]

如果在某一跳之后延迟明显陡增，则通常判断该节点存在网络异常。如上图所示，从第5跳之后的后续节点延迟明显陡增，则推断是第5跳节点出现了网络异常。不过，高延迟并不一定完全意味着相应节点存在异常。如上图所示，第5跳之后，虽然后续节点延迟明显陡增，但测试数据最终仍然正常到达了目的主机。所以，延迟大也有可能是在数据回包链路中引发的。所以，需要结合反向链路测试一并分析。

##### 场景二：ICMP限速导致延迟增加 [#场景二icmp限速导致延迟增加]

ICMP策略限速也可能会导致相应节点的延迟陡增，但后续节点通常会恢复正常。如上图所示，第3跳有100%的丢包率，同时延迟也明显陡增。但随后节点的延迟马上恢复了正常。所以判断该节点的延迟陡增及丢包是由于策略限速所致。

## 常见的链路异常场景 [#常见的链路异常场景]

常见的链路异常场景及测试报告如下。

### 场景一：目标主机网络配置不当 [#场景一目标主机网络配置不当]

示例数据如下。

\[root\@mycentos6 \~]# mtr —no-dns [www.google.com](http://www.google.com)
My traceroute  \[v0.75]
mycentos6.6 (0.0.0.0)                         Wed Jun 15 19:06:29 2016
Keys:  Help   Display mode                    Packets               Pings
Host                                        Loss%   Snt   Last   Avg  Best  Wrst StDev
1\. ???
2\. ???
3\. 1XX.X.X.X                              0.0%     10  521.3  90.1   2.7 521.3 211.3
4\. 11X.X.X.X                              0.0%     10    2.9   4.7   1.6  10.6   3.9
5\. 2X.X.X.X                               80.0%    10    3.0   3.0   3.0   3.0   0.0
6\. 2X.XX.XX.XX                            0.0%     10    1.7   7.2   1.6  34.9  13.6
7\. 1XX.1XX.XX.X                             0.0%     10    5.2   5.2   5.1   5.2   0.0
8\. 2XX.XX.XX.XX                             0.0%     10    5.3   5.2   5.1   5.3   0.1
9\. 173.194.200.105                          100.0%   10    0.0   0.0   0.0   0.0   0.0

在该示例中，数据包在目标地址出现了100%的丢包。从数据上看是数据包没有到达，其实很有可能是目标服务器相关安全策略（比如防火墙、iptables 等）禁用了ICMP所致，导致目的主机无法发送任何应答。所以，该场景需要排查目标服务器的安全策略配置。

### 场景二：ICMP限速 [#场景二icmp限速]

示例数据如下。

\[root\@mycentos6 \~]# mtr --no-dns [www.google.com](http://www.google.com)
My traceroute  \[v0.75]
mycentos6.6 (0.0.0.0)                         Wed Jun 15 19:06:29 2016
Keys:  Help   Display mode                    Packets               Pings
Host                                        Loss%   Snt   Last   Avg  Best  Wrst StDev
1\. 63.247.X.X               			 0.0%    10    0.3   0.6   0.3   1.2   0.3
2\. 63.247.X.XX                 		 0.0%    10    0.4   1.0   0.4   6.1   1.8
3\. 209.51.130.213              		 0.0%    10    0.8   2.7   0.8  19.0   5.7
4\. aix.pr1.atl.google.com        	        0.0%    10    6.7   6.8   6.7   6.9   0.1
5\. 72.14.233.56                 		 60.0%    10   27.2  25.3  23.1  26.4   2.9
6\. 209.85.254.247                		 0.0%    10   39.1  39.4  39.1  39.7   0.2
7\. 64.233.174.46                 		 0.0%    10   39.6  40.4  39.4  46.9   2.3
8\. gw-in-f147.1e100.net          		 0.0%    10   39.6  40.5  39.5  46.7   2.2

在该示例中，在第5跳出现了明显的丢包，但后续节点均未见异常。所以推断是该节点ICMP限速所致。该场景对最终客户端到目标服务器的数据传输不会有影响，所以，分析的时候可以忽略。

### 场景三：环路 [#场景三环路]

示例数据如下。

\[root\@mycentos6 \~]# mtr —no-dns [www.google.com](http://www.google.com)
My traceroute  \[v0.75]
mycentos6.6 (0.0.0.0)                         Wed Jun 15 19:06:29 2016
Keys:  Help   Display mode                    Packets               Pings
Host                                        Loss%   Snt   Last   Avg  Best  Wrst StDev
1\. 63.247.7X.X                  		 0.0%    10    0.3   0.6   0.3   1.2   0.3
2\. 63.247.6X.X                 		 0.0%    10    0.4   1.0   0.4   6.1   1.8
3\. 209.51.130.213                		 0.0%    10    0.8   2.7   0.8  19.0   5.7
4\. aix.pr1.atl.google.com        		 0.0%    10    6.7   6.8   6.7   6.9   0.1
5\. 72.14.233.56                  		 0.0%    10    0.0   0.0   0.0   0.0   0.0
6\. 72.14.233.57                  		 0.0%    10    0.0   0.0   0.0   0.0   0.0
7\. 72.14.233.56                  		 0.0%    10    0.0   0.0   0.0   0.0   0.0
8\. 72.14.233.57                  		 0.0%    10    0.0   0.0   0.0   0.0   0.0
9 ???                            		 0.0%    10    0.0   0.0   0.0   0.0   0.0

在该示例中，数据包在第5跳之后出现了循环跳转，导致最终无法到达目标服务器。这通常是由于运营商相关节点路由配置异常所致。所以，该场景需要联系相应节点归属运营商处理。

### 场景四：链路中断 [#场景四链路中断]

示例数据如下。

\[root\@mycentos6 \~]# mtr —no-dns [www.google.com](http://www.google.com)
My traceroute  \[v0.75]
mycentos6.6 (0.0.0.0)                         Wed Jun 15 19:06:29 2016
Keys:  Help   Display mode                    Packets               Pings
Host                                        Loss%   Snt   Last   Avg  Best  Wrst StDev
1\. 63.247.7X.X                  		 0.0%    10    0.3   0.6   0.3   1.2   0.3
2\. 63.247.6X.X                 		 0.0%    10    0.4   1.0   0.4   6.1   1.8
3\. 209.51.130.213                		 0.0%    10    0.8   2.7   0.8  19.0   5.7
4\. aix.pr1.atl.google.com        		 0.0%    10    6.7   6.8   6.7   6.9   0.1
5\. ???                           		 0.0%    10    0.0   0.0   0.0   0.0   0.0
6\. ???                           		 0.0%    10    0.0   0.0   0.0   0.0   0.0
7\. ???                           		 0.0%    10    0.0   0.0   0.0   0.0   0.0
8\. ???                           		 0.0%    10    0.0   0.0   0.0   0.0   0.0
9 ???                            		 0.0%    10    0.0   0.0   0.0   0.0   0.0

在该示例中，数据包在第4跳之后就无法收到任何反馈。这通常是由于相应节点中断所致。建议结合反向链路测试做进一步确认。该场景需要联系相应节点归属运营商处理。

## 链路测试步骤 [#链路测试步骤]

通常情况下，链路测试步骤如下图所示。

![](/docs-assets/faq/qvm/qvm-network/7055-use-the-ping-command-packet-loss-or-not-the-link-test-method/Fo0A_RZI6qdynCGa0woUu1xjm8Xo-b9fb38b172fc.webp)

相关步骤的详情说明如下。

### 步骤一：获取本地网络对应的公网IP [#步骤一获取本地网络对应的公网ip]

在客户端本地网络内访问淘宝IP地址库，获取本地网络对应的公网IP地址。

![](/docs-assets/faq/qvm/qvm-network/7055-use-the-ping-command-packet-loss-or-not-the-link-test-method/FvVlTn_KWSIVOtVfbeItRuXuZN7y-3aa643dbd80b.webp)

### 步骤二：正向链路测试（ping和mtr） [#步骤二正向链路测试ping和mtr]

从客户端向目标服务器做如下测试。

* 从客户端向目标服务器域名或IP做持续的ping测试，建议至少ping 100个数据包，记录测试结果。
* 根据客户端操作系统的不同，使用WinMTR或mtr，设置测试目的地址为目标服务器域名或IP，然后进行链路测试，记录测试结果。

### 步骤三：反向链路测试（ping和mtr） [#步骤三反向链路测试ping和mtr]

进入目标服务器系统内部做如下测试。

* 从目标服务器向[步骤一](#WixRs)获取的客户端IP做持续的ping测试，建议至少ping 100个数据包，记录测试结果。
* 根据目标服务器操作系统的不同，使用WinMTR或mtr，设置测试目的地址为客户端的IP地址，然后进行链路测试，记录测试结果。

### 步骤四：测试结果分析 [#步骤四测试结果分析]

参阅[测试结果的简要分析](#eMWjW)，对测试结果进行分析。确认异常节点后，访问如下链接或其他可以查询IP归属地的网站，获取该异常节点的归属运营商信息。如果是客户端本地网络相关节点出现异常，则需要对本地网络进行相应排查分析。如果是运营商相关节点出现异常，则需要向运营商反馈问题。查询结果类似如下。
![](/docs-assets/faq/qvm/qvm-network/7055-use-the-ping-command-packet-loss-or-not-the-link-test-method/Fh6MDjcRiawoJ5bzMbTLQxBHMFVL-32363dd5140f.webp)

## 测试完成后的解决方法 [#测试完成后的解决方法]

* 当出现ping丢包或ping不通时，首先请参考云服务器QVM网络故障诊断，排查是否为网络故障。
* 如果确认是因系统中病毒导致使用ping命令测试QVM实例的IP地址间歇性丢包，则可参考使用ping命令测试QVM实例的IP地址间歇性丢包进行处理。
* 如果是因删除QVM实例的默认安全组规则导致无法ping通QVM实例，可参考删除QVM实例的默认安全组规则导致无法ping通QVM实例进行处理。
* 如果在Linux系统内核没有禁PING的情况下，是因系统内部防火墙策略设置导致QVM服务器PING不通。可参考Linux系统的QVM中没有禁PING却PING不通的解决方法。

# 适用于 [#适用于]

* 云服务器 QVM


# 无法访问 QVM 实例中运行网站的详细排查方法 (/faq/qvm/qvm-network/7056-don-t-have-access-to-detailed-screening-method-of-ecs-instance-running-in-the-web-site)



最近更新时间: 2026-05-07 16:24:58

> **免责声明：** 本文档可能包含第三方产品信息，该信息仅供参考。七牛云对第三方产品的性能、可靠性以及操作可能带来的潜在影响，不做任何暗示或其他形式的承诺。

# **概述** [#概述]

本文主要介绍无法访问QVM实例中运行网站的排查方法。

# 详细信息 [#详细信息]

> 七牛云提醒您：
>
> * 如果您对实例或数据有修改、变更等风险操作，务必注意实例的容灾、容错能力，确保数据安全。
> * 如果您对实例（包括但不限于QVM、RDS）等进行配置与数据修改，建议提前创建快照或开启RDS日志备份等功能。
> * 如果您在七牛云平台授权或者提交过登录账号、密码等安全信息，建议您及时修改。

无法打开网站时，应该先查看报错提示的含义，查看报错原因。如果没有返回状态码，可参考以下步骤进行排查。

* [网络通信问题](#h_3635120323071590042175297)
* [端口通信问题](#端口通信问题)
* [防火墙配置异常](#防火墙配置异常)
* [重新配置安全组公网规则](#安全组公网规则)
* [其他问题](#WSwYj)

## 网络通信问题 [#网络通信问题]

本节主要介绍分别在Linux系统和Windows系统中网络通信问题的排查方法。

### Linux实例网络通信问题排查 [#linux实例网络通信问题排查]

* 执行`ifconfig`或者`ip addr`命令，查看IP地址。系统显示类似如下。

![](/docs-assets/faq/qvm/qvm-network/7056-don-t-have-access-to-detailed-screening-method-of-ecs-instance-running-in-the-web-site/FhMMqj-fYJ2QKNKz7xfQdZtYoUwq-91a9f8a85175.webp)
![](/docs-assets/faq/qvm/qvm-network/7056-don-t-have-access-to-detailed-screening-method-of-ecs-instance-running-in-the-web-site/Fl0T_nbPm3P45SaNE41eCMxC5C8k-68581dbd9607.webp)   

* 执行以下命令，通过实例路由表查看网关。

route -n

系统显示类似如下。
![](/docs-assets/faq/qvm/qvm-network/7056-don-t-have-access-to-detailed-screening-method-of-ecs-instance-running-in-the-web-site/Fp_q1msvbtHTB_krtRAru3cXx0lg-b1b9ef002935.webp)

* 使用ping命令访问公网，检查是否为网络通信问题。

### Windows实例网络通信问题排查 [#windows实例网络通信问题排查]

* 打开命令行窗口，执行以下命令，查看IP地址。

ipconfig

* 执行以下命令，通过实例路由表查看网关。

route print

> **说明**：
>
> * 若网卡驱动未开启或网卡配置有问题，请检查网卡驱动，并重新安装。
>
> * 关于网络相关问题的测试工具，请参见[ping 丢包或不通时链路测试说明](/faq/qvm/qvm-network/7055-use-the-ping-command-packet-loss-or-not-the-link-test-method)。

* 使用ping命令访问公网，检查是否为网络通信问题。

## 端口通信问题 [#端口通信问题]

本节主要介绍分别在Linux系统和Windows系统中端口通信问题的排查方法。

### Linux实例端口通信问题 [#linux实例端口通信问题]

* 执行以下命令，检测sshd服务的运行状态，确认端口是否有正常监听。

netstat -antpu | grep sshd

系统显示类似如下。

![sshdservice](/docs-assets/faq/qvm/qvm-network/7056-don-t-have-access-to-detailed-screening-method-of-ecs-instance-running-in-the-web-site/Fo5nTrvqe7SqhAKfXubgQI-q8xhT-44b42e43e3c4.webp)

* 根据不同操作系统，执行下列命令查看服务运行状态。

* CentOS 6：`service sshd status`

* CentOS 7：`systemctl status sshd`

* 如果sshd服务没有正常运行，则根据不同操作系统，执行下列命令手动启动sshd服务。

* CentOS 6：`service sshd restart`

* CentOS 7：`systemctl restart sshd`

* 查看sshd程序日志。

* 如果无法正常启动sshd服务，CentOS 6系统一般会直接输出错误信息，而CentOS 7启动时没有输出信息，需要通过secure日志进行查看。sshd日志所在目录：`/var/log/secure`。

* 通过secure日志的报错信息，一般是可以定位绝大部分sshd启动异常的问题。

### Windows 实例端口通信问题 [#windows-实例端口通信问题]

依次执行以下命令，检测远程端口，其中\[$PID]为第一条命令返回的PID值。

Tasklist /svc | findstr "Ter"
netstat -ano | findstr "\[$PID]"

系统返回类似如下。

![remoteport](/docs-assets/faq/qvm/qvm-network/7056-don-t-have-access-to-detailed-screening-method-of-ecs-instance-running-in-the-web-site/FkmgZB-EzX-T_F409_cNYsQNSN_M-53d6f21876f4.webp)

## 防火墙配置异常 [#防火墙配置异常]

本节主要介绍分别在Linux系统和Windows系统中防火墙配置异常的排查方法。

### Windows实例中关闭防火墙后连接恢复正常 [#windows实例中关闭防火墙后连接恢复正常]

> \*\*注意：\*\*只有在已授权可关闭防火墙的情况下，才能做该项排查。

* 调整防火墙配置策略。。

* 调整后，重新进行远程连接。

### Linux实例中关闭Iptables后连接恢复正常 [#linux实例中关闭iptables后连接恢复正常]

> \*\*注意：\*\*只有在已授权可关闭Iptables的情况下，才能做调整Iptables配置策略排查。

* 执行以下命令，查看防火墙规则。

iptables -nvL --line-number

> **说明**：
>
> * -n：不对IP地址进行反查，加上这个参数显示速度会快很多。
>
> * -v：输出详细信息，包含通过该规则的数据包数量、总字节数及相应的网络接口。
>
> * -L：查看当前表的所有规则，默认查看的是filter表，如果要查看NAT表，可以加上`-t NAT`参数。

* 修改iptables规则，具体操作步骤如下所示。

> **说明**：如果之前已设置过规则策略，则执行`cp -a /etc/sysconfig/iptables /etc/sysconfig/iptables.bak`命令保存一份原有的Iptables文件，避免丢失已设置过策略。

* 执行以下命令，清空实例上所有的规则。

iptables -F

* 执行以下命令，拒绝INPUT方向所有的请求。

iptables -P INPUT DROP

> **注意**：线上业务请勿直接操作，会导致业务直接中断。

* 依次执行下列命令，放行80端口。

iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A OUTPUT -p tcp --sport 80 -j ACCEPT

或者您也可以参见以下命令，允许指定IP访问80端口，此处以“192.168.1.1”为例。

iptables -I INPUT -s 192.168.1.1 -p tcp --dport 80 -j ACCEPT

* 执行以下命令，查看添加的规则是否生效。

iptables -L

系统显示类似如下。

![iptables -L](/docs-assets/faq/qvm/qvm-network/7056-don-t-have-access-to-detailed-screening-method-of-ecs-instance-running-in-the-web-site/FrV2hXx1i0xqPgXpJUJQdIVM7J6X-7fb28715279c.webp)

* 执行以下命令，保存添加的规则。

iptables-save > /etc/sysconfig/iptables

* 执行`service iptables restart`或`/etc/init.d/iptables restart`命令，重启Iptables。

* 执行以下命令，重启实例验证配置。

systemctl reboot

* 重新进行SSH连接实例。

## 重新配置安全组公网规则 [#重新配置安全组公网规则]

由于安全组默认没有放行网站使用的端口（如80端口），因此需要自行放行该端口。以下是放行该端口的具体操作步骤，添加安全组公网规则。

* 登录[QVM 控制台](https://portal.qiniu.com/qvm/dashboard "登陆 QVM 控制台")，定位实例。
* 单击实例ID，进入详情页，再单击**本实例安全组**>**安全组列表**>**配置规则**。
* 根据网站使用的端口配置新的安全组规则，放行网站使用的端口，最后单击**确定**。

# 适用于 [#适用于]

* 云服务器QVM


# 检查TCP 80端口是否正常工作 (/faq/qvm/qvm-network/7057-check-the-tcp-port-80-is-working-correctly)



最近更新时间: 2026-05-07 16:30:46

# 概述 [#概述]

本文主要介绍在不同操作系统中检查TCP 80端口是否正常工作的方法。

# 详细信息 [#详细信息]

> 七牛云提醒您：
>
> * 如果您对实例或数据有修改、变更等风险操作，务必注意实例的容灾、容错能力，确保数据安全。
> * 如果您对实例（包括但不限于QVM、RDS）等进行配置与数据修改，建议提前创建快照或开启RDS日志备份等功能。
> * 如果您在七牛云平台授权或者提交过登录账号、密码等安全信息，建议您及时修改。

如果实例无法对外提供HTTP服务，可以按以下思路检查Web服务相关的接口（默认为TCP 80）是否正常工作。

* 在QVM管理控制台，确认安全组已经放行该端口。
* 远程连接QVM实例，确认服务已经开启。
* 确认端口正常被监听。如没有，请修改监听地址。
* 确认实例防火墙已经放行服务。
* 若仍无法解决，请提交工单咨询。

本文分别介绍在以下不同操作系统中检查TCP 80端口是否正常工作的方法：

* [Windows Server 2012](#win2012)
* [Windows Server 2008](#win2008)
* [CentOS 7.3](#centos)
* [Ubuntu 16.04](#ubuntu)

以下是在Windows Server 2012系统中检查TCP 80端口是否正常工作的方法。

## Windows Server 2012 [#windows-server-2012]

> **说明**：在Windows 2012系统的Windows实例中安装IIS服务为例。

* 登录[QVM 管理控制台](https://portal.qiniu.com/qvm/dashboard "点击进入 QVM 管理控制台")，确认实例所在安全组里已经添加以下安全组规则。

| 网络类型   | 网卡类型  | 规则方向 | 授权策略 | 协议类型     | 端口范围  | 授权类型  | 授权对象       | 优先级 |
| ------ | ----- | ---- | ---- | -------- | ----- | ----- | ---------- | --- |
| VPC 网络 | 不需要配置 | 入方向  | 允许   | HTTP(80) | 80/80 | 地址段访问 | 10.0.0.0/8 | 1   |
| 经典网络   | 公网    | 入方向  | 允许   | HTTP(80) | 80/80 | 地址段访问 | 10.0.0.0/8 | 1   |

* 参见远程连接 Windows 实例，登录Windows实例。

* 以下是查看IIS服务是否已经开启的操作步骤：

* 在**服务器管理器**窗口，单击**工具**>**Internet Information Services (IIS)管理器**。如果找不到这个选项，则说明没有成功安装IIS服务，需要重新安装IIS服务。
  ![Windows2012\_确认已安装IIS服务](/docs-assets/faq/qvm/qvm-network/7057-check-the-tcp-port-80-is-working-correctly/Fkl16U7LLj0vrDPOhsoUEsWubozS-5d1caf288240.webp)

* 在**Internet Information Services (IIS)管理器**窗口中确认以下信息：

* 在**连接**导航栏里，右键单击实例ID，如果**启动**处于灰色状态，表示IIS服务已经开启。

* 单击**网站**，在右边列表页查看您安装的网站的状态。如果网站**状态**为**已停止**，则单击网站，在右侧**操作**栏的**管理站点**部分，单击**启动**，启动网站。
  ![Windows2012\_确认站点已启动](/docs-assets/faq/qvm/qvm-network/7057-check-the-tcp-port-80-is-working-correctly/FtGc8flpqeXJ1dlQMTwYOBmycJS-1a33cabef22c.webp)

* 以下是查看端口在实例中是否正常被监听的操作步骤：

* 启动**命令提示符**。

* 执行以下命令。

netstat -ano | findstr :80

如果返回类似`TCP 0.0.0.0:80 0.0.0.0:0 LISTENING 4`，则说明80端口正常全网监听。如果返回的不是该端口，请在Internet Information Services (IIS)管理器窗口中，单击指定网站，然后单击右侧**操作**栏中的**绑定**，将绑定的端口该为80端口。

* 以下是查看实例里防火墙是否已经放行Web服务的操作步骤：

* 单击**控制面板**>**系统与安全**>**Windows 防火墙**。

* 根据防火墙状态，执行不同操作。

* 如果防火墙处于关闭状态，不需要再做其他处理。如果仍无法访问网站，请提交工单咨询。

* 如果防火墙处于开启状态，则执行以下操作。

* 单击**高级设置**。

* 在弹出窗口的左侧导航栏中，单击**入站规则**。

* 选择&#x2A;*万维网服务（HTTP 流入量）**，如果处于禁用状态，在**操作**栏里，单击**启用规则**。
  ![Windows2012\_防火墙里启用HTTP入站规则](/docs-assets/faq/qvm/qvm-network/7057-check-the-tcp-port-80-is-working-correctly/FkkFe-6b9HFjjYDArwgLpnMe3u9Y-3d9e40314bb7.webp)

* 完成上述检查，如果仍不能访问实例，请提交工单咨询。

以下是在Windows Server 2008系统中检查TCP 80端口是否正常工作的方法。

## Windows Server 2008 [#windows-server-2008]

> **说明**：以在Windows 2008系统的Windows实例中安装IIS服务为例。

* 登录[QVM 管理控制台](https://portal.qiniu.com/qvm/dashboard "点击进入 QVM 管理控制台")，确认实例所在安全组里已经添加以下安全组规则。

| 网络类型   | 网卡类型  | 规则方向 | 授权策略 | 协议类型     | 端口范围  | 授权类型  | 授权对象       | 优先级 |
| ------ | ----- | ---- | ---- | -------- | ----- | ----- | ---------- | --- |
| VPC 网络 | 不需要配置 | 入方向  | 允许   | HTTP(80) | 80/80 | 地址段访问 | 10.0.0.0/8 | 1   |
| 经典网络   | 公网    | 入方向  | 允许   | HTTP(80) | 80/80 | 地址段访问 | 10.0.0.0/8 | 1   |

* 参见远程连接 Windows 实例，登录Windows实例。

* 以下是查看IIS服务是否已经开启的操作步骤。

* 在**服务器管理器**窗口，选择**角色**>**Web 服务器**。如果找不到这个选项，则说明没有成功安装IIS服务。

* 在**Web 服务器**窗口，确认**系统服务**部分显示为**全部正在运行**。如果不是这个状态，请启动所有服务。
  ![Windows2008\_确认已安装IIS服务](/docs-assets/faq/qvm/qvm-network/7057-check-the-tcp-port-80-is-working-correctly/Fi4NUDfHZI-QEF90Mt826ZsZQo_g-ec25e4348a09.webp)

* 以下是查看端口在实例中是否正常被监听的操作步骤。

* 启动**命令提示符**。

* 执行以下命令。

netstat -ano | findstr :80

如果返回`TCP 0.0.0.0:80 0.0.0.0:0 LISTENING 4`，则说明80端口正常全网监听。如果返回的不是该端口，请在Internet Information Services (IIS)管理器窗口中，单击指定网站，然后单击右侧**操作**栏中的**绑定**，将绑定的端口该为80端口。

* 以下是查看实例里防火墙是否已经放行Web服务的操作步骤。

* 单击**控制面板**>**系统与安全**>**检查防火墙状态**。

* 根据防火墙状态，执行不同操作。

* 如果防火墙处于关闭状态，不需要再做其他处理。如果仍无法访问网站，请提交工单咨询。

* 如果防火墙处于开启状态，则执行以下操作。

* 单击**高级设置**。

* 在弹出窗口的左侧导航栏中，单击**入站规则**。

* 选择&#x2A;*万维网服务（HTTP 流入量）**，如果处于禁用状态，在**操作**栏里，单击**启用规则**。
  ![Windows2008\_防火墙里启用HTTP入站规则](/docs-assets/faq/qvm/qvm-network/7057-check-the-tcp-port-80-is-working-correctly/FvILzh_B0hheHLCN_6J0zxIQfnZt-eb3bd2cb71b1.webp)

* 完成上述检查，如果仍不能访问实例，请提交工单咨询。

以下是在CentOS 7.3系统中检查TCP 80端口是否正常工作的方法。

## CentOS 7.3 [#centos-73]

> **说明**：以在CentOS 7.3系统的Linux实例中安装Nginx服务为例。

* 登录[QVM 管理控制台](https://portal.qiniu.com/qvm/dashboard "点击进入 QVM 管理控制台")，确认实例所在安全组里已经添加以下安全组规则。

| 网络类型   | 网卡类型  | 规则方向 | 授权策略 | 协议类型     | 端口范围  | 授权类型  | 授权对象       | 优先级 |
| ------ | ----- | ---- | ---- | -------- | ----- | ----- | ---------- | --- |
| VPC 网络 | 不需要配置 | 入方向  | 允许   | HTTP(80) | 80/80 | 地址段访问 | 10.0.0.0/8 | 1   |
| 经典网络   | 公网    | 入方向  | 允许   | HTTP(80) | 80/80 | 地址段访问 | 10.0.0.0/8 | 1   |

* 参见远程连接 Linux实例，登录Linux实例。
* 执行以下运行命令。

systemctl status nginx

如果系统返回类似如下，则说明Nginx已经启动。如果未开启，则执行`systemctl start nginx`命令。
![CentOS7.3\_nginx已启动](/docs-assets/faq/qvm/qvm-network/7057-check-the-tcp-port-80-is-working-correctly/FiIFcSKNt5TvRXl24snrxNy9u2zc-f91ecee5f573.webp)

* 执行以下命令，查看端口在实例中是否正常被监听。

netstat -an | grep 80

如果返回`tcp 0 0 0.0.0.0:80 0.0.0.0:* LISTEN`，则说明80端口正常全网监听。如果返回的不是上述结果，请修改监听地址。关于如何修改监听地址，请参见如何修改Nginx服务端口监听地址。

* CentOS 7之后的版本默认安装Firewalld。如果已经启用`firewalld.service`，则需要放行 TCP 80 端口。执行以下命令。若返回结果为`success`，则表示已经放行TCP 80端口。

firewall-cmd --add-port=80/tcp --permanent

> 使用CentOS 7之前的版本并开启默认防火墙iptables时，应注意iptables默认不拦截访问，如果配置了iptables规则，需要执行以下步骤。
>
> * 查看规则列表：执行命令 `iptables --line -vnL`。根据返回结果执行不同操作。
> * 如果设置了默认拦截，添加规则放行TCP 80端口。执行命令`iptables -A INPUT -p tcp --dport 80 -j ACCEPT`。
> * 如果设置了DROP TCP 80端口，替换规则放行 80 端口。执行命令`iptables -R INPUT [80端口对应的规则编号] -p tcp --dport 80 -j ACCEPT`。
> * 保存上述规则，执行命令 `service iptables save`。

* 完成上述检查，如果仍不能访问实例，请提交工单咨询。

以下是在Ubuntu 16.04系统中检查TCP 80端口是否正常工作的方法。

## Ubuntu 16.04 [#ubuntu-1604]

> **说明**：以在Ubuntu 16.04系统的Linux实例中安装Apache2 Web服务器为例。

* 登录[QVM 管理控制台](https://portal.qiniu.com/qvm/dashboard "点击进入 QVM 管理控制台")，确认实例所在安全组里已经添加以下安全组规则。

| 网络类型   | 网卡类型  | 规则方向 | 授权策略 | 协议类型     | 端口范围  | 授权类型  | 授权对象       | 优先级 |
| ------ | ----- | ---- | ---- | -------- | ----- | ----- | ---------- | --- |
| VPC 网络 | 不需要配置 | 入方向  | 允许   | HTTP(80) | 80/80 | 地址段访问 | 10.0.0.0/8 | 1   |
| 经典网络   | 公网    | 入方向  | 允许   | HTTP(80) | 80/80 | 地址段访问 | 10.0.0.0/8 | 1   |

* 参见远程连接 Linux实例，登录Linux实例。

* 查看Apache2 Web服务器是否已经开启。执行命令`service apache2 status`。如果返回以下结果，说明 Apache2 Web服务器已经启动。如果未开启，执行命令 `service apache2 start`。
  ![Ubuntu 16.04\_Apache2 Web 服务器正常工作](/docs-assets/faq/qvm/qvm-network/7057-check-the-tcp-port-80-is-working-correctly/FktOd7G3YGfOEwmGA19hi1ZV6Hmu-93c78b965572.webp)

* 执行以下命令，查看端口在实例中是否正常被监听。

netstat -an | grep 80

如果返回`tcp 0 0 0.0.0.0:80 0.0.0.0:* LISTEN`，则说明80端口正常全网监听。如果返回的不是上述结果，请修改监听地址。关于如何修改监听地址，请参见如何修改Apache服务端口监听地址。

* 如果您已经启用UFW（Ubuntu 预装防火墙），需要放行TCP 80端口或HTTP服务。执行命令`ufw allow 80/tcp`或`ufw allow http`。返回结果为`Rule added` 表示已经放行TCP 80端口或HTTP服务。

> **说明**：如果实例中已经安装Firewalld并且已经启用firewalld.service，若需要放行 TCP 80 端口，执行命令`firewall-cmd --add-port=80/tcp --permanent`。返回结果为`success`即表示已经放行TCP 80端口。

* 完成上述检查，如果仍不能访问实例，请提交工单咨询。

# 适用于 [#适用于]

* 云服务器QVM


# Linux实例网站访问丢包延时高的排查方法 (/faq/qvm/qvm-network/7058-linux-instance-website-lost-package-delay-high-screening-method)



最近更新时间: 2026-05-07 16:44:13

# 概述 [#概述]

当网站访问很慢或无法访问时，若已经排除显著的问题，而使用ping命令检测到有明显丢包时，建议您做链路测试。Linux环境下，推荐优先使用mtr命令行工具测试，或使用traceroute命令行工具进行链路测试来判断问题来源。通常情况下，链路测试步骤如下。

1. 利用链路测试工具探测网络状况和服务器状态。
2. 根据链路测试结果分析处理。

# 详细信息 [#详细信息]

> 七牛云提醒您：
>
> * 如果您对实例或数据有修改、变更等风险操作，务必注意实例的容灾、容错能力，确保数据安全。
> * 如果您对实例（包括但不限于QVM、RDS）等进行配置与数据修改，建议提前创建快照或开启RDS日志备份等功能。
> * 如果您在七牛云平台授权或者提交过登录账号、密码等安全信息，建议您及时修改。

如下分别介绍[mtr命令行工具](#TPrCz)和[tracert命令行工具](#h2-traceroute-2)的使用方法及如何分析链路测试结果。

## mtr命令行工具 [#mtr命令行工具]

mtr（My traceroute）几乎是所有Linux发行版本预装的网络测试工具，集成了tracert与ping这两个命令的图形界面，功能十分强大。ping与tracert通常被用来检测网络状况和服务器状态，具体说明如下。

| 命令名称    | 具体说明                                      |
| ------- | ----------------------------------------- |
| ping    | 送出封包到指定的服务器。如果服务器有回应就会传送回封包，并附带返回封包来回的时间。 |
| tracert | 返回从用户的电脑到指定的服务器中间经过的所有节点（路由）以及每个节点的回应速度。  |

mtr默认发送ICMP数据包进行链路探测，通过“-u”参数指定UDP数据包用于探测。相对于traceroute只做一次链路跟踪测试，mtr会对链路上的相关节点做持续探测并给出相应的统计信息。mtr能避免节点波动对测试结果的影响，所以其测试结果更正确，建议优先使用。

### 用法说明 [#用法说明]

mtr \[-hvrctglspni46] \[--help] \[--version] \[--report]
\[--report-cycles=COUNT] \[--curses] \[--gtk]
\[--raw] \[--split] \[--no-dns] \[--address interface]
\[--psize=bytes/-s bytes]
\[--interval=SECONDS] HOSTNAME \[PACKETSIZE]

### 示例输出 [#示例输出]

\[root\@centos \~]# mtr 223.5.5.5
My traceroute \[v0.75]
mycentos6.6 (0.0.0.0) Wed Jun 15 23:16:27 2016
Keys: Help Display mode Restart statistics Order of fields quit
Packets Pings
Host Loss% Snt Last Avg Best Wrst StDev
1\. ???
2\. 192.X.X.20 0.0% 7 13.1 5.6 2.1 14.7 5.7
3\. 111.X.X.41 0.0% 7 3.0 99.2 2.7 632.1 235.4
4\. 111.X.X.197 0.0% 7 1.8 2.0 1.2 2.9 0.6
5\. 211.X.X.25 0.0% 6 0.9 4.7 0.9 13.9 5.8
6\. 211.X.X.70 0.0% 6 1.8 22.8 1.8 50.8 23.6
211.X.X.134
211.X.X.2
211.X.X.66
7\. 42.X.X.186 0.0% 6 1.4 1.6 1.3 1.8 0.2
42.X.X.198
8\. 42.X.X.246 0.0% 6 2.8 2.9 2.6 3.2 0.2
42.X.X.242
9\. ???
10\. 223.5.5.5 0.0% 6 2.7 2.7 2.5 3.2 0.3

### 常见可选参数说明 [#常见可选参数说明]

* -r或--report：以报告模式显示输出。
* -p或--split：将每次追踪的结果分别列出来，而非--report统计整个结果。
* -s或--psize：指定ping数据包的大小。
* -n或--no-dns：不对IP地址做域名反解析。
* -a或--address：设置发送数据包的IP地址。用于主机有多个IP的情况。
* -4：只使用IPv4协议。
* -6：只使用IPv6协议。

在mtr运行过程中，您也可以输入相应字母来快速切换模式，各字母的含义如下。

* ?或h：显示帮助菜单。
* d：切换显示模式。
* n：切换启用或禁用DNS域名解析。
* u：切换使用ICMP或UDP数据包进行探测。

### 返回结果说明 [#返回结果说明]

默认配置下，返回结果中各数据列的说明如下。

* 第一列（Host）：节点IP地址和域名。按 **n** 键可切换显示。
* 第二列（Loss%）：节点丢包率。
* 第三列（Snt）：每秒发送数据包数。默认值是10，可以通过“-c”参数指定。
* 第四列（Last）：最近一次的探测延迟。
* 第五、六、七列（Avg、Best、Worst）：分别是探测延迟的平均值、最小值和最大值。
* 第八列（StDev）：标准偏差。越大说明相应节点越不稳定。

## traceroute命令行工具 [#traceroute命令行工具]

traceroute是几乎所有Linux发行版本预装的网络测试工具，用于跟踪Internet 协议（IP）数据包传送到目标地址时经过的路径。traceroute先发送最大存活时间值（Max\_TTL）的UDP探测数据包，然后侦听从网关开始的整个链路上的ICMP TIME\_EXCEEDED响应。探测从TTL=1开始，TTL值逐步增加，直至接收到ICMP PORT\_UNREACHABLE消息。ICMP PORT\_UNREACHABLE消息用于标识目标主机已经被定位，或命令已经达到允许跟踪的最大TTL值。traceroute默认发送UDP数据包进行链路探测。可以通过“-I”参数来指定发送ICMP数据包用于探测。

### 用法说明 [#用法说明-1]

traceroute \[-I] \[ -m Max\_ttl ] \[ -n ] \[ -p Port ] \[ -q Nqueries ] \[ -r ] \[ -s SRC\_Addr ] \[  -t TypeOfService ] \[ -f flow ] \[ -v ] \[  -w WaitTime ] Host \[ PacketSize ]

### 示例输出 [#示例输出-1]

\[root\@centos \~]# traceroute -I 223.5.5.5
traceroute to 223.5.5.5 (223.5.5.5), 30 hops max, 60 byte packets
1 \* \* \*
2 192.X.X.20 (192.X.X.20) 3.965 ms 4.252 ms 4.531 ms
3 111.X.X.41 (111.X.X.41) 6.109 ms 6.574 ms 6.996 ms
4 111.X.X.197 (111.X.X.197) 2.407 ms 2.451 ms 2.533 ms
5 211.X.X.25 (211.X.X.25) 1.321 ms 1.285 ms 1.304 ms
6 211.X.X.70 (211.X.X.70) 2.417 ms 211.138.114.66 (211.X.X.66) 1.857 ms 211.X.X.70 (211.X.X.70) 2.002 ms
7 42.X.X.194 (42.X.X.194) 2.570 ms 2.536 ms 42.X.X.186 (42.X.X.186) 1.585 ms
8 42.X.X.246 (42.X.X.246) 2.706 ms 2.666 ms 2.437 ms
9 \* \* \*
10 public1.alidns.com (223.5.5.5) 2.817 ms 2.676 ms 2.401 ms

### 常见可选参数说明 [#常见可选参数说明-1]

* -d：使用Socket层级的排错功能。
* -f：设置第一个检测数据包的存活数值TTL的大小。
* -F：设置不要分段标识。
* -g：设置来源路由网关，最多可设置8个。
* -i：使用指定的网卡送出数据包。用于主机有多个网卡时。
* -I：使用ICMP数据包替代UDP数据包进行探测。
* -m：设置检测数据包的最大存活数值TTL的大小。
* -n：直接使用IP地址而非主机名称（禁用DNS反查）。
* -p：设置UDP传输协议的通信端口。
* -r：忽略普通的Routing Table，直接将数据包送到远端主机上。
* -s：设置本地主机送出数据包的IP地址。
* -t：设置检测数据包的TOS数值。
* -v：详细显示指令的执行过程。
* -w：设置等待远端主机回包时间。
* -x：开启或关闭数据包的正确性检验。

## 分析链路测试结果 [#分析链路测试结果]

以如下链路测试结果示例图为基础进行阐述。

![](/docs-assets/faq/qvm/qvm-network/7058-linux-instance-website-lost-package-delay-high-screening-method/FjkXqTlCQXPO_Bwu6xv9dpNV9U01-31039b9789b2.webp)

1. 判断各区域是否存在异常，并根据各区域的情况分别处理。
   * 区域A：客户端本地网络，即本地局域网和本地网络提供商网络。针对该区域异常，客户端本地网络相关节点问题，请对本地网络进行排查分析。本地网络提供商网络相关节点问题，请向当地运营商反馈。

   * 区域B：运营商骨干网络。针对该区域异常，可根据异常节点IP查询归属运营商，然后直接或通过七牛云售后技术支持，向相应运营商反馈问题。

   * 区域C：目标服务器本地网络，即目标主机归属网络提供商网络。针对该区域异常，需要向目标主机归属网络提供商反馈问题。

2. 结合Avg（平均值）和StDev（标准偏差），判断各节点是否存在异常。

   * 若StDev很高，则同步观察相应节点的Best和Worst，来判断相应节点是否存在异常。
   * 若StDev不高，则通过Avg来判断相应节点是否存在异常。

     > \*\*注意：\*\*上述StDev高或者不高，并没有具体的时间范围标准。而需要根据同一节点其它列的延迟值大小来进行相对评估。比如，如果Avg为30ms，那么，当StDev为25ms，则认为是很高的偏差。而如果Avg为325ms，则同样的StDev为25ms，反而认为是不高的偏差。

3. 查看节点丢包率，若“Loss%”不为零，则说明这一跳路由的网络可能存在问题。导致节点丢包的原因通常有两种。

   * 人为限制了节点的ICMP发送速率，导致丢包。
   * 节点确实存在异常，导致丢包。

4. 确定当前异常节点的丢包原因。

   * 若随后节点均没有丢包，说明当前节点丢包是由于运营商策略限制所致，可以忽略。如前文链路测试结果示例图中的第2跳路由的网络所示。

   * 若随后节点也出现丢包，说明当前节点存在网络异常，导致丢包。如前文链路测试结果示例图中的第5跳路由的网络所示。

     > \*\*说明：\*\*前述两种情况可能同时发生，即相应节点既存在策略限速，又存在网络异常。对于这种情况，若当前节点及其后续节点连续出现丢包，而且各节点的丢包率不同，则通常以最后几跳路由的网络的丢包率为准。如前文链路测试结果示例图所示，在第5、6、7跳路由的网络均出现了丢包。所以，最终丢包情况，以第7跳路由的网络的40%作为参考。

5. 通过查看是否有明显的延迟，来确认节点是否存在异常。通过如下两个方面进行分析。

   * 若某一跳路由的网络之后延迟明显陡增，则通常判断该节点存在网络异常。如前文链路测试结果示例图所示，从第5跳路由的网络之后的后续节点延迟明显陡增，则推断是第5跳路由的网络节点出现了网络异常。

     > 注：高延迟并不一定完全意味着相应节点存在异常，延迟大也有可能是在数据回包链路中引发的，建议结合反向链路测试一并分析。

   * ICMP策略限速也可能会导致相应节点的延迟陡增，但后续节点通常会恢复正常。如前文链路测试结果示例图所示，第3跳路由的网络有100%的丢包率，同时延迟也明显陡增。但随后节点的延迟马上恢复了正常。所以判断该节点的延迟陡增及丢包是由于策略限速所致。

## 操作建议 [#操作建议]

* 若数据包在目标地址出现了100%的丢包，建议对目标服务器的安全策略配置进行排查。
* 若数据包出现循环跳转，导致无法到达目标服务器，建议联系相应节点归属运营商处理。
* 若数据包在跳转后无法收到任何反馈，建议结合反向链路测试做进一步确认，并联系相应节点归属运营商进行处理。
* 七牛云中国内地机房和其他国家或地区机房有网络通信的专线，为降低通信时候的丢包率，推荐使用高速通道。
* 若主机掉包和延迟非常高，建议做mtr双向测试，即本地到服务器的和服务器到本地的测试。无法远程登录时，请通过管理终端进行登录。

# 适用于 [#适用于]

* 云服务器 QVM


# Windows实例网络访问丢包延时高的排查方法 (/faq/qvm/qvm-network/7059-windows-instance-network-access-packet-delay-high-screening-method)



最近更新时间: 2026-05-07 16:47:13

# 概述 [#概述]

当网站访问很慢或无法访问时，若已经排除显著的问题，而使用ping命令检测到有明显丢包时，建议您做链路测试。在Windows环境中，推荐优先使用WinMTR工具，或者tracert命令行进行链路测试以判断问题来源。通常情况下，链路测试步骤如下。

1. 利用链路测试工具探测网络状况和服务器状态。
2. 根据链路测试结果分析处理。

# 详细信息 [#详细信息]

> 七牛云提醒您：
>
> * 如果您对实例或数据有修改、变更等风险操作，务必注意实例的容灾、容错能力，确保数据安全。
> * 如果您对实例（包括但不限于QVM、RDS）等进行配置与数据修改，建议提前创建快照或开启RDS日志备份等功能。
> * 如果您在七牛云平台授权或者提交过登录账号、密码等安全信息，建议您及时修改。

## WinMTR工具 [#winmtr工具]

mtr（My traceroute）作为一款网络测试工具，集成了tracert与ping这两个命令的图形界面。ping与tracert通常被用于检测网络状况和服务器状态，具体说明如下。

| 命令名称    | 具体说明                                     |
| ------- | ---------------------------------------- |
| ping    | 送出封包到指定的服务器。如果服务器有回应就会传送回封包，并附带返回封包来回的时间 |
| tracert | 返回从用户的电脑到指定的服务器中间经过的所有节点（路由）以及每个节点的回应速度。 |

WinMTR是mtr工具在Windows环境下的图形化实现，适合Windows下做路由追踪及ping测试。WinMTR默认发送ICMP数据包进行探测，无法切换。

相比tracert命令行工具，WinMTR能避免节点波动对测试结果的影响，测试结果更正确。Windows环境下，建议优先使用WinMTR进行链路测试。下载[WinMTR工具](https://sourceforge.net/projects/winmtr/files/latest/download)。

1. 下载WinMTR工具后，直接解压运行。运行程序后，在 **Host** 字段输入目标服务器域名或IP。
   ![1](/docs-assets/faq/qvm/qvm-network/7059-windows-instance-network-access-packet-delay-high-screening-method/Fk2y5rl32mSoMXqywbyXf3o8OOxH-24302ab5088a.webp)
2. 单击 **Start** 开始测试。开始测试后，相应按钮变成了 **Stop**。
3. 运行一段时间后，单击 **Stop** 停止测试。

   > \*\*说明：\*\*您可以多测试几分钟，测试结束后，将结果导出。

### 常见可选参数说明 [#常见可选参数说明]

* Copy Text to clipboard：将测试结果以文本格式复制到粘贴板。
* Copy HTML to clipboard：将测试结果以HTML格式复制到粘贴板。
* Export TEXT：将测试结果以文本格式导出到指定文件。
* Export HTML：将测试结果以HTML格式导出到指定文件。
* Options：为可选参数。具体包括以下参数。
  * Interval（sec）：每次探测的间隔（过期）时间，默认为1秒。
  * Ping size（bytes）：ping 探测所使用的数据包大小，默认为64字节。
  * Max hosts in LRU list：LRU列表支持的最大主机数，默认值为128。
  * Resolve names：通过反查IP以域名显示相关节点。

### WinMTR运行后的返回结果说明 [#winmtr运行后的返回结果说明]

默认配置下，WinMTR测试结果说明如下。

* 第一列（Hostname）：到目标服务器要经过的每个节点主机IP或域名。
* 第二列（Nr）：节点编号。
* 第三列（Loss%）：节点丢包率。ping数据包回复失败的百分比，由此可判断哪个节点（线路）出现故障，是服务器所在机房还是国际路由干路。
* 第四列（Sent）：已发送的数据包数量。
* 第五列（Recv）：已成功接收的数据包数量。
* 第六、七、八、九列（Best 、Avg、Worst、Last）：分别是回应时间的最小值、平均值、最大值和最后一个数据包的回应时间。

## tracert命令行工具 [#tracert命令行工具]

tracert (Trace Route) 是Windows自带的网络诊断命令行实用程序，用于跟踪Internet协议（IP）数据包传送到目标地址时经过的路径。

tracert通过向目标地址发送ICMP数据包来确定到目标地址的路由。在这些数据包中，tracert使用了不同的IP生存期 (TTL) 值。由于要求沿途的路由器在转发数据包前至少必须将TTL减少1，因此TTL实际上相当于一个跃点计数器 (hop counter)。当某个数据包的TTL达到零时，相应节点就会向源计算机发送一个ICMP超时的消息。tracert第一次发送TTL为1的数据包，并在每次后续传输时将TTL增加1，直到目标地址响应或达到TTL的最大值。中间路由器发送回来的ICMP超时消息中包含了相应节点的信息。

1. 在桌面底部单击 **开始** 菜单，选择 **运行**。

2. 打开运行框后，在框中输入 **cmd**，并单击 **确定**。

3. 在命令运行界面中，输入 **tracert** ，按回车键后，界面将显示tracert的用法说明。

   ![2](/docs-assets/faq/qvm/qvm-network/7059-windows-instance-network-access-packet-delay-high-screening-method/Fj0SAwM7fvmYrXz7eAxfBQ46fNKJ-56e59545e6f9.webp)

4. 根据具体用法，输入待跟踪的目标地址，示例如下。

   C:\\> tracert -d 223.5.5.5
   通过最多 30 个跃点跟踪到 223.5.5.5 的路由
   1     \*        \*        \*     请求超时。
   2    9 ms     3 ms    12 ms   192.X.X.20
   3    4 ms     9 ms     2 ms   111.X.X.41
   4    9 ms     2 ms     1 ms   111.X.X.197
   5   11 ms     \*        \*      211.X.X.57
   6    3 ms     2 ms     2 ms   211.X.X.62
   7    2 ms     2 ms     1 ms   42.X.X.190
   8   32 ms     4 ms     3 ms   42.X.X.238
   9     \*        \*        \*     请求超时。
   10   3 ms     2 ms     2 ms   223.5.5.5

## 分析链路测试结果 [#分析链路测试结果]

以如下链路测试结果示例图为基础进行阐述。

![](/docs-assets/faq/qvm/qvm-network/7059-windows-instance-network-access-packet-delay-high-screening-method/Fh7pj3nciHj9PWO1wdvRZH7anG7h-769a3fe12f06.webp)

1. 判断各区域是否存在异常，并根据各区域的情况分别处理。
   * 区域A：客户端本地网络，即本地局域网和本地网络提供商网络。针对该区域异常，客户端本地网络相关节点问题，请对本地网络进行排查分析；本地网络提供商网络相关节点问题，请向当地运营商反馈。

   * 区域B：运营商骨干网络。针对该区域异常，可根据异常节点IP查询归属运营商，然后直接或通过七牛云售后技术支持，向相应运营商反馈问题。

   * 区域C：目标服务器本地网络，即目标主机归属网络提供商网络。针对该区域异常，需要向目标主机归属网络提供商反馈问题。

2. 结合Avg（平均值）和StDev（标准偏差），判断各节点是否存在异常。

   * 若StDev很高，则同步观察相应节点的Best和Worst，来判断相应节点是否存在异常。
   * 若StDev不高，则通过Avg来判断相应节点是否存在异常。

     > \*\*注意：\*\*上述StDev高或者不高，并没有具体的时间范围标准。而需要根据同一节点其它列的延迟值大小来进行相对评估。比如，如果Avg为30ms，那么，当StDev为25ms，则认为是很高的偏差。而如果Avg为325ms，则同样的StDev为25ms，反而认为是不高的偏差。

3. 查看节点丢包率，若“Loss%”不为零，则说明这一跳路由的网络可能存在问题。导致节点丢包的原因通常有两种。

   * 人为限制了节点的ICMP发送速率，导致丢包。
   * 节点确实存在异常，导致丢包。

4. 确定当前异常节点的丢包原因。

   * 若随后节点均没有丢包，说明当前节点丢包是由于运营商策略限制所致，可以忽略。如前文链路测试结果示例图中的第2跳路由的网络所示。

   * 若随后节点也出现丢包，说明当前节点存在网络异常，导致丢包。如前文链路测试结果示例图中的第5跳路由的网络所示。

     > \*\*说明：\*\*前述两种情况可能同时发生，即相应节点既存在策略限速，又存在网络异常。对于这种情况，若当前节点及其后续节点连续出现丢包，而且各节点的丢包率不同，则通常以最后几跳路由的网络的丢包率为准。如前文链路测试结果示例图所示，在第5、6、7跳路由的网络均出现了丢包。所以，最终丢包情况，以第7跳的40%作为参考。

5. 通过查看是否有明显的延迟，来确认节点是否存在异常。通过如下两个方面进行分析。

   * 若某一跳路由的网络之后延迟明显陡增，则通常判断该节点存在网络异常。如前文链路测试结果示例图所示，从第5跳路由的网络之后的后续节点延迟明显陡增，则推断是第5跳路由的网络节点出现了网络异常。

     > 注：高延迟并不一定完全意味着相应节点存在异常，延迟大也有可能是在数据回包链路中引发的，建议结合反向链路测试一并分析。

   * ICMP策略限速也可能会导致相应节点的延迟陡增，但后续节点通常会恢复正常。如前文链路测试结果示例图所示，第3跳路由的网络有100%的丢包率，同时延迟也明显陡增。但随后节点的延迟马上恢复了正常。所以判断该节点的延迟陡增及丢包是由于策略限速所致。

## 操作建议 [#操作建议]

* 若数据包在目标地址出现了100%的丢包，建议对目标服务器的安全策略配置进行排查。
* 若数据包出现循环跳转，导致无法到达目标服务器，建议联系相应节点归属运营商处理。
* 若数据包在跳转后无法收到任何反馈，建议结合反向链路测试作进一步确认，并联系相应节点归属运营商进行处理。
* 七牛云中国内地机房和其他国家或地区有网络通信的专线，为降低通信时候的丢包率，推荐使用高速通道。
* 若主机掉包和延迟非常高，建议做WinMTR双向测试，即本地到服务器的和服务器到本地的测试。无法远程登录时，请通过管理终端进行登录。

# 适用于 [#适用于]

* 云服务器 QVM


# 云主机安全事件 (/faq/qvm/qvm-other-faq/13580-qvm-security-events)



最近更新时间: 2026-09-30 14:56:07

Q: 收到主机安全事件通知或者短信 - 云主机实例被检测到严重级别的File containing malicious code包含恶意代码文件安全事件 ，去哪里查看

A： 如果收到安全事件通知，且是使用的qvm云主机，可以在[https://portal.qiniu.com/qvm/4service?type=sas](https://portal.qiniu.com/qvm/4service?type=sas) 中查看，可以在安全事件中查看一些异常行为
![image.png](/docs-assets/faq/qvm/qvm-other-faq/13580-qvm-security-events/FssjTfmiVlrx8kAn-EkZA1Zpa6LY-7eb74b270f69.webp)


# 七牛主机礼品卡使用介绍 (/faq/qvm/qvm-other-faq/5675-seven-niuyun-host-gift-card-use-is-introduced)



最近更新时间: 2025-07-07 16:12:45

# 卡券介绍 [#卡券介绍]

七牛主机礼品卡，是用户通过参与七牛相关活动获取的购物优惠券，可用于购买云主机、云数据库、弹性公网带宽、云安全等服务和产品。

# 使用方法 [#使用方法]

用户登录七牛云管理控制台，选择七牛云主机服务中的产品加入订单，在支付订单时，按照界面提示输入优惠券号及密码，直接抵扣。
![主机礼品卡](/docs-assets/faq/qvm/qvm-other-faq/5675-seven-niuyun-host-gift-card-use-is-introduced/Fi1fAJwsBHikqjysGGeymae65y2O-304c1c29c6f1.webp)

# 规则说明 [#规则说明]

1. 七牛云([www.qiniu.com](http://www.qiniu.com)) 是本礼品卡唯一的发放渠道。
2. 本礼品卡相当于折扣卡，券内预付价值一元等值于一元人民币，卡券面值50、100、200，订单分别满100、200、400时可使用；
3. 本礼品卡自2019年1月1日起生效，有效期为1年。
4. 使用抵用券购买的订单，抵用券不可退费。
5. 每张抵用券限一个订单使用。
6. 礼品卡不可以与网站其他促销优惠活动同时使用。
7. 礼品卡购买时若需要发票，请提前说明或在具体选项前标明，在购买预付费产品时，礼品卡支付部分不再提供发票。
8. 礼品卡禁止以获利为目的进行二次销售。
9. 本礼品卡相关最终解释权在法律范围内归七牛云所有。


# 云主机SSH连接 (/faq/qvm/the-remote-connection/13581-qvm-ssh-connection)



最近更新时间: 2026-09-30 17:37:29

Q: qvm云主机可以在IPV6的环境下SSH链接么
A: qvm云主机默认不支持IPV6的SSH连接，目前默认ssh的链接端口是22 ，需要使用 ipv4的环境和地址进行连接，连接命令 `ssh root@主机ipv4弹性公网IP -p 22`


# 为什么云主机连接不上 Redis？ (/faq/qvm/the-remote-connection/5099-connection-on-redis)



最近更新时间: 2020-08-13 19:25:15

两者通过内网连接必须满足的条件如下：

* 云主机 QVM 和 Redis 在相同的地域

* 云主机 QVM 和 Redis 在相同的网络环境，即：必须都属于同一个 VPC 下

* 云主机 QVM 内网 IP 在 Redis 白名单中


# 如何为 Linux 服务器安装 GRUB (/faq/qvm/the-remote-connection/5146-how-to-install-grub-for-linux-server)



最近更新时间: 2020-08-13 19:25:15

当你无法通过[迁云工具](/products/qvm/1-server-migration-qiniu)迁移内核版本较低，自带系统引导程序 GRUB 版本为 0.97 及其以下的 Linux 服务器，例如，CentOS 5 和 Debian 7。而且日志文件提示`Do Grub Failed`时，可能是因为没有安装 1.9 以上版本的系统引导程序 GRUB（GRand Unified Bootloader）。本文档即将介绍如何为你的源服务器安装系统引导程序 GRUB 1.99 版本。

<br />

<a id="step01" />

### **操作步骤** [#操作步骤]

\*\*1. \*\*登录源服务器

\*\*2. \*\*运行以下命令查看原 grub、grub-install 以及 grub-mkconfig 的路径：

```
which grub
which grub-install
which grub-mkconfig
```

\*\*3. \*\*使用`mv`命令为旧版本 grub、grub-install 以及 grub-mkconfig 改名以备份文件。你可以在使用迁云工具迁移服务器后，恢复原名以使用原配置。

```
mv /sbin/grub /sbin/grub-old
mv /sbin/grub-install /sbin/grub-install-old
mv /sbin/grub-mkconfig /sbin/grub-mkconfig-old
```

\*\*4. \*\*运行`yum install -y bison gcc make`安装 GRUB 依赖的 bison、gcc 以及 make 工具。

\*\*5. \*\*运行以下命令安装 flex。

```
test -d /root/tools || mkdir -p /root/tools
cd /root/tools
wget https://github.com/westes/flex/releases/download/v2.6.4/flex-2.6.4.tar.gz
tar xzf flex-2.6.4.tar.gz
cd flex-2.6.4
mkdir -p build
cd build
../configure
make && make install
ln -s /usr/local/bin/flex /usr/bin/flex
```

\*\*6. \*\*运行以下命令安装 GRUB 1.99 依赖。

```
test -d /root/tools || mkdir -p /root/tools
cd /root/tools
wget https://alpha.gnu.org/gnu/grub/grub-1.99~rc1.tar.gz
tar xzf grub-1.99~rc1.tar.gz
cd grub-1.99~rc1
mkdir -p build
cd build
../configure
make && make install
ln -s /usr/local/sbin/grub-install /sbin/grub-install
ln -s /usr/local/sbin/grub-mkconfig /sbin/grub-mkconfig
```

说明：若编译过程中出现了`-Werror`报错，你可以定位到编译对象的编译文件 makefile 中，去掉`-Werror`选项重新编译。

\*\*7. \*\*运行`grub-install --version`检查 GRUB 版本是否更新为 1.99。

成功更新系统引导程序 GRUB 1.99 版本后，你可以使用[迁云工具](/products/qvm/1-server-migration-qiniu)迁移服务器至 QVM。

迁云成功后，运行以下命令恢复使用旧版本 GRUB：

```
rm /sbin/grub-install
rm /sbin/grub-mkconfig
rm /boot/grub/grub.cfg
mv /sbin/grub-old /sbin/grub
mv /sbin/grub-install-old /sbin/grub-install
```


# 远程连接Windows实例时出现身份验证错误的处理方法 (/faq/qvm/the-remote-connection/6869-remote-connection-windows-instances-when-solving-method-of-authentication-error)



最近更新时间: 2026-08-18 11:56:44

# 问题描述 [#问题描述]

通过微软的RDP协议客户端，远程连接Windows实例时，系统提示“出现身份验证错误，要求的函数不受支持（The function requested is not supported）”错误。

![](/docs-assets/faq/qvm/the-remote-connection/6869-remote-connection-windows-instances-when-solving-method-of-authentication-error/Fohr3rxVS9sVAz4iXu_s89Gclo5h-41cb64c4cee9.webp)

# 问题原因 [#问题原因]

微软官方2018年5月，更新了凭据安全支持提供程序协议（CredSSP）相关补丁和身份验证请求方式。当遇到如下一种情景时，就会出现该连接错误。

* 情景一：客户端未更新该补丁，服务器端已更新该补丁且加密Oracle修正的策略为强制更新的客户端。
* 情景二：客户端已更新该补丁且加密Oracle修正的策略为强制更新的客户端，服务器端未更新该补丁。
* 情景三：客户端已更新该补丁且加密Oracle修正的策略为缓解，服务器端未更新该补丁。

# 解决方案 [#解决方案]

## 方法一 ：服务器端允许任意版本的远程桌面连接 [#方法一-服务器端允许任意版本的远程桌面连接]

由于Windows Server系统版本较多，且各版本之间操作略有差异，此处分别以Windows Server 2008 R2、Windows Server 2012 R2和Windows Server 2016三个主流版本为例，步骤如下。

<br />

### Windows Server 2008 R2系统版本 [#windows-server-2008-r2系统版本]

1. 通过 [VNC远程连接](/products/qvm/cloud-server/instances/qvm-windows-login/2-use-the-management-terminal-vnc-connection-windows-instance) 登录Windows实例，打开 **开始** ，右键单击 计**算机**，选择\*\* 属性\*\*。
   ![](/docs-assets/faq/qvm/the-remote-connection/6869-remote-connection-windows-instances-when-solving-method-of-authentication-error/FqXDpegwqUTFk0VlEC4wT4v12_wG-2c6e5a0a808b.webp)
2. 在系统控制面板中，单击\*\* 远程设置\*\*，在弹出的\*\* 远程桌面 \*\*选项中选择 允许运行任意版本远程桌面的计算机连接（较不安全） 并单击 **确定**。
   ![](/docs-assets/faq/qvm/the-remote-connection/6869-remote-connection-windows-instances-when-solving-method-of-authentication-error/Frsht5eBFmcMmoWzSewGdeSSxsTd-9ea5ab87c56a.webp)

<br />

### Windows Server 2012 R2系统版本 [#windows-server-2012-r2系统版本]

1. 通过 [VNC远程连接](/products/qvm/cloud-server/instances/qvm-windows-login/2-use-the-management-terminal-vnc-connection-windows-instance) 登录Windows实例，打开 **开始** ，右键单击 计**算机**，选择\*\* 属性\*\*。
   ![](/docs-assets/faq/qvm/the-remote-connection/6869-remote-connection-windows-instances-when-solving-method-of-authentication-error/FqnGEzQI3N9-CqALAP95kM4zE0oQ-06048fbff2ac.webp)
2. 在系统控制面板中，单击 **远程设置**，在弹出的 **远程桌面** 选项中取消选择 &#x2A;*仅允许运行使用网络级别身份验证的远程桌面的计算机连接（建议）** 并单击 **确定**。
   ![](/docs-assets/faq/qvm/the-remote-connection/6869-remote-connection-windows-instances-when-solving-method-of-authentication-error/Fi0U8BNLT9uGrZmrS5scYDIZLfE9-018ea30aa516.webp)

<br />

### Windows Server 2016系统版本 [#windows-server-2016系统版本]

1. 通过 [VNC远程连接](/products/qvm/cloud-server/instances/qvm-windows-login/2-use-the-management-terminal-vnc-connection-windows-instance) 登录Windows实例，打开 **开始** ，右键单击 计**算机**，选择\*\* 属性\*\*。
   ![](/docs-assets/faq/qvm/the-remote-connection/6869-remote-connection-windows-instances-when-solving-method-of-authentication-error/FrEnHErgH_tOXfAvuLTvv7zAJVGp-bf92320b0fb5.webp)
2. 在系统控制面板中，单击 **远程设置**，在弹出的 **远程桌面** 选项中取消选择 &#x2A;*仅允许运行使用网络级别身份验证的远程桌面的计算机连接（建议）** 并单击 **确定**。
   ![](/docs-assets/faq/qvm/the-remote-connection/6869-remote-connection-windows-instances-when-solving-method-of-authentication-error/FpKSugWhirKaFB78CzOkIvtJVIy-c395f30eda6c.webp)

<br />

## 方法二 ：Windows安全更新 [#方法二-windows安全更新]

1. 通过 [VNC远程连接](/products/qvm/cloud-server/instances/qvm-windows-login/2-use-the-management-terminal-vnc-connection-windows-instance) 登录Windows实例，搜索并打开 **Windows 更新** 页面，单击 **检查更新** 下载更新。
   ![](https://dn-odum9helk.qbox.me/Fidn1ViQZSPmyzGRMFJRBqgZSQPl)
2. 等待更新下载和安装。如果需要手动安装CredSSP对应安全更新包，请参考[微软官网地址](https://www.microsoft.com/zh-cn/windows/?spm=a2c4g.11186623.2.25.6a554c07N27Vca)进行选择对应版本的安全更新下载。
3. 重启实例或重启本地计算机以完成安装更新。

<br />

## 方法三：修改注册表 [#方法三修改注册表]

> 提示：此处以Windows Server 2016系统版本为例，其他Windows系统版本操作类似。

### **手动修改** [#手动修改]

当客户端或服务器端完成CredSSP相关补丁的更新后，请选择以下一种方式修改其注册表。如果修改注册表不当，可能会出现严重问题，您需要自行承担修改注册表风险。修改注册表之前，建议您先通过创建快照备份数据，以免数据丢失。

1. 登录Windows实例或者本地计算机，单击 **开始 > 运行**，输入**regedit**，单击 确定。
2. 单击 **HKEY\_LOCAL\_MACHINE > SOFTWARE > Microsoft > Windows > CurrentVersion > Policies > System > CredSSP > Parameters**。
   ![](/docs-assets/faq/qvm/the-remote-connection/6869-remote-connection-windows-instances-when-solving-method-of-authentication-error/Fvd9BlARIEYemK5y0Kq6LGesR_SK-38c264a4e672.webp)
3. 如果 **CredSSP** 项或者 **Parameters** 项不存在，请新建 **CredSSP** 项或者 **Parameters** 项，在 **Parameters** 项下新建 **REG\_DWORD** 类型的 **AllowEncryptionOracle** 值，并设置数据为2。
   ![](/docs-assets/faq/qvm/the-remote-connection/6869-remote-connection-windows-instances-when-solving-method-of-authentication-error/FhPK0E-lFo1XJOdjaZtkXtdrSpfd-5ead9131769e.webp)
4. 重启实例或重启本地计算机。

### **脚本修改** [#脚本修改]

1. 登录Windows实例或者本地计算机，以管理员身份运行Windows PowerShell，执行如下脚本。
2. 重启实例或重启本地计算机。

脚本：

```
New-Item -Path HKLM:\Software\Microsoft\Windows\CurrentVersion\Policies\System -Name CredSSP -Force
New-Item -Path HKLM:\Software\Microsoft\Windows\CurrentVersion\Policies\System\CredSSP -Name Parameters -Force
Get-Item -Path HKLM:\Software\Microsoft\Windows\CurrentVersion\Policies\System\CredSSP\Parameters | New-ItemProperty -Name AllowEncryptionOracle -Value 2 -PropertyType DWORD -Force
```

> 注：若您优先使用本方法修改了注册表，随后又更新了客户端和ECS实例安全补丁，我们建议您将AllowEncryptionOracle的值设为0或者1以获得更高的安全性。


# 无法连接到Windows实例 (/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance)



最近更新时间: 2020-08-13 19:25:15

> \*\*免责声明：\*\*本文档可能包含第三方产品信息，该信息仅供参考。七牛云对第三方产品的性能、可靠性以及操作可能带来的潜在影响，不做任何暗示或其他形式的承诺。

# [](#概述)概述 [#概述]

本文主要介绍无法远程连接Windows实例的排查方法。

# 详细信息 [#详细信息]

> 七牛云提醒您：
>
> * 如果您对实例或数据有修改、变更等风险操作，务必注意实例的容灾、容错能力，确保数据安全。
> * 如果您对实例（包括但不限于QVM、RDS）等进行配置与数据修改，建议提前创建快照或开启RDS日志备份等功能。
> * 如果您在七牛云平台授权或者提交过登录账号、密码等安全信息，建议您及时修改。

无法远程连接Windows实例的原因较多，可通过以下排查方法，排查并解决无法远程连接Windows实例的问题。

* [步骤一：使用管理终端登录实例](#zfpkA)
* [步骤二：检查登录密码](#zfpkA)
* [步骤三：检查端口及安全组](#FQsdM)
* [步骤四：检查远程桌面服务](#h2-u8FDCu7A0Bu684Cu9762u670Du52A1u672Au5F00u542Fu5BFCu81F412)
* [步骤五：检查网络](#BRtjH)
* [步骤六：检查CPU负载、带宽及内存使用情况](#mGxfy)
* [步骤七：检查防火墙配置](#dFyni)
* [步骤八：设置系统的安全策略](#h2-u7CFBu7EDFu7684u5B89u5168u7B56u7565u8BBEu7F6Eu5BFCu81F411)
* [步骤九：检查远程终端服务的配置](#JzNpy)
* [步骤十：检查杀毒软件](#h3-u670Du52A1u5668u4FA7u81EAu7B7Eu540Du8BC1u4E66u635Fu574F)
* [步骤十一：尝试重启实例](#AnSBy)
* [常见报错案例](#ndFDW)

## 步骤一：使用管理终端登录实例 [#步骤一使用管理终端登录实例]

无论何种原因导致无法远程连接实例，请先尝试用七牛云提供的远程连接功能进行连接，确认实例还有响应，没有完全宕机，然后再按原因分类进行故障排查。

1. 登录[QVM管理控制台](https://portal.qiniu.com/qvm/dashboard)，单击左侧导航栏中的**实例**，在目标实例右侧单击**远程连接**。
2. 在首次连接或忘记连接密码时，单击**修改远程连接密码**，修改远程连接的密码。
3. 然后通过远程连接密码连接实例。

## 步骤二：登录密码检查 [#步骤二登录密码检查]

在确保登录密码正确的情况下，确认之前是否曾重置过密码。检查重置实例密码后是否未重启实例，如果存在实例密码修改记录，但无重启实例记录，则参考以下操作步骤重启实例。

1. 登录QVM管理控制台，单击左侧导航栏中的**实例**。
2. 在页面顶部的选择对应的地域，目标实例右侧单击**更多**>**实例状态**>**重启**，再单击**确定**即可。

## 步骤三：端口及安全组检查 [#步骤三端口及安全组检查]

进一步检查端口是否正常，以及安全组规则是否有限制。

1. 参见如何查看和修改Windows实例远程桌面的默认端口，检查实例远程链接的端口是否被修改。如果登录方式改变或者QVM安全组规则中未放行修改后的端口号，则参考如下步骤放行修改后的端口。

   > **说明**：QVM的安全组规则中默认放行3389端口。修改了远程桌面的端口后，需要在安全组规则中放行修改后的端口号。

   1. 登录QVM管理控制台。
   2. 找到该实例，单击**管理**进入**实例详情**页面，在左侧导航栏，单击**本实例安全组**。找到安全组，单击操作列下的**配置规则**。
      ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/e09b6e8e-6696-4e0f-a31f-494be50bb366-c30a844726ae.webp)
   3. 在安全组规则页面，单击**添加安全组规则**。
   4. 在弹出的页面中，**端口范围**输入修改后的远程桌面端口号。**授权对象**输入客户端的公网IP地址。比如修改后的远程桌面端口号为4389，则**端口范围**应输入**4389/4389**。填写完成后，单击**确定**。
      ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/78d34903-2f59-42f6-8ad9-b8f66a7d8891-675f75627dc6.webp)
   5. 通过“IP:端口”的方式进行远程桌面连接。连接方式类似如下。
      ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/9094ed90-2997-4941-b153-6286344b0a48-5de89da8e1d3.webp)

2. 通过上一步获取的端口，参见以下命令，进行端口测试，判断端口是否正常。如果端口测试失败，请参见使用ping命令正常但端口不通时的端口可用性探测说明进行排查。

   telnet \[$IP] \[$Port]

   > **说明**：
   >
   > * \[$IP]指Windows实例的IP地址。
   > * \[$Port]指Windows实例的RDP端口号。

   系统显示类似如下，比如执行`telnet 192.168.0.1 4389`命令，正常情况下返回结果类似如下。

   Trying 192.168.0.1 ...
   Connected to 192.168.0.1  4389.
   Escape character is '^]'

3. 检查Windows远程端口设置是否超出范围，如果超出范围，您需将端口重新修改为0到65535之间，且没有被占用的其它端口，具体操作请参见以下操作。
   1. 登录实例，依次选择**开始**>**运行**，输入**regedit**，然后单击**确认**。

   2. 打开注册表编辑器，依次选择**HKEY\_LOCAL\_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal Server\Wds\rdpwd\Tds\tcp**。

   3. 双击**PortNumber**，单击**十进制**，将原端口由“113322”修改为0到65535之间且不与当前端口冲突的端口，例如5588等端口。

      > **说明**：113322为PortNumber右侧显示的端口号。

   4. 再打开**HKEY\_LOCAL\_MACHINE\SYSTEM\CurrentControlSet\Control\Tenninal Server\WinStations\RDP-Tcp**。

   5. 双击**PortNumber**，单击**十进制**，将原端口“113322”修改为与第3步一致的端口号。

   6. 然后重启主机，确认远程连接成功。

## 步骤四：远程桌面服务检查 [#步骤四远程桌面服务检查]

您可以查看Windows服务器的系统是否开启了远程桌面服务。具体操作如下：

1. 使用控制台远程连接功能登录到Windows实例。
2. 右键单击**我的电脑**，选择**属性**>**高级系统设置**。
3. 在**系统属性**窗口，选择**远程**选项卡，在**远程桌面**区域，确认已勾选**允许远程连接到此计算机**。
   ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/b6a3a26c-fc6f-4eef-99b2-e05ed3bd726d-b88285851401.webp)
4. 用户为了提高系统安全性，有时错误的将远程桌面服务所依赖的某些关键服务禁用，导致远程桌面服务异常。可通过以下操作进行检查。
   1. 使用控制台远程连接功能登录到Windows实例。
   2. 选择**开始**>**运行**。 输入`msconfig`，单击**确定**。 
      ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/9-b7129c9d79a6.webp)
   3. 在弹出的窗口中，选择**常规**选项卡，选择**正常启动**，然后重启服务器即可。 
      ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/10-aa6c23abf810.webp)

## 步骤五：网络检查 [#步骤五网络检查]

无法正常远程连接Windows实例时，需要先检查网络是否正常。

1. 用其他网络环境中(不同网段或不同运营商)的电脑连接对比测试，判断是本地网络问题还是服务器端的问题。如果是本地网络问题或运营商问题，请联系本地IT人员或运营商解决。如果是网卡驱动存在异常，则重新安装。排除本地网络故障后进行下一步检查。
2. 在客户端使用ping命令测试与实例的网络连通性。
   * 网络异常时，请参见网络异常时如何抓取数据包进行排查。
   * 当出现ping丢包或ping不通时，请参见使用ping命令丢包或不通时的链路测试方法进行排查。
   * 如果出现间歇性丢包，QVM实例的网络一直处于不稳定状态时，请参见使用ping命令测试QVM实例的IP地址间歇性丢包进行解决。
3. 在实例中使用ping命令测试与客户端的连通性，提示“一般故障”的错误，请参见Windows实例ping外网地址提示“一般故障”进行解决。

## 步骤六：检查CPU负载、带宽及内存使用情况 [#步骤六检查cpu负载带宽及内存使用情况]

* 确认是否存在CPU负载过高的情况，如果存在，则参考本步骤解决问题，如果不存在，则执行下一步步骤。
  * 检查CPU负载过高时，通过实例详情页面的终端登录实例，检查后台是否正在执行Windows Update操作。
  * 运行Windows Update来安装最新的微软安全补丁。
  * 若应用程序有大量的磁盘访问、网络访问行为、高计算需求，CPU负载过高是正常结果。您可以尝试升配实例规格来解决资源瓶颈问题。
  * CPU负载过高的解决方法，请参见Windows系统QVM实例的CPU使用率较高的解决方法。
* 无法远程连接可能是公网带宽不足导致的，具体排查方法如下。可通过续费QVM实例，然后重启实例解决。详情请参见手动续费，或者请参见自动续费。

  1. 登录QVM管理控制台。

  2. 找到该实例， 单击**管理**进入实例详情页面，查看网络监控数据。

  3. 检查服务器带宽是否为“1k”或“0k”。如果购买实例时没有购买公网带宽，后来升级了公网带宽，续费的时候没有选择续费带宽，带宽就会变成“1k”。
* 远程连接输入用户密码登录后，不能正常显示桌面直接退出，也没有错误信息。这种情况可能是服务器内存不足导致的，需要查看一下服务器的内存使用情况。具体操作如下。

1. 1. 使用控制台远程连接功能登录到Windows实例。

2. 2. 选择**开始**>**控制面板**>**管理工具**，双击**事件查看器**。查看一下是否有内存资源不足的警告日志信息。如有日志信息提示内存不足，具体解决方法参考Windows 虚拟内存不足问题的处理。

## 步骤七：防火墙配置检查 [#步骤七防火墙配置检查]

您只有在已授权可关闭防火墙的情况下，才能进行该项排查。确认防火墙是否已关闭，如果没有关闭，则通过调整防火墙配置策略修复，具体操作请参见如何配置Windows实例远程连接的防火墙。完成操作后，请再进行远程连接，确认连接成功。本文以Windows Server 2012初次登录开启防火墙为例。新购的Windows 2012实例，首次连接服务器是可以的。连接服务器并激活系统后，会提示如下图片中的信息，用户需要单击 **是**，如果单击 **否**，服务器会自动开启公网的防火墙，连接会直接断开。此问题可参考以下步骤进行解决。

![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/1-30f9c4bf72de.webp)

1. 使用控制台远程连接功能登录到Windows实例。

2. 在菜单栏选择**开始**>**控制面板** 。

3. **查看方式**选择**小图标**，单击**Windows 防火墙**。 
   ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/1-16667be96c08.webp)

4. 在Windows防火墙窗口，单击**高级设置**。

5. 在弹出的窗口中，单击**入站规则**，在右侧拉至最下方，右键单击&#x2A;*远程桌面-用户模式(TCP-In)**，选择**启动规则**。 
   ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/2-522b963f45ca.webp)

6. 返回上一个页面， 单击**Windows防火墙属性**。 
   ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/4-42bdf8b2911b.webp)

7. 选择&#x2A;*启用（推荐）**，单击**应用**。

   > **说明**：建议将**域配置文件**、**专用配置文件**、**公用配置文件**选项卡下的防火墙全部启用。

   ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/5-f6cbaee6a246.webp)

更多关于防火墙的设置，请参考设置Windows实例远程连接防火墙。

## 步骤八：系统的安全策略设置 [#步骤八系统的安全策略设置]

您可以查看Windows服务器上是否有阻止远程桌面连接的相关安全策略。具体操作如下。

1. 使用控制台远程连接功能登录到Windows实例。

2. 选择**开始**>**控制面板**>**管理工具**，双击**本地安全策略**。 
   ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/12-e42351744b7c.webp)

3. 在弹出的窗口中，单击**IP安全策略**，查看是否有相关的安全策略。

4. 如果有，右键单击相关策略，选择**删除**，或双击该IP的安全策略来重新配置以允许远程桌面连接。然后再使用远程桌面连接。 
   ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/14-6346c573f27a.webp)

## 步骤九：远程终端服务的配置检查 [#步骤九远程终端服务的配置检查]

无法连接Windows实例远程桌面可能是由于以下远程终端服务的配置异常而导致。

### 异常一：服务器侧自签名证书损坏 [#异常一服务器侧自签名证书损坏]

客户端如果是Windows 7以上版本的系统，会尝试与服务器建立TLS连接。若服务器侧用于TLS连接的自签名证书损坏，则会导致远程连接失败。

1. 使用控制台远程连接功能登录到Windows实例。

2. 选择**开始**>**管理工具**>**远程桌面服务**，然后双击**远程桌面会话主机配置**。 
   ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/16-3ec77db38fec.webp)

3. 选择**RDP-Tcp**。在RDP-Tcp属性窗口，将**安全层**修改成**RDP安全层**。 
   ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/17-6fff15e137ac.webp)

4. 在操作栏单击**禁用连接**，再单击**启用连接**即可。 

### 异常二：远程桌面会话主机配置连接被禁用 [#异常二远程桌面会话主机配置连接被禁用]

使用netstat命令查询，发现端口未正常监听。使用控制台远程连接功能登录到Windows实例后，发现远程桌面RDP连接属性配置文件被禁用。参考[服务器侧自签名证书损坏](#h3-u670Du52A1u5668u4FA7u81EAu7B7Eu540Du8BC1u4E66u635Fu574F)找到RDP连接属性配置文件，如果**RDP-Tcp**被禁用，单击**启用连接**即可。

![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/19-925d72a06a0d.webp)

### 异常三：终端服务器角色配置 [#异常三终端服务器角色配置]

1. 用户在使用远程桌面访问Windows实例时，有时会出现如下提示。
   ![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/2-9ced04f8b2c7.webp)
2. 这种情况一般是由于在服务器上安装配置了**终端服务器**，但是没有配置有效的访问授权导致的。可参见如下两个解决方案处理。
   * Windows服务器远程桌面提示“没有远程桌面授权服务器可以提供许可证”错误
   * 远程登录Windows实例报“远程桌面用户组没有该权限”错误

## 步骤十：杀毒软件检查 [#步骤十杀毒软件检查]

无法连接远程桌面可能是由于第三方杀毒软件设置导致，可通过以下方法进行解决。此处列举两个安全狗配置导致远程访问失败的解决案例。

* 如果杀毒软件在后台执行，可通过实例详情页面的终端登录，将杀毒软件升级至最新版本或者直接删除。
* 请使用商业版杀毒软件，或者使用Microsoft Safety Scanner微软免费安全工具，在安全模式下扫描杀毒，相关信息请参见[安全扫描程序](https://www.microsoft.com/security/scanner/zh-cn/default.aspx)。

### 案例一：安全狗黑名单拦截 [#案例一安全狗黑名单拦截]

如果安装了安全狗后，出现如下情况，请确认防护软件中是否做了安全设置或对应的拦截。

* 客户端本地无法远程桌面连接Windows实例，但其他区域可以远程连接。
* 无法ping通服务器IP地址，且通过tracert命令跟踪路由，发现无法到达服务器。
* 云盾未拦截本地公网IP地址。

可打开**服务器安全狗**进行检查，选择**网络防火墙**。单击**超级黑名单**的**规则设置**，如果黑名单中存在实例公网IP，则将此黑名单规则删除，然后将公网IP添加到**超级白名单**。

![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/7-4119c43ed60c.webp)

> **说明**：如果云盾的阈值设置过低，则可能拦截实例公网IP。建议把清洗阈值调高，避免出现拦截实例公网IP的情况发生，具体请参见DDoS基础防护。

### 案例二：安全狗程序异常 [#案例二安全狗程序异常]

使用控制台远程连接功能登录到Windows实例后，在系统桌面右下角，安全狗弹出错误提示，系统显示类似如下。该问题可能是由于安全狗软件出现异常导致的。可通过Windows系统卸载安全狗软件后，重启服务器，网络即可恢复。

![](/docs-assets/faq/qvm/the-remote-connection/7051-unable-to-connect-to-the-windows-instance/8-bf5d60552f9a.webp)

## 步骤十一：尝试重启实例 [#步骤十一尝试重启实例]

若用七牛云提供的远程连接功能仍无法成功连接实例，请尝试重启实例。重启操作会使实例停止工作，从而中断业务，请谨慎执行。

> **提示**：重启实例前，需给实例创建快照，用于数据备份或者制作镜像。创建快照的方法请参见创建快照。

1. 登录QVM管理控制台，单击左侧导航栏中的**实例**。
2. 在页面顶部的选择对应的地域，在目标实例右侧单击**更多**>**实例状态**>**重启**，再单击**确认**即可。

## 常见报错案例 [#常见报错案例]

* 协议相关报错常见案例如下。
  * 远程连接Windows系统的QVM实例时提示协议错误
* 授权相关报错常见案例如下。
  * 启用密码保护共享导致Windows系统远程访问出现“凭据无法工作”错误
  * 远程桌面连接QVM实例时报"连接被拒绝，因为没有授权此用户帐户进行远程登录"错误
  * Windows系统实例中未指定远程桌面授权服务器解决方法
  * Windows 2008系统的QVM实例远程登录时提示“要登录到此远程计算机，您必须被授予允许通过终端服务登录的权限”
* 桌面无法显示的报错案例如下。
  * Windows系统的QVM实例远程登录后无法显示桌面或显示异常
* 连接数相关报错案例及说明如下。
  * Windows系统实例远程连接提示"终端服务器超出了最大允许连接"
  * Windows Server实例远程连接数以及License授权服务器的相关说明
* 配置策略相关报错案例如下。
  * 远程登录Windows Server 2008 R2系统时提示未知的用户名或密码错误

# [](#适用于)适用于 [#适用于]

* 云服务器QVM


# Windows实例提示“由于协议错误，会话将被中断。请重新连接到远程计算机。” (/faq/qvm/the-remote-connection/7052-windows-instance-prompt-error-due-to-the-agreement-the-session-will-be-interrupted-please-connect-to-the-remote-computer-again)



最近更新时间: 2026-05-07 16:09:44

> \*\*免责声明：\*\*本文档可能包含第三方产品信息，该信息仅供参考。七牛云对第三方产品的性能、可靠性以及操作可能带来的潜在影响，不做任何暗示或其他形式的承诺。

# 问题描述 [#问题描述]

远程连接Windows系统的QVM实例时，提示协议错误。具体的报错如下：

由于协议错误，会话将被中断。请重新连接到远程计算机。

# 问题原因 [#问题原因]

可能导致该问题的部分原因如下：

* 原因一
  目标实例的远程会话配置错误。当远程会话配置错误，远程连接时会出现协议错误的提示。
* 原因二
  目标实例的远程连接端口被其他应用占用。Windows系统默认远程桌面连接端口号为3389，当该端口被其他程序占用时，远程连接服务将无法正常运行。

# 解决方案 [#解决方案]

> 七牛云提醒您：
>
> * 如果您对实例或数据有修改、变更等风险操作，务必注意实例的容灾、容错能力，确保数据安全。
> * 如果您对实例（包括但不限于QVM、RDS）等进行配置与数据修改，建议提前创建快照或开启RDS日志备份等功能。
> * 如果您在七牛云平台授权或者提交过登录账号、密码等安全信息，建议您及时修改。

不同问题原因对应的解决方案不同，您可以根据现场实际情况选择对应的问题原因及解决方案。

> **说明**：本文中的操作步骤以Windows Server 2016版本为例。

## 原因一：目标实例的远程会话配置错误 [#原因一目标实例的远程会话配置错误]

处理步骤如下：

* [使用VNC登录](/products/qvm/cloud-server/instances/qvm-windows-login/2-use-the-management-terminal-vnc-connection-windows-instance)Windows实例。
* 单击**开始**，输入`gpedit.msc`。单击**Enter**按钮，打开**本地组策略编辑器**。
* 在**本地组策略编辑器**窗口中，依次单击**计算机配置**>**管理模板**>**Windows 组件**>**远程桌面服务**>**远程桌面会话主机**>**安全\*\*\*\*计算机配置**。
* 在**安全**目录中，双击**远程（RDP）连接要求使用指定的安全层**。
  ![](/docs-assets/faq/qvm/the-remote-connection/7052-windows-instance-prompt-error-due-to-the-agreement-the-session-will-be-interrupted-please-connect-to-the-remote-computer-again/FtdNAncenvIN46M1qplYv1yWdhkg-c926c134a72d.webp)
* 选择**已启用** ，在**安全层**选项中选择**RDP**，单击**确定**。
  ![](/docs-assets/faq/qvm/the-remote-connection/7052-windows-instance-prompt-error-due-to-the-agreement-the-session-will-be-interrupted-please-connect-to-the-remote-computer-again/Fs1HLwIaOYoJUm7_-aQqt55eYRPx-bf5f617a1586.webp)
* 单击**开始**，输入`cmd`，单击**Enter**按钮，打开命令行。
* 执行以下命令，完成策略更新，使以上的设置生效。

gpupdate

系统显示如下图，计算机策略更新完成。
![](/docs-assets/faq/qvm/the-remote-connection/7052-windows-instance-prompt-error-due-to-the-agreement-the-session-will-be-interrupted-please-connect-to-the-remote-computer-again/FlzsGCdfvnk6y79HIhYR-FZgVOkw-ce3bb4064893.webp)

* 重试远程连接，确认问题已经修复。

## 原因二：目标实例的远程连接端口被其他应用占用 [#原因二目标实例的远程连接端口被其他应用占用]

如果目标实例的远程连接端口被其他应用占用，您可以从下列两种解决方案中选择其一。

### 方案一：修改远程连接端口号 [#方案一修改远程连接端口号]

参考下列步骤，修改远程连接的端口号，然后使用新的端口号重试远程连接：

* [使用VNC登录](/products/qvm/cloud-server/instances/qvm-windows-login/2-use-the-management-terminal-vnc-connection-windows-instance)Windows实例。
* 单击**开始**，输入`regedit`，单击**Enter**按钮，打开**注册表编辑器**。
* 依次进入以下目录。

HKEY\_LOCAL\_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal Server\WinStations\RDP-Tcp

* 双击**RDP-Tcp**目录中名称为**PortNumber**的注册表项。
  ![](/docs-assets/faq/qvm/the-remote-connection/7052-windows-instance-prompt-error-due-to-the-agreement-the-session-will-be-interrupted-please-connect-to-the-remote-computer-again/Fp6W8t120drxq6NtmEMGnIy5ep63-2d2b55a29fc8.webp)
  ![](/docs-assets/faq/qvm/the-remote-connection/7052-windows-instance-prompt-error-due-to-the-agreement-the-session-will-be-interrupted-please-connect-to-the-remote-computer-again/FjwFgzcM0lEh137hYlNdHLoqRUTX-8ddf27fc6493.webp)
* 在编辑页面，选择**基数**选项中的**十进制**，修改**数值数据**中的值，该值即为远程桌面使用的端口号。

> **说明**：修改远程桌面默认端口时，请根据现场情况选择合适的TCP端口号。

![](/docs-assets/faq/qvm/the-remote-connection/7052-windows-instance-prompt-error-due-to-the-agreement-the-session-will-be-interrupted-please-connect-to-the-remote-computer-again/FnqT0MoWarqmbx81bvq9wx0cinQZ-dcd8d3928fc4.webp)

> **说明**：图中的3389端口号为远程连接的默认端口号，仅作为示例。

* 重启Windows系统或重启该QVM实例。

### 方案二：关闭占用远程连接端口的应用进程 [#方案二关闭占用远程连接端口的应用进程]

参考下列步骤，关闭正在占用远程连接端口的应用进程，以释放端口号，然后重试远程连接：

* [使用VNC登录](/products/qvm/cloud-server/instances/qvm-windows-login/2-use-the-management-terminal-vnc-connection-windows-instance)Windows实例。
* 单击**开始**，输入`cmd`，单击**Enter**按钮，打开命令行。
* 执行以下命令，获取占用远程连接端口的进程号（PID）。

netstat -ano |findstr 3389

> **说明**：此处以远程连接默认端口号3389为例，现场需要以实际情况为准。

* 执行以下命令，根据PID查看进程对应的应用程序。正常情况下，远程连接端口被svchost.exe进程占用。

tasklist |findstr \[$PID]

> **说明**：\[$PID]指上一步获取的PID。

* 如果远程连接端口被svchost.exe之外的进程占用，则表明远程连接端口的确被其他应用所占用。您可以执行以下命令，根据PID关闭指定的进程，释放被占用的远程连接端口。

> **警告**：关闭进程属于风险操作，请确保关闭进程后不影响业务运行，方可执行此操作。

taskkill /f /pid \[$PID]

# [](#适用于)适用于 [#适用于]

* 云服务器QVM

如果您的问题仍未解决，您可以[提交工单](https://support.qiniu.com/tickets/new/?ref=developer.qiniu.com)联系七牛云技术支持。


# Windows实例提示“凭据无法工作”报错 (/faq/qvm/the-remote-connection/7053-windows-instance-prompt-error-credentials-will-not-work)



最近更新时间: 2026-05-07 16:14:08

> **免责声明：** 本文档可能包含第三方产品信息，该信息仅供参考。七牛云对第三方产品的性能、可靠性以及操作可能带来的潜在影响，不做任何暗示或其他形式的承诺。

# 问题描述 [#问题描述]

使用远程桌面访问Windows系统的QVM实例时，出现如下错误。使用管理终端连接服务器可正常登录。

![](/docs-assets/faq/qvm/the-remote-connection/7053-windows-instance-prompt-error-credentials-will-not-work/FikZT-NivVN8sp17kEOfXtOBsKtc-1c90b8c6ca43.webp)

# 问题原因 [#问题原因]

Windows操作系统内开启密码保护共享功能。

# 解决方案 [#解决方案]

> 七牛云提醒您：
>
> * 如果您对实例或数据有修改、变更等风险操作，务必注意实例的容灾、容错能力，确保数据安全。
> * 如果您对实例（包括但不限于QVM、RDS）等进行配置与数据修改，建议提前创建快照或开启RDS日志备份等功能。
> * 如果您在七牛云平台授权或者提交过登录账号、密码等安全信息，建议您及时修改。

参考如下操作步骤，关闭密码保护共享功能。

1. 使用管理终端登录QVM实例。
2. 打开 **控制面板** > **所有控制面板项** > **网络和共享中心** > **高级共享设置**。
3. 在 **密码保护的共享** 配置项，选择 **关闭密码保护共享** 即可。
   ![](/docs-assets/faq/qvm/the-remote-connection/7053-windows-instance-prompt-error-credentials-will-not-work/Fhp6n_TDRhSuY_FPZhPADg0bnh1Q-7a161c9ec67c.webp)

# 适用于 [#适用于]

* 云服务器 QVM

如果您的问题仍未解决，您可以[提交工单](https://support.qiniu.com/tickets/new/?ref=developer.qiniu.com)联系七牛云技术支持。


# 父子账号说明 (/products/af/manual/1433-father-and-son-account-instructions)



最近更新时间: 2026-08-13 11:16:37

## 功能说明 [#功能说明]

OEM 父子账号功能，提供了资源隔离和子账号管理能力。您可以通过 OEM 模式，包装七牛的基础产品并为您的客户提供服务。您可以基于 OEM 子账号的用量，单独和您的客户进行结算，拥有独立的计费模式。

所有 OEM 子账号的产品用量将计入父账号，统一在父账号计费，享受阶梯优惠，七牛不会对 OEM 子账号额外收取费用。

注意：
1、目前仅 API 支持 OEM 模式，控制台暂不支持 OEM 模式
2、如需开通，可添加 [工单界面](https://support.qiniu.com/tickets) 左下角专属商务二维码申请开通。

## 子账号管理 API [#子账号管理-api]

首先要获取管理账号凭证，使用管理凭证进行其他操作，获取子账号信息，或者创建子账号等

* 获取账户信息（/v1/user/info）
* [创建子账号（/v1/user/create\_child）](/products/af/manual/1433-father-and-son-account-instructions)
* 禁用子账号（/v1/user/disable\_child）
* 启用子账号（/v1/user/enable\_child）
* 列举子账号（/v1/user/children）
* [查询子账号密钥（/v1/user/child\_key）](/products/af/manual/1433-father-and-son-account-instructions)

## 产品 API [#产品-api]

获取子账号 AK/SK 后，可以用子账号的身份，使用各类七牛产品的 API：

| 产品      | API 概览                                                                                                            | 计量 API                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 对象存储    | [API 概览\_API 文档\_对象存储 - 七牛开发者中心](/products/kodo/3939-overview-of-the-api)                                         | [空间统计信息 API](/products/kodo/1-statistic-interface)                                                                                                                                                   |
| CDN     | [域名相关\_API 文档\_CDN - 七牛开发者中心](/products/cdn/4-fusion-api-domain-management)                                       | [流量带宽\_API 文档\_CDN - 七牛开发者中心](/products/cdn/6-fusion-api-usage-stats)                                                                                                                                |
| 直播云miku | [创建流\_API 文档\_直播云 - 七牛开发者中心](/products/mikustream/mikustream-live-stream-api/0-mikustream-live-stream-create-api) | [查询直播上行流量](/products/mikustream/mikustream-live-statistics-api/3-mikustream-live-log-upflow-api)、 [查询直播下行流量](/products/mikustream/mikustream-live-statistics-api/4-mikustream-live-log-downflow-api) |
| 视频监控    | [API概述\_API 文档\_视频监控 - 七牛开发者中心](/products/qvs/0-summary-of-the-api)                                               | [查询流量数据\_API 文档\_视频监控 - 七牛开发者中心](/products/qvs/data/0-query-the-network-traffic-data)                                                                                                                |
| 智能多媒体服务 | [数据处理机制介绍\_API 文档\_智能多媒体服务 - 七牛开发者中心](/products/dora/processing-mechanism/1-directions-for-use-pfop)              | Dora 计量接口\_API 文档\_智能多媒体服务 - 七牛开发者中心                                                                                                                                                                 |
| 内容审核    | [API调用图片审核\_API 文档\_内容审核 - 七牛开发者中心](/products/censor/image-censor)                                                | 暂无（即将上线）                                                                                                                                                                                             |

## 使用示例 [#使用示例]

* Java 示例： [https://github.com/liangchao07115/qiniu-accountManager.git](https://github.com/liangchao07115/qiniu-accountManager.git)


# 冻结服务解释 (/products/af/manual/4162-freeze-service)



最近更新时间: 2026-05-08 18:29:52

**余额**

余额为客户 Portal 中看到的金额，包含现金金额及赠送金金额。
![image.png](/docs-assets/products/af/manual/4162-freeze-service/Fnz3zFmPW5WWzqHKLB5xfAiNRFwc-24ee8f1a588c.webp)

**已出账未扣费**

已经有账单，但是账单未扣费。

**已使用未出账**

已经使用但是并未在账单中体现的费用。例如目前七牛的很多账单为月粒度结算，也就是当月使用需要当月结束后才会体现在账单中，则未在账单体现钱

**欠费**

例如，假设时间为 2018.2.6，余额 1000 元，可以查到 2018.1 月账单 1500 元状态为未扣费，另还有 2018.2.1\~2018.2.6 的使用量未出账单，假设为未出账费用系统算出为 200 元。则用户实际费用 = 余额 - 已出账未扣费 - 已使用未出账 = 1000 - 1500 - 200 = -700 元，即用户欠费 700 元。

**最低充值金额**

最低充值金额为客户欠费的绝对值。当客户收到 24 小时后将被冻结的预警邮件后，需要至少按照最低充值金额充值，才不会在 24 小时后被冻结。

但是非常不建议完全依照该值充值，因为该值为收到冻结预警时刻的欠费金额，经过一天的使用又会在此基础上产生新的使用费用。

例如客户在 2.6 早上 9:10 收到 24 小时后冻结告知邮件，欠费 700 元，最低充值金额为 700 元。客户收到邮件后继续使用七牛服务，并照此充值 700 元。则到 2.7 日 9:10，客户不会被冻结。但是因为 2.7 的使用又产生了额外的费用，例如新增 100 元消费。则客户又将在 2.7 收到信的冻结告知邮件，通知将在 2.8 日将被冻结，最低充值金额为 100 元。

因此，最低充值金额只是一个门槛，但是不建议完全按照最低充值金额充值。

**建议充值金额**

建议充值金额为计算用户最近两月的平均消费，预估三个月费用。


# API 通用约定 (/products/agentapi/api/13618-agentapi-api-conventions)



最近更新时间: 2026-10-13 17:21:31

本页供查阅公共 API 的请求约定、资源范围和事件类型。完整请求与响应字段以 [OpenAPI 规范](/products/agentapi/api/13619-agentapi-openapi)为准；首次接入的任务流程见[通过 API 构建](/products/agentapi/quick_start/13587-agentapi-quickstart)，按能力使用接口的步骤见下表中的使用指南。

AgentAPI 公共 API 会随版本更新增加资源和字段。客户端应忽略响应中的未知字段，并处理错误响应和事件中可选字段缺失的情况。

## 请求约定 [#请求约定]

### 服务地址和认证 [#服务地址和认证]

AgentAPI 服务地址按区域选择，并通过环境变量传入：

```bash
export AGENTAPI_BASE_URL="https://your-agentapi-endpoint"
export AGENTAPI_API_KEY="your-maas-api-key"
```

`/v1/*` 请求使用七牛 MaaS API Key 鉴权。推荐使用 `x-api-key` 请求头；JSON 请求还应设置 `content-type: application/json`。

```bash
curl --request GET "$AGENTAPI_BASE_URL/v1/agents" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

### 资源范围 [#资源范围]

AgentAPI 当前提供以下资源 API：

| 资源    | 主要路径                       | 使用指南                                                                                                                                                                                                                                                                        |
| ----- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 智能体   | `/v1/agents`               | [创建与管理智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)                                                                                                                                                 |
| 环境    | `/v1/environments`         | [配置云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)、[自托管执行器](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted) |
| 会话    | `/v1/sessions`             | [创建会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)、[会话操作](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13598-agentapi-sessions-and-tasks-session-lifecycle)                   |
| 会话事件  | `/v1/sessions/{id}/events` | [事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)                                                                                                                                                    |
| 文件    | `/v1/files`                | [附加和下载文件](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)                                                                                                                                              |
| 技能    | `/v1/skills`               | [Agent Skills](/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills)                                                                                                                                            |
| 凭证保管库 | `/v1/vaults`               | [凭证管理](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13606-agentapi-data-and-integrations-vaults)                                                                                                                                                |
| 持久记忆  | `/v1/memory_stores`        | [构建持久记忆](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13603-agentapi-data-and-integrations-memory)                                                                                                                                              |
| 定时部署  | `/v1/deployments`          | [定时部署](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13600-agentapi-sessions-and-tasks-scheduled-deployments)                                                                                                                                       |
| 部署运行  | `/v1/deployment_runs`      | [查询运行结果](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13600-agentapi-sessions-and-tasks-scheduled-deployments)                                                                                                                                     |

### 响应和分页 [#响应和分页]

* 成功响应使用 JSON；删除操作可能返回 `204 No Content`。
* 所有响应都包含 `X-Trace-ID`，可用于关联请求日志。
* 智能体、环境、会话、事件、技能、保管库、记忆和部署列表使用 `{ "data": [...], "next_page": "..." }`。将 `next_page` 原样作为下一次请求的 `page` 参数，不要自行解析或修改；没有更多数据时该字段为 `null`。
* Files API 使用另一种游标格式：`{ "data": [...], "has_more": true, "first_id": "...", "last_id": "...", "next_page": "..." }`。有下一页时优先把响应中的 `next_page` 原样作为 `page` 查询参数传回；兼容旧客户端的 `after_id` 和 `before_id` 仍可使用，但不能把 `last_id` 直接当作 `page`。
* 列表接口默认返回 20 条，具体上限以接口定义为准；Files API 的 `limit` 最大为 1,000，部署运行列表最多返回 1,000 条。
* 时间字段使用 RFC 3339 格式。

### 常见错误 [#常见错误]

| 状态码   | 含义                |
| ----- | ----------------- |
| `400` | 请求体、查询参数或事件格式无效   |
| `401` | API Key 缺失或无效     |
| `404` | 资源不存在，或不属于当前账户    |
| `409` | 资源状态不允许当前操作，例如已归档 |
| `503` | 依赖的运行时或服务暂时不可用    |

## 事件类型 [#事件类型]

会话事件通过 `POST /v1/sessions/{id}/events` 写入，通过事件列表或 SSE 接口读取。用户消息的结构化内容使用 `input.parts`，详见 [事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)。

### 用户事件 [#用户事件]

| 类型                        | 描述             |
| ------------------------- | -------------- |
| `user.message`            | 发送文本、图像或文件输入   |
| `user.interrupt`          | 中断当前执行         |
| `user.custom_tool_result` | 返回自定义工具的执行结果   |
| `user.tool_confirmation`  | 批准或拒绝需要确认的工具调用 |
| `user.define_outcome`     | 定义需要智能体完成的结果   |

### 智能体事件 [#智能体事件]

| 类型                      | 描述           |
| ----------------------- | ------------ |
| `agent.message`         | 智能体输出        |
| `agent.thinking`        | 智能体正在处理的进度信号 |
| `agent.tool_use`        | 调用内置工具       |
| `agent.tool_result`     | 内置工具返回结果     |
| `agent.mcp_tool_use`    | 调用 MCP 工具    |
| `agent.mcp_tool_result` | MCP 工具返回结果   |
| `agent.custom_tool_use` | 调用应用提供的自定义工具 |

### 会话状态事件 [#会话状态事件]

| 类型                           | 描述            |
| ---------------------------- | ------------- |
| `session.status_running`     | 会话正在执行        |
| `session.status_idle`        | 当前轮次完成或等待用户操作 |
| `session.status_rescheduled` | 会话将在稍后重试      |
| `session.status_terminated`  | 会话已终止         |
| `session.deleted`            | 会话已删除         |
| `session.updated`            | 会话配置已更新       |
| `session.error`              | 会话执行发生错误      |

`session.status_idle` 表示当前轮次暂停或结束执行，不能作为任务成功的唯一依据。请读取其 `stop_reason.type`，确认停止原因：

| `stop_reason.type`  | 含义                                                  |
| ------------------- | --------------------------------------------------- |
| `end_turn`          | 正常完成当前轮次，或 `native` 本轮被中断；需结合 `user.interrupt` 事件区分 |
| `interrupted`       | `claudecode`、`codex` 本轮被 `user.interrupt` 中断        |
| `requires_action`   | 等待工具结果或工具确认；按 `event_ids` 处理后会恢复执行                  |
| `retries_exhausted` | 瞬时失败重试次数耗尽；请结合相邻的 `session.error` 排查                |
| `budget_reached`    | Native 本轮执行达到限制；核对已完成的部分后决定是否继续                     |

### Span 事件 [#span-事件]

Span 事件用于标记模型请求或结果评估的开始、进行中和结束：

* `span.model_request_start`、`span.model_request_end`
* `span.outcome_evaluation_start`、`span.outcome_evaluation_ongoing`、`span.outcome_evaluation_end`

### 系统事件 [#系统事件]

* `system.message`：为当前及后续轮次追加系统级指导。

## 支持的 MCP 服务器类型 [#支持的-mcp-服务器类型]

AgentAPI 支持在智能体上配置远程 MCP 服务器。服务器端点和工具权限通过 [MCP 连接器](/products/agentapi/development_guidelines/agentapi-agent-configuration/13592-agentapi-agent-configuration-mcp) 配置。`claudecode` 和 `codex` 从会话沙箱连接 MCP 服务；`native` 由 AgentAPI 服务端连接，但仍会校验会话环境的网络配置。使用 `limited` 网络时，MCP 服务主机必须包含在 `allowed_hosts` 中。Native 中显式设置 `allow_mcp_servers: false` 会禁止 MCP 工具接入；设置为 `true` 不会绕过主机白名单。

## 相关页面 [#相关页面]

* [事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)：发送事件、读取历史和建立 SSE 连接。
* [使用 SDK](/products/agentapi/quick_start/13587-agentapi-quickstart)：配置客户端并传入 AgentAPI 扩展字段。


# OpenAPI 规范 (/products/agentapi/api/13619-agentapi-openapi)



最近更新时间: 2026-10-14 14:03:34

完整请求、响应字段和数据结构见 [下载 OpenAPI YAML](https://dn-odum9helk.qbox.me/FvPJkqgApx2DcsC4EdR9Ym2mYv_t)。该文件可导入支持 OpenAPI 的接口工具。

## 接口索引 [#接口索引]

| 方法     | 路径                                                                               | 说明                                  |
| ------ | -------------------------------------------------------------------------------- | ----------------------------------- |
| GET    | `/v1/agents`                                                                     | List agents                         |
| POST   | `/v1/agents`                                                                     | Create agent                        |
| DELETE | `/v1/agents/{id}`                                                                | Delete agent                        |
| GET    | `/v1/agents/{id}`                                                                | Get agent                           |
| PATCH  | `/v1/agents/{id}`                                                                | Patch agent                         |
| POST   | `/v1/agents/{id}`                                                                | Update agent                        |
| POST   | `/v1/agents/{id}/archive`                                                        | Archive agent                       |
| GET    | `/v1/agents/{id}/versions`                                                       | List agent versions                 |
| GET    | `/v1/deployment_runs`                                                            | List deployment runs                |
| GET    | `/v1/deployment_runs/{deployment_run_id}`                                        | Get deployment run                  |
| GET    | `/v1/deployments`                                                                | List deployments                    |
| POST   | `/v1/deployments`                                                                | Create deployment                   |
| GET    | `/v1/deployments/{deployment_id}`                                                | Get deployment                      |
| POST   | `/v1/deployments/{deployment_id}`                                                | Update deployment                   |
| POST   | `/v1/deployments/{deployment_id}/archive`                                        | Archive deployment                  |
| POST   | `/v1/deployments/{deployment_id}/pause`                                          | Pause deployment                    |
| POST   | `/v1/deployments/{deployment_id}/run`                                            | Run deployment now                  |
| POST   | `/v1/deployments/{deployment_id}/unpause`                                        | Unpause deployment                  |
| GET    | `/v1/environments`                                                               | List environments                   |
| POST   | `/v1/environments`                                                               | Create environment                  |
| GET    | `/v1/environments/{environment_id}/work`                                         | List self-hosted work               |
| GET    | `/v1/environments/{environment_id}/work/poll`                                    | Poll self-hosted environment work   |
| GET    | `/v1/environments/{environment_id}/work/stats`                                   | Get self-hosted work queue stats    |
| GET    | `/v1/environments/{environment_id}/work/{work_id}`                               | Get self-hosted work                |
| POST   | `/v1/environments/{environment_id}/work/{work_id}`                               | Update self-hosted work metadata    |
| POST   | `/v1/environments/{environment_id}/work/{work_id}/ack`                           | Acknowledge self-hosted work        |
| POST   | `/v1/environments/{environment_id}/work/{work_id}/heartbeat`                     | Heartbeat self-hosted work          |
| POST   | `/v1/environments/{environment_id}/work/{work_id}/stop`                          | Stop self-hosted work               |
| DELETE | `/v1/environments/{id}`                                                          | Delete environment                  |
| GET    | `/v1/environments/{id}`                                                          | Get environment                     |
| POST   | `/v1/environments/{id}`                                                          | Update environment                  |
| POST   | `/v1/environments/{id}/archive`                                                  | Archive environment                 |
| GET    | `/v1/files`                                                                      | List files                          |
| POST   | `/v1/files`                                                                      | Upload file                         |
| DELETE | `/v1/files/{id}`                                                                 | Delete file                         |
| GET    | `/v1/files/{id}`                                                                 | Get file metadata                   |
| GET    | `/v1/files/{id}/content`                                                         | Download file content               |
| GET    | `/v1/memory_stores`                                                              | List memory stores                  |
| POST   | `/v1/memory_stores`                                                              | Create memory store                 |
| DELETE | `/v1/memory_stores/{memory_store_id}`                                            | Delete memory store                 |
| GET    | `/v1/memory_stores/{memory_store_id}`                                            | Get memory store                    |
| POST   | `/v1/memory_stores/{memory_store_id}`                                            | Update memory store                 |
| POST   | `/v1/memory_stores/{memory_store_id}/archive`                                    | Archive memory store                |
| GET    | `/v1/memory_stores/{memory_store_id}/memories`                                   | List memories                       |
| POST   | `/v1/memory_stores/{memory_store_id}/memories`                                   | Create memory                       |
| DELETE | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`                       | Delete memory                       |
| GET    | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`                       | Get memory                          |
| POST   | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`                       | Update memory                       |
| GET    | `/v1/memory_stores/{memory_store_id}/memory_versions`                            | List memory versions                |
| GET    | `/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}`        | Get memory version                  |
| POST   | `/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}/redact` | Redact memory version               |
| GET    | `/v1/sessions`                                                                   | List sessions                       |
| POST   | `/v1/sessions`                                                                   | Create session                      |
| DELETE | `/v1/sessions/{id}`                                                              | Delete session                      |
| GET    | `/v1/sessions/{id}`                                                              | Get session                         |
| POST   | `/v1/sessions/{id}`                                                              | Update session                      |
| POST   | `/v1/sessions/{id}/archive`                                                      | Archive session                     |
| GET    | `/v1/sessions/{id}/events`                                                       | List session events                 |
| POST   | `/v1/sessions/{id}/events`                                                       | Send session events                 |
| GET    | `/v1/sessions/{id}/events/stream`                                                | Stream session events               |
| GET    | `/v1/sessions/{id}/resources`                                                    | List session resources              |
| POST   | `/v1/sessions/{id}/resources`                                                    | Add session resource                |
| DELETE | `/v1/sessions/{id}/resources/{resource_id}`                                      | Delete session resource             |
| GET    | `/v1/sessions/{id}/resources/{resource_id}`                                      | Get session resource                |
| POST   | `/v1/sessions/{id}/resources/{resource_id}`                                      | Update session resource             |
| GET    | `/v1/skills`                                                                     | List skills                         |
| POST   | `/v1/skills`                                                                     | Create skill                        |
| DELETE | `/v1/skills/{skill_id}`                                                          | Delete skill                        |
| GET    | `/v1/skills/{skill_id}`                                                          | Get skill                           |
| GET    | `/v1/skills/{skill_id}/versions`                                                 | List skill versions                 |
| POST   | `/v1/skills/{skill_id}/versions`                                                 | Create skill version                |
| DELETE | `/v1/skills/{skill_id}/versions/{version}`                                       | Delete skill version                |
| GET    | `/v1/skills/{skill_id}/versions/{version}`                                       | Get skill version                   |
| GET    | `/v1/skills/{skill_id}/versions/{version}/content`                               | Download skill version content      |
| GET    | `/v1/skills/{skill_id}/versions/{version}/files`                                 | List skill version files            |
| GET    | `/v1/skills/{skill_id}/versions/{version}/files/content`                         | Download skill version file content |
| GET    | `/v1/vaults`                                                                     | List vaults                         |
| POST   | `/v1/vaults`                                                                     | Create vault                        |
| DELETE | `/v1/vaults/{vault_id}`                                                          | Delete vault                        |
| GET    | `/v1/vaults/{vault_id}`                                                          | Get vault                           |
| POST   | `/v1/vaults/{vault_id}`                                                          | Update vault                        |
| POST   | `/v1/vaults/{vault_id}/archive`                                                  | Archive vault                       |
| GET    | `/v1/vaults/{vault_id}/credentials`                                              | List credentials                    |
| POST   | `/v1/vaults/{vault_id}/credentials`                                              | Create credential                   |
| DELETE | `/v1/vaults/{vault_id}/credentials/{credential_id}`                              | Delete credential                   |
| GET    | `/v1/vaults/{vault_id}/credentials/{credential_id}`                              | Get credential                      |
| POST   | `/v1/vaults/{vault_id}/credentials/{credential_id}`                              | Update credential                   |
| POST   | `/v1/vaults/{vault_id}/credentials/{credential_id}/archive`                      | Archive credential                  |


# 计费说明 (/products/agentapi/buying_guide/13623-agentapi-billing-instructions)



最近更新时间: 2026-10-16 09:58:23

AgentAPI 的费用按实际使用情况计量，现阶段限时免费。

* **模型调用费用**：模型调用使用七牛云大模型推理服务，按实际 Token 用量及所选模型价格计费。具体模型价格请以[七牛云大模型推理服务模型列表](https://portal.qiniu.com/ai-inference/model)为准。
* **AgentAPI 服务费**：现阶段限时免费，暂不收取服务费。

## 模型调用费用 [#模型调用费用]

一个任务可能包含多次模型调用，费用会随着实际模型用量产生。实际费用取决于模型调用产生的 Token 用量和所选模型的价格。


# 术语表 (/products/agentapi/glossary/13621-agentapi-glossary)



最近更新时间: 2026-10-13 17:20:58

| 术语      | 英文或字段        | 定义与详细说明                                                                                                                                                                                                                                                                                      |
| ------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MaaS    | MaaS         | 七牛大模型推理服务，提供模型调用与 API Key 管理。AgentAPI 使用 MaaS API Key 鉴权，见[接入准备](/products/agentapi/quick_start/13585-agentapi-access)。                                                                                                                                                                      |
| 智能体     | Agent        | 可复用、带版本的模型、提示、工具与运行时配置。见[智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)。                                                                                                                                              |
| 智能体版本   | AgentVersion | 智能体的一份固定配置；已有会话继续引用固定版本。见[版本与会话](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)。                                                                                                                                           |
| 运行时     | `runtime`    | 智能体的执行方式，可选择 `claudecode`、`codex` 或 `native`。见[运行时和模型](/products/agentapi/development_guidelines/agentapi-agent-configuration/13589-agentapi-agent-configuration-runtime-and-models)。                                                                                                        |
| 模型      | `model`      | 执行推理与生成的模型配置。见[模型选择](/products/agentapi/development_guidelines/agentapi-agent-configuration/13589-agentapi-agent-configuration-runtime-and-models)。                                                                                                                                          |
| 环境      | Environment  | 定义工具执行所需的软件与网络条件。见[云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)和[自托管执行器](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。 |
| 会话      | Session      | 保存持续交互的历史、执行状态和文件，并引用固定的智能体版本。见[会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)。                                                                                                                                        |
| 执行轮次    | Turn         | 会话中一次由输入触发的执行，可以包含多次模型请求和工具调用。见[任务与执行轮次](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)。                                                                                                                                   |
| 事件      | Event        | 任务输入、智能体输出、工具活动或生命周期变化的记录。见[事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)。                                                                                                                                         |
| 事件流     | SSE          | 通过持久 HTTP 连接回放历史并推送实时事件。见[订阅事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)。                                                                                                                                            |
| 工具      | Tool         | 智能体调用的执行能力，包括内置工具和应用提供的自定义工具。见[工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)。                                                                                                                                         |
| MCP 连接器 | MCP          | 通过 Model Context Protocol 接入远程工具服务。见[MCP 连接器](/products/agentapi/development_guidelines/agentapi-agent-configuration/13592-agentapi-agent-configuration-mcp)。                                                                                                                                |
| 智能体技能   | Agent Skills | 按任务需要加载的工作说明和辅助文件。见[Agent Skills](/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills)。                                                                                                                                         |
| 凭证保管库   | Vault        | 管理会话使用的凭证及其注入配置。见[凭证管理](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13606-agentapi-data-and-integrations-vaults)。                                                                                                                                               |
| 持久记忆    | Memory Store | 在会话之外管理可复用的记忆及其版本。见[构建持久记忆](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13603-agentapi-data-and-integrations-memory)。                                                                                                                                           |
| 结果      | Outcome      | 通过评分标准定义预期结果，供执行后的评估与修订使用。见[定义结果](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13599-agentapi-sessions-and-tasks-outcomes)。                                                                                                                                         |
| 定时部署    | Deployment   | 按计划或手动触发会话的配置。见[定时部署](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13600-agentapi-sessions-and-tasks-scheduled-deployments)。                                                                                                                                        |
| 自托管执行器  | Worker       | 领取自托管环境中的工作并回传执行结果的程序。见[自托管执行器](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。                                                                                                                                |


# 迁移到 AgentAPI (/products/agentapi/development_guidelines/13617-agentapi-migration)



最近更新时间: 2026-10-13 15:32:36

本页介绍从 OpenAI Responses API、LangChain 自定义循环及 Claude Managed Agents/Claude Agent SDK 迁移到 AgentAPI 的方法。

迁移后，应用管理智能体、云端环境、会话及业务状态；AgentAPI 在云端运行智能体循环、执行内置工具并保存事件。请先按下表确定迁移范围。

## 迁移范围 [#迁移范围]

| 原有架构                      | 需要保留在应用中的内容          | 迁移到 AgentAPI 的内容                                                              |
| ------------------------- | -------------------- | ----------------------------------------------------------------------------- |
| Claude Managed Agents API | 业务鉴权、业务状态和结果展示       | Base URL、MaaS API Key、Agent/Environment/Session 资源，以及 AgentAPI 的 `runtime` 扩展 |
| Claude Agent SDK（本地运行）    | 业务工具实现、审批界面和业务数据     | 云端环境、会话事件流、文件/仓库资源；本地 SDK 的进程生命周期不再由应用管理                                      |
| OpenAI Responses API      | 业务输入输出转换和自定义函数       | 智能体循环、内置工具执行、云端沙箱和事件持久化                                                       |
| LangChain 自定义循环           | 检查点中的业务状态、自定义工具和业务超时 | 智能体版本、会话状态机和事件流                                                               |

使用 CMA Session API 的应用，请先按[接入准备](/products/agentapi/quick_start/13585-agentapi-access)验证地址和 MaaS API Key，并核对三项差异：

* 智能体增加 AgentAPI 扩展字段 `runtime`。
* 结构化 HTTP 输入使用 `input.parts`。
* SDK 可能仍生成兼容字段 `content`。

![迁移到 AgentAPI：执行边界上移](/docs-assets/products/agentapi/development_guidelines/13617-agentapi-migration/Fp1VIolY-zDe2S52CohrGjysGp5L-bbddbbe016f5.webp)

## 从 OpenAI Responses API 迁移 [#从-openai-responses-api-迁移]

如果应用通过 `responses.create` 调用模型、遍历函数调用并将 `function_call_output` 追加到下一轮输入，那么应用本身承担了智能体循环的职责。迁移到 AgentAPI 后，这部分循环和内置工具执行可以交给云端服务。

![从 Responses API 循环迁移到 AgentAPI 事件流](/docs-assets/products/agentapi/development_guidelines/13617-agentapi-migration/FnH8R_YN9LR_DM-6tBk9CMdP8d-4-39ee901dc2e5.webp)

### 执行职责迁移 [#执行职责迁移]

| 之前                                                       | 之后                                                               |
| -------------------------------------------------------- | ---------------------------------------------------------------- |
| 应用维护 Responses 输入，并在每轮调用中传递已有输出或 `previous_response_id`。 | AgentAPI 在服务端保存会话历史；应用只需发送和接收事件。                                 |
| 应用遍历 `function_call`，执行函数，再追加 `function_call_output`。    | 文件和命令工具在云端沙箱中执行；网页工具按运行时执行。应用通过 `agent.custom_tool_use` 处理自定义工具。 |
| 应用自行准备沙箱，运行智能体生成的代码。                                     | AgentAPI 根据云端环境配置准备沙箱，并在其中执行代码、文件操作和 Bash 命令。                    |
| 应用自行判断智能体循环何时结束。                                         | AgentAPI 通过状态事件报告本轮停止，应用需检查停止原因、错误与业务结果。                         |

### 代码对比 [#代码对比]

迁移前（简化的 Responses API 函数调用循环）：

Python

```python
import json

input_items = [{"role": "user", "content": task}]
while True:
    response = client.responses.create(
        model="gpt-5.6",
        input=input_items,
        tools=tools,
    )

    input_items.extend(response.output)
    function_calls = [item for item in response.output if item.type == "function_call"]
    if not function_calls:
        break

    for call in function_calls:
        result = execute_tool(call.name, json.loads(call.arguments))
        input_items.append(
            {
                "type": "function_call_output",
                "call_id": call.call_id,
                "output": result,
            }
        )
```

TypeScript

```typescript
const input: any[] = [{ role: "user", content: task }];
while (true) {
  const response = await client.responses.create({
    model: "gpt-5.6",
    input,
    tools
  });

  input.push(...response.output);
  const functionCalls = response.output.filter(
    (item) => item.type === "function_call"
  );
  if (functionCalls.length === 0) {
    break;
  }

  for (const call of functionCalls) {
    const result = await executeTool(call.name, JSON.parse(call.arguments));
    input.push({
      type: "function_call_output",
      call_id: call.call_id,
      output: result
    });
  }
}
```

迁移后（AgentAPI）：

以下示例假设已按照[接入准备](/products/agentapi/quick_start/13585-agentapi-access)配置 SDK 客户端，并创建了云端环境。智能体和云端环境可以跨多个会话复用。
以下内置工具示例显式选择 `native`。模型从 `AGENTAPI_MODEL_ID` 读取，请先在[七牛 MaaS 模型管理页](https://portal.qiniu.com/ai-inference/model)获取模型 ID，并确认所用 Key 在所选区域可调用该模型。SDK 通过扩展请求参数传入运行时，客户端初始化见[通过 API 构建](/products/agentapi/quick_start/13587-agentapi-quickstart)。

cURL

```bash
TASK="${TASK:-请分析当前项目并给出改进建议。}"

agent=$(
  curl --fail-with-body -sS "$AGENTAPI_BASE_URL/v1/agents" \
    -H "x-api-key: $AGENTAPI_API_KEY" \
    -H "content-type: application/json" --data @- <<EOF
{
      "name": "任务执行助手",
      "runtime": "native",
      "model": {"id": "$AGENTAPI_MODEL_ID"},
      "tools": [{"type": "agent_toolset_20260401"}]
}
EOF
)
agent_id=$(jq -r '.id' <<< "${agent}")

session_id=$(
  curl --fail-with-body -sS "$AGENTAPI_BASE_URL/v1/sessions" \
    -H "x-api-key: $AGENTAPI_API_KEY" \
    -H "content-type: application/json" --data "$(jq -n --argjson a "${agent}" --arg env "${ENVIRONMENT_ID}" \
      '{agent: {type: "agent", id: $a.id, version: $a.version}, environment_id: $env}')" \
  | jq -r '.id'
)

# 在后台打开 SSE 流，然后发送用户消息。
stream_log=$(mktemp)
curl --fail-with-body -sS -N \
  "$AGENTAPI_BASE_URL/v1/sessions/${session_id}/events/stream" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  > "${stream_log}" &
stream_pid=$!

curl --fail-with-body -sS \
  "$AGENTAPI_BASE_URL/v1/sessions/${session_id}/events" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" --data "$(jq -n --arg text "${TASK}" \
    '{events: [{type: "user.message", input: {parts: [{type: "text", text: $text}]}}]}')" \
  > /dev/null

# 等待会话进入空闲状态。grep 在首次匹配时退出，并且
# 通过进程替换读取意味着 shell 不会等待
# tail（前台的 `tail -f | grep -m1` 管道会挂起：tail
# 只会在下一次写入时终止，而流空闲后不会再有写入）。
grep -m1 '"session.status_idle"' <(tail -f -n +1 "${stream_log}") > /dev/null

kill "${stream_pid}" 2>/dev/null || true
rm -f "${stream_log}"
```

Python

```python
import os

agent = client.beta.agents.create(
    name="任务执行助手",
    model={"id": os.environ["AGENTAPI_MODEL_ID"]},
    tools=[{"type": "agent_toolset_20260401"}],
    extra_body={"runtime": "native"},
)

session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment.id,
)

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{"type": "user.message", "content": [{"type": "text", "text": task}]}],
    )
    for event in stream:
        if event.type == "session.status_idle":
            break
```

TypeScript

````typescript
const agentParams = {
  name: "任务执行助手",
  model: { id: process.env.AGENTAPI_MODEL_ID! },
  tools: [{ type: "agent_toolset_20260401" }]
} satisfies Parameters<typeof client.beta.agents.create>[0];
const agent = await client.beta.agents.create(agentParams, {
  body: { ...agentParams, runtime: "native" },
});

const session = await client.beta.sessions.create({
  agent: { type: "agent", id: agent.id, version: agent.version },
  environment_id: environment.id
});

const stream = await client.beta.sessions.events.stream(session.id);

await client.beta.sessions.events.send(session.id, {
  events: [
    {
      type: "user.message",
      content: [{ type: "text", text: task }]
    }
  ]
});

for await (const event of stream) {
  if (event.type === "session.status_idle") {
    break;
  }
}
```csharp
```csharp
using Anthropic.Models.Beta.Agents;
using System.Text.Json;
using System.Linq;
var agentParams = new AgentCreateParams
{
    Name = "任务执行助手",
    Model = new BetaManagedAgentsModelConfigParams { ID = System.Environment.GetEnvironmentVariable("AGENTAPI_MODEL_ID")! },
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = "agent_toolset_20260401",
        },
    ],
};
var agentBody = agentParams.RawBodyData.ToDictionary(entry => entry.Key, entry => entry.Value);
agentBody["runtime"] = JsonSerializer.SerializeToElement("native");
agentParams = AgentCreateParams.FromRawUnchecked(
    agentParams.RawHeaderData, agentParams.RawQueryData, agentBody);
var agent = await client.Beta.Agents.Create(agentParams);

var session = await client.Beta.Sessions.Create(new()
{
    Agent = new BetaManagedAgentsAgentParams
    {
        Type = "agent",
        ID = agent.ID,
        Version = agent.Version,
    },
    EnvironmentID = environment.ID,
});

var stream = client.Beta.Sessions.Events.StreamStreaming(session.ID);

await client.Beta.Sessions.Events.Send(session.ID, new()
{
    Events =
    [
        new BetaManagedAgentsUserMessageEventParams
        {
            Type = "user.message",
            Content = [new BetaManagedAgentsTextBlock { Type = "text", Text = task }],
        },
    ],
});

await foreach (var streamEvent in stream)
{
    if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent)
    {
        break;
    }
}
````

Go

```go
	agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
		Name: "任务执行助手",
		Model: anthropic.BetaManagedAgentsModelConfigParams{
			ID: os.Getenv("AGENTAPI_MODEL_ID"),
		},
		Tools: []anthropic.BetaAgentNewParamsToolUnion{{
			OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
				Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			},
		}},
	}, option.WithJSONSet("runtime", "native"))
	if err != nil {
		log.Fatal(err)
	}

	session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
		Agent: anthropic.BetaSessionNewParamsAgentUnion{
			OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
				Type:    anthropic.BetaManagedAgentsAgentParamsTypeAgent,
				ID:      agent.ID,
				Version: anthropic.Int(agent.Version),
			},
		},
		EnvironmentID: environment.ID,
	})
	if err != nil {
		log.Fatal(err)
	}

	stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
	defer stream.Close()

	_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
		Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
			OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
				Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
				Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
					OfText: &anthropic.BetaManagedAgentsTextBlockParam{
						Type: anthropic.BetaManagedAgentsTextBlockTypeText,
						Text: task,
					},
				}},
			},
		}},
	})
	if err != nil {
		log.Fatal(err)
	}

	for stream.Next() {
		event := stream.Current()
		if event.Type == "session.status_idle" {
			break
		}
	}
	if err := stream.Err(); err != nil {
		log.Fatal(err)
	}
```

Java

```java
    var agent = client.beta().agents().create(
        AgentCreateParams.builder()
        .putAdditionalBodyProperty("runtime", com.anthropic.core.JsonValue.from("native"))
            .name("任务执行助手")
            .model(BetaManagedAgentsModelConfigParams.builder().id(System.getenv("AGENTAPI_MODEL_ID")).build())
            .addTool(
                BetaManagedAgentsAgentToolset20260401Params.builder()
                    .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                    .build()
            )
            .build()
    );

    var session = client.beta().sessions().create(
        SessionCreateParams.builder()
            .agent(
                BetaManagedAgentsAgentParams.builder()
                    .type(BetaManagedAgentsAgentParams.Type.AGENT)
                    .id(agent.id())
                    .version(agent.version())
                    .build()
            )
            .environmentId(environment.id())
            .build()
    );

    try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
        client.beta().sessions().events().send(
            session.id(),
            EventSendParams.builder()
                .addEvent(
                    BetaManagedAgentsUserMessageEventParams.builder()
                        .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
                        .addTextContent(task)
                        .build()
                )
                .build()
        );
        stream.stream()
            .takeWhile(event -> !event.isSessionStatusIdle())
            .forEach(_ -> {});
    }
```

PHP

```php
$agent = $client->beta->agents->create(
    name: '任务执行助手',
    model: ['id' => getenv('AGENTAPI_MODEL_ID')],
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
        ),
    ],
    requestOptions: ['extraBodyParams' => ['runtime' => 'native']],
);

$session = $client->beta->sessions->create(
    agent: BetaManagedAgentsAgentParams::with(
        type: 'agent',
        id: $agent->id,
        version: $agent->version,
    ),
    environmentID: $environment->id,
);

$stream = $client->beta->sessions->events->streamStream($session->id);

$client->beta->sessions->events->send(
    $session->id,
    events: [
        [
            'type' => 'user.message',
            'content' => [['type' => 'text', 'text' => $task]],
        ],
    ],
);

foreach ($stream as $event) {
    if ($event->type === 'session.status_idle') {
        break;
    }
}
```

Ruby

```ruby
agent = client.beta.agents.create(
  name: "任务执行助手",
  model: {id: ENV.fetch("AGENTAPI_MODEL_ID")},
  tools: [{type: "agent_toolset_20260401"}],
  request_options: {extra_body: {runtime: "native"}}
)

session = client.beta.sessions.create(
  agent: {type: "agent", id: agent.id, version: agent.version},
  environment_id: environment.id
)

stream = client.beta.sessions.events.stream_events(session.id)
client.beta.sessions.events.send_(
  session.id,
  events: [{type: "user.message", content: [{type: "text", text: task}]}]
)
stream.each do
  break if it.type == :"session.status_idle"
end
```

### 应用职责 [#应用职责]

* 系统提示和模型： 仍由应用决定，但配置从单次模型请求移到智能体定义中。
* 自定义工具： 仍然使用 JSON Schema 声明。执行方式从循环内直接调用，改为处理 `agent.custom_tool_use` 事件并返回结果。请参阅[事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)。
* 网页访问： `claudecode` 和 `codex` 使用各自运行时提供的网页能力；`native` 提供 `web_search` 和 `web_fetch`，由 AgentAPI 执行，不在自托管 worker 上运行。
* 任务上下文： 可以通过系统提示、[文件资源](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)或[技能](/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills)向智能体提供上下文。

## 从基于 LangChain 的自定义智能体循环迁移 [#从基于-langchain-的自定义智能体循环迁移]

如果应用使用 LangChain 的模型和工具抽象，但通过 `bind_tools` 或 `bindTools` 自行维护消息列表、分派工具并控制循环结束条件，那么迁移方式与直接调用模型类似。主要变化是将这套循环交给 AgentAPI 在云端运行，并将原有配置映射为智能体、云端环境、会话和事件。

![从 LangChain 自定义循环映射到 AgentAPI 资源](/docs-assets/products/agentapi/development_guidelines/13617-agentapi-migration/Fv3XV4IUNSoLf1v_vUjGvQogFkSj-3bbef18e51e4.webp)

### 架构映射 [#架构映射]

| LangChain 智能体循环                                          | AgentAPI                                                                                                                                                                                      |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 使用 `model.bind_tools(...)` 或 `model.bindTools(...)` 绑定工具 | 在[智能体定义](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)中配置工具，AgentAPI 在服务端保存配置并管理版本。                                        |
| 应用保存消息列表并反复调用 `model.invoke(...)`                        | 创建会话并发送用户事件；AgentAPI 保存会话历史并运行智能体循环。                                                                                                                                                          |
| 应用读取 `tool_calls`、执行工具并追加 `ToolMessage`                  | 内置工具由 AgentAPI 在云端沙箱中执行；自定义工具通过 `agent.custom_tool_use` 和 `user.custom_tool_result` 事件衔接。                                                                                                     |
| 本地工具直接访问应用所在机器的文件系统                                      | 将[文件](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)作为会话资源上传或挂载；智能体在隔离的云端沙箱中处理文件。                                       |
| 每次调用时传入系统提示和模型配置                                         | 在智能体的 `system` 和 `model` 中配置；更新智能体时生成新版本。                                                                                                                                                     |
| 应用自行保存检查点并恢复消息历史                                         | AgentAPI 持久保存会话和事件；应用通过会话 ID 继续交互。                                                                                                                                                            |
| 应用在循环中实现工具确认逻辑                                           | 使用 [`permission_policy`](/products/agentapi/development_guidelines/agentapi-agent-configuration/13593-agentapi-agent-configuration-permissions) 控制工具是否需要确认，并通过 `user.tool_confirmation` 返回选择。 |

### 代码对比 [#代码对比-1]

迁移前（使用 LangChain 自行维护工具调用循环）：

Python

```python
from langchain.chat_models import init_chat_model
from langchain.tools import tool

@tool
def get_weather(city: str) -> str:
    """查询城市当前的天气。"""
    return f"{city}：18°C，晴"

model = init_chat_model("openai:gpt-5.6")
model_with_tools = model.bind_tools([get_weather])
messages = [{"role": "user", "content": "东京天气怎么样？"}]

while True:
    response = model_with_tools.invoke(messages)
    messages.append(response)
    if not response.tool_calls:
        print(response.text)
        break
    for tool_call in response.tool_calls:
        messages.append(get_weather.invoke(tool_call))
```

TypeScript

```typescript
import { initChatModel, tool } from "langchain";
import { z } from "zod";

const getWeather = tool(
  ({ city }) => `${city}：18°C，晴`,
  {
    name: "get_weather",
    description: "查询城市当前的天气。",
    schema: z.object({ city: z.string() })
  }
);

const model = await initChatModel("openai:gpt-5.6");
const modelWithTools = model.bindTools([getWeather]);
const messages: any[] = [{ role: "user", content: "东京天气怎么样？" }];

while (true) {
  const response = await modelWithTools.invoke(messages);
  messages.push(response);
  if (!response.tool_calls?.length) {
    console.log(response.text);
    break;
  }
  for (const toolCall of response.tool_calls) {
    if (toolCall.name === getWeather.name) {
      messages.push(await getWeather.invoke(toolCall));
    }
  }
}
```

迁移后（AgentAPI）：

下面选择 `native`，由应用处理天气查询工具并回传结果。天气数据在示例中由本地函数返回；接入真实服务时，在该函数中完成鉴权、参数校验、超时和错误处理。

Python

```python
import os

from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["AGENTAPI_API_KEY"],
    base_url=os.environ["AGENTAPI_BASE_URL"],
)

agent = client.beta.agents.create(
    name="天气助手",
    model={"id": os.environ["AGENTAPI_MODEL_ID"]},
    system="你是一名简洁、准确的天气助手。",
    tools=[
        {
            "type": "custom",
            "name": "get_weather",
            "description": "查询城市当前的天气。",
            "input_schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        }
    ],
    extra_body={"runtime": "native"},
)
environment = client.beta.environments.create(
    name="weather-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment.id,
)

def get_weather(city: str) -> str:
    return f"{city}：18°C，晴"

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "东京天气怎么样？"}],
            }
        ],
    )
    for event in stream:
        if event.type == "agent.message":
            print(
                "".join(block.text for block in event.content if block.type == "text")
            )
        elif event.type == "agent.custom_tool_use":
            result = get_weather(**event.input)
            client.beta.sessions.events.send(
                session.id,
                events=[
                    {
                        "type": "user.custom_tool_result",
                        "custom_tool_use_id": event.id,
                        "content": [{"type": "text", "text": result}],
                    }
                ],
            )
        elif (
            event.type == "session.status_idle"
            and event.stop_reason
            and event.stop_reason.type == "end_turn"
        ):
            break
```

TypeScript

````typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.AGENTAPI_API_KEY!,
  baseURL: process.env.AGENTAPI_BASE_URL,
});

const agentParams = {
  name: "天气助手",
  model: { id: process.env.AGENTAPI_MODEL_ID! },
  system: "你是一名简洁、准确的天气助手。",
  tools: [
    {
      type: "custom",
      name: "get_weather",
      description: "查询城市当前的天气。",
      input_schema: {
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"]
      }
    }
  ]
} satisfies Parameters<typeof client.beta.agents.create>[0];
const agent = await client.beta.agents.create(agentParams, {
  body: { ...agentParams, runtime: "native" },
});
const environment = await client.beta.environments.create({
  name: "weather-env",
  config: { type: "cloud", networking: { type: "unrestricted" } }
});

const session = await client.beta.sessions.create({
  agent: { type: "agent", id: agent.id, version: agent.version },
  environment_id: environment.id
});

function getWeather({ city }: Record<string, unknown>): string {
  return `${city}：18°C，晴`;
}

const stream = await client.beta.sessions.events.stream(session.id);

await client.beta.sessions.events.send(session.id, {
  events: [
    {
      type: "user.message",
      content: [{ type: "text", text: "东京天气怎么样？" }]
    }
  ]
});

for await (const event of stream) {
  if (event.type === "agent.message") {
    for (const block of event.content) {
      if (block.type === "text") {
        console.log(block.text);
      }
    }
  } else if (event.type === "agent.custom_tool_use") {
    const result = getWeather(event.input);
    await client.beta.sessions.events.send(session.id, {
      events: [
        {
          type: "user.custom_tool_result",
          custom_tool_use_id: event.id,
          content: [{ type: "text", text: result }]
        }
      ]
    });
  } else if (event.type === "session.status_idle" && event.stop_reason?.type === "end_turn") {
    break;
  }
}
```csharp
```csharp
using System.Linq;
using System.Text.Json;

using Anthropic;
using Anthropic.Core;
using Anthropic.Models.Beta.Agents;
using Anthropic.Models.Beta.Environments;
using Anthropic.Models.Beta.Sessions;
using Anthropic.Models.Beta.Sessions.Events;

var client = new AnthropicClient(new ClientOptions
{
    ApiKey = System.Environment.GetEnvironmentVariable("AGENTAPI_API_KEY")
        ?? throw new InvalidOperationException("AGENTAPI_API_KEY is required"),
    BaseUrl = System.Environment.GetEnvironmentVariable("AGENTAPI_BASE_URL")
        ?? throw new InvalidOperationException("AGENTAPI_BASE_URL is required"),
});

var agentParams = new AgentCreateParams
{
    Name = "天气助手",
    Model = new BetaManagedAgentsModelConfigParams { ID = System.Environment.GetEnvironmentVariable("AGENTAPI_MODEL_ID")! },
    System = "你是一名简洁、准确的天气助手。",
    Tools =
    [
        new BetaManagedAgentsCustomToolParams
        {
            Type = "custom",
            Name = "get_weather",
            Description = "查询城市当前的天气。",
            InputSchema = new()
            {
                Properties = new Dictionary<string, JsonElement>
                {
                    ["city"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                },
                Required = ["city"],
            },
        },
    ],
};
var agentBody = agentParams.RawBodyData.ToDictionary(entry => entry.Key, entry => entry.Value);
agentBody["runtime"] = JsonSerializer.SerializeToElement("native");
agentParams = AgentCreateParams.FromRawUnchecked(
    agentParams.RawHeaderData, agentParams.RawQueryData, agentBody);
var agent = await client.Beta.Agents.Create(agentParams);
var environment = await client.Beta.Environments.Create(new()
{
    Name = "weather-env",
    Config = new BetaCloudConfigParams
    {
        Networking = new BetaUnrestrictedNetwork(),
    },
});

var session = await client.Beta.Sessions.Create(new()
{
    Agent = new BetaManagedAgentsAgentParams
    {
        Type = "agent",
        ID = agent.ID,
        Version = agent.Version,
    },
    EnvironmentID = environment.ID,
});

static string GetWeather(string city) => $"{city}：18°C，晴";

using var stream = await client.Beta.Sessions.Events.WithRawResponse.StreamStreaming(session.ID);

await client.Beta.Sessions.Events.Send(session.ID, new()
{
    Events =
    [
        new BetaManagedAgentsUserMessageEventParams
        {
            Type = "user.message",
            Content = [new BetaManagedAgentsTextBlock { Type = "text", Text = "东京天气怎么样？" }],
        },
    ],
});

await foreach (var streamEvent in stream.Enumerate())
{
    if (streamEvent.Value is BetaManagedAgentsAgentMessageEvent message)
    {
        Console.WriteLine(string.Concat(message.Content.Select(block => block.Text)));
    }
    else if (streamEvent.Value is BetaManagedAgentsAgentCustomToolUseEvent toolUse)
    {
        var result = GetWeather(toolUse.Input["city"].GetString()!);
        await client.Beta.Sessions.Events.Send(session.ID, new()
        {
            Events =
            [
                new BetaManagedAgentsUserCustomToolResultEventParams
                {
                    Type = "user.custom_tool_result",
                    CustomToolUseID = toolUse.ID,
                    Content =
                    [
                        new BetaManagedAgentsTextBlock
                        {
                            Type = "text",
                            Text = result,
                        },
                    ],
                },
            ],
        });
    }
    else if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent idle
        && idle.StopReason?.Value is BetaManagedAgentsSessionEndTurn)
    {
        break;
    }
}
````

Go

```go
client := anthropic.NewClient(
	option.WithoutEnvironmentDefaults(),
	option.WithBaseURL(os.Getenv("AGENTAPI_BASE_URL")),
	option.WithAPIKey(os.Getenv("AGENTAPI_API_KEY")),
)
ctx := context.Background()

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "天气助手",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: os.Getenv("AGENTAPI_MODEL_ID"),
	},
	System: anthropic.String("你是一名简洁、准确的天气助手。"),
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfCustom: &anthropic.BetaManagedAgentsCustomToolParams{
			Type:        anthropic.BetaManagedAgentsCustomToolParamsTypeCustom,
			Name:        "get_weather",
			Description: "查询城市当前的天气。",
			InputSchema: anthropic.BetaManagedAgentsCustomToolInputSchemaParam{
				Properties: map[string]any{
					"city": map[string]any{"type": "string"},
				},
				Required: []string{"city"},
			},
		},
	}},
}, option.WithJSONSet("runtime", "native"))
if err != nil {
	panic(err)
}
environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
	Name: "weather-env",
	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
		OfCloud: &anthropic.BetaCloudConfigParams{
			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
				OfUnrestricted: &anthropic.BetaUnrestrictedNetworkParam{},
			},
		},
	},
})
if err != nil {
	panic(err)
}

session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
			Type:    anthropic.BetaManagedAgentsAgentParamsTypeAgent,
			ID:      agent.ID,
			Version: anthropic.Int(agent.Version),
		},
	},
	EnvironmentID: environment.ID,
})
if err != nil {
	panic(err)
}

getWeather := func(city string) string {
	return fmt.Sprintf("%s：18°C，晴", city)
}

stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
defer stream.Close()

_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
					Text: "东京天气怎么样？",
				},
			}},
		},
	}},
})
if err != nil {
	panic(err)
}

loop:
for stream.Next() {
	event := stream.Current()
	switch event.Type {
	case "agent.message":
		for _, block := range event.AsAgentMessage().Content {
			if block.Type == "text" {
				fmt.Println(block.Text)
			}
		}
	case "agent.custom_tool_use":
		toolUse := event.AsAgentCustomToolUse()
		result := getWeather(toolUse.Input["city"].(string))
		if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
			Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
				OfUserCustomToolResult: &anthropic.BetaManagedAgentsUserCustomToolResultEventParams{
					Type:            anthropic.BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult,
					CustomToolUseID: toolUse.ID,
					Content: []anthropic.BetaManagedAgentsUserCustomToolResultEventParamsContentUnion{{
						OfText: &anthropic.BetaManagedAgentsTextBlockParam{
							Type: anthropic.BetaManagedAgentsTextBlockTypeText,
							Text: result,
						},
					}},
				},
			}},
		}); err != nil {
			panic(err)
		}
	case "session.status_idle":
		idle := event.AsSessionStatusIdle()
		if _, ok := idle.StopReason.AsAny().(anthropic.BetaManagedAgentsSessionEndTurn); ok {
			break loop
		}
	}
}
if err := stream.Err(); err != nil {
	panic(err)
}
```

Java

```java
import java.util.Map;
import java.util.function.Function;

import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.agents.AgentCreateParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsCustomToolInputSchema;
import com.anthropic.models.beta.agents.BetaManagedAgentsCustomToolParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsModelConfigParams;
import com.anthropic.models.beta.environments.BetaCloudConfigParams;
import com.anthropic.models.beta.environments.BetaUnrestrictedNetwork;
import com.anthropic.models.beta.environments.EnvironmentCreateParams;
import com.anthropic.models.beta.sessions.BetaManagedAgentsAgentParams;
import com.anthropic.models.beta.sessions.SessionCreateParams;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsStreamSessionEvents;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserCustomToolResultEventParams;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams;
import com.anthropic.models.beta.sessions.events.EventSendParams;

var client = AnthropicOkHttpClient.builder()
    .apiKey(System.getenv("AGENTAPI_API_KEY"))
    .baseUrl(System.getenv("AGENTAPI_BASE_URL"))
    .build();

var agent = client.beta().agents().create(AgentCreateParams.builder()
        .putAdditionalBodyProperty("runtime", com.anthropic.core.JsonValue.from("native"))
    .name("天气助手")
    .model(BetaManagedAgentsModelConfigParams.builder().id(System.getenv("AGENTAPI_MODEL_ID")).build())
    .system("你是一名简洁、准确的天气助手。")
    .addTool(BetaManagedAgentsCustomToolParams.builder()
        .type(BetaManagedAgentsCustomToolParams.Type.CUSTOM)
        .name("get_weather")
        .description("查询城市当前的天气。")
        .inputSchema(BetaManagedAgentsCustomToolInputSchema.builder()
            .properties(BetaManagedAgentsCustomToolInputSchema.Properties.builder()
                .putAdditionalProperty("city", JsonValue.from(Map.of("type", "string")))
                .build())
            .addRequired("city")
            .build())
        .build())
    .build());
var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
    .name("weather-env")
    .config(BetaCloudConfigParams.builder()
        .networking(BetaUnrestrictedNetwork.builder().build())
        .build())
    .build());

var session = client.beta().sessions().create(SessionCreateParams.builder()
    .agent(BetaManagedAgentsAgentParams.builder()
        .type(BetaManagedAgentsAgentParams.Type.AGENT)
        .id(agent.id())
        .version(agent.version())
        .build())
    .environmentId(environment.id())
    .build());

Function<String, String> getWeather = city -> city + "：18°C，晴";

try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
    client.beta().sessions().events().send(
        session.id(),
        EventSendParams.builder()
            .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
                .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
                .addTextContent("东京天气怎么样？")
                .build())
            .build());

    for (var event : (Iterable<BetaManagedAgentsStreamSessionEvents>) stream.stream()::iterator) {
        if (event.isAgentMessage()) {
            for (var block : event.asAgentMessage().content()) {
                block.text().ifPresent(textBlock -> IO.println(textBlock.text()));
            }
        } else if (event.isAgentCustomToolUse()) {
            var toolUse = event.asAgentCustomToolUse();
            var city = toolUse.input()._additionalProperties().get("city").asStringOrThrow();
            var result = getWeather.apply(city);
            client.beta().sessions().events().send(
                session.id(),
                EventSendParams.builder()
                    .addEvent(BetaManagedAgentsUserCustomToolResultEventParams.builder()
                        .type(BetaManagedAgentsUserCustomToolResultEventParams.Type.USER_CUSTOM_TOOL_RESULT)
                        .customToolUseId(toolUse.id())
                        .addTextContent(result)
                        .build())
                    .build());
        } else if (event.isSessionStatusIdle()
            && event.asSessionStatusIdle().stopReason().isEndTurn()) {
            break;
        }
    }
}
```

PHP

```php
use Anthropic\Client;
use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolInputSchema;
use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolParams;
use Anthropic\Beta\Sessions\BetaManagedAgentsAgentParams;

$client = new Client(
    apiKey: getenv('AGENTAPI_API_KEY') ?:
        throw new RuntimeException('AGENTAPI_API_KEY is required'),
    baseUrl: getenv('AGENTAPI_BASE_URL') ?:
        throw new RuntimeException('AGENTAPI_BASE_URL is required'),
);

$agent = $client->beta->agents->create(
    name: '天气助手',
    model: ['id' => getenv('AGENTAPI_MODEL_ID')],
    system: '你是一名简洁、准确的天气助手。',
    tools: [
        BetaManagedAgentsCustomToolParams::with(
            type: 'custom',
            name: 'get_weather',
            description: '查询城市当前的天气。',
            inputSchema: BetaManagedAgentsCustomToolInputSchema::with(
                properties: ['city' => ['type' => 'string']],
                required: ['city'],
            ),
        ),
    ],
    requestOptions: ['extraBodyParams' => ['runtime' => 'native']],
);
$environment = $client->beta->environments->create(
    name: 'weather-env',
    config: ['type' => 'cloud', 'networking' => ['type' => 'unrestricted']],
);

$session = $client->beta->sessions->create(
    agent: BetaManagedAgentsAgentParams::with(
        type: 'agent',
        id: $agent->id,
        version: $agent->version,
    ),
    environmentID: $environment->id,
);

function getWeather(string $city): string
{
    return "{$city}：18°C，晴";
}

$stream = $client->beta->sessions->events->streamStream($session->id);

$client->beta->sessions->events->send(
    $session->id,
    events: [
        [
            'type' => 'user.message',
            'content' => [['type' => 'text', 'text' => "东京天气怎么样？"]],
        ],
    ],
);

foreach ($stream as $event) {
    if ($event->type === 'agent.message') {
        foreach ($event->content as $block) {
            if ($block->type === 'text') {
                echo $block->text . "\n";
            }
        }
    } elseif ($event->type === 'agent.custom_tool_use') {
        $result = getWeather($event->input['city']);
        $client->beta->sessions->events->send(
            $session->id,
            events: [
                [
                    'type' => 'user.custom_tool_result',
                    'custom_tool_use_id' => $event->id,
                    'content' => [['type' => 'text', 'text' => $result]],
                ],
            ],
        );
    } elseif ($event->type === 'session.status_idle' && $event->stopReason?->type === 'end_turn') {
        break;
    }
}
$stream->close();
```

Ruby

```ruby
require "anthropic"

client = Anthropic::Client.new(
  api_key: ENV.fetch("AGENTAPI_API_KEY"),
  base_url: ENV.fetch("AGENTAPI_BASE_URL")
)

agent = client.beta.agents.create(
  name: "天气助手",
  model: {id: ENV.fetch("AGENTAPI_MODEL_ID")},
  system_: "你是一名简洁、准确的天气助手。",
  tools: [
    {
      type: "custom",
      name: "get_weather",
      description: "查询城市当前的天气。",
      input_schema: {
        type: "object",
        properties: {city: {type: "string"}},
        required: ["city"]
      }
    }
  ],
  request_options: {extra_body: {runtime: "native"}}
)
environment = client.beta.environments.create(
  name: "weather-env",
  config: {type: "cloud", networking: {type: "unrestricted"}}
)

session = client.beta.sessions.create(
  agent: {type: "agent", id: agent.id, version: agent.version},
  environment_id: environment.id
)

def get_weather(city)
  "#{city}：18°C，晴"
end

stream = client.beta.sessions.events.stream_events(session.id)
client.beta.sessions.events.send_(
  session.id,
  events: [{type: "user.message", content: [{type: "text", text: "东京天气怎么样？"}]}]
)

stream.each do |event|
  case event.type
  when :"agent.message"
    event.content.each do |block|
      puts block.text if block.type == :text
    end
  when :"agent.custom_tool_use"
    result = get_weather(event.input[:city])
    client.beta.sessions.events.send_(
      session.id,
      events: [
        {
          type: "user.custom_tool_result",
          custom_tool_use_id: event.id,
          content: [{type: "text", text: result}]
        }
      ]
    )
  when :"session.status_idle"
    break if event.stop_reason&.type == :end_turn
  end
end
```

智能体和云端环境创建后可在多个会话中复用。自定义工具函数仍在应用进程中运行。迁移后，应用通过读取 `agent.custom_tool_use` 事件并返回工具结果参与执行，模型调用循环由 AgentAPI 管理。

### 业务逻辑保留范围 [#业务逻辑保留范围]

迁移到云端智能体循环后，以下与应用业务相关的逻辑仍需要保留：

| 原有逻辑                | AgentAPI 中的处理方式                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 消息输入和输出转换           | 在发送 `user.message` 前或接收 `agent.message` 后，由应用继续完成格式转换和业务处理。                                                                  |
| 自定义工具前后的校验或审计       | 在处理 `agent.custom_tool_use` 和发送 `user.custom_tool_result` 时执行。对于 `native` 内置工具，可使用 `permission_policy: always_ask` 在执行前请求确认。 |
| LangChain 检查点中的业务状态 | 将业务状态保留在应用自己的存储中；会话消息和执行事件由 AgentAPI 保存。                                                                                     |
| 循环次数或业务超时限制         | 由应用根据事件和时间进行控制，必要时发送 `user.interrupt` 中断当前任务。                                                                                |

## 迁移清单 [#迁移清单]

1. [创建一个云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)，配置任务所需的软件包；使用 `limited` 网络时，放行 MCP 服务和软件源的实际主机。
2. 将系统提示、模型、运行时和工具配置迁移到[智能体定义](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)中，并保存返回的版本号。
3. 使用明确的智能体版本创建会话。传入智能体 ID 字符串时，只会在创建会话时解析并固定最新版本；已有会话不会随智能体更新切换。
4. 使用 [`sessions.create`](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session) 和 [`sessions.events.stream`](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events) 替换原有的智能体循环。客户端必须处理历史事件回放、`requires_action`、`interrupted`、`retries_exhausted` 和 `terminated`。
5. 智能体需要读取本地文件时，通过 [Files API](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files) 上传文件，并将其作为 `resources` 挂载到会话中。
6. 将自定义工具处理程序接入事件循环，用于响应 `agent.custom_tool_use` 事件并返回结果；`claudecode`、`codex` 还需要服务端已配置自定义工具桥接；本页自定义工具示例选择 `native`，直接通过事件回传结果。
7. 用同一批任务对比旧系统与 AgentAPI 的事件、产物和失败恢复；业务状态仍保留在应用自己的存储中。
8. 在将生产流量指向新流程之前，先用测试会话进行验证，并为调度任务设计业务幂等键。

## 更新智能体使用的模型 [#更新智能体使用的模型]

需要切换模型或模型版本时，更新[智能体定义](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)中的 `model` 即可。更新会生成新的智能体版本；新建会话时引用该版本，现有会话仍然使用创建时固定的智能体版本。

下面将目标模型 ID 保存在 `AGENTAPI_MODEL_ID` 中。请先在[七牛 MaaS 模型管理页](https://portal.qiniu.com/ai-inference/model)确认账户和区域可用的模型，再设置该变量。

cURL

```bash
curl --request POST "$AGENTAPI_BASE_URL/v1/agents/$AGENT_ID" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  --data "$(jq -n --argjson version "$AGENT_VERSION" --arg model "$AGENTAPI_MODEL_ID" \
    '{version: $version, model: {id: $model}}')"
```

Python

```python
client.beta.agents.update(
    agent.id,
    version=agent.version,
    model={"id": os.environ["AGENTAPI_MODEL_ID"]},
)
```

TypeScript

````typescript
await client.beta.agents.update(agent.id, {
  version: agent.version,
  model: { id: process.env.AGENTAPI_MODEL_ID! }
});
```csharp
```csharp
await client.Beta.Agents.Update(agent.ID, new()
{
    Version = agent.Version,
    Model = new BetaManagedAgentsModelConfigParams
    {
        ID = System.Environment.GetEnvironmentVariable("AGENTAPI_MODEL_ID")
            ?? throw new InvalidOperationException("AGENTAPI_MODEL_ID is required"),
    },
});
````

Go

```go
_, err = client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
	Version: agent.Version,
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: os.Getenv("AGENTAPI_MODEL_ID"),
	},
})
if err != nil {
	panic(err)
}
```

Java

```java
client.beta().agents().update(
    agent.id(),
    AgentUpdateParams.builder()
        .version(agent.version())
        .model(BetaManagedAgentsModelConfigParams.builder()
            .id(System.getenv("AGENTAPI_MODEL_ID"))
            .build())
        .build()
);
```

PHP

```php
$client->beta->agents->update(
    $agent->id,
    version: $agent->version,
    model: ['id' => getenv('AGENTAPI_MODEL_ID')],
);
```

Ruby

```ruby
client.beta.agents.update(
  agent.id,
  version: agent.version,
  model: {id: ENV.fetch("AGENTAPI_MODEL_ID")}
)
```

更新模型时，还需要注意以下差异：

* 模型行为： 不同模型的工具选择、输出风格和任务完成效果可能不同，切换前应使用测试会话验证关键任务。
* 请求参数： 模型请求由 AgentAPI 在智能体循环中发起。应用无需在每一轮请求中重复设置 `max_tokens` 或推理参数。
* 会话输入： AgentAPI 使用事件驱动的会话模型，不支持通过预填充助手消息来约束下一段输出。
* 工具参数： `agent.custom_tool_use` 事件提供结构化的工具输入，应用无需自行解析原始 JSON 字符串。


# 基本概念 (/products/agentapi/product_introduction/13583-agentapi-concepts)



最近更新时间: 2026-10-13 15:30:58

AgentAPI 通过智能体与环境保存可复用配置，通过会话与事件管理具体任务的执行和交互。

## 智能体（Agent） [#智能体agent]

智能体是一份可复用的行为配置，包含运行时、模型、系统提示、工具和技能等内容，用于定义角色、规则和可用能力。创建智能体只保存配置，任务在会话中执行；同一个智能体可以供多个会话使用。配置发生变化时生成新版本。详见[创建与管理智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)。

## 运行时与模型 [#运行时与模型]

运行时（`runtime`）组织模型调用与工具执行，模型（`model`）负责推理与生成，两者分别配置在智能体上。AgentAPI 支持 `claudecode`、`codex` 和 `native`：前两者分别由 Claude Code SDK 与 Codex 执行引擎驱动，Native 由 AgentAPI 管理执行循环。运行时会影响工具能力和执行方式，模型需选择当前账户与区域可调用的型号。详见[运行时和模型](/products/agentapi/development_guidelines/agentapi-agent-configuration/13589-agentapi-agent-configuration-runtime-and-models)。

## 工具与技能 [#工具与技能]

[工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)提供文件读写、代码执行或外部服务调用等操作能力；[技能（Agent Skills）](/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills)保存可复用的工作说明和辅助文件，例如分析步骤或报告规范。工具决定能够执行哪些操作，技能指导如何完成任务。技能中的脚本仍需相应工具和环境依赖才能运行。

## 环境与沙箱 [#环境与沙箱]

环境是一份可复用的执行配置，定义工具所需的软件包、网络等条件，在创建会话时引用。沙箱是会话执行文件和代码操作的实际工作空间。多个会话可以共用云端环境配置，各自使用独立沙箱，文件系统状态不会共享。详见[配置云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)；使用自有执行资源时，见[自托管执行器](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

## 会话与执行轮次 [#会话与执行轮次]

会话保存一个任务的输入、输出、工具活动和交互历史，引用固定的智能体版本与环境。向会话发送消息后开始执行，一次由输入触发的执行称为轮次（Turn），可以包含多次模型请求和工具调用。同一任务的补充与修订可继续使用原会话，独立任务应创建新会话；已有会话不会随智能体更新而切换版本。详见[创建会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)。

## 事件与任务结果 [#事件与任务结果]

事件记录用户输入、智能体回答、工具活动和状态变化。应用可以查询事件历史，或通过事件流（SSE）实时观察进度。提交输入成功表示任务已接收；会话进入 `idle` 表示当前执行已停止，仍需结合停止原因、回答和产物判断任务结果。详见[事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)。

## 配置与任务的关系 [#配置与任务的关系]

![应用通过 Portal 或 API 提交任务；会话引用智能体版本与环境，并通过事件返回执行记录](/docs-assets/products/agentapi/product_introduction/13583-agentapi-concepts/FsLKckGhC3SggayLZ2pj9q9GdSxr-30b532f10481.webp)

具体操作见[在 Portal 中构建](/products/agentapi/quick_start/13586-agentapi-portal)或[通过 API 构建](/products/agentapi/quick_start/13587-agentapi-quickstart)。


# 产品概述 (/products/agentapi/product_introduction/13584-agentapi-overview)



最近更新时间: 2026-10-14 11:36:18

AgentAPI 是在托管环境中运行的可配置智能体框架。适合长时间运行的任务和异步工作。

## 使用方式 [#使用方式]

AgentAPI 支持 Portal 可视化使用和 API 方式使用，两种方式都可以配置智能体、运行任务并查看结果。

| 使用方式       | 适用场景                                                                                                 | 入门指南                                                                  |
| ---------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Portal 可视化 | 快速上手，或无需编写代码即可配置、测试和调整智能体。                                                                           | [在 Portal 中构建](/products/agentapi/quick_start/13586-agentapi-portal)  |
| API        | 将 AgentAPI 集成到自有智能体产品或业务系统，通过代码管理配置、提交任务并处理结果。支持直接发送 HTTP 请求或使用 SDK。API 兼容 Claude Managed Agents 协议。 | [通过 API 构建](/products/agentapi/quick_start/13587-agentapi-quickstart) |

可以先在 Portal 验证配置，再在代码中引用已有智能体和环境。

## 采用条件 [#采用条件]

适用于需要以下能力的任务：

* **长时间运行的执行**： 运行数分钟或数小时、涉及多次工具调用的任务
* **云基础设施**： 预装软件包并具备网络访问能力的安全沙箱
* **自托管执行**： 在您控制的基础设施上运行沙箱，以满足合规性或数据驻留要求
* **最少的基础设施**： 无需自行构建智能体循环、沙箱或工具执行层
* **有状态会话**： 跨多次交互持久保存的文件系统和对话历史
* **定时执行**： 通过定时部署按 cron 计划定期运行智能体

产品的配置对象、会话关系和任务执行流程见[基本概念](/products/agentapi/product_introduction/13583-agentapi-concepts)。

## 应用责任 [#应用责任]

AgentAPI 管理执行过程；应用校验业务用户与资源归属，保存任务与会话的关联，处理业务工具和审批，并验收结果。自托管模式下，worker 的运行、隔离与清理由部署方负责。


# 接入准备 (/products/agentapi/quick_start/13585-agentapi-access)



最近更新时间: 2026-10-16 10:13:03

开始调用 AgentAPI 前，先在七牛 Portal 创建 API Key，再根据所在区域选择服务地址。

## 创建 API Key [#创建-api-key]

1. 打开[七牛 Portal 的 AgentAPI 页面](https://portal.qiniu.com/agentapi)。
2. 在 API Key 设置中创建 Key。Portal 会创建七牛 MaaS（大模型推理服务）的 API Key，并自动绑定到当前 AgentAPI 账户。
3. 将创建的 Key 用于后续 API 请求。同一账户可以保留多个已绑定的 Key，分别用于不同应用。

> 更换 API Key
>
> 先在 Portal 创建新 Key，再替换客户端的 Key；确认切换完成后，再停用或删除旧 Key。创建新 Key 不会覆盖已有绑定。Portal 中删除 Key 会同时删除 MaaS API Key 和 AgentAPI 绑定记录，其他 Key 不受影响。
>
> 停用 MaaS API Key 不会自动解除 AgentAPI 绑定。AgentAPI 鉴权当前仅检查绑定记录，因此不能以停用操作确认旧 Key 已失去 AgentAPI 访问权限；需要撤销访问时，应在 Portal 删除旧 Key。

请勿将真实 Key 写入代码、文档或版本库。本文使用环境变量占位符。

## 选择服务区域 [#选择服务区域]

AgentAPI 当前提供两个服务入口：

| 区域 | 服务地址                         |
| -- | ---------------------------- |
| 华东 | `https://agent.qiniuapi.com` |
| 美西 | `https://agent.sufy.com`     |

> 区域数据独立
>
> 不同区域的资源与数据彼此独立，不跨区域共享。在某一区域创建的智能体、环境、会话和文件等资源，应通过该区域的服务地址访问。切换 Portal 地域或 API 服务地址不会迁移已有资源与数据。

通用示例使用 `AGENTAPI_BASE_URL`，请根据所在区域和 Portal 中可用的模型权限设置服务地址。

## 配置环境变量 [#配置环境变量]

```bash
export AGENTAPI_BASE_URL="https://your-agentapi-endpoint"
export AGENTAPI_API_KEY="your-maas-api-key"
export AGENTAPI_MODEL_ID="your-model-id"
```

> 选择模型
>
> `AGENTAPI_MODEL_ID` 必须替换为当前账户和区域可用的模型 ID。请前往[七牛 MaaS 模型管理页](https://portal.qiniu.com/ai-inference/model)获取模型 ID，并确认所用 Key 可调用该模型。

## 验证鉴权 [#验证鉴权]

```bash
curl --request GET "$AGENTAPI_BASE_URL/v1/agents" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

请求 JSON 接口时，同时设置 `content-type: application/json`。AgentAPI 使用七牛 MaaS API Key，并通过 `x-api-key` 请求头鉴权。

## 常见问题 [#常见问题]

| 现象          | 检查项                          |
| ----------- | ---------------------------- |
| `401`       | Key 是否填写正确，是否已在 Portal 绑定    |
| 模型不可用       | 模型是否属于当前账户和区域，是否具备使用权限       |
| 请求地址错误      | `AGENTAPI_BASE_URL` 是否对应所选区域 |
| 更换 Key 后仍失败 | 新 Key 是否已绑定，是否处于启用状态         |

准备完成后，继续阅读[通过 API 构建](/products/agentapi/quick_start/13587-agentapi-quickstart)。


# 在 Portal 中构建 (/products/agentapi/quick_start/13586-agentapi-portal)



最近更新时间: 2026-10-13 15:31:05

[AgentAPI Portal](https://portal.qiniu.com/agentapi) 适合快速上手，以及无需编写代码即可配置、测试和调整智能体的场景。通过可视化界面选择配置、发送任务并查看结果，也可以先验证配置，再通过 API 接入应用。首次使用时，按页面引导创建 API Key；地域与鉴权说明见[接入准备](/products/agentapi/quick_start/13585-agentapi-access)。

## 配置智能体 [#配置智能体]

从“快速开始”选择模板，或在“Agent”页面创建智能体，配置以下内容：

* 运行时、模型和系统提示词：选择执行引擎与模型，定义任务要求和输出约束。
* 工具和 MCP：配置内置工具、自定义工具或远程 MCP 服务；所需凭证在创建会话时关联。
* 技能：附加已上传的技能，复用任务说明和辅助文件。

再选择或创建环境，设置运行方式、网络与软件依赖。资源页面提供“API 调用示例”，便于将已验证的配置用于代码。

## 测试智能体 [#测试智能体]

“快速开始”按创建智能体、配置环境、创建会话、发送消息四步完成一次测试。也可以在“会话”页面引用已有智能体和环境，新建测试会话。

发送消息后，在会话详情的“对话”中查看回答与工具调用，“轨迹”中检查事件和停止原因，“文件”中下载产物；需要完整记录时，使用“Raw JSONL”导出。

会话空闲只表示当前执行停止，仍需核对回答和产物是否符合任务要求。调整智能体后，创建新会话验证新版本。

## 在代码中复用配置 [#在代码中复用配置]

配置验证通过后：

1. 从 Portal 记录智能体 ID、版本和环境 ID。
2. 在应用中[创建会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)时引用这些配置，使用同一地域的服务地址和已绑定 Key。
3. 按[通过 API 构建](/products/agentapi/quick_start/13587-agentapi-quickstart)中的 HTTP 或 SDK 方式，在代码中发送任务并获取结果。

## 配置 Webhook 通知 [#配置-webhook-通知]

在“服务设置 → Webhook”中为当前地域创建通知端点、选择事件，并保存一次性签名密钥。随后可在列表管理订阅、启停和密钥轮换；“API Key”入口独立管理模型调用凭证。租户身份由服务端自动维护，无需填写内部 ID。接收服务的验签、可靠确认及失败恢复见 [Webhook 通知](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13605-agentapi-data-and-integrations-webhooks)。


# 通过 API 构建 (/products/agentapi/quick_start/13587-agentapi-quickstart)



最近更新时间: 2026-10-13 15:31:07

API 方式适合将 AgentAPI 集成到自有智能体产品或业务系统，通过代码管理配置、自动提交任务，并把回答、执行进度和文件产物用于业务流程。

可以直接发送 HTTP 请求，也可以使用 SDK调用相同接口。两种方式都围绕智能体、环境、会话和事件完成任务；SDK 部分说明客户端初始化和 AgentAPI 扩展字段的传入方式。

下面的 HTTP 示例完成一次文件生成任务：创建配置与会话、发送任务、读取事件，再下载并核对前 20 个斐波那契数。完成标志是本地拿到内容正确的 `fibonacci.txt`。已在 Portal 验证的配置可以直接复用，创建会话时引用已有智能体 ID、版本和环境 ID。

![AgentAPI 从接入到事件的快速开始流程](/docs-assets/products/agentapi/quick_start/13587-agentapi-quickstart/Fluovb9iJZdUaLQ3_YNHj3Orn3nJ-ee3cc2b1373c.webp)

## 前提条件 [#前提条件]

* 已完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)
* `AGENTAPI_BASE_URL`、`AGENTAPI_API_KEY` 和 `AGENTAPI_MODEL_ID` 已设置

## 使用 HTTP [#使用-http]

以下示例需要 Bash、`curl` 和 `jq`，在同一个 Bash 终端中依次执行。

```bash
set -euo pipefail

: "${AGENTAPI_BASE_URL:?请先设置 AGENTAPI_BASE_URL}"
: "${AGENTAPI_API_KEY:?请先设置 AGENTAPI_API_KEY}"
: "${AGENTAPI_MODEL_ID:?请先设置 AGENTAPI_MODEL_ID}"
```

### 创建智能体 [#创建智能体]

示例使用 `claudecode`、云端环境和内置工具集，任务不需要第三方凭证或额外网络访问。需要其他执行引擎或应用参与工具调用时，先按[运行时和模型](/products/agentapi/development_guidelines/agentapi-agent-configuration/13589-agentapi-agent-configuration-runtime-and-models)选择配置。

```bash
agent=$(curl --request POST --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/agents" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
  "name": "快速开始助手",
  "runtime": "claudecode",
  "model": {"id": "$AGENTAPI_MODEL_ID"},
  "system": "你是一名编程助手，请完成用户任务并说明结果。",
  "tools": [{"type": "agent_toolset_20260401"}]
}
EOF
)

AGENT_ID=$(jq -er '.id' <<<"$agent")
AGENT_VERSION=$(jq -er '.version' <<<"$agent")
```

### 创建云端环境 [#创建云端环境]

```bash
environment=$(curl --request POST --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/environments" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "name": "quickstart-environment",
    "config": {
      "type": "cloud",
      "networking": {"type": "limited", "allowed_hosts": []}
    }
  }')

ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")
```

### 创建会话 [#创建会话]

```bash
session=$(curl --request POST --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/sessions" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
  "agent": {"type": "agent", "id": "$AGENT_ID", "version": $AGENT_VERSION},
  "environment_id": "$ENVIRONMENT_ID",
  "title": "快速开始会话"
}
EOF
)

SESSION_ID=$(jq -er '.id' <<<"$session")
```

### 发送任务并读取事件 [#发送任务并读取事件]

在后台订阅 SSE，再发送 `user.message`。流会回放历史，因此连接建立稍晚也能读到已保存的事件。用户消息的结构化内容使用 `input.parts`。

脚本保存本次输入的事件 ID，只接受该输入之后的停止事件，避免把创建会话时的空闲状态当作完成。它检查事件历史，不依赖轮询恰好看到短暂的 `running` 状态。

```bash
EVENT_LOG=$(mktemp)
curl --fail-with-body --silent --show-error --no-buffer \
  "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events/stream" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  >"$EVENT_LOG" &
STREAM_PID=$!
trap 'kill "$STREAM_PID" 2>/dev/null || true; wait "$STREAM_PID" 2>/dev/null || true; rm -f "$EVENT_LOG"' EXIT

accepted=$(curl --request POST --fail-with-body --silent --show-error \
  "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "events": [
      {
        "type": "user.message",
        "input": {
          "parts": [
            {"type": "text", "text": "从 0、1 开始生成前 20 个斐波那契数，将这 20 个整数按每行一个的格式保存到 /mnt/session/outputs/fibonacci.txt，作为可下载文件，不添加标题或其他文字。"}
          ]
        }
      }
    ]
  }')
INPUT_EVENT_ID=$(jq -er '.data[0].id' <<<"$accepted")

stop_event=""
for _ in $(seq 1 120); do
  events=$(jq -Rsc 'split("\n") | map(
    select(startswith("data: ")) | ltrimstr("data: ") | fromjson?
  )' "$EVENT_LOG")
  input_sequence=$(jq -r --arg id "$INPUT_EVENT_ID" '
    [.[] | select(.id == $id and .processed_at != null) | .sequence_number]
    | first // empty
  ' <<<"$events")
  if [[ -n "$input_sequence" ]]; then
    stop_event=$(jq -c --argjson sequence "$input_sequence" '
      [.[] | select(.sequence_number > $sequence)
        | select(.type == "session.status_idle" or .type == "session.status_terminated")]
      | first // empty
    ' <<<"$events")
    [[ -n "$stop_event" ]] && break
  fi
  if ! kill -0 "$STREAM_PID" 2>/dev/null; then
    cat "$EVENT_LOG" >&2
    printf '事件连接已结束，请按会话 ID 恢复查询：%s\n' "$SESSION_ID" >&2
    exit 1
  fi
  sleep 1
done

kill "$STREAM_PID" 2>/dev/null || true
wait "$STREAM_PID" 2>/dev/null || true
jq '.[] | select(.type == "agent.message" or .type == "session.error")' <<<"$events"
rm -f "$EVENT_LOG"
trap - EXIT

[[ -n "$stop_event" ]] || {
  printf '120 秒内未确认本轮停止；保留会话继续查询，不要重复提交：%s\n' "$SESSION_ID" >&2
  exit 1
}
jq . <<<"$stop_event"
[[ $(jq -r '.type' <<<"$stop_event") == "session.status_idle" && \
   $(jq -r '.stop_reason.type' <<<"$stop_event") == "end_turn" ]] || {
  printf '本轮未正常结束，请先按停止原因处理，再验收产物。\n' >&2
  exit 1
}
```

本例是新建会话的一轮执行，等待上限为 120 秒。关闭本地 SSE 观察不会取消云端任务；超时后保留 `SESSION_ID`，通过 [Portal](https://portal.qiniu.com/agentapi) 或[事件历史](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)继续检查。生产应用应按[事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)恢复消费，并按[文件](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)的规则验收产物。

`end_turn` 只说明本轮结束，仍需下载验收文件。其他停止原因及后续处理见[执行结果判断](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)。

### 下载并验证结果 [#下载并验证结果]

会话文件可能在停止事件之后才收集完成。以下代码等待 `fibonacci.txt` 出现在文件列表中，再下载；本例只生成一个文件。较大任务应按[文件列表分页](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)读取全部结果。

```bash
FILE_ID=""
for _ in $(seq 1 10); do
  files=$(curl --fail-with-body --silent --show-error \
    "$AGENTAPI_BASE_URL/v1/files?scope_id=$SESSION_ID" \
    --header "x-api-key: $AGENTAPI_API_KEY")
  FILE_ID=$(jq -r '[.data[] | select(.filename == "fibonacci.txt")][0].id // empty' <<<"$files")
  [[ -n "$FILE_ID" ]] && break
  sleep 1
done
[[ -n "$FILE_ID" ]] || {
  printf 'fibonacci.txt 尚未收集完成，请检查输出路径、文件限额与会话事件。\n' >&2
  exit 1
}
curl --fail-with-body --silent --show-error \
  "$AGENTAPI_BASE_URL/v1/files/$FILE_ID/content" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --output fibonacci.txt
```

验证应将文件的每一行与预期序列比较。使用下面的命令完成内容验收：

```bash
jq -Rse '
  split("\n") | map(gsub("\r$"; ""))
  | if last == "" then .[:-1] else . end
  | . == ([0,1,1,2,3,5,8,13,21,34,55,89,144,233,377,610,987,1597,2584,4181]
    | map(tostring))
' fibonacci.txt
```

输出 `true` 且退出码为 0 表示文件包含正确的 20 行整数。验收失败时，查看回答与文件内容，在原会话补充要求后重新检查；不要仅因文件存在就判定成功。

### 清理示例资源 [#清理示例资源]

文件下载验收后，可以删除本页创建的会话、智能体与环境。会话删除会同时清理事件和会话作用域文件；如需保留历史，改用[归档会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13598-agentapi-sessions-and-tasks-session-lifecycle)。

```bash
curl --request DELETE --fail-with-body --silent --show-error \
  "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID" --header "x-api-key: $AGENTAPI_API_KEY"
curl --request DELETE --fail-with-body --silent --show-error \
  "$AGENTAPI_BASE_URL/v1/agents/$AGENT_ID" --header "x-api-key: $AGENTAPI_API_KEY"
curl --request DELETE --fail-with-body --silent --show-error \
  "$AGENTAPI_BASE_URL/v1/environments/$ENVIRONMENT_ID" --header "x-api-key: $AGENTAPI_API_KEY"
```

业务系统中复用的智能体与环境应按自身保留策略管理；这里的删除操作只用于本页专门创建的示例资源。

## 使用 SDK [#使用-sdk]

AgentAPI 的智能体、环境、会话和事件接口可以使用 Anthropic SDK 调用。客户端放在应用服务端，显式配置 AgentAPI 服务地址和已绑定的 MaaS API Key。

### 请求配置 [#请求配置]

| 配置      | 注意事项                                                                                                     |
| ------- | -------------------------------------------------------------------------------------------------------- |
| 服务地址    | 将 `base_url`、`baseURL` 或对应语言的选项设为 `AGENTAPI_BASE_URL`，使用所选区域的 AgentAPI 服务根地址，不附加 `/v1`。SDK 的资源方法会拼接接口路径。 |
| API Key | 将 `api_key`、`apiKey` 或对应选项设为 `AGENTAPI_API_KEY`，SDK 会通过 `x-api-key` 发送。Key 必须已在 Portal 绑定到 AgentAPI 账户。  |
| 模型      | 创建智能体时使用当前账户和区域可调用的模型 ID，示例从 `AGENTAPI_MODEL_ID` 读取。模型选择与 `runtime` 选择是两个独立字段。                           |

### 获取 SDK [#获取-sdk]

按所用语言安装依赖，软件包、安装命令和官方源码入口见[SDK 下载](/products/agentapi/sdk/13620-agentapi-sdk-download)。

### 初始化客户端 [#初始化客户端]

以下片段与专题中的调用代码放在同一作用域，按调用补充所需的类型导入。专题涉及的 `agent`、`environment`、`session` 等变量来自对应资源的创建或查询响应。

Python

```python
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["AGENTAPI_API_KEY"],
    base_url=os.environ["AGENTAPI_BASE_URL"],
)
```

TypeScript

````typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.AGENTAPI_API_KEY!,
  baseURL: process.env.AGENTAPI_BASE_URL,
});
```csharp
```csharp
using Anthropic;
using Anthropic.Core;

var client = new AnthropicClient(new ClientOptions
{
    ApiKey = System.Environment.GetEnvironmentVariable("AGENTAPI_API_KEY")
        ?? throw new InvalidOperationException("AGENTAPI_API_KEY is required"),
    BaseUrl = System.Environment.GetEnvironmentVariable("AGENTAPI_BASE_URL")
        ?? throw new InvalidOperationException("AGENTAPI_BASE_URL is required"),
});
````

Go

```go
import (
    "context"
    "os"

    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
)

client := anthropic.NewClient(
    option.WithoutEnvironmentDefaults(),
    option.WithBaseURL(os.Getenv("AGENTAPI_BASE_URL")),
    option.WithAPIKey(os.Getenv("AGENTAPI_API_KEY")),
)
ctx := context.Background()
```

Java

```java
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

var client = AnthropicOkHttpClient.builder()
    .apiKey(System.getenv("AGENTAPI_API_KEY"))
    .baseUrl(System.getenv("AGENTAPI_BASE_URL"))
    .build();
```

PHP

```php
use Anthropic\Client;

$client = new Client(
    apiKey: getenv('AGENTAPI_API_KEY') ?:
        throw new RuntimeException('AGENTAPI_API_KEY is required'),
    baseUrl: getenv('AGENTAPI_BASE_URL') ?:
        throw new RuntimeException('AGENTAPI_BASE_URL is required'),
);
```

Ruby

```ruby
require "anthropic"

client = Anthropic::Client.new(
  api_key: ENV.fetch("AGENTAPI_API_KEY"),
  base_url: ENV.fetch("AGENTAPI_BASE_URL")
)
```

### 传入扩展字段 [#传入扩展字段]

`runtime` 是创建和更新智能体时的 AgentAPI 扩展字段，取值为 `claudecode`、`codex` 或 `native`；创建时省略会使用 `claudecode`，建议按任务场景显式指定（见[运行时和模型](/products/agentapi/development_guidelines/agentapi-agent-configuration/13589-agentapi-agent-configuration-runtime-and-models)）。SDK 的类型未必声明该字段，需要通过扩展请求参数传入，使其出现在请求体顶层。

Python 使用 `extra_body`；TypeScript 通过第二个参数的 `body` 传入，需保留原请求字段。例如：

Python

```python
agent = client.beta.agents.create(
    name="编程助手",
    model={"id": os.environ["AGENTAPI_MODEL_ID"]},
    extra_body={"runtime": "claudecode"},
)
```

TypeScript

```typescript
const params = {
  name: "编程助手",
  model: { id: process.env.AGENTAPI_MODEL_ID! },
} satisfies Parameters<typeof client.beta.agents.create>[0];

const agent = await client.beta.agents.create(params, {
  body: { ...params, runtime: "claudecode" },
});
```

`agentapi_options` 同样通过扩展请求参数传入，具体配置见[智能体配置字段](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)。其他语言的扩展字段写法见[创建智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)。

按业务步骤使用[智能体创建](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)、[环境创建](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)、[会话创建](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)和[事件收发](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)中的 SDK 示例。HTTP 用户消息的结构化内容以 `input.parts` 为准，SDK 的兼容写法见[提交输入](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)；完整字段与限制以 [API 参考](/products/agentapi/api/13618-agentapi-api-conventions)为准。

## 后续步骤 [#后续步骤]

* [更换任务配置](/products/agentapi/development_guidelines/agentapi-agent-configuration/13589-agentapi-agent-configuration-runtime-and-models)：选择不同运行时、工具或执行环境。
* [事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)：恢复消费，判断停止原因并处理工具等待。
* [文件](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)：准备输入材料、下载并验收产物。


# SDK 下载 (/products/agentapi/sdk/13620-agentapi-sdk-download)



最近更新时间: 2026-10-13 17:21:25

AgentAPI 的智能体、环境、会话和事件接口可以使用 Anthropic SDK 调用。以下列出各语言的安装方式与官方源码入口。

| 语言                      | 安装方式                                                         | 官方源码                                                                               |
| ----------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| Python                  | `pip install anthropic`                                      | [anthropic-sdk-python](https://github.com/anthropics/anthropic-sdk-python)         |
| TypeScript / JavaScript | `npm install @anthropic-ai/sdk`                              | [anthropic-sdk-typescript](https://github.com/anthropics/anthropic-sdk-typescript) |
| Java（Gradle）            | `implementation("com.anthropic:anthropic-java:2.62.0")`      | [anthropic-sdk-java](https://github.com/anthropics/anthropic-sdk-java)             |
| Go                      | `go get github.com/anthropics/anthropic-sdk-go`              | [anthropic-sdk-go](https://github.com/anthropics/anthropic-sdk-go)                 |
| C#                      | `dotnet add package Anthropic`                               | [anthropic-sdk-csharp](https://github.com/anthropics/anthropic-sdk-csharp)         |
| Ruby                    | `bundle add anthropic`                                       | [anthropic-sdk-ruby](https://github.com/anthropics/anthropic-sdk-ruby)             |
| PHP                     | `composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7"` | [anthropic-sdk-php](https://github.com/anthropics/anthropic-sdk-php)               |

接入 AgentAPI 时，需要显式设置服务地址、已绑定的 MaaS API Key，并通过扩展请求参数传入 `runtime` 等 AgentAPI 字段。客户端初始化与接入注意事项见[通过 API 构建：使用 SDK](/products/agentapi/quick_start/13587-agentapi-quickstart)。


# 获取AI大模型推理API密钥令牌KEY🔑 (/products/aitokenapi/0-how-to-get-api-key)



最近更新时间: 2026-04-29 11:54:55

**🎉🎉 注册有奖活动：现在注册 `qiniu.com/ai` 开发者账号，立即获得 300万免费 Token 资源包！详见 [活动详情](/products/aitokenapi/0-ai-token-api-pricing)**
![编组.png](/docs-assets/products/aitokenapi/%280-manual%29/0-how-to-get-api-key/Fu7siL7La5ITV8gKacLyv9A8OekA-e1ee25cfbb09.webp)

## 方法一：用微信扫码“七牛云”小程序领取 [#方法一用微信扫码七牛云小程序领取]

**STEP 1** 用微信扫码，或搜索 `七牛云` 小程序，选择 “手机号快捷登录”
**STEP 2** 打开【我的】，选择【我的控制台】
**STEP 3** 然后即可创建新密钥、或复制已有 API密钥 🔑

> 注: `首次创建API密钥，即激活300万Token免费额度资源包`。
>
> 密钥可设置到环境变量 `OPENAI_API_KEY`(对应`OPENAI_BASE_URL=https://api.qnaigc.com/v1`)
> 也可以设置到 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`(对应`ANTHROPIC_BASE_URL=https://api.qnaigc.com`)
> 以及各种LLM兼容库的相应字段上使用。

## 方法二：登录到 `qiniu.com/ai` 控制台领取 [#方法二登录到-qiniucomai-控制台领取]

**STEP 1** 打开 [qiniu.com/ai](https://www.qiniu.com/ai/agent) 网站 [立即注册 和 登录账号](https://s.qiniu.com/umqq6n)
**STEP 2** 进入[【控制台 / AI大模型推理 / API Key】](https://portal.qiniu.com/ai-inference/api-key) 即可创建、或复制密钥。🔑

![image.png](/docs-assets/products/aitokenapi/%280-manual%29/0-how-to-get-api-key/FtYB-41OPzIiBMuyyzpihVzacKn5-c06175bca67c.webp)

**备注：**

* 在创建KEY时，请输入名称信息（即备注），有助于帮您记住使用该KEY的用途、业务场景、或者内部使用者标识等。
* 用户可以通过一个KEY查询该KEY的Token用量；也可以使用管理员AK/SK签名查询该账号下全部KEY的Token用量。参考[用量查询](/products/aitokenapi/0-how-to-get-api-key)
* 用户可以通过管理员AK/SK签名，调用API来批量创建不同KEYs （待发布）
  ![image.png](/docs-assets/products/aitokenapi/%280-manual%29/0-how-to-get-api-key/FpYzX_dW0tdMJQF_Ri_GFx7NMS73-93687cb8d2fa.webp)

🎉🎉 恭喜你，已经成功获取到了 API 密钥了


# 大模型Token价格与计费说明 (/products/aitokenapi/0-ai-token-api-pricing)



最近更新时间: 2026-04-29 18:22:42

## **上线活动** [#上线活动]

为了庆祝产品上线，现针对所有 AI 推理的新客户，**免费赠送**全系列共享 **300 万** tokens 资源包，现在就立刻体验吧!

* 领取条件：推理服务新用户，之前未使用过推理服务的账号
* 领取方式：使用服务并产生计费后自动发放，可能有 1 小时左右延迟
* 查看方式：前往[我的资源包](https://portal.qiniu.com/financial/orders/respack-mgr/all)可以查看资源包的过期时间和剩余额度
* 抵扣范围：具体抵扣范围请前往账号查看资源包详情，以资源包详情信息为准（特别注意：新模型进入资源包的抵扣时间会与模型上线有所延迟）
* 额度用完：免费资源包额度用完之后会自动转为按量价格对后续用量进行计费，请务必关注资源包的剩余额度和用量信息，避免产生意外费用。

关于融合资源包详细使用规则，请阅读：[资源包使用规则](/products/aitokenapi/1-fusion-resource-package)

## **计费方式** [#计费方式]

AI 推理服务采用**按量付费**模式，根据实际消耗进行计费，无需预付费用。

### **更新周期** [#更新周期]

* 预估账单：延迟15分钟左右，每天可以在预估账单中查看截止15分钟之前的账单
* 资源包剩余额度：延迟15分钟左右，每天可以在资源包管理中查看截止15分钟之前的资源包用量剩余额度信息

### **价格说明** [#价格说明]

不同模型的单价不同，具体价格请查看[模型广场页面](https://www.qiniu.com/ai/models)。价格可能会根据市场情况进行调整，请定期关注最新价格信息。

### **余额不足处理** [#余额不足处理]

* 当账户余额不足时，推理/生成等 API 调用将返回错误，服务将暂停
* 建议设置余额预警，及时充值以保证服务连续性，建议至少保证余额满足 3 天的消费。
* 可前往[财务中心](https://portal.qiniu.com/financial/overview)查看账户余额和消费明细

## **费用查询** [#费用查询]

您可以通过以下方式查询用量和费用信息:

* **账单汇总**:[财务中心 - 预估账单](https://portal.qiniu.com/financial/bills/estimated-consume)
* **用量统计**:[控制台 - 用量统计](https://portal.qiniu.com/ai-inference/usage)
* **请求日志**:[控制台 - 请求日志](https://portal.qiniu.com/ai-inference/request-log)
* **资源包**:[我的资源包](https://portal.qiniu.com/financial/orders/respack-mgr/all)

## **常见问题** [#常见问题]

### **如何避免超额消费?** [#如何避免超额消费]

* 设置账户余额预警，及时充值
* 设置资源包余量预警，及时查看
* 定期查看消费明细，监控使用情况

### **资源包如何使用?** [#资源包如何使用]

资源包会自动抵扣符合条件的用量，无需手动操作。具体使用规则请参考:[资源包使用规则](/products/aitokenapi/1-fusion-resource-package)


# AI大模型融合资源包使用规则 (/products/aitokenapi/1-fusion-resource-package)



最近更新时间: 2026-05-09 10:37:18

# 概述 [#概述]

AI大模型融合资源包**Token数是以DeepSeek-V3.1基准的数量，在使用其他模型时扣减Token数将基于不同价格按比例抵扣**（即用越贵的模型扣除倍数高、输出上下文比输入更长时扣除倍数高、用越便宜的模型扣除系数越低）。通过统一的抵扣标准，让您能够在不同价位的AI模型间自由切换，享受便捷的计费体验。请登录七牛云小程序或主站控制台及时查看Token消耗数、请求记录，也可以通过API查询Token实时用量。

# 使用规则 [#使用规则]

## 1. 价格比例抵扣机制 [#1-价格比例抵扣机制]

融合资源包以 **deepseek-v3.1** 模型的输入价格（**0.004元/千tokens**）作为基准标准，根据您实际使用模型的各种计费项按比例进行抵扣。

### 计算公式 [#计算公式]

```text
抵扣数量 = 模型计费项实际用量 × 资源包抵扣比例
```

其中：

* **资源包抵扣比例** = 目标模型计费项价格 ÷ deepseek-v3.1标准价格
* **deepseek-v3.1标准价格** = 0.004元/千tokens（输入价格基准）
* **目标模型计费项价格** = 您实际使用模型的对应计费项价格/千tokens

### 示例说明 [#示例说明]

#### 示例1：使用更实惠的模型 [#示例1使用更实惠的模型]

* 假设模型A的某个计费项价格为 0.002元/千tokens
* 您的实际使用量：10,000 tokens
* 抵扣比例计算：0.002 ÷ 0.004 = 0.5
* 实际抵扣：10,000 × 0.5 = 5,000 tokens
* 说明：由于模型A的该计费项价格比基准价格低50%，抵扣比例为0.5，更加经济实惠

#### 示例2：使用基准价格模型 [#示例2使用基准价格模型]

* 使用deepseek-v3.1模型输入（0.004元/千tokens）
* 您的实际使用量：10,000 tokens
* 抵扣比例计算：0.004 ÷ 0.004 = 1
* 实际抵扣：10,000 × 1 = 10,000 tokens
* 说明：基准价格模型按1:1比例抵扣，计费透明直观

#### 示例3：使用高性能模型 [#示例3使用高性能模型]

* 假设模型B的某个计费项价格为 0.060元/千tokens
* 您的实际使用量：10,000 tokens
* 抵扣比例计算：0.060 ÷ 0.004 = 15
* 实际抵扣：10,000 × 15 = 150,000 tokens
* 说明：由于模型B的该计费项价格比资源包基准价格高，抵扣倍数为15，适合高质量需求场景

#### 示例4：使用顶级模型 [#示例4使用顶级模型]

* 假设模型C的某个计费项价格为 0.108元/千tokens（约 $15/1MTok）
* 您的实际使用量：10,000 tokens
* 抵扣比例计算：0.108 ÷ 0.004 = 27
* 实际抵扣：10,000 × 27 = 270,000 tokens
* 说明：由于模型C的该计费项价格比基准价格贵27倍，导致资源包消耗较大，需要时刻关注余量。

## 2. 后续计费方式 [#2-后续计费方式]

当资源包余额用尽后，系统将自动切换至**按量计费**模式，继续按照各模型的实际计费项价格为您提供服务，确保业务连续性。

## 3. 数据更新周期 [#3-数据更新周期]

* **用量统计**：分钟级更新
* **账户余额更新**：5-10分钟后 更新
* **资源包余额更新**：5-10分钟后 更新

## 4. 资源包抵扣范围 [#4-资源包抵扣范围]

不同类型的融合资源包具有不同的模型抵扣范围和适用场景：

### 抵扣范围说明 [#抵扣范围说明]

* **通用融合包**：覆盖大部分主流AI模型，适合多样化使用需求
* **专业融合包**：针对特定领域或高性能模型，抵扣范围相对集中
* **基础融合包**：主要支持基础模型和常用功能，经济实惠

### 重要提醒 [#重要提醒]

⚠️ **对于已发放到账户的资源包，具体的抵扣比例和支持的模型范围以资源包详情页面显示的信息为准**

不同规格的资源包可能有以下差异：

* 支持的模型种类和数量
* 具体的抵扣比例设置
* 计费项覆盖范围（如输入、输出、特殊功能等）
* 使用期限和额度限制

注意：请参考第7节说明，查看实时Token用量。**超出资源包设定用量会产生费用账单，欠费将导致账号冻结**。

### 查看方式 [#查看方式]

对于已购买的资源包，请查看资源包详情页面的：

* **抵扣比例列表**：显示该资源包对各模型的具体抵扣比例
* **适用范围说明**：明确列出支持的模型和计费项
* **使用限制条件**：了解任何特殊的使用要求或限制

## 5. 抵扣比例查询 [#5-抵扣比例查询]

您可以随时查看具体的资源包抵扣比例：
**控制台 → 财务中心 → 订单管理 → 资源包管理**

![image.png](/docs-assets/products/aitokenapi/%281-buying-guide%29/1-fusion-resource-package/FhnmuXx5QxHpfEQ_J5Hcou9CpxL9-763a524eaebc.webp)

## 6. 使用优先级 [#6-使用优先级]

当您的账户同时拥有资源包和账户余额时：

1. **优先使用资源包**进行抵扣
2. 资源包用完后，**自动使用账户余额**按量计费
3. 无需手动切换，系统智能管理

## 7. 实际Token用量查询 [#7-实际token用量查询]

用户可登录控制台，在AI大模型推理控制台中查询用量：

* 在[控制台/AI大模型推理/API Key](https://portal.qiniu.com/ai-inference/api-key)中查询每个令牌(KEY)的近7天的用量
* 在[控制台/AI大模型推理/用量统计](https://portal.qiniu.com/ai-inference/usage)中查询所选定时段内每个模型ID、和每个KEY的用量
  ![image.png](/docs-assets/products/aitokenapi/%281-buying-guide%29/1-fusion-resource-package/FnD-LLXGeR1sQytBku5sYwuxnQTy-77485ac8cd90.webp)

# 注意事项 [#注意事项]

1. **有效期限制**：资源包有效期内未使用完的余额恕不退还，请合理规划使用
2. **资源包叠加**：不同规格的资源包可以叠加使用，灵活满足各种需求
3. **实时调整**：资源包抵扣比例会根据模型的具体计费项价格实时调整
4. **使用监控**：建议定期查看资源包使用情况，合理规划使用计划，避免浪费

# 常见问题 [#常见问题]

## 问: 为什么我看不到资源包？ [#问-为什么我看不到资源包]

**答:**

1. 首先须登录帐号，打开控制台左侧菜单AI大模型中[【创建API KEY】](/products/aitokenapi/0-how-to-get-api-key)（至少创建一个Key作为承载大模型Token资源包的载体）
2. 然后在控制台右上角[【财务中心/订单管理/资源包管理】](https://portal.qiniu.com/financial/orders/respack-mgr/current) 中查看奖励和发放的大模型资源包。

## 问: 为什么实际消耗与我的预期使用量不符？ [#问-为什么实际消耗与我的预期使用量不符]

**答:** 这是使用AI工具时的常见现象，主要原因包括：

### 主要原因 [#主要原因]

1. **工具上下文开销**：AI工具通常会自动携带大量上下文信息和工具参数，这些隐性内容都会计入token消耗
2. **Agent智能迭代**：类似 ReAct 的智能Agent会进行多轮思考和工具调用，每次迭代都会产生token消耗
3. **认知偏差**：您可能只输入了简短的问题（十几个token），但系统内部实际调用时可能需要处理上万甚至十几万token的上下文

### 典型场景 [#典型场景]

* **AI助手对话**：每次交互可能包含完整的历史对话记录、工具定义说明、系统提示词等
* **复杂任务执行**：Agent执行复杂任务时，需要多轮分析、规划和工具调用才能给出最终结果
* **代码智能生成**：代码生成工具需要分析大量项目上下文和相关代码才能提供准确建议

### 优化建议 [#优化建议]

* **查看明细**：在控制台的使用详情中查看具体的token消耗明细，了解实际用量分布
* **了解机制**：深入了解所使用AI工具的token计费机制和工作原理
* **合理控制**：适当控制对话历史长度和上下文范围，在功能性与成本间找到平衡

# 相关文档 [#相关文档]

如需了解更多资源包相关信息，请参考：[资源包功能介绍](/account/resource-package-management/0-the-resource-bundle-is-introduced)


# AI 大模型企业订阅产品说明 (/products/aitokenapi/2-subscription-introduction)



最近更新时间: 2026-06-01 11:12:00

欢迎使用我们的 AI 大模型企业订阅服务！

我们专为企业用户打造了一站式 AI 推理订阅方案，现已全面升级。<br /> 服务覆盖主流大模型能力（通用对话、代码生成、推理增强、多模态等）; <br /> 支持多家领先模型与版本的灵活选择和自由切换,可无缝接入常见的开发与业务系统（控制台、API/SDK、工作流与自动化集成等）; <br /> 为贵司提供高可用、低延迟、可观测的稳定推理体验，帮助企业更快完成从原型验证到生产落地，全面提升研发效率与业务质量。

## **1. 订阅计划介绍** [#1-订阅计划介绍]

### **1.1 产品理念** [#11-产品理念]

企业在实际业务中往往需要更高的并发能力与更充裕的调用额度，而市面上大多数 AI 订阅方案主要面向个人用户设计，<br /> 在速率限制和额度管理上难以满足团队协作与生产级工作流的需求。为此 -- <br />我们推出了多模型组合订阅计划，覆盖通用对话、代码生成、推理增强、多模态等主流模型能力，同时提供更充裕的可用额度与更灵活的刷新机制。<br /> 企业用户只需一个订阅，即可在等级范围内自由切换多种模型，享受企业级的服务保障，以更优的性价比驱动多场景 AI 落地，助力业务高效运转。

### **1.2 订阅等级** [#12-订阅等级]

* 每个订阅等级包含一组精选 AI 模型，具体模型详情请见2.6。
* 不同订阅等级的使用额度与限流配置不同。

### **1.3 订阅权益** [#13-订阅权益]

* **多模型自由切换**：无须额外购买多平台会员，使用统一 API Key 访问订阅包含的全部模型。
* **灵活用量管理*&#x2A;：按积分计算消耗，&#x2A;*`每自然周实时刷新额度`**，支持高效连续使用。
* **高可靠性和安全性**：专属 API Key 及访问控制确保服务安全。
* **升级与续订便利**：可随时按需求升级等级，支持自动续订，保证服务不中断。

## **2. 订阅规则说明** [#2-订阅规则说明]

### **2.1 模型与价格系数** [#21-模型与价格系数]

* 本订阅采用统一积分体系。
* **`不同模型根据其刊例价设有对应的价格系数，调用时后端按「实际消耗token × 价格系数」实时扣除积分`** 。
* **`价格系数越高的模型，同等积分可使用的token越少；价格系数越低，则越多`**。
* 以 ¥0.004/千token 为基准单价，价格系数为 1.0 表示与基准持平。
* 针对新模型或资源比较紧张的模型，价格系数会适度上调，已购买过的用户在[【我的订阅】](https://portal.qiniu.com/ai-inference/subscription/info) 可查看上调的“额外价格系数“。普通模型的额外价格系数均为1

### **2.2 访问权限与 API Key 管理** [#22-访问权限与-api-key-管理]

* 订阅必须通过订阅专用 API Key 访问
* 使用订阅专用 API Key 访问非订阅等级内模型或超额请求将被拒绝，提示错误信息。

### **2.3 速率与用量限制** [#23-速率与用量限制]

* 采用基于积分的用量限制，&#x2A;*`按每自然周定期刷新额度`**，避免长时间等待，体验更流畅。
* 订阅等级对应不同月度积分总额度，所有订阅内模型共享此额度，防止额度被单独模型快速耗尽。

### **2.4 订阅管理政策** [#24-订阅管理政策]

* 支持选择不同等级订阅，满足不同场景需求。
* **升级订阅*&#x2A;：切换后 &#x2A;*`立即生效`** 。
* **取消订阅**：通过取消续订方式生效，服务到期自动终止。
* **自动续订**：到期自动续费，服务持续运行。

### **2.5 订阅周期与扣费** [#25-订阅周期与扣费]

* 订阅周期分别为：一个月30天，一个季度90天，一年365天。
* 下次扣费时间：在订阅周期到期的最后一天扣费

### **2.6 订阅与按量付费的差异** [#26-订阅与按量付费的差异]

| 差异       | 企业订阅                     | 按量付费                                                |
| -------- | ------------------------ | --------------------------------------------------- |
| **请求限制** | 与当前订阅相关                  | 标准限制                                                |
| **模型范围** | 订阅内的模型                   | 全部模型                                                |
| **付费方式** | 购买每月/季/年订阅，无法后付费，无法按量付费。 | 购买资源包或者按量，支持后付费，但需确保账户内有充足可用资源（如资源包、抵扣券、充值余额或信用额度）。 |

### **2.7 当前覆盖模型范围：** [#27-当前覆盖模型范围]

* z-ai/glm-4.6
* z-ai/glm-4.7
* z-ai/glm-5
* z-ai/glm-5.1
* minimax/minimax-m2.5
* minimax/minimax-m2.5-highspeed
* minimax/minimax-m2.7
* minimax/minimax-m3
* moonshotai/kimi-k2.5
* moonshotai/kimi-k2.6
* deepseek/deepseek-v3.2-251201
* deepseek/deepseek-v4-pro
* deepseek/deepseek-v4-flash

后续将持续更新…敬请期待

## **3. 关于自动续费服务** [#3-关于自动续费服务]

* 在购买前，请您详细阅读 [《自动续费服务协议》](https://www.qiniu.com/agreements/auto-renewal)，了解续费规则、续费方式等相关条款。

## **4. 常见问题解答（FAQ）** [#4-常见问题解答faq]

**Q1：我可以同时购买多个订阅吗？**
A1：单个用户当前仅支持同时拥有一个有效的 AI 订阅。如需提升服务，可以升级当前订阅等级。

**Q2：订阅内的模型是否会随时变动？**
A2：订阅内模型会根据市场与技术动态适时优化，重大调整将提前通知，保障用户体验连续性。

**Q3：如果我的积分用完了怎么办？**
A3：如果仅是当前每周窗口内的额度已耗尽，建议您耐心等待下一个刷新周期，届时额度将自动恢复；若当月订阅的全部额度均已用完，建议您通过按量付费模式的 API Key 继续使用服务，确保您的使用不受影响。

**Q4：API 访问权限如何保障安全？**
A4：订阅仅能通过订阅 API Key 访问，可以前往[【API Key 管理】](https://portal.qiniu.com/ai-inference/api-key)管理你的订阅访问。

**Q5：可以随时升级或取消计划吗？**
A5：可以，升级订阅计划，权益&#x2A;*立即生效（例如从包月升级到包季或包年）**；取消订阅后，当前订阅周期内服务不变，到期后自动终止。目前暂不支持降级。

**Q6：订阅的积分额度没用完会不会过期？**
A6：所有订阅计划的月度额度遵循"**订阅周期清零**"规则，不累计至下一周期。订阅周期分别为：一个月30天，一个季度90天，一年365天。请您合理规划用量。

**Q7："每自然周刷新额度"具体是什么意思？如果我每自然周额度不够用怎么办？**
A7：这意味着系统**每自然周**为您补充一次可用额度。如果您在某个刷新周期内提前用完额度，则需要等待下一个刷新周期开始才能获得新额度。建议您合理规划使用；或者您也可以随时用"按量模式"应急。且固定时间内，订阅范围中所有模型**共享同一额度限制**，不单独计算。

**Q8：升级订阅时费用如何计算？**
A8：升级时，系统会自动计算当前订阅剩余天数对应的差价，您只需支付差额即可。升级后新计划立即生效，下次续费将按新计划价格扣费。例如：您在包月计划使用一半时升级到包季，只需按照剩余天数补缴差价，无需重新支付全额。

**Q9：价格系数与额外价格系数是如何抵扣积分的？**

A9：以deepseek-v3.2-251201为例，模型的输入价为0.002 元 / K，输出价为0.003 元 / K；价格系数=用户的实际使用费用/0.004(基准价）；抵扣积分=用户实际用量x价格系数x 额外价格系数

假设用户其中一次请求输入tokens为300，输出tokens为50，根据价格系数折算后抵扣的积分为：300x（0.002/0.004）+50 x(0.003/0.004) x 1 =187.5
最后抵扣积分为187积分（积分保留整数）

**Q10：我该如何选择订阅计划？**
A10：您可以根据贵司主要的使用场景来预估大致的需求量。如果仍难以决定，欢迎随时联系我们的客服，将竭诚为您提供个性化的选择建议。

**Q11：我可以在购买之后退款吗？**
A11：用户通过购买本订阅以及自动续费完成的扣款，除法律法规另有规定、支付渠道另有规则或本平台另有明确承诺外，已生效周期的服务费用不予退还，感谢您的理解。

## **5. 结束语** [#5-结束语]

我们致力于打造透明公平、灵活便捷的 AI 模型订阅服务，帮助您轻松体验最前沿、最丰富的人工智能能力。若您遇到问题，欢迎随时联系我们的客服支持，获取更多帮助与建议！

感谢您的支持与信赖，祝您使用愉快！


# 实名认证说明 (/products/aitokenapi/0-verify-real-name)



最近更新时间: 2026-03-26 10:34:00

## 一、实名认证要求 [#一实名认证要求]

根据《中华人民共和国网络安全法》《互联网信息服务管理办法》等国家法律法规的要求，所有云服务提供商必须对用户进行实名认证后方可提供服务。为了合法合规地为您提供 AI 推理服务，我们需要您完成实名认证。

## 二、新用户体验政策 [#二新用户体验政策]

为了让您更好地体验我们的 AI 推理服务，我们为新注册用户提供 **24 小时免认证体验期**：

* **体验期时长**：自首次使用 AI 推理产品起 24 小时内（与注册时间无关）
* **体验期权益**：在此期间您可以正常使用 AI 推理服务的各项功能
* **认证提醒**：我们会在体验期内多次提醒您完成实名认证
* **逾期限制**：24 小时体验期结束后，如您尚未完成实名认证，将无法继续使用服务

**重要提示**：为避免影响您的正常使用，建议您尽早完成实名认证。

## 三、未实名用户服务限制 [#三未实名用户服务限制]

在完成实名认证之前，您的账户将受到以下限制：

### 请求频率限制 [#请求频率限制]

* **RPM（Requests Per Minute）**：每分钟请求次数受到限制
* **TPM（Tokens Per Minute）**：每分钟处理的 Token 数量受到限制

这些限制旨在确保服务的合规性和安全性。完成实名认证后，您将享受完整的服务配额和更高的使用额度。

## 四、如何完成实名认证 [#四如何完成实名认证]

前往 [个人中心/实名认证](https://portal.qiniu.com/developer/user/identity/choice)模块完成实名认证。

## 五、常见问题 [#五常见问题]

**Q：实名认证需要多长时间？**
A：通常情况下，实名认证审核会在当天内完成。

**Q：我的个人信息安全吗？**
A：我们严格遵守国家相关法律法规，采用严格的信息加密和安全措施保护您的个人信息。

**Q：体验期过后没有完成认证会怎样？**
A：24 小时体验期结束后，如您未完成实名认证，账户将无法继续使用 AI 推理服务，直到完成认证为止。

**Q：企业用户如何认证？**
A：企业用户需要提供营业执照等企业资质文件进行企业认证。

## 六、联系我们 [#六联系我们]

如果有任何意外和特殊情况，请通过工单联系我们。


# 计费预估 (/products/aitokenapi/1-ai-inference-bill-api)



最近更新时间: 2026-05-09 10:59:57

您可以在 &#x2A;*【AI 大模型推理】** 控制台查询计费预估数据。
<font color="red"> &#x2A;*注意：** </font>

* 该页面账单不计算折扣、资源包、抵扣劵等优惠，只展示基于使用量和模型价格计算的预估计费数据，仅作为实时费用账单参考，实际以最终财务中心的 &#x2A;*[月结算账单](https://portal.qiniu.com/financial/bills/overview)** 为准。
* 包含资源包抵扣的预估计费数据可在 &#x2A;*[按量计费预估](https://portal.qiniu.com/financial/bills/estimated-consume)** 查看

<br />

## **计费预估** [#计费预估]

1. 登录 &#x2A;*【AI大模型推理】*&#x2A; 控制台进入 &#x2A;*[计费预估](https://portal.qiniu.com/ai-inference/bill)** 界面
2. 选择 **查询月份*&#x2A;，然后点击 &#x2A;*【查询】** 即可，支持导出Excel数据。
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/1-ai-inference-bill-api/Fpdz4BCz0Lr2Wvf7NFky0Kyq2hog-3a2690b2547f.webp)


# 请求日志 (/products/aitokenapi/2-request-log-api)



最近更新时间: 2026-05-09 10:59:00

您可以在 &#x2A;*【AI 大模型推理】** 控制台查询请求日志

<br />

## **请求日志** [#请求日志]

1. 登录 &#x2A;*【AI大模型推理】*&#x2A; 控制台进入 &#x2A;*[请求日志](https://portal.qiniu.com/ai-inference/request-log)** 界面
2. 点击 &#x2A;*【筛选条件】*&#x2A; 勾选所需条件，点击 &#x2A;*【查询】** 即可。
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/2-request-log-api/FjFjMLgZWVrljPZHQlSUSzCBOw39-f04a272625d8.webp)
3. 说明：

* 单次查询指定时间范围不能超过一个月，数据量较大建议进行分段查询；
* 出现请求错误时，如果本地未记录到请求ID，可以在这里查询，将对应的请求ID通过 &#x2A;*[工单](https://support.qiniu.com/tickets/new-for-person)**  给技术支持排查确认；
* 筛选条件支持：**时间范围**、**API Key**、**模型**、**响应状态**
  ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/2-request-log-api/FiFYhdh5OSdI4P8AQiZZuoeDhNkx-bc6e760f5fb5.webp)


# 用量统计 (/products/aitokenapi/3-use-count-api)



最近更新时间: 2026-05-09 10:57:58

您可以在 &#x2A;*【AI 大模型推理】** 控制台查询用量统计数据

<br />

## **用量统计** [#用量统计]

1. 登录 &#x2A;*【AI大模型推理】*&#x2A; 控制台进入 &#x2A;*[用量统计](https://portal.qiniu.com/ai-inference/usage)** 界面
2. 选择 **查询时间范围**、**天/小时**、&#x2A;*API Key(不勾选默认查询全部)*&#x2A; ，然后点击 &#x2A;*【查询】** 即可
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/3-use-count-api/FusQFeiyUwMPkKlHyOs0Ign-4jL6-d739669a2426.webp)
3. 如需导出数据，点击 &#x2A;*【导出】** 按钮即可，导出数据是JSON格式
4. **说明：**

* 查询时间范围小于等于7天：支持按天或小时查询
* 查询时间范围大于7天：仅支持按天查询
* 支持根据 **API Key** 查询用量数据


# 请求日志下载 (/products/aitokenapi/0-log-download-api)



最近更新时间: 2026-07-09 15:41:21

# 请求日志导出接口 [#请求日志导出接口]

**Base URL:** `https://api.qnaigc.com`

## 概述 [#概述]

本接口用于导出请求日志（`monitor_log`），是 log 查询接口的导出版本。提供两个接口：

* **`GET /v2/stat/export_log`**：以 JSON 响应体返回（带统一包裹结构）。
* **`GET /v2/stat/export_log_file`**：以 JSON **文件**形式返回（浏览器触发下载，响应体为裸数组）。

两个接口的**查询参数、鉴权方式、过滤与排序逻辑完全相同**，**仅返回结构不同**（见下方各接口的响应说明）。

> 日志保留周期约为 30 天（以实际配置为准），请及时下载所需数据。

***

## 认证方式 [#认证方式]

支持两种鉴权方式：

1. **APIKey 认证**：使用 APIKey 进行认证
   ```
   Authorization: Bearer <APIKey>
   ```

2. **AK/SK 签名认证**：使用七牛云标准的 [AK/SK](https://portal.qiniu.com/developer/user/key) 签名认证
   ```
   Authorization: Qiniu <AccessKey>:<EncodedSign>
   ```

> 数字签名生成算法可参考文档站中「批量生成 APIKey」部分。

***

## 查询参数（两接口通用） [#查询参数两接口通用]

| 参数       | 类型        | 必填 | 说明                                                                               |
| -------- | --------- | -- | -------------------------------------------------------------------------------- |
| `start`  | `string`  | 否  | 开始时间，格式为 RFC3339（`2006-01-02T15:04:05Z07:00`）。作为时间过滤的**左闭**边界（`>=`）。建议传入以限定查询范围。 |
| `end`    | `string`  | 否  | 结束时间，格式为 RFC3339。作为时间过滤的**右开**边界（`<`）。当 `start` 与 `end` **同时**传入时才会校验范围上限。       |
| `size`   | `integer` | 是  | 每页返回数据条数，范围为 `1~500`，**无默认值**，不传或越界将返回 400 错误。                                   |
| `page`   | `integer` | 否  | 页码，从 `1` 开始，不传或 `<=0` 时默认为 `1`。用于超出 500 条数据的分批导出。                                |
| `model`  | `string`  | 否  | 模型名称，用于过滤特定模型的请求日志。示例：`deepseek/deepseek-v3.1`                                   |
| `code`   | `integer` | 否  | HTTP 状态码过滤，精确匹配。`0` 或不传表示不限制（返回所有状态码）。示例：`200`                                   |
| `apikey` | `string`  | 否  | APIKey 值，用于过滤特定 APIKey 的请求日志，会同时匹配带或不带 `Bearer ` 前缀的记录。示例：`sk-xx`                |

**请求头：**

| 名称              | 类型       | 必填 | 描述                       |
| --------------- | -------- | -- | ------------------------ |
| `Authorization` | `string` | 是  | 支持 APIKey 与 AK/SK 两种鉴权方式 |

### 排序与时间限制 [#排序与时间限制]

* **排序**：结果固定按请求开始时间（`start_time`）**倒序**排列，不支持自定义排序。
* **时间上限**：当 `start` 与 `end` 同时传入时，`end - start` 不得超过 **35 天**，且 `end` 不得早于 `start`，否则返回 400 错误。
* 仅传入 `start` 或 `end` 其中一个时，不做范围上限校验（按单边过滤）。
* 时间按项目标准时区 CST（东八区）解析。

***

## 接口一：导出日志（JSON 响应体） [#接口一导出日志json-响应体]

### **GET** `/v2/stat/export_log` [#get-v2statexport_log]

以项目统一响应结构返回 JSON，`data` 字段**直接为日志数组**。

**请求示例：**

```bash
curl --location "https://api.qnaigc.com/v2/stat/export_log?start=2024-01-01T00:00:00Z&end=2024-01-08T00:00:00Z&size=100&page=1" \
  --header "Authorization: Bearer sk-xx"
```

**成功响应（200 OK）**

```json
{
  "status": true,
  "data": [
    {
      "id": "65a1f2c3...",
      "model_id": "deepseek/deepseek-v3.1",
      "api_key": "sk-***xxxx",
      "start_time": "2024-01-01T10:00:00+08:00",
      "end_time": "2024-01-01T10:00:02+08:00",
      "server_type": "chat",
      "code": 200,
      "errors": null,
      "state": "",
      "usage": {
        "input": 1024,
        "output": 512,
        "cached_input": 0,
        "cache_creation": 0
      },
      "bo_usage": {
        "input_tokens": 1024
      },
      "bo_usage_cost": {
        "input_tokens": 0.001
      }
    }
  ]
}
```

***

## 接口二：导出日志（JSON 文件下载） [#接口二导出日志json-文件下载]

### **GET** `/v2/stat/export_log_file` [#get-v2statexport_log_file]

以**文件**形式返回。响应头包含：

```
Content-Disposition: attachment; filename=logs.json
Content-Type: application/json
```

**响应体为裸数组**（**没有** `status` / `data` 包裹），内容与 `export_log` 的 `data` 字段完全一致。

**请求示例：**

```bash
curl --location "https://api.qnaigc.com/v2/stat/export_log_file?start=2024-01-01T00:00:00Z&end=2024-01-08T00:00:00Z&size=100&page=1" \
  --header "Authorization: Bearer sk-xx" \
  -o logs.json
```

**成功响应（200 OK）**

```json
[
  {
    "id": "65a1f2c3...",
    "model_id": "deepseek/deepseek-v3.1",
    "api_key": "sk-***xxxx",
    "start_time": "2024-01-01T10:00:00+08:00",
    "end_time": "2024-01-01T10:00:02+08:00",
    "server_type": "chat",
    "code": 200,
    "errors": null,
    "state": "",
    "usage": {
      "input": 1024,
      "output": 512
    }
  }
]
```

> **注意区别**：`export_log` 返回 `{"status":true,"data":[...]}`；`export_log_file` 直接返回 `[...]`。两者字段含义相同，仅包裹方式不同。

***

## 响应字段说明（日志对象 `data[]`） [#响应字段说明日志对象-data]

| 字段              | 类型                    | 说明                                                                                                                                                                                           |
| --------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | `string`              | 日志记录的唯一 ID（MongoDB 文档 `_id`）                                                                                                                                                                 |
| `model_id`      | `string`              | 请求所使用的模型标识                                                                                                                                                                                   |
| `api_key`       | `string`              | 发起请求的 APIKey（已**脱敏**处理）                                                                                                                                                                      |
| `start_time`    | `string`              | 请求开始时间，RFC3339 格式                                                                                                                                                                            |
| `end_time`      | `string`              | 请求结束时间，RFC3339 格式                                                                                                                                                                            |
| `server_type`   | `string`              | 服务类型，如 `chat` / `image` / `video` 等                                                                                                                                                          |
| `code`          | `integer`             | 上游返回的 HTTP 状态码                                                                                                                                                                               |
| `errors`        | `array&lt;string&gt;` | 错误信息列表，无错误时为 `null`                                                                                                                                                                          |
| `state`         | `string`              | 请求状态标识                                                                                                                                                                                       |
| `usage`         | `object`              | 用量统计。key 因模型类型不同而异，常见包括 `input`、`output`、`cached_input`、`cache_creation`（文本/对话类），`tts_bytes`（TTS）、`asr_ms`（ASR）、`ocr_requests`（OCR）、`search_requests`（搜索）、`video_second`（视频）等；无用量数据时为 `null` |
| `bo_usage`      | `object`              | BO 计费用量明细（按计费项 key 聚合），无数据时省略                                                                                                                                                                |
| `bo_usage_cost` | `object`              | BO 计费用量对应的费用（人民币元），无数据时省略                                                                                                                                                                    |

***

## 错误响应 [#错误响应]

接口对错误采用两种返回风格：

### 1. 真实 HTTP 错误状态码（`status:false` + `error` 对象） [#1-真实-http-错误状态码statusfalse--error-对象]

| HTTP 状态码 | 触发条件                                                 | 响应示例                                                                                                 |
| -------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `400`    | 参数错误：`size` 越界、时间格式非法、时间范围超过 35 天、`end` 早于 `start` 等 | `{"status":false,"error":{"message":"invalid size,should be between 1 and 500","type":"param err"}}` |
| `401`    | AK/SK 签名无效或缺失                                        | `{"status":false,"error":{"message":"invalid ak/sk sign","type":"authorization err"}}`               |

### 2. HTTP 200 + `status:false`（项目统一错误风格） [#2-http-200--statusfalse项目统一错误风格]

| 场景                | 响应示例                                         |
| ----------------- | -------------------------------------------- |
| APIKey 无效或未提供鉴权   | `{"status":false,"error":"UNAUTHENTICATED"}` |
| 服务器内部错误（如数据库查询失败） | `{"status":false,"error":"INTERNAL_ERROR"}`  |

> ⚠️ 注意：鉴权失败（APIKey 模式）与服务器内部错误返回的是 **HTTP 200**，需以响应体中的 `"status": false` 判断是否成功。

***

## 代码示例 [#代码示例]

### 使用 APIKey 认证 [#使用-apikey-认证]

```bash
curl --location "https://api.qnaigc.com/v2/stat/export_log?start=2024-01-01T00:00:00Z&end=2024-01-08T00:00:00Z&size=100&page=1" \
  --header "Authorization: Bearer sk-xx"
```

### 使用 AK/SK 签名认证 [#使用-aksk-签名认证]

```bash
curl --location "https://api.qnaigc.com/v2/stat/export_log?start=2024-01-01T00:00:00Z&end=2024-01-08T00:00:00Z&size=100&page=1&model=deepseek/deepseek-v3.1" \
  --header "Authorization: Qiniu <AccessKey>:<EncodedSign>"
```

### 导出为文件 [#导出为文件]

```bash
curl --location "https://api.qnaigc.com/v2/stat/export_log_file?start=2024-01-01T00:00:00Z&end=2024-01-08T00:00:00Z&size=100&page=1" \
  --header "Authorization: Bearer sk-xx" \
  -o logs.json
```

### 分批导出大量数据 [#分批导出大量数据]

单次最多返回 500 条（`size` 上限为 500）。如需导出 1500 条，需分 3 次请求，每次仅修改 `page`，其余参数保持不变：

```bash
# 第 1 批：page=1, size=500
curl --location "https://api.qnaigc.com/v2/stat/export_log?start=2024-01-01T00:00:00Z&end=2024-01-08T00:00:00Z&size=500&page=1" \
  --header "Authorization: Bearer sk-xx"

# 第 2 批：page=2, size=500
curl --location "https://api.qnaigc.com/v2/stat/export_log?start=2024-01-01T00:00:00Z&end=2024-01-08T00:00:00Z&size=500&page=2" \
  --header "Authorization: Bearer sk-xx"

# 第 3 批：page=3, size=500
curl --location "https://api.qnaigc.com/v2/stat/export_log?start=2024-01-01T00:00:00Z&end=2024-01-08T00:00:00Z&size=500&page=3" \
  --header "Authorization: Bearer sk-xx"
```

***

## 注意事项 [#注意事项]

1. **两接口仅返回结构不同**：`export_log` 返回 `{status, data}` 包裹；`export_log_file` 返回裸数组并触发文件下载。参数、鉴权、过滤与排序逻辑完全一致。
2. **时间范围**：`start` 与 `end` 同时传入时，跨度上限为 **35 天**，且 `end` 不得早于 `start`；单边传入不校验上限。
3. **`size` 必填**：范围为 `1~500`，无默认值，不传或越界返回 400。
4. **分页**：超出 500 条时用 `page` 分批，每次仅改 `page`、其余参数不变。
5. **排序**：固定按 `start_time` 倒序，不支持自定义。
6. **时间格式**：RFC3339（`2006-01-02T15:04:05Z07:00`），按东八区解析。
7. **APIKey 脱敏**：返回结果中的 `api_key` 已做脱敏处理，非完整明文。
8. **成功判断**：APIKey 模式下鉴权失败与服务器错误均返回 HTTP 200，须依据响应体 `"status"` 字段判断。


# 全网搜索 API (/products/aitokenapi/1-web-search-api)



最近更新时间: 2026-03-26 11:49:31

# 简介 [#简介]

本接口提供高质量的全网搜索服务（即`百度Search API`）。
支持多种搜索类型和过滤条件，返回结构化的搜索结果，适用于智能问答、内容聚合、信息检索等多种应用场景。

# 功能特性 [#功能特性]

* **多种搜索类型**：支持网页搜索、图片搜索等多种搜索模式
* **灵活过滤**：支持时间过滤、站点过滤等多维度筛选条件
* **结构化结果**：返回标准化的搜索结果，包含标题、链接、摘要、来源等完整信息
* **高可用性**：基于成熟的搜索引擎技术，提供稳定可靠的搜索服务
* **易于集成**：标准 RESTful API，便于与各类系统对接

# API 接入点 [#api-接入点]

```
https://api.qnaigc.com/v1
```

# API 调用方式 [#api-调用方式]

## 获取接口密钥 [#获取接口密钥]

* 使用前提：[获取 API KEY(API 密钥)](/products/aitokenapi/0-how-to-get-api-key)

## 1. 请求示例 [#1-请求示例]

使用 curl 命令调用搜索接口：

```bash
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<你的七牛云 AI API KEY>"

curl --location "$OPENAI_BASE_URL/search/web" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --data '{
    "query": "今日新闻",
    "max_results": 10,
    "search_type": "web",
    "time_filter": "year",
    "site_filter": ["news.cctv.com", "www.xinhuanet.com"]
  }'
```

## 参数说明 [#参数说明]

| 参数名          | 类型     | 必填 | 说明                                                    |
| ------------ | ------ | -- | ----------------------------------------------------- |
| query        | string | 是  | 搜索关键词或查询语句                                            |
| max\_results | int    | 否  | 返回结果数量，网页搜索默认20，最大50，视频最大10（默认5），图片搜索最大30（默认15）       |
| search\_type | string | 否  | 搜索类型，默认"web"（网页搜索）                                    |
| time\_filter | string | 否  | 时间过滤，可选值：week（一周内）、month（一月内）、year（一年内）、semiyear(半年内) |
| site\_filter | array  | 否  | 站点过滤，指定搜索特定网站的内容（最多20个）                               |

## 搜索类型说明 [#搜索类型说明]

| 搜索类型  | 说明       |
| ----- | -------- |
| web   | 网页搜索（默认） |
| video | 视频搜索     |
| image | 图片搜索     |

# 返回结果示例 [#返回结果示例]

```json
{
  "success": true,
  "data": {
    "query": "今日新闻",
    "results": [
      {
        "id": 1,
        "title": "美政府"停摆"40天 共和党称"已有协议"拟今日表决",
        "url": "https://news.cctv.com/2025/11/10/ARTI4CtlbQAsLlX48iMqqvBE251110.shtml",
        "content": "美东时间11月9日,是本次美国政府自10月1日"停摆"以来的第40天。政府"停摆"已经在过去的一个多月内给全美多行业带来负面影响...",
        "date": "2025-11-10 09:14:08",
        "source": "央视国际",
        "score": 1,
        "type": "web",
        "icon": "https://search-operate.cdn.bcebos.com/d6289c25f5be88e38885ced0f53b60ef.jpeg",
        "authority_score": 1
      },
      {
        "id": 2,
        "title": "重要数据,今日公布;下周一,巴菲特发声",
        "url": "https://finance.eastmoney.com/a/202511093558946224.html",
        "content": "据新华社,商务部新闻发言人就安世半导体问题答记者问。中方注意到荷兰经济大臣卡雷曼斯于11月6日发表的声明...",
        "date": "2025-11-09 08:29:00",
        "source": "东方财富网",
        "score": 1,
        "type": "web",
        "icon": "https://finance.eastmoney.com/favicon.ico",
        "authority_score": 1
      }
    ],
    "total": 17,
    "request_id": "3b3d247c-719a-4856-a231-f35614bfa840"
  }
}
```

# 返回字段说明 [#返回字段说明]

## 响应结构 [#响应结构]

| 字段名     | 类型      | 说明            |
| ------- | ------- | ------------- |
| success | boolean | 请求是否成功        |
| message | string  | 错误信息（仅在失败时返回） |
| data    | object  | 搜索结果数据        |

## 搜索结果数据（data） [#搜索结果数据data]

| 字段名         | 类型     | 说明        |
| ----------- | ------ | --------- |
| query       | string | 搜索查询词     |
| results     | array  | 搜索结果列表    |
| total       | int    | 搜索结果总数    |
| request\_id | string | 本次请求的唯一标识 |

## 搜索结果项（results 数组元素） [#搜索结果项results-数组元素]

| 字段名              | 类型                                                                    | 说明                                        |
| ---------------- | --------------------------------------------------------------------- | ----------------------------------------- |
| id               | int                                                                   | 结果项ID                                     |
| title            | string                                                                | 页面标题                                      |
| url              | string                                                                | 页面链接                                      |
| content          | string                                                                | 页面摘要内容                                    |
| date             | string                                                                | 发布时间                                      |
| source           | string                                                                | 来源网站名称                                    |
| score            | float                                                                 | 相关性评分                                     |
| type             | string                                                                | 结果类型（web/news等）                           |
| icon             | string                                                                | 网站图标链接                                    |
| authority\_score | float                                                                 | 权威性评分                                     |
| image            | 包含三个字段：url,height,width,表达图片的链接，高，宽                                   | 图片                                        |
| video            | 包含： url,height,width,size（单位bytes）,duration（时长，单位秒）,hover\_pic(封面url) | 对于url为空的情况，上级的页面链接url字段为视频平台链接，视频本身无直接url |

# 示例代码 [#示例代码]

```python
import requests
import json

def web_search(query, max_results=10):
    url = "https://api.qnaigc.com/v1/search/web"
    headers = {
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY"
    }

    data = {
        "query": "今日新闻",
        "max_results": 10,
        "search_type": "web"
    }

    response = requests.post(url, headers=headers, json=data)

    if response.status_code == 200:
        result = response.json()
        if result["success"]:
            return result["data"]
        else:
            print(f"搜索失败: {result['message']}")
    else:
        print(f"请求失败: {response.status_code}")

    return None

# 使用示例
results = web_search("今日新闻", 5)
if results:
    print(f"找到 {results['total']} 个结果")
    for item in results['results']:
        print(f"标题: {item['title']}")
        print(f"链接: {item['url']}")
        print(f"摘要: {item['content'][:100]}...")
        print("---")
```


# MCP 使用说明⚒️ (/products/aitokenapi/2-mcp-user-manual)



最近更新时间: 2026-06-08 15:21:50

## 前言 [#前言]

本说明文档旨在帮助用户快速了解并高效使用 MCP 接入服务。MCP（模型上下文协议）接入服务是为各类大模型推理服务提供统一、安全、标准化接入与编排的中间层。关于 MCP 协议本身，请参见《[什么是 MCP](/products/aitokenapi/0-what-is-mcp)》文档。

## 产品简介 [#产品简介]

MCP 接入服务是七牛云 AI 推出的统一模型能力接入与编排平台。它为企业和开发者提供标准协议转换、安全密钥托管、服务聚合、统一管理等能力，帮助用户高效、安全地对接和管理各类 MCP 服务。

### 适用场景 [#适用场景]

1. 一步调用LLM推理大模型和多个流行MCP工具，支持开发更复杂的Agent应用
2. 需要灵活编排、聚合多种工具和模型，统一接入和管理，增强服务扩展性
3. 需要集中安全托管多种MCP的敏感密钥，避免在多个用户和终端暴露
4. 本地终端系统多样，难以配置和运行多种代码编写和工具依赖的MCP服务

## 接入方式总览 [#接入方式总览]

⚒️ MCP 支持多种标准协议接入，满足不同业务和系统集成需求：

### 1、Agent 协议接入 [#1agent-协议接入]

七牛云 AI Agent 协议目前兼容 OpenAI，可以无缝对接到 OpenAI 的生态链中。

* 地址格式：
  `https://api.qnaigc.com/v1/agent/instance/${mcp-id}`
* 适用场景：无需本地部署，直接通过兼容 OPENAI 的 Agent 协议接入

### 1.1、Agent 的多服务聚合 [#11agent-的多服务聚合]

* 支持在 BaseUrl 中拼接多个 MCP-ID，实现一次聚合多个服务：
  `https://api.qnaigc.com/v1/agent/group/${mcp-id-1},${mcp-id-2},${mcp-id-3}`

### 2、标准 MCP 协议接入 [#2标准-mcp-协议接入]

* SSE 协议：
  `https://api.qnaigc.com/v1/mcp/sse/${mcp-id}`
* HTTP-Streamable 协议：
  `https://api.qnaigc.com/v1/mcp/http-streamable/${mcp-id}`
* 适用场景：与本地 MCP 服务更灵活的搭配使用

## 核心优势 [#核心优势]

* **协议标准化**：支持 OPENAI、SSE、HTTP-Streamable 等主流协议，屏蔽底层差异
* **安全托管**：API Key、密钥等敏感信息云端托管，终端无需暴露
* **灵活聚合**：支持多服务聚合调用，能力自由组合
* **统一管理**：可视化控制台统一管理所有接入服务

## 主要功能 [#主要功能]

* MCP 服务接入与协议转换
* 安全密钥托管与权限管理
* 支持标准协议（OPENAI、SSE、HTTP-Streamable）对接
* 多服务聚合与编排
* 可视化服务管理

## 详细配置与使用示例 [#详细配置与使用示例]

### 控制台配置 MCP 接入服务 [#控制台配置-mcp-接入服务]

* 登录七牛云 AI 控制台，进入 [MCP 服务管理页面](https://portal.qiniu.com/ai-inference/mcp/store)
* 添加或管理已有的 MCP 服务，获取专属的 MCP-ID

### 获取接入地址 [#获取接入地址]

* 控制台会为每个 MCP 接入服务生成专属的接入地址，支持多种协议

### Agent 协议详细示例 [#agent-协议详细示例]

以 `curl` 为例：

```bash
export OPENAI_BASE_URL="https://api.qnaigc.com/v1/agent/instance/${mcp-id}"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "messages": [{"role": "user", "content": "请调用你支持的三个 MCP 能力，并列举全部能力"}],
        "model": "deepseek-v3-tool"
    }'
```

#### 注意事项 [#注意事项]

* Agent 协议下无需本地安装任何 MCP 组件，直接调用即可
* API Key 请妥善保管，避免泄露
* MCP 接入服务本身不直接提供大模型能力，而是作为能力编排与接入中间层

### MCP 标准协议接入服务 [#mcp-标准协议接入服务]

我们支持标准的 MCP 协议类型，选择对应的 MCP 协议地址配置到 MCP 客户端上即可，这里我们以 Node 的官方 SDK 中使用 HTTPStreamable 为例子：

```javascript
import { Client } from "@modelcontextprotocol/sdk/client/index"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp"

const serverUrl = '你的 MCP 服务 Url '
const apiKey = '你的七牛云 AI 推理 API Key'

const client = new Client({
  name: 'qiniu-sse-test-client',
  version: '1.0.0'
})

// 这里设置你的七牛云 api key 和 StreamableHTTP 连接地址
const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
  requestInit: { headers: { 'Authorization': `Bearer ${apiKey}` } }
})

async function main() {
  // 开始连接
  await client.connect(transport)

  // 列举 MCP 工具
  const tools = await client.listTools()

  // 查看支持的工具
  console.log(tools)
}

main()
  .then(() => { console.log('Client connected successfully') })
  .catch((error) => { console.error('Error connecting client:', error) })
```

## 常见问题 [#常见问题]

1. **如何获取 MCP-ID？**
   * 登录控制台，在 MCP 接入服务详情页可查看和复制
2. **Agent 协议和标准 MCP 协议有何区别？**
   * Agent 协议适合无需本地部署、直接云端调用场景；标准协议适合与本地服务深度集成混排
3. **API Key 泄露怎么办？**
   * 立即在控制台重置 API Key，并排查相关调用记录
4. **MCP 接入服务能否直接提供大模型能力？**
   * 不能，MCP 接入服务仅作为能力编排与接入中间层，实际模型能力由后端服务提供

## 联系我们 [#联系我们]

如有更多问题或建议，请联系七牛云 AI 技术支持。


# OpenClaw 安装配置指南 (/products/aitokenapi/1-openclaw-installation-cuide)



最近更新时间: 2026-04-29 17:43:45

# OpenClaw 安装配置指南 [#openclaw-安装配置指南]

## 1. 介绍 [#1-介绍]

OpenClaw 是一个强大的 AI 代理工具，支持配置多种 AI 模型提供商。通过 OpenClaw，您可以轻松接入七牛云 AI 推理服务，使用多种先进的大语言模型来提升您的开发效率。

OpenClaw 的主要特点：

* 🚀 支持多模型提供商配置
* 🔧 灵活的配置方式
* 💡 开箱即用的 AI 代理能力
* 🔐 安全的 API Key 管理

## 2. 安装 [#2-安装]

### 主要流程 [#主要流程]

1. **确认环境**：准备 Node.js 22+（支持 macOS / Linux / Windows，Windows 建议 WSL2）。
2. **执行安装**（推荐官方脚本）：

```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```

3. **完成初始化**：按提示完成 onboarding；若需要手动安装可使用：

```bash
npm install -g openclaw@latest
openclaw onboard --install-daemon
```

### 安装完成后检查 [#安装完成后检查]

```bash
openclaw doctor
openclaw status
openclaw dashboard
```

### 报错处理 [#报错处理]

安装报错（包括 `npm/pnpm`、`sharp build errors`、`openclaw not found` 等）请直接参考官方安装文档：

* [https://docs.openclaw.ai/install](https://docs.openclaw.ai/install)
* [https://docs.openclaw.ai/install#npm-pnpm:sharp-build-errors](https://docs.openclaw.ai/install#npm-pnpm:sharp-build-errors)

## 3. 配置七牛模型 [#3-配置七牛模型]

### 环境变量配置 [#环境变量配置]

首先，设置您的七牛 API Key 环境变量：

```bash
export QINIU_API_KEY="sk-your-api-key-here"
```

### 完整配置示例 [#完整配置示例]

在 OpenClaw 配置文件中添加以下配置：

```javascript
{
  env: { QINIU_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "qiniu/deepseek-v3.2-251201" },
      models: {
        "qiniu/z-ai/glm-5": { alias: "GLM 5" },
        "qiniu/deepseek-v3.2-251201": { alias: "DeepSeek V3.2" },
        "qiniu/moonshotai/kimi-k2.5": { alias: "Kimi K2.5" },
        "qiniu/minimax/minimax-m2.5": { alias: "Minimax M2.5" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      qiniu: {
        baseUrl: "https://api.qnaigc.com/v1",
        apiKey: "${QINIU_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "deepseek-v3.2-251201",
            name: "DeepSeek V3.2",
            reasoning: false,
            input: ["text"],
            contextWindow: 128000,
            maxTokens: 8192,
            compat: {
              supportsStore: false,
              supportsDeveloperRole: false,
              supportsReasoningEffort: false
            }
          },
          {
            id: "moonshotai/kimi-k2.5",
            name: "Kimi K2.5",
            reasoning: false,
            input: ["text"],
            contextWindow: 256000,
            maxTokens: 8192,
            compat: {
              supportsStore: false,
              supportsDeveloperRole: false,
              supportsReasoningEffort: false
            }
          },
          {
            id: "z-ai/glm-5",
            name: "GLM 5",
            reasoning: false,
            input: ["text"],
            contextWindow: 128000,
            maxTokens: 8192,
            compat: {
              supportsStore: false,
              supportsDeveloperRole: false,
              supportsReasoningEffort: false
            }
          },
          {
            id: "minimax/minimax-m2.5",
            name: "Minimax M2.5",
            reasoning: false,
            input: ["text"],
            contextWindow: 128000,
            maxTokens: 8192,
            compat: {
              supportsStore: false,
              supportsDeveloperRole: false,
              supportsReasoningEffort: false
            }
          },
        ],
      },
    },
  },
}
```

### 配置说明 [#配置说明]

**基础配置项：**

* `baseUrl`: 七牛 AI 推理服务的 API 端点：`https://api.qnaigc.com/v1`
* `apiKey`: 通过环境变量 `${QINIU_API_KEY}` 引用您的 API Key
* `api`: 使用 `openai-completions` 协议（OpenAI 兼容）

### 模型引用格式 [#模型引用格式]

七牛云模型引用使用 `qiniu/<modelId>` 格式，例如：

* `qiniu/deepseek-v3.2-251201`
* `qiniu/moonshotai/kimi-k2.5`
* `qiniu/deepseek-r1`
* `qiniu/qwen3-max`
* `qiniu/z-ai/glm-5`

### 获取 API Key [#获取-api-key]

您可以通过以下步骤获取七牛 AI 推理服务的 API Key：

1. 登录 [七牛云控制台](https://portal.qiniu.com/ai-inference/api-key)
2. 进入 AI 推理服务管理页面
3. 创建或查看您的 API Key
4. 妥善保管您的 API Key，切勿泄露

## 💡 使用提示 [#-使用提示]

* **模型选择**：根据您的任务需求选择合适的模型。DeepSeek V3.2 和 Qwen3 Max 适合复杂任务，DeepSeek R1 和 Kimi K2 Thinking 支持推理能力
* **上下文管理**：注意不同模型的 `contextWindow` 限制，合理控制对话长度
* **成本优化**：可以根据实际使用情况更新 `cost` 配置，便于成本追踪
* **自定义模型**：如需添加更多模型，按照相同格式在 `models` 数组中添加即可

## ⚠️ 注意事项 [#️-注意事项]

1. **API Key 安全**：请勿在代码中硬编码 API Key，始终使用环境变量
2. **配置更新**：七牛云会不断更新可用模型列表，请关注官方文档获取最新信息
3. **实名认证**：使用七牛 AI 推理服务需要完成实名认证，详见[实名认证说明](/products/aitokenapi/0-verify-real-name)
4. **配额限制**：注意您的账户配额限制，避免超额使用

## 🙋 需要帮助？ [#-需要帮助]

如在配置过程中遇到任何问题：

* 📖 查阅 [OpenClaw 官方文档](https://docs.openclaw.ai/)
* 💬 联系七牛云技术支持
* 📝 提交工单获取专业帮助

***

祝您使用愉快！开始您的 AI 开发之旅吧！ 🚀


# 聊天客户端 NextChat 配置说明 (/products/aitokenapi/12888-next-chat-configuration-instructions)



最近更新时间: 2026-10-15 17:14:37

NextChat 官方地址：[https://nextchat.dev/](https://nextchat.dev/)

NextChat 客户端下载地址：- [请到 NextChat 官方开源仓库的 Releases（发布）页面下载](https://github.com/ChatGPTNextWeb/NextChat/releases)

本教程主要指导大家如何将七牛的推理服务配置到 **Next Chat** 客户端中。

NextChat 是一款开源的大模型聊天客户端，在 GitHub 上很受欢迎。配置七牛 AI 模型服务后，即可在 NextChat 中与 deepseek-v3、qwen3、kimi-k2 等模型对话。

### 前置准备 [#前置准备]

* [如何获取七牛云 Token API 密钥](/products/aitokenapi/0-how-to-get-api-key)

### **配置说明** [#配置说明]

1. 点击左下角设置按钮进入设置界面

   ![1738921865191.png](/docs-assets/products/aitokenapi/%285-best-practices%29/12888-next-chat-configuration-instructions/FpeNucFSZ_8bhpD4AZQGibVvyyhz-a8dc8c5f67f3.webp)

2. 修改配置，使用七牛云推理服务
   1. 在模型服务商中选择“OpenAI 兼容”格式，
      1. 该选项代表使用 OpenAPI 的接口协议
   2. 接口地址填入：[https://api.qnaigc.com](https://api.qnaigc.com/)
      1. 改地址为七牛的推理服务端口地址
   3. API Key 输入上方获取到的密钥
   4. 自定义模型名称，输入七牛支持的模型 id，以半角逗号 , 分开
      1. 例如：deepseek-r1,deepseek-v3
      2. 更多请参考：[七牛云模型广场](https://portal.qiniu.com/ai-inference/model)

3. 选择模型

   1. 在下方的模型选项中，选择我们上方自定义的模型。例如我这里的 deepseek-r1

   ![image.png](/docs-assets/products/aitokenapi/%285-best-practices%29/12888-next-chat-configuration-instructions/FjgnCOXiq74sDqUmHCeo5UUjQ3A4-a5080cc2393d.webp)

4. 测试效果

   ![image.png](/docs-assets/products/aitokenapi/%285-best-practices%29/12888-next-chat-configuration-instructions/FrZ3WTZUKuU4rUTpT4MGNnv-jkO7-e4229a5cc09f.webp)

🎉🎉 恭喜你，已经配置成功啦！！


# 什么是 MCP (/products/aitokenapi/0-what-is-mcp)



最近更新时间: 2026-09-17 15:09:27

MCP（Model Context Protocol，模型上下文协议）是一种用于标准化大模型与外部系统之间交互的协议。它的核心目标是为大语言模型（如 LLM 等）提供一种统一、结构化的方式来获取外部知识、调用工具、访问数据库或与其他服务集成。

## 主要特点 [#主要特点]

1. **标准化接口**：MCP 定义了一套通用的 API 和数据格式，使不同的模型和工具可以通过一致的方式进行通信，降低了集成和扩展的难度。
2. **上下文管理**：MCP 强调“上下文”的概念，允许模型在推理过程中动态获取、更新和管理外部信息，从而提升模型的智能和实用性。
3. **工具调用**：通过 MCP，模型可以安全、可控地调用外部工具（如搜索引擎、计算服务、数据库等），实现“工具增强型智能”。
4. **可扩展性**：MCP 协议支持多种扩展方式，便于开发者根据实际需求自定义接口、数据结构和权限控制。

## 应用场景 [#应用场景]

* **智能助手**：通过 MCP，助手可以访问日历、邮件、知识库等外部资源，提供更丰富的服务。
* **企业集成**：企业可以用 MCP 将大模型与内部系统（如 ERP、CRM）对接，实现自动化办公。
* **数据分析**：模型可通过 MCP 动态获取数据源，进行实时分析和报告生成。

## 安全问题与托管方案 [#安全问题与托管方案]

MCP 协议虽然极大地提升了模型的能力，但也带来了新的安全挑战。例如：

* **权限滥用**：如果没有严格的权限控制，模型可能访问到敏感数据或执行高风险操作。
* **数据泄露**：模型与外部系统频繁交互，存在数据在传输或处理过程中被窃取的风险。
* **工具滥用**：模型调用外部工具时，若缺乏审计和限制，可能被恶意利用。

为了解决这些安全问题，推荐采用**托管（Managed）MCP 服务**：

* 托管服务通常由专业团队运维，具备完善的安全防护措施，如身份认证、权限管理、访问审计等。
* 托管平台会对模型的每一次外部调用进行监控和日志记录，及时发现异常行为。
* 托管环境下，开发者可以灵活配置哪些工具和数据对模型开放，降低误用和攻击风险。

通过托管 MCP，可以大幅提升协议的安全性和可控性，让企业和开发者更安心地将大模型能力融入实际业务。

## 总结 [#总结]

MCP 协议为大模型与外部世界之间架起了一座桥梁，使其具备更强的交互能力和实际应用价值。


# 模型特性：多模态 (/products/aitokenapi/1-model-features-multimodality)



最近更新时间: 2025-07-30 16:57:23

在人工智能发展中，单一模态模型渐难满足复杂场景需求。LLM 多模态凭借跨模态理解与生成能力成为焦点，它打破文本、图像、音频等模态壁垒，让模型能像人类一样综合多种感官信息认知决策。

## LLM 多模态的核心内涵 [#llm-多模态的核心内涵]

LLM 多模态是基于大语言模型架构，融合多种信息模态处理的智能系统。相比仅能处理文本的传统语言模型，它可理解图像、音频、视频等非文本信息，还能实现不同模态间的转换与生成。

其核心是 “融合”，并非简单信息叠加，而是深度语义整合。通过联合学习不同模态数据，模型能挖掘模态间潜在关联，更全面准确理解输入。比如看到 “小狗在草地上玩耍” 的图片，模型不仅能识别元素，还能转化为文本描述，甚至依描述生成对应图像。

技术架构上，通常包含模态编码器、跨模态融合器和模态生成器。模态编码器将不同输入转化为统一语义向量；跨模态融合器处理向量，构建模态关联；模态生成器根据融合信息生成目标模态输出，确保不同模态在统一语义空间高效交互。

## LLM 多模态的典型能力 [#llm-多模态的典型能力]

围绕 “跨模态理解” 与 “跨模态生成”，有以下典型能力：

**跨模态语义匹配**：判断不同模态信息是否语义相同，如文本与图片、音频与文字记录是否匹配，在内容检索、信息校验中作用重大。

**多模态内容理解**：深层解读混合模态输入，如分析带文字说明的图表、理解视频动作与同期声关联、解读图文社交媒体内容的情感倾向。

**跨模态内容生成**：基于一种模态生成另一种，除图像转文本，还有文本生成图像、音频转文本、文本生成音频、视频生成文字梗概等，拓展内容创作边界。

## LLM 多模态的技术价值 [#llm-多模态的技术价值]

它极大拓展了人工智能应用边界。教育领域，可将文本知识转化为生动图像、音频，提升学习体验；医疗行业，结合病历与医学影像辅助精准诊断；娱乐场景，依文字描述生成个性化图像、视频；智能驾驶中，融合图像、雷达数据及语音指令，实现安全行车决策。

## 基于 OpenAI 接口的多模态应用示例 [#基于-openai-接口的多模态应用示例]

OpenAI 接口为开发者提供便利，以下是基础应用示例：

### 文本与图像的关联处理 [#文本与图像的关联处理]

通过接口可实现文本对图像的描述请求。传入 “请描述这张图像的内容” 及图像数据，接口会返回文本描述。调用逻辑大致如下：

```python
import openai

response = openai.ChatCompletion.create(
  model="...",  # 对应的模型标识
  messages=[
    {"role": "user", "content": [
      {"type": "text", "text": "请描述这张图像的内容"},
      {"type": "image_url", "image_url": {"url": "图像的URL地址"}}
    ]}
  ]
)
print(response.choices[0].message.content)
```

此调用实现文本与图像模态交互，调整文本指令还能完成 “分析产品图片设计风格” 等复杂任务，体现模型深层理解能力。

LLM 多模态技术正快速发展，随着模态融合加深和效率优化，应用将更广泛，未来融入视频、3D 模型等复杂模态后，有望接近人类认知水平。


# 模型特性：结构化输出 (/products/aitokenapi/2-model-features-structured-output)



最近更新时间: 2026-09-17 15:08:33

在大语言模型的实际应用中，**结构化输出**是提升结果实用性的核心特性。相较于自由文本，结构化输出能将模型生成的内容限定在预设格式（如 JSON、XML、表格等）中，显著降低下游系统的解析成本，尤其适用于数据处理、自动化流程集成等场景。

## 什么是结构化输出？ [#什么是结构化输出]

结构化输出指模型按照特定格式生成内容，确保输出结果具备固定字段、清晰层次和可预测逻辑。例如，当用户要求 “提取新闻关键信息” 时，模型不会返回零散的文字描述，而是生成包含 “标题、发布时间、主体、关键词、情感倾向” 等字段的 JSON 对象，直接满足数据入库或分析工具的格式要求。

这种特性的核心价值体现在：

* **降低开发成本**：省去下游系统编写复杂文本解析逻辑的工作；
* **提升数据一致性**：保证同类任务的输出格式统一，便于批量处理；
* **增强可靠性**：减少歧义性表述，让机器能直接理解并使用结果。

## 常见的结构化输出格式 [#常见的结构化输出格式]

模型支持的结构化格式需结合应用场景选择，以下为几种典型类型：

* **JSON 格式**：应用最广泛的轻量级数据交换格式，适合存储键值对形式的结构化信息。例如，提取产品评价核心要素：

```
{
 "产品名称": "无线蓝牙耳机",
 "评价日期": "2025-07-28",
 "评分": 4.5,
 "优点": ["续航时间长", "音质清晰"],
 "缺点": ["降噪效果一般"],
 "用户关注点": ["续航", "音质", "降噪"]
}
```

* **表格格式（CSV/Markdown 表格）**：适用于展示具有行列关系的结构化数据，如多维度对比、列表类信息。例如，生成手机型号对比表：

```
| 型号       | 处理器   | 内存 | 电池容量 | 价格（元） |
|------------|----------|------|----------|------------|
| 型号A      | 骁龙8 Gen3 | 12GB | 5000mAh  | 4999       |
| 型号B      | 天玑9300 | 16GB | 4800mAh  | 5299       |
```

* **XML 格式**：适合需要嵌套层级的复杂结构，常用于文档标记、配置文件等场景。例如，标注合同关键条款：

```xml
<contract>
 <party name="甲方">XX科技有限公司</party>
 <party name="乙方">YY贸易公司</party>
 <term type="有效期">
   <start_date>2025-08-01</start_date>
   <end_date>2026-07-31</end_date>
 </term>
 <amount currency="人民币">500000元</amount>
</contract>
```

## 基于 OpenAI 接口的结构化输出实现 [#基于-openai-接口的结构化输出实现]

OpenAI 的 API 可通过`function_call`参数或提示词引导，强制模型生成结构化内容。以下为具体实践示例：

### 示例 1：通过提示词约束 JSON 输出 [#示例-1通过提示词约束-json-输出]

当需要提取文章中的人物信息时，可在提示词中直接指定 JSON 格式：

```python
import openai
openai.api_key = "你的API密钥"
response = openai.ChatCompletion.create(
 model="moonshotai/kimi-k2.6",
 messages=[
   {"role": "system", "content": "你是信息提取工具，请从用户提供的文本中提取人物信息，返回JSON格式，包含字段：姓名、性别、年龄（若提及）、职业、关键事件。若信息不完整，缺失字段用null填充。"},
   {"role": "user", "content": "文本：李明，男，35岁，是一名软件工程师，上周在公司技术竞赛中获得一等奖。他的同事张燕，女，负责产品设计，也参与了此次竞赛。"}
 ]
)
print(response.choices[0].message['content'])
```

**输出结果**：

```json
[
 {
   "姓名": "李明",
   "性别": "男",
   "年龄": 35,
   "职业": "软件工程师",
   "关键事件": "上周在公司技术竞赛中获得一等奖"
 },
 {
   "姓名": "张燕",
   "性别": "女",
   "年龄": null,
   "职业": "产品设计",
   "关键事件": "参与公司技术竞赛"
 }
]
```

### 示例 2：使用 function\_call 强制结构化格式 [#示例-2使用-function_call-强制结构化格式]

对于更复杂的场景，可通过定义函数的 JSON Schema，让模型严格遵循格式输出：

```python
import openai
openai.api_key = "你的API密钥"
response = openai.ChatCompletion.create(
 model="moonshotai/kimi-k2.6",
 messages=[
   {"role": "system", "content": "你需要分析用户提供的订单信息，返回标准化的订单详情。"},
   {"role": "user", "content": "订单：用户王华在2025年7月29日购买了2件T恤（红色，M码）和1双运动鞋（黑色，42码），总金额399元，付款方式为微信支付。"}
 ],
 functions=[
   {
     "name": "format_order",
     "parameters": {
       "type": "object",
       "properties": {
         "user_name": {"type": "string"},
         "order_date": {"type": "string", "format": "YYYY-MM-DD"},
         "items": {
           "type": "array",
           "items": {
             "type": "object",
             "properties": {
               "product": {"type": "string"},
               "attributes": {"type": "object"},
               "quantity": {"type": "integer"}
             },
             "required": ["product", "quantity"]
           }
         },
         "total_amount": {"type": "number"},
         "payment_method": {"type": "string"}
       },
       "required": ["user_name", "order_date", "items", "total_amount"]
     }
   }
 ],
 function_call={"name": "format_order"}  # 强制调用指定函数
)
# 提取结构化结果
structured_result = eval(response.choices[0].message['function_call']['arguments'])
print(structured_result)
```

**输出结果**（Python 字典格式）：

```json
{
 "user_name": "王华",
 "order_date": "2025-07-29",
 "items": [
   {
     "product": "T恤",
     "attributes": {"颜色": "红色", "尺码": "M码"},
     "quantity": 2
   },
   {
     "product": "运动鞋",
     "attributes": {"颜色": "黑色", "尺码": "42码"},
     "quantity": 1
   }
 ],
 "total_amount": 399,
 "payment_method": "微信支付"
}
```

## 结构化输出的注意事项 [#结构化输出的注意事项]

1. **格式明确性**：提示词中需清晰定义字段名称、数据类型（如字符串 / 数字 / 数组）及约束条件（如日期格式），避免模型产生歧义；

2. **容错处理**：实际应用中需考虑模型偶尔出现的格式错误（如遗漏引号、括号不匹配），可通过正则校验或工具库（如`json`模块）进行二次处理；

3. **复杂度平衡**：过于复杂的结构（如多层嵌套）可能降低模型准确率，建议根据需求拆分字段或分步骤生成。

通过结构化输出，大语言模型能更高效地与数据库、ERP 系统、自动化工具等下游组件协同，成为连接自然语言交互与机器可执行流程的核心纽带。


# AI编程工具配置大全（AI Coding） (/products/aitokenapi/0-tools-ai-coding-api)



最近更新时间: 2026-09-17 14:36:14

# AI编程工具分类 [#ai编程工具分类]

目前AI编程工具有IDE（集成开发环境）、VS Code插件、Cli（命令行）工具三类。
一般通过选择其API Provider中的OpenAI Compatible模式（即配置Base URL + API Key + Model）即可使用：

* Base URL: `https://api.qnaigc.com/v1`
* API Key: `sk-9b******edf77`  (参考[AI大模型API密钥](/products/aitokenapi/0-how-to-get-api-key) )
* Model: `z-ai/glm-4.6` 、`minimax/minimax-m2`、`moonshotai/kimi-k2-thinking`等

# VS Code插件 [#vs-code插件]

## **Kilo** [#kilo]

![kiro.png](/docs-assets/products/aitokenapi/%284-tools%29/0-tools-ai-coding-api/FqTCy_hFgtOBeRNadVKEu4rpUnO0-29b25e00895f.webp)

## **Cline** [#cline]

![cline.png](/docs-assets/products/aitokenapi/%284-tools%29/0-tools-ai-coding-api/FhhI8Z5B4eUIyQHDTAanYtyxP1cp-0b83c1079345.webp)

## **Roo Code** [#roo-code]

![roo.png](/docs-assets/products/aitokenapi/%284-tools%29/0-tools-ai-coding-api/FgiPR5jhOKuWx2ORnxL5p54MLK_2-a41c10b90573.webp)

## **Blackbox** [#blackbox]

![blackbox.png](/docs-assets/products/aitokenapi/%284-tools%29/0-tools-ai-coding-api/FmozlY24wFKWzdtdQq2Yb8yN_-I4-0ffa9fe80e16.webp)

# Cli命令行工具 [#cli命令行工具]

## **Cline** Cli [#cline-cli]

```shell
npm install -g cline
```

## **Open Code** Cli [#open-code-cli]

```
# YOLO
curl -fsSL https://opencode.ai/install | bash

# Package managers
npm i -g opencode-ai@latest        # or bun/pnpm/yarn
scoop bucket add extras; scoop install extras/opencode  # Windows
choco install opencode             # Windows
brew install opencode              # macOS and Linux
paru -S opencode-bin               # Arch Linux
mise use --pin -g ubi:sst/opencode # Any OS
nix run nixpkgs#opencode           # or github:sst/opencode for latest dev branch
```

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.qnaigc.com/v1"
      }
    }
  }
}
```

[opencode@github](https://github.com/sst/opencode)

## **Aider** Cli [#aider-cli]

```
python -m pip install aider-install
aider-install

# Change directory into your codebase
cd /to/your/project

# Mac/Linux:
export OPENAI_API_BASE=https://api.qnaigc.com/v1
export OPENAI_API_KEY=sk-****

# Windows:
setx OPENAI_API_BASE https://api.qnaigc.com/v1
setx OPENAI_API_KEY sk-****
# ... restart shell after setx commands

```

# IDE 集成开发环境 [#ide-集成开发环境]

## **Cursor** 自定义模型 [#cursor-自定义模型]

![cursor.png](/docs-assets/products/aitokenapi/%284-tools%29/0-tools-ai-coding-api/Fg_69UALEw1qGYm4FMEzpSsxMr6d-c884e37fbc38.webp)

# Agent 任务工具 [#agent-任务工具]

## **Goose** [#goose]

### 选择 OpenAICompatible 类型并输入以下信息 [#选择-openaicompatible-类型并输入以下信息]

![goose5.png](/docs-assets/products/aitokenapi/%284-tools%29/0-tools-ai-coding-api/FgtYEXpUdbDOQFCkAZ3vVW48rXKD-57618fb0496b.webp)


# 产品概述 (/products/cdn/0-product-overview-fusion)



最近更新时间: 2021-02-04 14:17:15

# 产品简介 [#产品简介]

七牛 CDN 是在传统 CDN 基础上实现的对数据网络加速进一步优化的智能管理服务。通过全方位的 CDN 质量监控，以及智能易用的节点调度等功能，提供稳定快速的网络访问服务。保障客户的音视频点播、大文件下载、应用及 Web 加速服务的稳定及连续性。

# 产品架构 [#产品架构]

<img src="/docs-assets/products/cdn/%281-product-introduction%29/0-product-overview-fusion/img-chanpinjiagou-334f1ae22a21e74d595dd0c9a42d294b67c0d0983d390b-5258f4a5607b.webp" width="800" />


# 名词解释 (/products/cdn/1-noun-explanation-fusion)



最近更新时间: 2021-02-04 14:17:15

# CNAME域名 [#cname域名]

在七牛云Portal创建加速域名后，会给域名分配一个 “CNAME域名”（例：example.qiniudns.com）。用户需要在域名服务商处配置一条主机记录为 example 的 CNAME 记录类型，并将需要记录值指向 example.qiniudns.com 。
生效后域名就会正式指向七牛云 CDN ，该域名所有的请求都开始享有CDN加速效果。

# DNS [#dns]

即 Domain Name System ，域名解析服务。把域名转换成为网络可以识别的 IP 地址（人们习惯记忆域名，但机器互相只认 IP ），能够使人更方便地访问互联网，它们之间的转换工作称为域名解析。

# 边缘节点 [#边缘节点]

距离最终用户最近的 CDN 节点，提高响应速度和连接速度，提高用户浏览网页视频的体验，边缘节点的主要工作是将访问量较大的网页内容和音视频等文件保存在服务器前端的专用缓存设备上。

# 源站 [#源站]

即客户的业务服务器。


# 功能特性 (/products/cdn/2-product-features-fusion)



最近更新时间: 2021-02-04 14:17:15

# 无盲区 [#无盲区]

沉淀多年的 CDN 管控经验，精选核心 CDN 高质量节点，实现覆盖全国的边缘节点架构体系，全面覆盖各地、各运营商的网络，实现全地域无盲区的覆盖。

# 智能调度 [#智能调度]

基于全网请求来源的智能调度系统，支持 DNS、HttpDNS、Http302 调度模式，有效提高访问响应速度，防止劫持，实现全网实时精准调度调度。

# 立体品控 [#立体品控]

基于权威 APM 的全网覆盖「性能监控」和七牛自研的监控数据为基础上自研的全网「实时可用性监控」，打造七牛 CDN 立体品控体系。

# 降低回源 [#降低回源]

自建 BGP 网络中间源，消除跨运营商网络回源慢甚至不可达等问题，保护源站带宽不受边缘节点请求波动影响，节省回源成本。

# 链路优化 [#链路优化]

七牛自研探测 AGENT，精确探测点到点之间的链路质量，凭借特有的链路决策算法，可以保证边缘节点到中间源再到源站直接的所有链路最优。

# 私有协议优化 [#私有协议优化]

使用私有传输协议作为 CDN 内部数据交换的基础，确保客户资源在 CDN 内部安全、快速的传输到各个节点，实现客户内容高效、可靠的进行分发。


# 使用场景 (/products/cdn/3-usage-scenarios-fusion)



最近更新时间: 2026-08-31 11:35:22

# 网页/小文件/图片加速 [#网页小文件图片加速]

网页静态资源优化加速分发，例如：html、css、js、img 等；全站 HTTPS 保证网站访问安全；自动图片瘦身， TCP 压缩优化使网页大图，样式等完成秒级加载，缩短网页响应时间提高用户体验。

配合七牛云-图片处理服务一起使用，还可以针对图片进行缩略、打水印，转格式等数据处理服务。

# 大文件下载 [#大文件下载]

大文件下载优化加速分发，例如：ipa、apk、mp3、exe、zip 等；七牛 CDN 在全球数千个节点，让用户在下载过程中获得更快的下载速度，并利用分段缓存技术提高了大文件下载传输的稳定性。

配合七牛云-存储服务一起使用，可有效降低回源和存储成本。

# 音视频点播服务 [#音视频点播服务]

音视频点播优化加速服务，例如：mp4、flv、rmvb、wmv、hls 等；七牛 CDN 利用 BGP 网络中间源技术降低回源带宽压力节省了用户回源成本、分段预取技术使用户在浏览音视频时更加的流畅，高级防盗链技术有效防止用户文件被盗用。

配合七牛云-音视频处理服务，还可以进行音视频转码、转格式、压缩等数据处理服务。


# CDN 产品价格说明 (/products/cdn/0-cdn-product-pricing)



最近更新时间: 2026-08-27 16:11:43

# 七牛云 CDN 计费说明 [#七牛云-cdn-计费说明]

七牛云 CDN 提供两种付费方式，默认计费方式为后付费按量计费。您也可使用 [CDN 价格计算器](https://www.qiniu.com/prices/qcdn?tab=calc) 进行用量预估；同时提供 [国内预付费资源包](https://qmall.qiniu.com/template/NTI?ref=category\&spec_combo=MTk0OA\&ref=doc) 和 [海外预付费资源包](https://qmall.qiniu.com/template/NTU?ref=category\&spec_combo=MjEzNA\&ref=doc)，可获得更优惠的价格。

## 目录 [#目录]

* [1. 按流量后付费](#sec-1)
  * [1.1 免费额度](#sec-1-1)
  * [1.2 价格详情](#sec-1-2)
  * [1.3 超额累进阶梯计费示例](#sec-1-3)
* [2. 按资源包预付费](#sec-2)
  * [2.1 资源包购买](#sec-2-1)
  * [2.2 资源包用量查询](#sec-2-2)
* [3. 常见问题](#sec-3)
  * [Q1. 开启 HTTPS 以后如何收费？](#q1-https-fee)
  * [Q2. 欠费以后还可以继续使用吗？](#q2-owe-service)
  * [Q3. 资源包可以叠加使用吗？抵扣顺序是什么？](#q3-pack-stack-order)
  * [Q4. 使用量超出资源包后如何计费？](#q4-over-pack-billing)
  * [Q5. 今天 8 点后购买的资源包，为什么没有进行抵扣？](#q5-resource-pack-no-deduction)

<a id="sec-1" />

## 1. 按流量后付费 [#1-按流量后付费]

七牛云 CDN 加速按国内流量和海外流量阶梯价格计费（动态加速在此基础上额外加收请求数费用），当月分别超额累进，以自然月为一个累计周期。

<a id="sec-1-1" />

### 1.1 免费额度 [#11-免费额度]

开通七牛云 CDN 并完成实名认证的用户即可享有以下免费额度：

* 每个分区（国内 + 海外各分区）10GB HTTP 下载流量
* 5 万次动态加速请求数

<a id="sec-1-2" />

### 1.2 价格详情 [#12-价格详情]

#### （1）国内流量价格 [#1国内流量价格]

| 名目                         | 流量阶梯（元/GB）       | 价格               |
| -------------------------- | ---------------- | ---------------- |
| HTTP 下载流量 / 动态加速 HTTP 流量   | 第 0 GB 至 10 GB   | 免费（仅限 HTTP 下载流量） |
| HTTP 下载流量 / 动态加速 HTTP 流量   | 第 10 GB 至 100 TB | 0.24             |
| HTTP 下载流量 / 动态加速 HTTP 流量   | 第 100 TB 至 1 PB  | 0.19             |
| HTTP 下载流量 / 动态加速 HTTP 流量   | 第 1 PB 以上        | 0.14             |
| HTTPS 下载流量 / 动态加速 HTTPS 流量 | 第 0 GB 至 100 TB  | 0.28             |
| HTTPS 下载流量 / 动态加速 HTTPS 流量 | 第 100 TB 至 1 PB  | 0.23             |
| HTTPS 下载流量 / 动态加速 HTTPS 流量 | 第 1 PB 以上        | 0.18             |

#### （2）海外流量价格 [#2海外流量价格]

| 名目                         | 流量阶梯（元/GB）       | 亚洲（港澳台/东南亚/印度）         | 亚洲（其他地区）               | 欧洲/北美洲                 | 南美洲                    | 大洋洲与其他                 |
| -------------------------- | ---------------- | ---------------------- | ---------------------- | ---------------------- | ---------------------- | ---------------------- |
| HTTP 下载流量 / 动态加速 HTTP 流量   | 第 0 GB 至 10 GB   | 免费（仅限 HTTP 下载流量）       | 免费（仅限 HTTP 下载流量）       | 免费（仅限 HTTP 下载流量）       | 免费（仅限 HTTP 下载流量）       | 免费（仅限 HTTP 下载流量）       |
| HTTP 下载流量 / 动态加速 HTTP 流量   | 第 10 GB 至 10 TB  | 0.76                   | 0.50                   | 0.34                   | 0.76                   | 0.94                   |
| HTTP 下载流量 / 动态加速 HTTP 流量   | 第 10 TB 至 50 TB  | 0.66                   | 0.44                   | 0.30                   | 0.66                   | 0.82                   |
| HTTP 下载流量 / 动态加速 HTTP 流量   | 第 50 TB 至 100 TB | 0.57                   | 0.38                   | 0.26                   | 0.57                   | 0.71                   |
| HTTP 下载流量 / 动态加速 HTTP 流量   | 第 100 TB 以上      | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 |
| HTTPS 下载流量 / 动态加速 HTTPS 流量 | 第 0 GB 至 10 TB   | 0.91                   | 0.60                   | 0.40                   | 0.91                   | 1.12                   |
| HTTPS 下载流量 / 动态加速 HTTPS 流量 | 第 10 TB 至 50 TB  | 0.79                   | 0.52                   | 0.36                   | 0.79                   | 0.98                   |
| HTTPS 下载流量 / 动态加速 HTTPS 流量 | 第 50 TB 至 100 TB | 0.68                   | 0.45                   | 0.31                   | 0.68                   | 0.85                   |
| HTTPS 下载流量 / 动态加速 HTTPS 流量 | 第 100 TB 以上      | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 |

说明：亚洲（港澳台/东南亚/印度）包含国家有港澳台、印度、越南、老挝、柬埔寨、缅甸、泰国、马来西亚、印度尼西亚、菲律宾、文莱、东帝汶。

#### （3）动态加速请求次数价格 [#3动态加速请求次数价格]

动态加速请求次数不分区域，全球统一价格。

| 名目      | 请求数         | 价格          |
| ------- | ----------- | ----------- |
| 动态加速请求数 | 第 0 次至 5 万次 | 免费          |
| 动态加速请求数 | 第 5 万次及以上   | 0.19 元 / 万次 |

<a id="sec-1-3" />

### 1.3 超额累进阶梯计费示例 [#13-超额累进阶梯计费示例]

假设用户 5 月只在中国大陆产生 HTTP 500 TB 下载流量，海外各大区均未产生消耗，根据国内 CDN 价格，各阶梯费用计算如下。

| 流量               | 单价（元/GB） | 本阶梯价格（元） | 累计价格（元） |
| ---------------- | -------- | -------- | ------- |
| 第 0 GB 至 10 GB   | 0        | 0        | 0       |
| 第 10 GB 至 10 TB  | 0.24     | 2455.2   | 2455.2  |
| 第 10 TB 至 500 TB | 0.19     | 95334.4  | 97789.6 |

<a id="sec-2" />

## 2. 按资源包预付费 [#2-按资源包预付费]

<a id="sec-2-1" />

### 2.1 资源包购买 [#21-资源包购买]

根据域名的加速范围，可以选择购买 [CDN 中国大陆资源包](https://qmall.qiniu.com/template/NTI?ref=category\&spec_combo=MTk0OA\&ref=doc) 或 [CDN 海外资源包](https://qmall.qiniu.com/template/NTU?ref=category\&spec_combo=MjEzNA\&ref=doc)。以下主要以国内资源包购买为例说明选择资源包的购买。

![资源包购买示意](/docs-assets/products/cdn/%282-buying-guide%29/0-cdn-product-pricing/FhCNYEZECEdzwl1cnQVNBR1yj_xM-b33a12f2cc6e.webp)

#### （1）资源包类型 [#1资源包类型]

“CDN 下行通用流量”适用于 http 和 https 的静态或动态加速下行流量，其中 http 和 https 协议按照 1:1.15 的系数抵扣，https 协议不额外收取静态加速请求次数费用。（自 2020 年 11 月 19 日开始，CDN 资源包更新为 CDN 融合资源包，可同时抵扣多种协议和场景的商品，历史已购买的分协议资源包使用不受影响。）

> 如何理解系数？实际使用 https 流量 100GB，相当于抵扣资源包流量 115GB。资源包的额度可以理解成诸如“点数”的概念，同单位的不同商品需要抵扣的点数不同。

> 按什么顺序抵扣？当资源包额度充足时（账单额度 \< 资源包余量），资源包可全部抵扣金额；当资源包额度不够时（账单额度 \< 资源包余量），按以下顺序抵扣：静态加速 HTTP、静态加速 HTTPS、动态加速 HTTP、动态加速 HTTPS。

#### （2）可用区域 [#2可用区域]

可根据域名的实际加速区域选择资源包的可用区域；如果加速区域为全球，可能同时产生国内流量和海外流量。

#### （3）可用时段 [#3可用时段]

为方便不同类型的用户优化 CDN 成本，七牛提供以下几种时段的资源包：

1. 全时段流量包：全时段指每天 0:00 - 24:00
2. 日间时段流量包：日间时段指每天 09:00 - 18:00
3. 闲时流量包：闲时段指每天 00:00 - 09:00

叠加使用规则和抵扣顺序参考 [Q3. 资源包可以叠加使用吗？抵扣顺序是什么？](#q3-pack-stack-order)

#### （4）用量额度（用量预估） [#4用量额度用量预估]

可根据实际使用需求预估资源包大小；额度越大单价越高，建议可预估一年用量购买。

可以根据历史用量预估资源包需求：在管理控制台页面进入 CDN，选择 [统计分析](https://portal.qiniu.com/cdn/statistics/usage) ，查看“用量统计”，支持按照域名维度、协议维度（http/https）、地区维度进行筛选查看；同时在流量趋势图上支持单独查看闲时、日间流量。

![用量统计示意](/docs-assets/products/cdn/%282-buying-guide%29/0-cdn-product-pricing/FlT8hRZpGKUnCizzzNWdRjPr3VNkwp-ab0bddbe63aa.webp)

#### （5）分配方式 [#5分配方式]

一次性分配资源包的流量在生效期内均可使用。

<a id="sec-2-2" />

### 2.2 资源包用量查询 [#22-资源包用量查询]

由于七牛目前按量付费资源采取月结算模式，系统每天 8 点左右将根据用户已使用的用量进行计费，更新一次按量计费预估，即按量计费预估为预估账单和余额预扣除，没有实际完成扣除，所以默认情况下，资源包的余量需要每个月完成月账单出账后更新状态，我们也可以通过下面的方法预估算资源包的使用情况。

#### （1）查看资源包余量 [#1查看资源包余量]

在 [管理控制台](https://portal.qiniu.com/financial/overview) 页面右上角选择“费用”，订单管理选择 [资源包管理](https://portal.qiniu.com/financial/orders/respack-mgr/current)，筛选需要查看的资源包，点击“详情”。

您可以看到当前资源包的剩余可用量以及历史每月账单结算后资源包的抵扣情况。

#### （2）查看本月预抵扣明细 [#2查看本月预抵扣明细]

注：按量计费预估每日 8 点更新，更新用量的使用时间是截止本日 0 点，非实时动态更新。

在 [管理控制台](https://portal.qiniu.com/financial/overview) 页面选择“财务中心”，账单管理选择 [按量计费预估](https://portal.qiniu.com/financial/orders)，查看从“上次月账单结算完成后”到“当日 0 点”的预估账单，参考下图，账单中可以下载“资源包抵扣明细”，抵扣明细中包含本月可用量 / 当前已用 / 本月剩余可用等参数。

<a id="sec-3" />

## 3. 常见问题 [#3-常见问题]

<a id="q1-https-fee" />

### Q1. 开启 HTTPS 以后如何收费？ [#q1-开启-https-以后如何收费]

域名开启 HTTPS 配置以后，该域名下所有流量（包括 HTTPS 和 HTTP 请求）即开始按照 HTTPS 协议的价格进行收费。HTTPS 域名产生的用量不计入免费额度，静态加速下 HTTPS 协议不额外收请求次数费用。对于月中升级为 https 的用户，本月计量都按照 https 计算。

默认配置下可兼容 HTTP 和 HTTPS 两种协议的请求，如需强制 HTTPS 访问，请在控制台开启“强制 HTTPS 访问”配置。

<a id="q2-owe-service" />

### Q2. 欠费以后还可以继续使用吗？ [#q2-欠费以后还可以继续使用吗]

欠费以后，无法新增域名和修改域名。更多信息请见：

* [欠费状态下各产品的限制功能](/account/0-owe-the-protection-limit-function)
* [新版欠费流程](/faq/account-finance/account-problem/5996-new-owe-the-process-description)

<a id="q3-pack-stack-order" />

### Q3. 资源包可以叠加使用吗？抵扣顺序是什么？ [#q3-资源包可以叠加使用吗抵扣顺序是什么]

资源包可叠加购买，出账时将按照以下规则进行抵扣：

![资源包抵扣顺序示意](/docs-assets/products/cdn/%282-buying-guide%29/0-cdn-product-pricing/FiDJc7qCvgUYYjQ_YpRpljIwEbwY-056b90b7e8b4.webp)

<a id="q4-over-pack-billing" />

### Q4. 使用量超出资源包后如何计费？ [#q4-使用量超出资源包后如何计费]

在资源包生效期间内，若当月用量超出可用资源包额度，出账时将优先抵扣完资源包额度，超出部分再按照官网 [CDN 后付费价格](https://www.qiniu.com/prices) 结算。

<a id="q5-resource-pack-no-deduction" />

### Q5. 今天 8 点后购买的资源包，为什么没有进行抵扣？ [#q5-今天-8-点后购买的资源包为什么没有进行抵扣]

按量计费预估每日 8 点更新，更新用量的使用时间是截止本日 0 点，非实时动态更新。当月生效的资源包，您可以在购买后第二天，在财务中心查看按量计费预估账单。


# 快速入门 (/products/cdn/0-fusion-quick-start)



最近更新时间: 2026-05-08 14:30:03

欢迎查看 cdn 帮助文档。您可以在任意时间地点使用七牛云 CDN 加速，以提供稳定快速的网络访问质量。

通过完成本快速入门指南中的步骤，您将成功绑定域名、配置 cname 、刷新预取、查询CDN流量宽带或是下载 CDN 日志。

七牛云为空间资源提供测试域名，该类域名的源站为域名所在空间，缓存设置时间 1个月，无法配置防盗链配置且不能配置 cname。鉴于它的诸多限制，建议您添加自定义域名使用。

为了顺利完成快速入门，您需要一个七牛云账号。如果您还没有七牛云账号，请通过以下步骤创建七牛云账号。

# 注册七牛云 [#注册七牛云]

1. 打开 [七牛开发者平台](https://portal.qiniu.com/)，选择 **注册**。
2. 遵循在线使用说明。

本快速入门指南涵盖以下内容：

* [Step 1：添加自定义域名](#step1)
* [Step 2：查询CDN流量带宽](#step2)
* [Step 3：下载CDN日志](#step3)

# 要求 [#要求]

* 域名已备案，且可以做域名解析；
* 账号已完成实名认证；

说明：域名配置不产生费用

<a id="step1" />

# 步骤1：添加自定义域名 [#步骤1添加自定义域名]

1. 登陆[七牛开发者平台](https://portal.qiniu.com/signin)。

2. **方式1**:

   选择 **控制台** ,然后选择 **添加加速域名** 。

   <img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/Fg6noo41nRrOns7B4CffwjACfNo5-f424419b999d.webp" width="800" />

   <img />

   **方式2**:

   点击 **产品与方案** ,然后选择 **CDN** 。

   <img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FjUB6Q8vI5gWV7cQFxMAm9kHxEdi-2650dd379f07.webp" width="800" />

   <img />

   操作完 方式1 或者 方式2 之后，会出现 **创建域名** 界面。

   <img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FiAJMJZYgmQQmUHOIlQ3CtGqB_G1-d26206ce56b0.webp" width="800" />

   <img />

   **注意**：

   如果您界面上方显示的是 **未完成实名认证** ，如下图所示：

   <img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FiaUFWtD_pYjdDjl3BGNetgssptH-0b314a2c576b.webp" width="800" />

   <img />

   此时您需要在 **个人中心** 进行实名认证

   <img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FoHa6DsnyltAMIkyX64jwwO9RPCs-66948064de9f.webp" width="800" />

   <img />

   此外，请您确认您的绑定域名是否是已备案的状态，您可以在[域名信息备案系统](http://beian.miit.gov.cn/state/outPortal/loginPortal.action)查询。

3.在 **创建加速域名** 界面，在 **域名类型** 栏选择域名类型。域名类型包含：普通域名，泛域名，泛子域名。

* 普通域名，是指您的主域名下的子域名。例如主域名qiniu.com，developer.qiniu.com是其二级域名，a.developer.qiniu.com是其三级域名,.....,这些都属于普通域名。
* 泛域名，是指域名\*.主域名，配置成功后可任意指定前缀进行访问；可基于该泛域名创建多个泛子域名来指定不同源站，例如泛域名 \*.qiniu.com。
* 泛子域名，基于泛域名创建的子域名；可独立指定源站，其它配置继承泛域名。

4.在 **创建加速域名** 界面，在 **加速域名** 栏填写**已备案**的域名。

5.在 **创建加速域名** 界面，在 **通信协议** 栏选择所需的通信协议。您可以选择 https 通信协议或者 http 通信协议。如果您选择 https协议，您还需上传有效期≥30天的 HTTPS 证书。（注：为了不影响正常使用，证书到期后请及时续期）

6.在 **创建加速域名** 界面，在 **使用场景** 栏选择所在的使用场景。使用场景分为图片小文件，下载分发和点播平台。

* 图片小文件，适用于网页、图片、小文件
* 下载分发，适用于文件下载，例如安装包，压缩包等二进制大文件
* 点播平台，适用于需要MP4/FLV等文件按照时间点进行播放
* 动态加速，适用于电商、社交、社区论坛、金融支付和游戏娱乐等方面

7.在 **创建加速域名** 界面，在 **源站配置** 栏选择源站。可以选择七牛云存储，源站域名，IP地址，高级设置。

* 七牛云存储，选择您的七牛云空间，您将需要加速的资源上传到空间 或者 您可以设置**空间镜像**，这样您的资源会更快的迁移到七牛云空间（如何设置空间[镜像存储](/products/kodo/kodo-console-guide/bucket-management/space-settings/8-set-up-the-mirror-back-to-the-source)）。
* 源站域名，填写您的源站域名，不能与**加速域名**相同。**源站测试**中需要您填写您需要加速的资源名，通过源站测试，表明源站配置正确。
* IP地址，填写您源站的IP地址，**源站测试**中需要您填写您需要加速的资源名，通过源站测试，表明源站配置正确。
* 高级配置，设置多个主线路或者备线路，访问请求根据权重分配。

8.在 **创建加速域名** 界面， **高级配置** 可以在创建域名时设置，即选择 **显示** ，此时您可以设置：

* **域名防盗链**
* **时间戳防盗链**
* **缓存配置**
* **图片处理**

9.在 **创建加速域名** 界面，选择 **创建** ，此时创建成功。

注：**7** 和 **8** 所设置的配置可以在创建之后可以修改。在 **七牛开发者平台** - **产品与方案** 页面选择 **CDN** ，选择 **域名管理** ，根据需要，选择您需要配置的 **域名** ，点击 **配置** 。

<img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FjUB6Q8vI5gWV7cQFxMAm9kHxEdi-2650dd379f07.webp" width="800" />

<img />

<img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/Fom_oMwEB56QxZXcxFDjn0plMvnz-9cd8d125eda6.webp" width="800" />

<img />

在 **配置** 界面，根据需要，可以修改 **回源配置** ， **缓存配置** ， **访问控制** ，**HTTPS配置** ， **图片优化** ，**HTTP 响应头配置**。

<img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/Fjv_F1RI4xldmu2vrPsIHiaELJBG-01b297b884aa.webp" width="800" />

<img />

<img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FioGkG46V5c0TLWG65kLL2Pa6NEL-ec86055dcfd9.webp" width="800" />

<img />

![image.png](/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FnXaxo7V1xwT_0hjdk_rv6tCAkL6-2a1a048723b6.webp)
![image.png](/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FnvqC9D6NyZ74vLYFJLx0rb6et7p-cb27189e64d3.webp)

<img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FjfnHpyyPlFjDaQ6GTzZXse5Fktu-ab41341c395f.webp" width="800" />

<img />

<img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FjfnHpyyPsdrgelFjDaQse6GTzZXse5Fkt-0c0bf995db60.webp" width="800" />

<img />

10.创建加速域名成功后，七牛云会提供cname地址。
选择 **CDN** ，在 **域名管理** 界面选择创建好的 **域名** ，点击 **配置** ，提供的cname在红框中标注。您可以点击**帮助** ，参考链接 **如何配置CNAME** 配置cname值。

<img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/Fj1lPg45-pBl_-dPugqlySTYEUM-2e276692955d.webp" width="800" />

<img />

<a id="step2" />

# 步骤2：查看CDN流量带宽 [#步骤2查看cdn流量带宽]

选择 **CDN** ，选择 **域名管理** ，选择您需要查看的 **域名** ，点击 **统计** 。
![image.png](/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FuirXasJhboMT_q6-tAbn6x0UhD0-14a9fa27dacb.webp)
或者选择 **CDN** ，选择 **统计分析** ，选择 **用量统计** 选择需要查看的 **域名** 。
![image.png](/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FoskNovD610muPqmUOJDeQ1BYNPi-e6fab9f10c84.webp)

在页面中间部分的红框处显示选中域名的CDN流量/宽带，通过点击按钮进行切换。
![image.png](/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/Fpbbyy_6OXFBMDLB9-GlMEU0ZaJv-60b45533c4a3.webp)

# 步骤3：下载CDN日志 [#步骤3下载cdn日志]

选择 **CDN** ，选择 **日志下载** ，设定搜索条件，点击 **查看日志** ，选择您具体需要查看的日志，点击 **下载** ，即可将日志下载到本地进行查看。

<img src="/docs-assets/products/cdn/%283-quick-start%29/0-fusion-quick-start/FpXM1nfUMYIQ0c8FG_8alEE2zBOd-4820b40a52cc.webp" width="800" />

<img />


# 海外加速节点 (/products/cdn/0-overseas-nodes)



最近更新时间: 2023-12-12 15:23:34

## 七牛全球下载加速的海外一览表 [#七牛全球下载加速的海外一览表]

| 大洲                  | 国家                   |          | 城市               |         |
| ------------------- | -------------------- | -------- | ---------------- | ------- |
| 北美（North America）   | Canada               | 加拿大      | Calgary          | 卡尔加里    |
|                     | Canada               | 加拿大      | Montréal         | 蒙特利尔    |
|                     | Canada               | 加拿大      | Ottawa           | 渥太华     |
|                     | Canada               | 加拿大      | Saskatoon        | 萨斯卡通    |
|                     | Canada               | 加拿大      | Toronto          | 多伦多     |
|                     | Canada               | 加拿大      | Vancouver        | 温哥华     |
|                     | Canada               | 加拿大      | Winnipeg         | 温尼伯     |
|                     | United States        | 美国       | Honolulu         | 火奴鲁鲁    |
|                     | United States        | 美国       | Houston          | 休斯顿     |
|                     | United States        | 美国       | Indianapolis     | 印第安纳波利斯 |
|                     | United States        | 美国       | Jacksonville     | 杰克逊维尔   |
|                     | United States        | 美国       | Kansas City      | 堪萨斯城    |
|                     | United States        | 美国       | Las Vegas        | 拉斯维加斯   |
|                     | United States        | 美国       | Los Angeles      | 洛杉矶     |
|                     | United States        | 美国       | Richmond         | 里士满     |
|                     | United States        | 美国       | Ashburn          | 阿什伯恩    |
|                     | United States        | 美国       | Atlanta          | 亚特兰大    |
|                     | United States        | 美国       | Boston           | 波斯顿     |
|                     | United States        | 美国       | Buffalo          | 布法罗     |
|                     | United States        | 美国       | Charleston       | 查尔斯顿    |
|                     | United States        | 美国       | Charlotte        | 夏洛特     |
|                     | United States        | 美国       | Chicago          | 芝加哥     |
|                     | United States        | 美国       | Columbus         | 哥伦布     |
|                     | United States        | 美国       | Council Bluffs   | 康瑟尔布拉夫斯 |
|                     | United States        | 美国       | Dallas           | 达拉斯     |
|                     | United States        | 美国       | Denver           | 丹佛      |
|                     | United States        | 美国       | Detroit          | 底特律     |
|                     | United States        | 美国       | Lenoir           | 勒努瓦     |
|                     | United States        | 美国       | Mcallen          | 麦卡伦     |
|                     | United States        | 美国       | Memphis          | 孟菲斯     |
|                     | United States        | 美国       | Miami            | 迈阿密     |
|                     | United States        | 美国       | Minneapolis      | 明尼阿波利斯  |
|                     | United States        | 美国       | Montgomery       | 蒙哥马利    |
|                     | United States        | 美国       | Nashville        | 纳什维尔    |
|                     | United States        | 美国       | New York         | 纽约市     |
|                     | United States        | 美国       | Newark           | 纽瓦克     |
|                     | United States        | 美国       | Norfolk          | 诺福克     |
|                     | United States        | 美国       | Omaha            | 奥马哈     |
|                     | United States        | 美国       | Philadelphia     | 费城      |
|                     | United States        | 美国       | Phoenix          | 凤凰      |
|                     | United States        | 美国       | Pittsburgh       | 匹兹堡     |
|                     | United States        | 美国       | Portland         | 波特兰     |
|                     | United States        | 美国       | Sacramento       | 沙加缅度    |
|                     | United States        | 美国       | Salt Lake City   | 盐湖城     |
|                     | United States        | 美国       | San Diego        | 圣地亚哥    |
|                     | United States        | 美国       | San Francisco    | 旧金山市    |
|                     | United States        | 美国       | San Jose         | 圣荷西     |
|                     | United States        | 美国       | Seattle          | 西雅图     |
|                     | United States        | 美国       | St. Louis        | 圣路易斯    |
|                     | United States        | 美国       | Tallahassee      | 塔拉哈西    |
|                     | United States        | 美国       | Tampa            | 坦帕      |
|                     | United States        | 美国       | The Dalles       | 达尔斯     |
|                     | United States        | 美国       | Tulsa            | 塔尔萨     |
| 大洋洲（Oceania）        | Australia            | 澳大利亚     | Adelaide         | 阿德莱德    |
|                     | Australia            | 澳大利亚     | Brisbane         | 布里斯班    |
|                     | Australia            | 澳大利亚     | Melbourne        | 墨尔本     |
|                     | Australia            | 澳大利亚     | Perth            | 珀斯      |
|                     | Australia            | 澳大利亚     | Sydney           | 悉尼      |
|                     | New Caledonia        | 新喀里多尼亚   | Noumea           | 努美阿     |
|                     | New Zealand          | 新西兰      | Auckland         | 奥克兰市    |
| 非洲（Africa）          | Angola               | 安哥拉      | Luanda           | 罗安达     |
|                     | Djibouti             | 吉布提      | Djibouti         | 吉布地     |
|                     | Egypt                | 埃及       | Cairo            | 开罗      |
|                     | France               | 法国       | Reunion          | 团圆      |
|                     | Kenya                | 肯尼亚      | Mombasa          | 蒙巴萨     |
|                     | Madagascar           | 马达加斯加    | Antananarivo     | 塔那那利佛   |
|                     | Mauritius            | 毛里求斯     | Port Louis       | 路易港     |
|                     | Morocco              | 摩洛哥      | Casablanca       | 卡萨布兰卡   |
|                     | Mozambique           | 莫桑比克     | Maputo           | 马普托     |
|                     | Nigeria              | 尼日利亚     | Lagos            | 拉各斯     |
|                     | Rwanda               | 卢旺达      | Kigali           | 基加利     |
|                     | Senegal              | 塞内加尔     | Dakar            | 达喀尔     |
|                     | South Africa         | 南非       | Cape Town        | 开普敦     |
|                     | South Africa         | 南非       | Durban           | 德班      |
|                     | South Africa         | 南非       | Johannesburg     | 约翰内斯堡   |
|                     | Tanzania             | 坦桑尼亚     | Dar Es Salaam    | 达累斯萨拉姆  |
| 拉丁美洲（South America） | Argentina            | 阿根廷      | Buenos Aires     | 布宜诺斯艾利斯 |
|                     | Argentina            | 阿根廷      | Cordoba          | 科尔多瓦    |
|                     | Argentina            | 阿根廷      | Neuquen          | 内乌肯     |
|                     | Brazil               | 巴西       | Curitiba         | 库里提巴    |
|                     | Brazil               | 巴西       | Fortaleza        | 福塔雷萨    |
|                     | Brazil               | 巴西       | Porto Alegre     | 阿雷格里港   |
|                     | Brazil               | 巴西       | Rio de Janeiro   | 里约热内卢   |
|                     | Brazil               | 巴西       | São Paulo        | 圣保罗     |
|                     | Chile                | 智利       | Arica            | 阿里卡     |
|                     | Chile                | 智利       | Valparaíso       | 瓦尔帕莱索   |
|                     | Colombia             | 哥伦比亚     | Bogota           | 波哥大     |
|                     | Colombia             | 哥伦比亚     | Medellín         | 麦德林     |
|                     | Curacao              | 库拉索      | Willemstad       | 威廉斯塔德   |
|                     | Ecuador              | 厄瓜多尔     | Quito            | 基多      |
|                     | Grenada              | 格林纳达     | St George’s      | 圣乔治     |
|                     | Guatemala            | 危地马拉     | Guatemala City   | 危地马拉城   |
|                     | Haiti                | 海地       | Port-Au-Prince   | 太子港     |
|                     | Mexico               | 墨西哥      | Mexico City      | 墨西哥城    |
|                     | Mexico               | 墨西哥      | Queretaro        | 克雷塔罗    |
|                     | Panama               | 巴拿马      | Panama City      | 巴拿马城    |
|                     | Paraguay             | 巴拉圭      | Asuncion         | 亚松森     |
|                     | Peru                 | 秘鲁       | Lima             | 利马      |
|                     | Chile                | 智利       | Santiago         | 圣地亚哥    |
| 欧洲（Europe）          | Belgium              | 比利时      | St. Ghislain     | 圣吉斯兰    |
|                     | Bulgaria             | 保加利亚     | Sofia            | 索非亚     |
|                     | Finland              | 芬兰       | Hamina           | 哈米纳     |
|                     | Germany              | 德国       | Frankfurt        | 法兰克福    |
|                     | Netherlands          | 荷兰       | Groningen        | 格罗宁根    |
|                     | Austria              | 奥地利      | Vienna           | 维也纳     |
|                     | Belgium              | 比利时      | Brussels         | 布鲁塞尔    |
|                     | Bulgaria             | 保加利亚     | Sofia            | 苏菲亚     |
|                     | Croatia              | 克罗地亚     | Zagreb           | 萨格勒布    |
|                     | Cyprus               | 塞浦路斯     | Nicosia          | 尼科西亚    |
|                     | Czech Republic       | 捷克       | Prague           | 布拉格     |
|                     | Denmark              | 丹麦       | Copenhagen       | 哥本哈根    |
|                     | Estonia              | 爱沙尼亚     | Tallinn          | 塔林      |
|                     | Finland              | 芬兰       | Helsinki         | 赫尔辛基    |
|                     | France               | 法国       | Marseille        | 马赛      |
|                     | France               | 法国       | Paris            | 巴黎      |
|                     | Germany              | 德国       | Berlin           | 柏林      |
|                     | Germany              | 德国       | Düsseldorf       | 杜塞尔多夫   |
|                     | Germany              | 德国       | Frankfurt        | 法兰克福    |
|                     | Germany              | 德国       | Hamburg          | 汉堡      |
|                     | Germany              | 德国       | Munich           | 慕尼黑     |
|                     | Greece               | 希腊       | Athens           | 雅典      |
|                     | Greece               | 希腊       | Thessaloniki     | 塞萨洛尼基   |
|                     | Hungary              | 匈牙利      | Budapest         | 布达佩斯    |
|                     | Iceland              | 冰岛       | Reykjavík        | 雷克雅未克   |
|                     | Ireland              | 爱尔兰      | Cork             | 软木      |
|                     | Ireland              | 爱尔兰      | Dublin           | 都柏林     |
|                     | Italy                | 意大利      | Milan            | 米兰      |
|                     | Italy                | 意大利      | Rome             | 罗马      |
|                     | Latvia               | 拉脱维亚     | Riga             | 里加      |
|                     | Lithuania            | 立陶宛      | Vilnius          | 维尔纽斯    |
|                     | Luxembourg           | 卢森堡      | Luxembourg City  | 卢森堡市    |
|                     | Moldova              | 摩尔多瓦     | Chișinău         | 基希讷乌    |
|                     | Netherlands          | 荷兰       | Amsterdam        | 阿姆斯特丹   |
|                     | Norway               | 挪威       | Oslo             | 奥斯陆     |
|                     | Poland               | 波兰       | Warsaw           | 华沙      |
|                     | Portugal             | 葡萄牙      | Lisbon           | 里斯本     |
|                     | Romania              | 罗马尼亚     | Bucharest        | 布加勒斯特   |
|                     | Russia               | 俄罗斯      | Moscow           | 莫斯科     |
|                     | Russia               | 俄罗斯      | St. Petersburg   | 圣彼得堡    |
|                     | Serbia               | 塞尔维亚     | Belgrade         | 贝尔格莱德   |
|                     | Spain                | 西班牙      | Barcelona        | 巴塞罗纳    |
|                     | Spain                | 西班牙      | Madrid           | 马德里     |
|                     | Sweden               | 瑞典       | Goteburg         | 哥德堡     |
|                     | Sweden               | 瑞典       | Stockholm        | 斯德哥尔摩   |
|                     | Switzerland          | 瑞士       | Geneva           | 日内瓦     |
|                     | Switzerland          | 瑞士       | Zürich           | 苏黎世     |
|                     | Turkey               | 土耳其      | Istanbul         | 伊斯坦堡    |
|                     | Ukraine              | 乌克兰      | Kyiv             | 基辅      |
|                     | United Kingdom       | 英国       | Edinburgh        | 爱丁堡     |
|                     | United Kingdom       | 英国       | London           | 伦敦      |
|                     | United Kingdom       | 英国       | Manchester       | 曼彻斯特    |
| 亚洲（Asia Pacific）    | China                | 中国       | Changhua County  | 彰化县     |
|                     | Bangladesh           | 孟加拉国     | Chittagong       | 吉大港市    |
|                     | Bangladesh           | 孟加拉国     | Dhaka            | 达卡      |
|                     | Bhutan               | 不丹       | Thimphu          | 廷布      |
|                     | Cambodia             | 柬埔寨      | Phnom Penh       | 金边      |
|                     | China                | 中国       | Hong Kong        | 香港      |
|                     | India                | 印度       | Bengaluru        | 班加罗尔    |
|                     | India                | 印度       | Chennai          | 钦奈      |
|                     | India                | 印度       | Hyderabad        | 海得拉巴    |
|                     | India                | 印度       | Kolkata          | 加尔各答    |
|                     | India                | 印度       | Mumbai           | 孟买      |
|                     | India                | 印度       | Nagpur           | 那格浦尔    |
|                     | India                | 印度       | New Delhi        | 新德里     |
|                     | Indonesia            | 印度尼西亚    | Jakarta          | 雅加达     |
|                     | Japan                | 日本       | Osaka            | 大阪      |
|                     | Japan                | 日本       | Tokyo            | 东京      |
|                     | Korea                | 韩国       | Seoul            | 汉城      |
|                     | China                | 中国       | Macau            | 澳门      |
|                     | Malaysia             | 马来西亚     | Kuala Lumpur     | 吉隆坡     |
|                     | Maldives             | 马尔代夫     | Male             | 马累      |
|                     | Mongolia             | 蒙古       | Ulaanbaatar      | 乌兰巴托    |
|                     | Nepal                | 尼泊尔      | Kathmandu        | 加德满都    |
|                     | Pakistan             | 巴基斯坦     | Islamabad        | 伊斯兰堡    |
|                     | Pakistan             | 巴基斯坦     | Karachi          | 卡拉奇     |
|                     | Pakistan             | 巴基斯坦     | Lahore           | 拉合尔     |
|                     | Philippines          | 菲律宾      | Cebu City        | 宿雾市     |
|                     | Philippines          | 菲律宾      | Manila           | 马尼拉     |
|                     | Republic of Armenia  | 亚美尼亚共和国  | Yerevan          | 叶里温     |
|                     | Singapore            | 新加坡      | Singapore        | 新加坡     |
|                     | Sri Lanka            | 斯里兰卡     | Colombo          | 科伦坡     |
|                     | China                | 中国       | Taipei           | 台北      |
|                     | Thailand             | 泰国       | Bangkok          | 曼谷      |
|                     | Vietnam              | 越南       | Hanoi            | 河内      |
|                     | Vietnam              | 越南       | Ho Chi Minh City | 胡志明市    |
| 中东（Middle East）     | United Arab Emirates | 阿拉伯联合酋长国 | Fujairah         | 富查伊拉    |
|                     | Azerbaijan           | 阿塞拜疆     | Baku             | 巴库      |
|                     | Bahrain              | 巴林       | Manama           | 麦纳麦     |
|                     | Iraq                 | 伊拉克      | Baghdad          | 巴格达     |
|                     | Israel               | 以色列      | Tel Aviv         | 特拉维夫    |
|                     | Jordan               | 约旦       | Amman            | 安曼      |
|                     | Kuwait               | 科威特      | Kuwait City      | 科威特城    |
|                     | Lebanon              | 黎巴嫩      | Beirut           | 贝鲁特     |
|                     | Oman                 | 阿曼       | Muscat           | 马斯喀特    |
|                     | Palestine            | 巴勒斯坦     | Ramallah         | 拉马拉     |
|                     | Qatar                | 卡塔尔      | Doha             | 多哈      |
|                     | Saudi Arabia         | 沙特阿拉伯    | Riyadh           | 利雅得     |
|                     | United Arab Emirates | 阿拉伯联合酋长国 | Dubai            | 迪拜      |


# 绑定加速域名和域名解析流程 (/products/cdn/1-custom-domain-name-binding-process)



最近更新时间: 2026-08-12 17:56:52

在七牛控制台配置 CDN 加速服务时，需要进行以下两个步骤：

1. 绑定加速域名
2. 绑定成功后，七牛会提供一条 CNAME 记录值，需要为该域名配置这条 CNAME 记录，将加速域名 CNAME 解析到七牛提供的 CNAME 地址。

# 绑定加速域名 [#绑定加速域名]

## 场景描述 [#场景描述]

存储空间 bucket01 中存放了许多图片文件，现在要为这个空间绑定一个域名进行 cdn 加速。

## 域名参考 [#域名参考]

注意：一个域名不能同时进行 cname 和 A 记录

如果网站的首页为 [www.qiniu.com](http://www.qiniu.com) ，并且已经进行了 A 记录，再使用该域名绑定自定义域名，会导致不能正常访问。所以这里我们这里绑定一个未被解析使用的二级域名，例如：images.qiniu.com

## 操作流程 [#操作流程]

在存储空间 bucket01 里找到 域名绑定 栏目点击添加。

进行加速域名配置。选项如下：

| 域名类型 | 默认                |
| ---- | ----------------- |
| 加速域名 | images.qiniu.com  |
| 覆盖范围 | 默认（只在国内访问）        |
| 通信协议 | 默认（HTTP）          |
| 使用场景 | 默认（图片小文件）         |
| 源站配置 | 默认（存储空间 bucket01） |

创建后控制台会回到存储空间 bucket01 中，可以在 CDN 加速域名 区域看到刚才我们添加的 images.qiniu.com 域名，状态为 处理中。

进入域名信息界面（点击加速域名后会直接跳转），域名信息一栏显示：域名正在创建处理中；域名配置完成后会显示 CNAME

这里我们耐心等待一下，通常 8 到 15 分钟就可以处理完毕（如果超时的话您可以直接提交工单，我们会尽快为您解决问题）

域名处理完成后，我们已经可以看到 CNAME 后面已经有了内容。

# 域名解析 [#域名解析]

域名解析需要在第三方的域名 DNS 解析服务提供商处完成，通常是购买域名的域名商。

首先登陆到第三方域名服务提供商的 DNS 解析界面, 找到加速域名的主域名 qiniu.com，添加一条 DNS 记录，其中需要修改的有3个字段:
主机值 ：images
记录类型 ：CNAME
记录值: 在七牛控制台的域名管理界面通过 “复制 CNAME”得到

其他字段如线路、TTL 值使用默认值即可。

添加该记录后，需要一些时间等待解析 DNS 完成，您可以在控制台界面查看 CNAME 解析状态。

1. 若状态显示“等待 CNAME”，表示七牛仍然在等待域名解析提供商返回解析结果；
2. 若状态显示"成功"，表示域名已经成功解析到七牛 CDN 节点，可以使用该域名作为空间 bucket01 的文件访问外链域名。
   示例：
   若空间 bucket01 已经配置加速域名 images.qiniu.com 完成，访问空间中的 “apple.png” 图片可使用如下外链获得加速访问效果：
   `http://images.qiniu.com/apple.png`


# 刷新预取 (/products/cdn/2-refresh-the-prefetch-fusion)



最近更新时间: 2026-08-12 17:56:52

刷新分为刷新文件、刷新目录两种方式，刷新文件是以文件为单位将缓存在CDN节点上对应的资源进行清除。刷新目录是以目录为单位，将目录下的所有缓存在CDN节点上的文件进行清除。文件预取是以文件为单位进行资源预热。

动态加速每次请求都会回源，因此该场景下不提供刷新预取服务。

<br />

# 操作说明 [#操作说明]

登录**七牛管理控制台**后，进入**CDN控制台**，选择【刷新预取】，进入配置界面：

![刷新预取.jpeg](/docs-assets/products/cdn/%284-development-guidelines%29/2-refresh-the-prefetch-fusion/FnMH3lvpNJGRkb7OSu7q9ZUfRQO0-bb3b09383138.webp)

### 文件刷新 [#文件刷新]

选择【文件刷新】后，在输入框中输入需要刷新的URL；输入时，多个 URL 请用回车换行分隔，每个 URL 应当以 `http://` 或 `https:// `开头， 例如 `http://www.example.com/index.html`；提交后，您可以在页面中看到今日剩余的文件刷新量。

![文件刷新.jpeg](/docs-assets/products/cdn/%284-development-guidelines%29/2-refresh-the-prefetch-fusion/FsjHuqL6CSo_IecSBdNGJQHkcJYZ-ad9f93e13af2.webp)

**注：文件刷新每天限额 500 个，单次提交文件刷新最多20个。**

### 目录刷新 [#目录刷新]

选择【目录刷新】后，在输入框中输入需要刷新的目录，目录必须以 `「/」` 结尾例如：`http://www.example.com/`；提交后，您可以在页面中看到今日剩余的目录刷新量。

![目录刷新.jpeg](/docs-assets/products/cdn/%284-development-guidelines%29/2-refresh-the-prefetch-fusion/FmGRfLXqdeIYcaZ0Pq8CCp8SG8kW-1b2a0cc044a4.webp)

**注：目录刷新每天限额 10 个。**

### 文件预取 [#文件预取]

选择【文件预取】后，输入框中输入需要预取的文件路径，提交后，您可以在页面中看到今日剩余的目录刷新量。；每个 URL 应当以 `http://` 或 `https:// `开头， 例如 `http://www.example.com/index.html`。

![文件预取.jpeg](/docs-assets/products/cdn/%284-development-guidelines%29/2-refresh-the-prefetch-fusion/FvejdwpSh5cyTABXjvPWv2Q_m5Ll-3c4970f75efa.webp)

**注：文件预取每天限额 100 个。**

### 操作记录 [#操作记录]

选择【操作记录】可以查询最近7天左右提交的缓存刷新或文件预取的操作记录，可以查询具体的URL，提交时间以及状态信息，状态信息包含：正在处理、成功、失败三种类型。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/2-refresh-the-prefetch-fusion/Fuko3jK49nMvMdEw5yH9j2mPMOR4-3c9417879438.webp)


# 告警服务 (/products/cdn/3-cdn-the-alarm-service)



最近更新时间: 2026-08-12 17:56:52

告警服务帮助用户对CDN流量、带宽、命中率、状态码等指标进行监控，包括告警配置和告警联系人两个模块。在告警配置模块中，针对每个域名，用户可以配置各项告警的触发条件。在告警联系人模块中，用户可以设置接收人、接收人组和Webhook，当某个告警条件被触发后，相应的接收者会收到邮件和短信通知。

<br />

# 告警配置 [#告警配置]

登陆[**七牛管理控制台**](https://portal.qiniu.com/signin)，进入[**CDN控制台**](https://portal.qiniu.com/cdn/overview)，选择【告警配置】。

<br />

## 搜索告警规则 [#搜索告警规则]

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/3-cdn-the-alarm-service/FuqJyiRzuDv8nqxIaTdGvWRkVu1v-bdd340d9dc5d.webp)

* 在域名告警规则界面，右上角搜索框输入规则名称或域名搜索相关告警规则。
* 支持规则名称和域名两个维度的搜索。
* 域名维度的搜索结果为关联该域名的所有告警规则。

<br />

## 新建告警规则 [#新建告警规则]

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/3-cdn-the-alarm-service/FvtKNnH8LX-NZxdncqg1286B0B_y-6c329f51968b.webp)

* 新建告警规则：在域名告警规则界面，左上角点击【新建告警规则】，可为新域名配置告警。
* 规则名称：告警规则的名称。
* 监控指标配置：用户根据业务需要配置监控指标，具体指标信息参考下表。<br />

<table>
  <tbody><tr><td align="center"><b>监控指标</b></td><td align="center"><b>选项</b></td><td align="center"><b>计量单位</b></td></tr><tr><td align="center">状态码</td><td align="center">高于/低于/环比波动/环比上升/环比下降</td><td align="center">百分比</td></tr><tr><td align="center">流量命中率</td><td align="center">高于/低于/环比波动/环比上升/环比下降</td><td align="center">百分比</td></tr><tr><td align="center">请求命中率</td><td align="center">高于/低于//环比波动/环比上升/环比下降</td><td align="center">百分比</td></tr><tr><td rowspan="2" align="center">带宽</td><td align="center">高于/低于</td><td align="center">Mbps</td></tr><tr><td align="center">环比波动/环比上升/环比下降</td><td align="center">百分比</td></tr><tr><td rowspan="2" align="center">流量</td><td align="center">高于/低于</td><td align="center">GB</td></tr><tr><td align="center">环比波动/环比上升/环比下降</td><td align="center">百分比</td></tr></tbody>
</table>

说明：
（1）每条告警规则可配置的监控指标数量不超过 10 条，如有需要配置超过 10 条的，请[**提交工单**](https://support.qiniu.com/tickets/new/form?category=%E9%85%8D%E7%BD%AE%E9%97%AE%E9%A2%98\&space=CDN)申请开通高级告警服务；
（2）可以通过配置监控指标持续数据点的数量，避免因为业务抖动导致的频繁的无效的告警；“持续1个数据点”即第一个达到告警阈值的5分钟数据点则告警，“持续2个数据点”即连续2个5分钟数据点都达到告警阈值才告警，“持续3/4/5个数据点”以此类推；
（3）多项监控指标之间支持【且】或【或】两种关系；多项监控指标关系为【且】时，只有所有监控指标都达到告警阈值才会触发告警；多项监控指标关系为【或】时，任何一项监控指标达到告警阈值就会触发告警。

* 监控接收人：用户可以选择接收人、接收人组或Webhook；若没有目标接收人，可点击【新建接收人】，创建好目标接收人后，点击【新建接收人】旁边的刷新按钮，即可以选择目标接收人。
* 监控域名：非必选项，可以先创建告警规则，再添加监控域名；选择监控域名，支持模糊搜索。

<br />

## 修改告警规则 [#修改告警规则]

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/3-cdn-the-alarm-service/FkhjCRY9yYoXH0_XJjf-cnKG03nR-e5414aa8f84f.webp)

* 在域名告警规则界面，查找到目标告警规则，在操作列点击【编辑】，告警规则参数的修改同【新建告警规则】。
* 修改规则名称会自动创建一条新的告警规则，原告警规则不变。
* 修改告警规则，告警规则会自动变为启用状态。

<br />

## 启停告警规则 [#启停告警规则]

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/3-cdn-the-alarm-service/Fn7pBCypjV6sl1pM0trV_KvAt9Oo-e33c04727e56.webp)

* 在域名告警规则界面，查找到目标告警规则，在告警启停列点击对应按钮，实现告警规则的启用或停用。

<br />

## 删除告警规则 [#删除告警规则]

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/3-cdn-the-alarm-service/FmBcEeVSnDQNNS1onxDWWDwMTo0i-b512edb9ba53.webp)

* 在域名告警规则界面，查找到目标告警规则，在告警启停列点击【删除】；勾选多条目标告警规则，点击告警列表右上角的【批量删除】。
* 删除告警规则需要先解绑关联的所有域名，否则无法删除。

<br />

## 查看告警规则 [#查看告警规则]

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/3-cdn-the-alarm-service/FogynJ5aYL8i71T1gvJ4WmEtuHRh-091c3607236a.webp)

* 在域名告警规则界面，查找到目标告警规则，在操作列点击【查看】。

# 告警联系人 [#告警联系人]

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/3-cdn-the-alarm-service/FpIf9tUKG8iNmS8DQiSFKIZDPeKW-b83f9a63f194.webp)
原有告警联系人模块迁移到了消息中心模块，您可以前往[**消息中心**](https://portal.qiniu.com/notification/recipient/user)进行设置，也可以通过上方导航栏的【消息】按钮进入消息中心进行设置。


# 域名归属校验 (/products/cdn/4-cdn-domain-verify-introduce)



最近更新时间: 2026-08-12 17:56:52

每个域名仅需做一次归属权校验，子域名无需重复校验。校验方法有两种：

* DNS解析验证
* 文件验证

# DNS解析验证 [#dns解析验证]

通过配置待加速域名的txt记录的方式，通过域名校验，具体方式如下

1. 通过 [https://portal.qiniu.com/cdn/domain/create](https://portal.qiniu.com/cdn/domain/create) 创建域名，提交之后系统会判断该域名是否曾经校验过。若校验过则会进入域名创建结果页。若未校验过则会进入域名验证页，如下：

![企业微信截图\_bba1a925-71d2-4171-b513-1606d66ef55f.png](/docs-assets/products/cdn/%284-development-guidelines%29/4-cdn-domain-verify-introduce/FkCJ3rTc9lgHxJsvKhSmxseQxioc-56759f14076c.webp)

2. 在您的域名解析服务商，添加TXT记录

3. 等待TXT解析生效，返回CDN控制台，单击「点击验证」，完成验证
   若如果系统提示“验证失败”，请检查TXT记录是否正确填写，并等待DNS记录生效后重新验证

# 文件验证 [#文件验证]

通过在域名源站上传验证文件，并保证外网的可访问性，具体方式如下

1. 在域名验证页面点击「文件验证」，进入获取验证的页面，如下图：

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/4-cdn-domain-verify-introduce/FhNRLs2gwN0TcjHkesglKhsBlB4z-9b008f0ad999.webp)

2. 点击下载验证文件

3. 将验证文件上传到源站服务器的根目录，并确保通过域名根目录可访问
   例如：配置加速域名verify.qiniu.com，需要将文件上传到qiniu.com所在的服务器源站，并确保 [http://qiniu.com/verification.html](http://qiniu.com/verification.html) 的外网访问性，我们将根据该文件的访问结果判断是否验证通过

4. 单击「点击验证」，完成验证

以上所有功能均可通过接口完成，详见：[/products/dcdn/9-domain-verify-information](/products/dcdn/9-domain-verify-information)


# CDN日志查询和下载工具 (/products/cdn/0-qlogfetch)



最近更新时间: 2026-04-29 14:45:04

# qlogfetch [#qlogfetch]

## 简介 [#简介]

CDN日志查询和下载工具，该工具是根据七牛的[日志下载](/products/cdn/10-fusion-api-log-download)开发的。
本工具提供有两种类型，一种是命令行工具，适用于Windows，Linux，Mac平台，另外一种是Windows下面的图形工具。

## 安装 [#安装]

本组工具不需要安装，直接下载即可使用，当然如果你使用的是命令行工具，记得从终端里面去运行，如果是图形工具直接双击打开即可使用。

## 下载 [#下载]

| 类型    | 适用平台                | 下载链接                                                                           |
| ----- | ------------------- | ------------------------------------------------------------------------------ |
| 命令行工具 | Windows, Linux, Mac | [qlogfetch-v1.0.6.zip](http://devtools.qiniu.com/qlogfetch-v1.0.6.zip)         |
| 图形工具  | Windows             | [QLogFetch-win-v1.1.1.zip](http://devtools.qiniu.com/QLogFetch-win-v1.1.1.zip) |

## 命令行工具使用 [#命令行工具使用]

| 命令      | 描述                             |
| ------- | ------------------------------ |
| reg     | 设置当前用户的`AccessKey`和`SecretKey` |
| info    | 显示当前设置的`AccessKey`和`SecretKey` |
| listlog | 列出指定日期，指定域名的日志文件列表             |
| downlog | 下载指定日期，指定域名下的所有日志文件            |
| domains | 查询账户下的所有域名                     |

由于查询日志和下载日志都需要七牛的API鉴权，所以我们在运行命令之前，需要设置下账号对应的`AccessKey`和`SecretKey`，它们可以从七牛的后台[这里](https://portal.qiniu.com/developer/user/key)获取。

首先要使用必须设置`AccessKey`和`SecretKey`，命令如下：

```
Usage: qlogfetch reg -ak <AccessKey> -sk <SecretKey>
	set access key and secret key
	example: qlogfetch reg -ak 'your access key' -sk 'your secret key'
```

如果你想查看当前的`AccessKey`和`SecretKey`设置，使用命令：

```
qlogfetch info
```

注意为了方便多账号切换使用，工具把`AccessKey`和`SecretKey`的内容存储在命令执行的目录下面。

查看当前帐号下的所有域名：

```
qlogfetch domains
```

获取指定日期，某个域名的日志文件列表：

```
Usage: qlogfetch [-pretty] -date <Date> -domains <Domains>
	list the log files of a domain of a date
	example: qlogfetch listlog -date '2016-11-23' -domains 'img.abc.com'
```

可以指定`-pretty`选项，让输出变得更可读：

```
qlogfetch listlog -date '2016-11-23' -domains 'img.abc.com' -pretty
```

下载指定日期，某个域名的所有日志文件：

```
Usage: qlogfetch downlog -date <Date> -domains <Domains> -dest <DestDir> -worker <Worker>
	donwload all the log files of a domain of a date
	example: qlogfetch downlog -date '2016-11-23' -domains 'img.abc.com' -dest '/tmp/logs'
```

其中注意`-dest`的选项指本地日志的存储路径，这个下载日志的功能具有如下的特点：

1. 支持单个日志文件的断点续传，这个很重要，因为文件一般都比较大，如果因为意外结束的话，可以直接运行原始命令进行文件的续传
2. 支持日志文件列表的增量下载，假设有10个日志文件，第一次下载3个，后面运行原始命令，可以继续下载剩下的文件
3. 注意为了能够实现上面的功能，命令必须在和之前相同的路径之下运行，因为相关的信息都保存在那个目录之下

当然如果希望同时列举多个域名某天的日志列表或者下载多个域名某天的日志文件时，可以指定多个域名，每个域名用分号（;）分开。
例如：

```
qlogfetch listlog -date '2016-11-23' -domains 'img.abc.com;video.abc.com' -pretty
```

```
qlogfetch downlog -date '2016-11-23' -domains 'img.abc.com;video.abc.com' -dest '/tmp/logs'
```

当然如果使用过程中，忘记了命令的用法，可以查看命令帮助信息，可以通过如下的两种方法：

```
qlogfetch -h
```

```
qlogfetch <cmd>
```

例如：

```
qlogfetch listlog
```

就可以显示`listlog`命令的使用方式。


# API列表 (/products/cdn/0-fusion-api-overview)



最近更新时间: 2026-09-03 10:24:50

# 1. 域名与鉴权绑定规范 [#1-域名与鉴权绑定规范]

| 接入域名                | 鉴权方式           | QPS  | 覆盖模块                             |
| ------------------- | -------------- | ---- | -------------------------------- |
| api.qiniu.com       | Qiniu (请求内容签名) | 10   | 域名管理、域名配置                        |
| fusion.qiniuapi.com | QBox (路径签名)    | 5-10 | 用量统计 / 运营统计 / 缓存管理 / 证书管理 / 日志下载 |

***

# 2. 文档索引 [#2-文档索引]

| 编号 | 文档                                                     | 内容                             |
| -- | ------------------------------------------------------ | ------------------------------ |
| 01 | [鉴权指南](/products/cdn/1-fusion-api-auth-guide)          | 鉴权指南 (Qiniu + QBox 签名算法)       |
| 02 | [公共错误码 & 通用约束](/products/cdn/2-fusion-api-error-codes) | 公共错误码 & 业务错误码速查                |
| 03 | [快速入门](/products/cdn/3-fusion-api-quick-start)         | 快速入门 (全流程接入指南)                 |
| 04 | [域名管理](/products/cdn/4-fusion-api-domain-management)   | 域名管理 (创建 / 查询 / 上下线 / 删除)      |
| 05 | [域名配置](/products/cdn/5-fusion-api-domain-config)       | 域名配置 (缓存 / 防盗链 / HTTPS / 回源)   |
| 06 | [用量统计](/products/cdn/6-fusion-api-usage-stats)         | 用量统计 (计量带宽 / 流量 / 监控)          |
| 07 | [运营统计](/products/cdn/7-fusion-api-analytics)           | 运营统计 (命中率 / 状态码 / UV / TopURL) |
| 08 | [缓存管理](/products/cdn/8-fusion-api-cache-management)    | 缓存刷新 & 预取                      |
| 09 | [证书管理](/products/cdn/9-fusion-api-cert-management)     | SSL 证书管理                       |
| 10 | [日志下载](/products/cdn/10-fusion-api-log-download)       | CDN 访问日志下载                     |

***

# 3. 接口模块分类 [#3-接口模块分类]

## 3.1 域名管理 [#31-域名管理]

**接入域名**: api.qiniu.com | **鉴权**: Qiniu | **明细**: [域名管理](/products/cdn/4-fusion-api-domain-management)

| 接口名称                                                                    | 请求方法   | 接口地址                    | 核心功能                |
| ----------------------------------------------------------------------- | ------ | ----------------------- | ------------------- |
| [创建域名](/products/cdn/4-fusion-api-domain-management#create-domain)      | POST   | /domain/\<Name>         | 新增普通 / 泛域名 CDN 加速配置 |
| [创建泛子域名](/products/cdn/4-fusion-api-domain-management#create-pandomain) | POST   | /pandomain/\<Name>      | 基于父泛域名创建子域名加速       |
| [下线域名](/products/cdn/4-fusion-api-domain-management#offline-domain)     | POST   | /domain/\<Name>/offline | 暂停域名 CDN 加速服务       |
| [上线域名](/products/cdn/4-fusion-api-domain-management#online-domain)      | POST   | /domain/\<Name>/online  | 恢复域名 CDN 加速服务       |
| [删除域名](/products/cdn/4-fusion-api-domain-management#delete-domain)      | DELETE | /domain/\<Name>         | 注销域名 CDN 加速配置       |
| [获取域名列表](/products/cdn/4-fusion-api-domain-management#list-domains)     | GET    | /domain                 | 分页查询账号下所有 CDN 域名    |
| [获取域名信息](/products/cdn/4-fusion-api-domain-management#get-domain)       | GET    | /domain/\<Name>         | 查询单个域名的详细配置与状态      |
| 注：Name为加速服务域名                                                           |        |                         |                     |

## 3.2 域名配置 [#32-域名配置]

**接入域名**: api.qiniu.com | **鉴权**: Qiniu | **明细**: [域名配置](/products/cdn/5-fusion-api-domain-config)

| 接口名称                                                                      | 请求方法 | 接口地址                          | 核心功能                   |
| ------------------------------------------------------------------------- | ---- | ----------------------------- | ---------------------- |
| [修改加速区域](/products/cdn/5-fusion-api-domain-config#update-geocover)        | PUT  | /domain/\<Name>/geocover      | 调整域名加速区域（国内 / 海外 / 全球） |
| [修改源站配置](/products/cdn/5-fusion-api-domain-config#update-source)          | PUT  | /domain/\<Name>/source        | 变更域名回源地址、类型、协议等        |
| [修改 Range 回源](/products/cdn/5-fusion-api-domain-config#update-range)      | PUT  | /domain/\<Name>/range         | 开启 / 关闭 Range 分片回源功能   |
| [修改回源超时](/products/cdn/5-fusion-api-domain-config#update-sourcetimeout)   | PUT  | /domain/\<Name>/sourcetimeout | 配置回源建连超时时间和回源读取超时时间    |
| [修改缓存规则](/products/cdn/5-fusion-api-domain-config#update-cache)           | PUT  | /domain/\<Name>/cache         | 调整文件 / 目录的缓存时长、忽略参数等   |
| [修改响应头](/products/cdn/5-fusion-api-domain-config#update-respheader)       | PUT  | /domain/\<Name>/respheader    | 配置 CDN 返回的 HTTP 响应头    |
| [开启 HTTPS](/products/cdn/5-fusion-api-domain-config#upgrade-https)        | PUT  | /domain/\<Name>/sslize        | 为域名开启 HTTPS 加速         |
| [修改 HTTPS 配置](/products/cdn/5-fusion-api-domain-config#update-httpsconf)  | PUT  | /domain/\<Name>/httpsconf     | 更换域名 HTTPS 绑定的 SSL 证书  |
| [配置 Referer 防盗链](/products/cdn/5-fusion-api-domain-config#update-referer) | PUT  | /domain/\<Name>/referer       | 设置域名的 Referer 黑白名单防盗链  |
| [配置 IP 黑白名单](/products/cdn/5-fusion-api-domain-config#update-ipacl)       | PUT  | /domain/\<Name>/ipacl         | 限制访问 CDN 的客户端 IP 范围    |
| [配置 UA 黑白名单](/products/cdn/5-fusion-api-domain-config#update-uaacl)       | PUT  | /domain/\<Name>/uaacl         | 限制访问 CDN 的客户端 UA 范围    |
| [配置时间戳防盗链](/products/cdn/5-fusion-api-domain-config#update-timeacl)       | PUT  | /domain/\<Name>/timeacl       | 开启域名时间戳 URL 防盗链        |
| [配置回源鉴权](/products/cdn/5-fusion-api-domain-config#update-bsauth)          | PUT  | /domain/\<Name>/bsauth        | 配置 CDN 回源时的身份鉴权信息      |
| 注：Name为加速服务域名                                                             |      |                               |                        |

## 3.3 用量统计 [#33-用量统计]

**接入域名**: fusion.qiniuapi.com | **鉴权**: QBox | **明细**: [用量统计](/products/cdn/6-fusion-api-usage-stats)

| 接口名称                                                                        | 请求方法 | 接口地址                          | 核心功能              |
| --------------------------------------------------------------------------- | ---- | ----------------------------- | ----------------- |
| [计量带宽查询](/products/cdn/6-fusion-api-usage-stats#query-billing-bandwidth)    | POST | /v2/tune/bandwidth            | 查询计量维度带宽数据，用于账单核对 |
| [计量流量查询](/products/cdn/6-fusion-api-usage-stats#query-billing-flux)         | POST | /v2/tune/flux                 | 查询计量维度流量数据，用于账单核对 |
| [监控带宽查询](/products/cdn/6-fusion-api-usage-stats#query-monitoring-bandwidth) | POST | /v2/tune/monitoring/bandwidth | 查询实时监控带宽数据，时效性优先  |
| [监控流量查询](/products/cdn/6-fusion-api-usage-stats#query-monitoring-flow)      | POST | /v2/tune/monitoring/flow      | 查询实时监控流量数据，时效性优先  |

## 3.4 运营统计 [#34-运营统计]

**接入域名**: fusion.qiniuapi.com | **鉴权**: QBox | **明细**: [运营统计](/products/cdn/7-fusion-api-analytics)

| 接口名称                                                                        | 请求方法 | 接口地址                              | 核心功能                    |
| --------------------------------------------------------------------------- | ---- | --------------------------------- | ----------------------- |
| [缓存命中率统计](/products/cdn/7-fusion-api-analytics#query-hitmiss)               | POST | /v2/tune/loganalyze/hitmiss       | 查询 CDN 缓存的命中 / 未命中次数及流量 |
| [HTTP 状态码统计](/products/cdn/7-fusion-api-analytics#query-statuscode)         | POST | /v2/tune/loganalyze/statuscode    | 查询各 HTTP 状态码的访问次数       |
| [请求次数统计](/products/cdn/7-fusion-api-analytics#query-reqcount)               | POST | /v2/tune/loganalyze/reqcount      | 按区域查询 CDN 总请求次数         |
| [UV 独立访客统计](/products/cdn/7-fusion-api-analytics#query-unique-visitor)      | POST | /v2/tune/loganalyze/uniquevisitor | 查询 CDN 独立访客数（UV）        |
| [访问次数Top URL统计](/products/cdn/7-fusion-api-analytics#query-top-count-url)   | POST | /v2/tune/loganalyze/topcounturl   | 查询访问次数 TOP 的资源 URL      |
| [访问流量Top URL统计](/products/cdn/7-fusion-api-analytics#query-top-traffic-url) | POST | /v2/tune/loganalyze/toptrafficurl | 查询访问流量 TOP 的资源 URL      |
| [访问次数Top IP统计](/products/cdn/7-fusion-api-analytics#query-top-count-ip)     | POST | /v2/tune/loganalyze/topcountip    | 查询访问次数 TOP 的客户端 IP      |
| [访问流量Top IP统计](/products/cdn/7-fusion-api-analytics#query-top-traffic-ip)   | POST | /v2/tune/loganalyze/toptrafficip  | 查询访问流量 TOP 的客户端 IP      |
| [区域运营商流量统计](/products/cdn/7-fusion-api-analytics#query-isp-traffic)         | POST | /v2/tune/loganalyze/traffic       | 按区域 / 运营商查询流量数据         |
| [区域运营商带宽统计](/products/cdn/7-fusion-api-analytics#query-isp-bandwidth)       | POST | /v2/tune/loganalyze/bandwidth     | 按区域 / 运营商查询带宽数据及峰值      |
| [ISP 请求次数统计](/products/cdn/7-fusion-api-analytics#query-isp-reqcount)       | POST | /v2/tune/loganalyze/ispreqcount   | 按运营商查询 CDN 请求次数         |
| [ISP 流量占比统计](/products/cdn/7-fusion-api-analytics#query-isp-traffic-ratio)  | POST | /v2/tune/loganalyze/isptraffic    | 查询各运营商的流量占比情况           |

## 3.5 缓存刷新 & 预取 [#35-缓存刷新--预取]

**接入域名**: fusion.qiniuapi.com | **鉴权**: QBox | **明细**: [缓存管理](/products/cdn/8-fusion-api-cache-management)

| 接口名称                                                               | 请求方法 | 接口地址                   | 核心功能                 |
| ------------------------------------------------------------------ | ---- | ---------------------- | -------------------- |
| [缓存刷新](/products/cdn/8-fusion-api-cache-management#cache-refresh)  | POST | /v2/tune/refresh       | 刷新 CDN 节点上的文件 / 目录缓存 |
| [刷新查询](/products/cdn/8-fusion-api-cache-management#query-refresh)  | POST | /v2/tune/refresh/list  | 查询缓存刷新任务的执行状态        |
| [资源预取](/products/cdn/8-fusion-api-cache-management#prefetch)       | POST | /v2/tune/prefetch      | 将源站新资源预取到 CDN 节点     |
| [预取查询](/products/cdn/8-fusion-api-cache-management#query-prefetch) | POST | /v2/tune/prefetch/list | 查询资源预取任务的执行状态        |

## 3.6 SSL 证书管理 [#36-ssl-证书管理]

**接入域名**: fusion.qiniuapi.com | **鉴权**: QBox | **明细**: [证书管理](/products/cdn/9-fusion-api-cert-management)

| 接口名称                                                            | 请求方法   | 接口地址                                      | 核心功能                    |
| --------------------------------------------------------------- | ------ | ----------------------------------------- | ----------------------- |
| [上传证书](/products/cdn/9-fusion-api-cert-management#upload-cert)  | POST   | /sslcert                                  | 上传 SSL 证书，用于域名 HTTPS 配置 |
| [删除证书](/products/cdn/9-fusion-api-cert-management#delete-cert)  | DELETE | /sslcert/\<certId>                        | 删除账号下未绑定的 SSL 证书        |
| [获取证书](/products/cdn/9-fusion-api-cert-management#get-cert)     | GET    | /sslcert/\<certId>                        | 查询单个 SSL 证书的详细信息        |
| [获取证书列表](/products/cdn/9-fusion-api-cert-management#list-certs) | GET    | /sslcert?marker=\<Marker>\&limit=\<Limit> | 分页查询账号下所有 SSL 证书        |
| 注：certId为证书ID                                                   |        |                                           |                         |

## 3.7 CDN 日志下载 [#37-cdn-日志下载]

**接入域名**: fusion.qiniuapi.com | **鉴权**: QBox | **明细**: [日志下载](/products/cdn/10-fusion-api-log-download)

| 接口名称                                                          | 请求方法 | 接口地址              | 核心功能                |
| ------------------------------------------------------------- | ---- | ----------------- | ------------------- |
| [日志下载](/products/cdn/10-fusion-api-log-download#download-log) | POST | /v2/tune/log/list | 申请并获取 CDN 访问日志的下载链接 |

***

# 4. 核心约束 [#4-核心约束]

| 约束项    | 说明                                                                                                                              |
| ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| 请求域名   | 域名管理/配置 → api.qiniu.com，其余 → fusion.qiniuapi.com                                                                                |
| 鉴权方式   | api → Qiniu AK:Sign，fusion → QBox access\_token，不可混用                                                                            |
| 请求格式   | 请求体均为紧凑 JSON，Header POST、PUT请求使用Content-Type:application/json；GET、DELETE请求使用Content-Type:application/x-www-form-urlencoded 或不追加 |
| 幂等性    | GET/DELETE/PUT 幂等，POST 部分非幂等 (创建/刷新/预取)                                                                                         |
| QPS 限制 | api 10 QPS，fusion 5-10 QPS，超限返回 403024                                                                                          |
| 生效时间   | 域名配置 5-10 分钟，刷新 5-10 分钟，预取 10-20 分钟                                                                                             |
| 参数差异   | 用量统计 domains=string(分号分隔)，运营统计 domains=array                                                                                    |
| 日志保留   | 仅 30 天内，仅支持单日查询                                                                                                                 |
| 统计数据保留 | 计量 180 天 / 监控 90 天 / 运营 90 天                                                                                                    |
| 时间统计跨度 | 用量统计跨度 ≤ 31 天，运营统计跨度 ≤ 30 天                                                                                                     |


# 鉴权指南 (/products/cdn/1-fusion-api-auth-guide)



最近更新时间: 2026-06-04 16:36:02

# 1. 概述 [#1-概述]

七牛云 CDN OpenAPI 采用 **双域名 + 双鉴权** 架构，两种鉴权方式与请求域名严格绑定，不可混用。

| 请求域名                  | 鉴权方式                  | 覆盖模块                                                                                                                                                                                                                                                | QPS  |
| --------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `api.qiniu.com`       | **Qiniu 鉴权** (请求内容签名) | [域名管理](/products/cdn/4-fusion-api-domain-management) 、[域名配置](/products/cdn/5-fusion-api-domain-config)                                                                                                                                              | 10   |
| `fusion.qiniuapi.com` | **QBox 鉴权** (路径签名)    | [用量统计](/products/cdn/6-fusion-api-usage-stats)、[运营统计](/products/cdn/7-fusion-api-analytics)、[缓存管理](/products/cdn/8-fusion-api-cache-management)、[证书管理](/products/cdn/9-fusion-api-cert-management)、[日志下载](/products/cdn/10-fusion-api-log-download) | 5-10 |

***

# 2. 接入准备 [#2-接入准备]

## 2.1 密钥获取 [#21-密钥获取]

**七牛云控制台 > 个人中心 > 密钥管理**，获取 AccessKey (AK) 和 SecretKey (SK)。

> **安全提示**: SK 为核心密钥，严禁在客户端暴露，所有鉴权操作必须在服务端完成。

## 2.2 环境要求 [#22-环境要求]

* **通信协议**: 仅 HTTPS (443 端口)
* **字符编码**: UTF-8
* **请求格式**: POST/PUT 请求体为紧凑 JSON (无格式化空格/换行)
* **请求方法**: 支持 GET/POST/PUT/DELETE
* **时间同步**: 服务器 UTC 时间偏差 ≤ 30 秒

***

# 3. Qiniu 鉴权详解 [#3-qiniu-鉴权详解]

### 3.1 适用范围 [#31-适用范围]

* `api.qiniu.com` 下所有接口：[域名管理](/products/cdn/4-fusion-api-domain-management) 、[域名配置](/products/cdn/5-fusion-api-domain-config)

## 3.2 签名算法 [#32-签名算法]

示例：对应 Python-SDK `QiniuMacAuth.token_of_request`，基于完整请求内容签名。

**签名原始串拼接规则：**

```
data  = "{Method} {PathWithQuery}"          # 例: "POST /domain/test.example.com"
data += "\nHost: {Host}"                    # 例: "\nHost: api.qiniu.com"
data += "\nContent-Type: {ContentType}"     # 例: "\nContent-Type: application/json"
data += "\n{X-Qiniu-Headers}"              # 例: "\nX-Qiniu-Date: 20260213T120000Z"
data += "\n\n"                              # 固定两个换行
data += "{Body}"                            # POST/PUT 请求体 (GET/DELETE 为空)
```

> 所有 X-Qiniu- 自定义头按字典序升序逐行拼接

**签名生成：**

```
Sign   = HmacSHA1(data, SK)
Token  = AK + ":" + urlsafe_base64(Sign)
Header = "Authorization: Qiniu {Token}"
```

> 注意：Qiniu 与 Token 之间必须保留一个英文空格

**URL 安全 Base64**: 标准 Base64 后将 `+` 替换为 `-`，`/` 替换为 `_`，保留尾部 `=`。

## 3.3 生成步骤 [#33-生成步骤]

1. **拼接 Method + Path**
   ```
   "PUT /domain/test.example.com/cache"
   ```

2. **追加 Host**
   ```
   "\nHost: api.qiniu.com"
   ```

3. **追加 Content-Type** (有请求体时)
   ```
   "\nContent-Type: application/json"
   ```

4. **追加 X-Qiniu-Date** (参与签名的自定义头)
   ```
   "\nX-Qiniu-Date: 20260213T120000Z"
   ```

5. **固定追加两个换行**
   ```
   "\n\n"
   ```

6. **追加请求体** (POST/PUT 时追加紧凑 JSON，GET/DELETE 不追加)
   ```
   {"cacheControls":[{"time":3,"timeunit":0,"type":"all","rule":"*"}],"ignoreParam":true}
   ```

7. **HmacSHA1 签名 + URL 安全 Base64 编码**

## 3.4 请求示例 [#34-请求示例]

```bash
curl -X PUT 'https://api.qiniu.com/domain/test.example.com/cache' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<urlsafe_b64_sign>' \
  -d '{"cacheControls":[{"time":3,"timeunit":0,"type":"all","rule":"*"}],"ignoreParam":true}'
```

## 3.5 关键注意 [#35-关键注意]

* Body 参与签名时 **必须与实际发送的请求体完全一致** (字节级)
* Qiniu 鉴权：Content-Type: application/octet-stream 二进制请求体不参与签名
* `X-Qiniu-Date` 为 UTC 时间，格式 `YYYYMMDDTHHMMSSZ`，偏差 ≤ 30 秒

***

# 4. QBox 鉴权详解 [#4-qbox-鉴权详解]

## 4.1 适用范围 [#41-适用范围]

* `fusion.qiniuapi.com` 下所有接口：[用量统计](/products/cdn/6-fusion-api-usage-stats)、[运营统计](/products/cdn/7-fusion-api-analytics)、[缓存管理](/products/cdn/8-fusion-api-cache-management)、[证书管理](/products/cdn/9-fusion-api-cert-management)、[日志下载](/products/cdn/10-fusion-api-log-download)

## 4.2 签名算法 [#42-签名算法]

示例：对应 Python-SDK `Auth.token_of_request`，基于接口路径签名，轻量高效。

**签名原始串拼接规则：**

```
data  = "{Path+Query}\n"    # 例: "/v2/tune/refresh\n" 或 "/sslcert?marker=&limit=10\n"
```

> **重要**: 仅当请求头 Content-Type 为 application/x-www-form-urlencoded 且存在请求体时，请求体才会参与 QBox 签名；application/json 及其他所有类型请求体均不参与 QBox 签名。CDN 所有接口均使用 JSON 请求体，因此 QBox 签名只拼接「路径 + query」

**签名生成：**

```
Sign   = HmacSHA1(data, SK)
Token  = AK + ":" + urlsafe_base64(Sign)
Header = "Authorization: QBox {Token}"
```

> 注意：QBox 与 Token 之间必须保留一个英文空格

## 4.3 生成步骤 [#43-生成步骤]

1. **拼接签名数据**: `接口路径 + query 参数 后加换行符`
   * 示例： `/sslcert?marker=&limit=10\n`
   * 签名串只包含路径和 query，不包含域名、协议、请求体

2. **HmacSHA1 签名**: 使用 SK 作为密钥

3. **拼接 Token**: `AK:urlsafe_base64(签名结果)`

## 4.4 请求示例 [#44-请求示例]

```bash
# 缓存刷新
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/refresh' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<urlsafe_b64_sign>' \
  -d '{"urls":["http://test.example.com/file.jpg"]}'

# 获取证书列表 (GET 无 body)
curl -X GET 'https://fusion.qiniuapi.com/sslcert?marker=&limit=10' \
  -H 'Authorization: QBox <AK>:<urlsafe_b64_sign>'
```

## 4.5 关键注意 [#45-关键注意]

* Token 与 **接口路径 + 完整 query 参数** 强绑定，不可跨接口、跨参数复用
* URL 带? query 参数时，query 必须完整参与签名，缺失参数会 401
* 除`Content-Type: application/x-www-form-urlencoded`外，JSON 及其他所有类型请求体均不参与签名，修改请求体不影响 Token

***

# 5. 响应规范 [#5-响应规范]

## 5.1 成功响应 [#51-成功响应]

**带 code 字段** (fusion.qiniuapi.com 接口):

```json
{
    "code": 200,
    "data": {
        ...
    }
}
```

**不带 code 字段** (api.qiniu.com 部分接口，如 GET /domain):

```json
{
    "name": "test.example.com",
    "cname": "xxx.cdn.dnsv1.com",
    "protocol": "https",
    ...
}
```

> api.qiniu.com 的 GET 域名详情接口直接返回域名信息，无 `code` 包装层。

## 5.2 失败响应 [#52-失败响应]

```json
{
    "code": 400020,
    "error": "域名未备案"
}
```

## 5.3 鉴权相关错误码 [#53-鉴权相关错误码]

| HTTP 状态码 | 业务 code | 含义     | 排查方向                                |
| -------- | ------- | ------ | ----------------------------------- |
| 401      | 401001  | 签名不匹配  | 检查签名原始串拼接、AK/SK 正确性                 |
| 401      | 401002  | 鉴权头无效  | 检查 `Authorization` 格式、空格位置          |
| 403      | 403024  | QPS 超限 | 降低请求频率，api 10 QPS / fusion 5-10 QPS |

***

# 6. SDK 接入 (推荐) [#6-sdk-接入-推荐]

七牛官方 SDK 已封装签名生成、参数校验、异常处理，无需手动编写鉴权代码。

| 语言      | SDK 文档                                                                                           |
| ------- | ------------------------------------------------------------------------------------------------ |
| Python  | [Python SDK](https://github.com/qiniu/python-sdk/blob/master/qiniu/auth.py)                      |
| Go      | [GO SDK](https://github.com/qiniu/go-sdk/blob/master/storage/token.go)                           |
| Java    | [JAVA SDK](https://github.com/qiniu/java-sdk/blob/master/src/main/java/com/qiniu/util/Auth.java) |
| Node.js | [Node.js SDK](/products/kodo/nodejs#fusion-cdn)                                                  |
| PHP     | [PHP SDK](https://github.com/qiniu/php-sdk/blob/master/src/Qiniu/Auth.php)                       |
| C#      | [C# SDK](https://github.com/qiniu/csharp-sdk/blob/master/src/Qiniu/Util/Auth.cs)                 |
| C/C++   | [C/C++ SDK](https://github.com/qiniu/c-sdk/blob/master/qiniu/rs.c)                               |
| Ruby    | [Ruby SDK](https://github.com/qiniu/ruby-sdk/blob/master/lib/qiniu/auth.rb)                      |

> **建议**: 优先使用 SDK，避免手动签名的格式错误、时间偏差等问题。

***

# 7. 常见错误排查 [#7-常见错误排查]

## 7.1 通用问题 [#71-通用问题]

| 现象       | 原因                | 解决                                                                                 |
| -------- | ----------------- | ---------------------------------------------------------------------------------- |
| 401 所有接口 | AK/SK 错误          | 核对控制台密钥                                                                            |
| 401 特定接口 | 鉴权方式与域名不匹配        | api→Qiniu，fusion→QBox                                                              |
| 401 间歇性  | 服务器时间不同步          | 同步 NTP，确保 UTC 偏差 ≤ 30s                                                             |
| 401 鉴权失败 | 错误携带 Content-Type | POST、PUT请求使用 application/json；GET/DELETE请求使用 application/x-www-form-urlencoded或不追加 |

## 7.2 Qiniu 鉴权排查 [#72-qiniu-鉴权排查]

| 现象         | 原因                      | 解决                       |
| ---------- | ----------------------- | ------------------------ |
| 签名始终不匹配    | Body 签名与发送不一致           | 确保签名用的 body 字符串与实际发送完全一致 |
| PUT 请求 401 | 签名串缺少 Content-Type      | 有请求体时必须追加 Content-Type 行 |
| GET 请求 401 | 签名串多了 body              | GET/DELETE 可以不追加 body    |
| 二进制接口 401  | 误将 octet-stream 请求体加入签名 | 遵循约束，该类型不参与签名            |

## 7.3 QBox 鉴权排查 [#73-qbox-鉴权排查]

| 现象              | 原因                         | 解决                                                            |
| --------------- | -------------------------- | ------------------------------------------------------------- |
| Token 跨接口失败     | Token 与接口路径+完整query参数强绑定   | 每个接口/每组参数单独生成 Token                                           |
| 带 query 参数时 401 | 签名路径不含 query               | 路径必须包含 `?query` 部分                                            |
| POST 接口 401     | 误把 JSON / 非 form 类型请求体加入签名 | 仅 application/x-www-form-urlencoded 支持 body 参与签名，JSON 无需带入签名串 |


# 日志下载 (/products/cdn/10-fusion-api-log-download)



最近更新时间: 2026-06-04 16:38:41

# 1. 快速查阅区 [#1-快速查阅区]

## 1.1 核心接口概览 [#11-核心接口概览]

| 接口功能                        | 请求方法 | 接口路径                | 核心参数        | 成功响应                        |
| --------------------------- | ---- | ------------------- | ----------- | --------------------------- |
| <a href="#P21">获取日志下载链接</a> | POST | `/v2/tune/log/list` | day、domains | `{"code":200,"data":{...}}` |

## 1.2 核心约束 [#12-核心约束]

* **请求域名**: `fusion.qiniuapi.com`
* **鉴权方式**: QBox 鉴权（详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)）；
* **数据保留**: 30 天，例如：当前日期为 2026-01-31，则只提供 2026-01-01 \~ 2026-01-30 的日志；
* **日志粒度**: 每小时一个 gz 压缩文件，单小时内日志过大会进行切分(分片大小128MB)；
* **日志延迟**: 6小时，例如：1月18日0点-1点的日志，会在1月18日8点-10点左右可下载。

***

# 2. 详细接口说明 [#2-详细接口说明]

<div id="P21" />

<span id="download-log" />

## 2.1 获取日志下载链接 [#21-获取日志下载链接]

### 基本信息 [#基本信息]

* **请求方法**: POST
* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/log/list`

### 请求参数 [#请求参数]

| 参数名     | 类型     | 必填 | 说明                                                                                  | 示例值             |
| ------- | ------ | -- | ----------------------------------------------------------------------------------- | --------------- |
| day     | string | 是  | 查询日期，格式 yyyy-MM-dd，仅支持单日                                                            | `"2026-02-12"`  |
| domains | string | 是  | 域名，分号分隔 (同[用量统计](/products/cdn/6-fusion-api-usage-stats#query-billing-request)，非数组) | `"a.com;b.com"` |

> **domains 为 string 类型**，传数组会报 400。

### 请求示例 [#请求示例]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/log/list' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"day":"2026-02-12","domains":"test.example.com"}'
```

### 响应参数 [#响应参数]

| 参数名    | 类型     | 说明                |
| ------ | ------ | ----------------- |
| name   | string | 日志文件名 (含域名+日期+小时) |
| size   | int    | 文件大小 (byte)       |
| mtime  | int    | 文件修改时间 (Unix 时间戳) |
| url    | string | 带签名的下载链接 (有时效)    |
| md5    | string | 文件 MD5            |
| domain | string | 所属域名              |

### 响应示例 [#响应示例]

**成功** (HTTP 200):

```json
{
  "code": 200,
  "error": "",
  "data": {
    "test.example.com": [
      {
        "name": "v2/test.example.com_2026-02-12-07_part-00000.gz",
        "size": 311,
        "mtime": 1770868332,
        "url": "https://fusionlog.qiniu.com/v2/test.example.com_2026-02-12-07_part-00000.gz?e=...&token=...",
        "md5": "",
        "domain": "test.example.com"
      }
    ]
  }
}
```

> data 按域名分组，每个域名对应一个日志文件数组。无数据时对应域名的数组为空。

**失败**:

```json
{
    "code": 400,
    "error": "请求参数格式错误",
    "data": {}
}
```

***

## 日志格式 [#日志格式]

每行一条记录，字段顺序如下：

**示例日志**:

```
148.153.188.135 UNKNOWN 1 [13/Feb/2026:12:09:15 +0800] "GET https://test.example.com/qiniu_do_not_delete.gif HTTP/1.1" 403 345 "-" "Q-uc-client"
```

**字段说明**:

| 序号 | 字段           | 说明               | 示例                                                 |
| -- | ------------ | ---------------- | -------------------------------------------------- |
| 1  | ClientIP     | 客户端 IP           | `148.153.188.135`                                  |
| 2  | Hit/Miss     | 命中状态             | `HIT` / `MISS` / `UNKNOWN`                         |
| 3  | ResponseTime | 响应时间 (毫秒)        | `1`                                                |
| 4  | Time         | 请求时间 (\[] 包裹)    | `[13/Feb/2026:12:09:15 +0800]`                     |
| 5  | Method       | 请求方法 ("" 包裹 5-7) | `GET`                                              |
| 6  | URL          | 请求 URL (含域名完整路径) | `https://test.example.com/qiniu_do_not_delete.gif` |
| 7  | Protocol     | 请求协议             | `HTTP/1.1`                                         |
| 8  | StatusCode   | HTTP 状态码         | `403`                                              |
| 9  | TrafficSize  | 响应大小 (byte)      | `345`                                              |
| 10 | Referer      | 来源页 ("" 包裹)      | `"-"`                                              |
| 11 | UserAgent    | 用户代理 ("" 包裹)     | `"Q-uc-client"`                                    |

> 格式说明: Method+URL+Protocol 被 `""` 包裹为一组，Referer 和 UserAgent 各自被 `""` 包裹。

***

# 3. 常见问题 [#3-常见问题]

## 3.1 专属错误码 [#31-专属错误码]

| 错误码    | 描述         | 场景                             | 解决方案       |
| ------ | ---------- | ------------------------------ | ---------- |
| 400    | 参数格式错误     | 日期格式非 yyyy-MM-dd 或 domains 传数组 | 修正参数格式     |
| 400032 | 请求中存在无效的域名 | 域名未接入 CDN 或拼写错误                | 确认域名已创建且上线 |

## 3.2 最佳实践 [#32-最佳实践]

* **查询时机**: 日志延迟6小时，查询前日日志，建议次日上午查询
* **下载链接**: url 含时效签名，获取后尽快下载
* **domains 格式**: string 类型分号分隔，同[用量统计](/products/cdn/6-fusion-api-usage-stats#query-billing-request)
* **日志命名**: `域名_日期-小时_part-序号.gz`，按小时拆分
* **批量下载**: 多域名一次查询，响应按域名分组

> **参考**: 鉴权详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)，错误码详见 [公共错误码&通用约束](/products/cdn/2-fusion-api-error-codes)。


# 公共错误码 & 通用约束 (/products/cdn/2-fusion-api-error-codes)



最近更新时间: 2026-05-21 09:21:02

# 1. 快速查阅区 [#1-快速查阅区]

## 1.1 HTTP 状态码 [#11-http-状态码]

| HTTP 状态码 | 含义            | 责任方 | 处理方式                    |
| -------- | ------------- | --- | ----------------------- |
| 200      | 成功            | -   | 正常处理返回数据                |
| 400      | 请求参数错误        | 调用方 | 按接口文档修正参数，检查 JSON 格式    |
| 401      | 鉴权失败          | 调用方 | 检查 AK/SK、签名算法、鉴权方式与域名匹配 |
| 403      | 权限不足 / QPS 超限 | 调用方 | 检查账号权限或降低调用频率           |
| 404      | 资源不存在         | 调用方 | 检查域名/证书ID/任务ID 拼写       |
| 405      | 请求方法错误        | 调用方 | 按接口文档指定的方法调用            |
| 429      | 请求频率超限        | 调用方 | 降低调用频率                  |
| 500      | 服务端内部错误       | 七牛云 | 记录 X-Reqid，稍后重试         |
| 503      | 服务暂不可用        | 七牛云 | 等待后重试，关注官网公告            |

## 1.2 高频业务错误码 [#12-高频业务错误码]

| 错误码    | 错误描述        | 所属模块 | 解决方案                                |
| ------ | ----------- | ---- | ----------------------------------- |
| 400013 | 重复操作        | 域名管理 | 域名已处于目标状态 (如已下线再下线)，无需处理            |
| 400020 | 域名未备案       | 域名管理 | 完成 ICP 备案，或 geoCover 设为 foreign 免备案 |
| 400030 | 正在处理中       | 域名管理 | 上一操作未完成 (5-10分钟)，等待后重试              |
| 400031 | invalid url | 缓存管理 | 检查 URL 格式，须为完整 http\:// 或 https\:// |
| 400033 | 预取配额超限      | 缓存管理 | 次日恢复，或控制台申请提升配额                     |
| 400034 | 刷新配额超限      | 缓存管理 | 次日恢复，或控制台申请提升配额                     |
| 400035 | 目录刷新配额超限    | 缓存管理 | 同上                                  |
| 400038 | 无目录刷新权限     | 缓存管理 | 控制台开通「目录刷新」功能                       |
| 400041 | 源站测试路径不可访问  | 域名管理 | testURLPath 须以 / 开头，源站需返回 200       |
| 400062 | 重复域名        | 域名管理 | 域名已存在，无需重复创建                        |
| 400309 | 缓存规则未设置全局   | 域名配置 | cacheControls 须包含 type=all 的全局兜底规则  |
| 400317 | 非已下线的域名     | 域名管理 | 删除/上线前须先下线域名                        |
| 400323 | 证书链验证失败     | 证书管理 | 拼接完整 PEM 证书链 (服务器→中间证书)             |
| 400401 | 无此证书        | 证书管理 | 检查 certId 正确性，证书可能已删除               |
| 401001 | 签名不匹配       | 鉴权   | 检查签名串拼接、AK/SK 正确性                   |
| 401002 | 鉴权头无效       | 鉴权   | 检查 Authorization 格式，Qiniu/QBox 后有空格 |
| 403024 | 单用户 QPS 超限  | 全局   | 降低频率，api 10QPS / fusion 5-10QPS     |
| 404001 | 资源不存在       | 全局   | 检查域名/证书ID/任务ID 拼写                   |
| 500000 | 服务端内部错误     | 全局   | 记录 X-Reqid，稍后重试，或提交工单               |

***

# 2. 详细错误码体系 [#2-详细错误码体系]

## 2.1 通用基础错误 (400xxx) [#21-通用基础错误-400xxx]

| 错误码    | 错误描述     | 详细排查                             |
| ------ | -------- | -------------------------------- |
| 400000 | 无效输入参数   | 参数值为空、参数组合不符合规则                  |
| 400001 | 参数解析错误   | 请求体非紧凑 JSON、语法错误、缺少 Content-Type |
| 400032 | 无效域名     | 域名格式错误、未接入 CDN、不归属当前账号           |
| 400080 | 开始时间格式错误 | 时间参数须为 yyyy-MM-dd 格式             |
| 400081 | 结束时间格式错误 | 同上                               |
| 400082 | 时间范围错误   | 开始时间 ≥ 结束时间，或跨度超出限制              |
| 400203 | 账号已禁用    | 因违规/欠费被限制，联系客服                   |

## 2.2 域名管理专属错误 [#22-域名管理专属错误]

| 错误码    | 错误描述       | 场景                      | 解决方案                      |
| ------ | ---------- | ----------------------- | ------------------------- |
| 400013 | 重复操作       | 已下线的域名再下线               | 已处于目标状态，无需处理              |
| 400020 | 域名未备案      | geoCover=china/global 时 | 完成 ICP 备案，或改用 foreign     |
| 400030 | 正在处理中      | 上一操作 (创建/上下线) 未完成       | 等待 5-10 分钟后重试             |
| 400041 | 源站测试路径不可访问 | 创建域名时 testURLPath 不可达   | 确保源站路径返回 200              |
| 400095 | 未知的父域名     | 创建泛子域名时                 | 检查 pareDomain 格式 (以 . 开头) |
| 400062 | 重复域名       | 重复创建同名域名                | 已存在，无需重复创建                |
| 400317 | 域名非下线状态    | 上线非下线域名 / 删除未下线域名       | 须先下线再操作                   |
| 400412 | 无效的泛子域名    | 泛子域名格式错误                | 仅支持一级子域名                  |

## 2.3 域名配置专属错误 [#23-域名配置专属错误]

| 错误码    | 错误描述        | 场景                        | 解决方案                            |
| ------ | ----------- | ------------------------- | ------------------------------- |
| 400042 | 配置参数错误      | 缓存规则/防盗链格式不符              | 检查参数格式符合接口要求                    |
| 400309 | 缓存规则未设置全局   | PUT /cache 缺少 type=all 兜底 | cacheControls 须含 type=all 的全局规则 |
| 400324 | 证书不存在/已过期   | sslize 时 certId 无效        | 重新上传有效证书                        |
| 400302 | 更改证书失败      | httpsconf 时域名未开启 HTTPS    | 需先 sslize 开启 HTTPS              |
| 400916 | http协议不允许降级 | unsslize 时域名未开启 HTTPS     | 域名未开启 HTTPS，无需降级                |
| 500235 | 该域名未绑定证书    | sslize 时域名未绑定证书           | 需先上传并绑定证书                       |
| 400520 | 互斥配置冲突      | 同时设置时间戳和回源鉴权              | 两者互斥，只能启用其一                     |

## 2.4 缓存管理专属错误 [#24-缓存管理专属错误]

| 错误码    | 错误描述        | 场景          | 解决方案                          |
| ------ | ----------- | ----------- | ----------------------------- |
| 400031 | invalid url | 刷新 URL 格式错误 | 须为完整 http\:// 或 https\:// URL |
| 400033 | 预取配额超限      | 每日预取次数超限    | 次日恢复，或控制台申请提升                 |
| 400034 | 刷新配额超限      | 每日刷新次数超限    | 次日恢复，或控制台申请提升                 |
| 400035 | 目录刷新配额超限    | 目录刷新次数超限    | 同上                            |
| 400038 | 无目录刷新权限     | 未开通目录刷新功能   | 控制台→CDN→功能管理开通                |

## 2.5 证书管理专属错误 [#25-证书管理专属错误]

| 错误码    | 错误描述    | 场景         | 解决方案                |
| ------ | ------- | ---------- | ------------------- |
| 400323 | 证书链验证失败 | 上传证书时链不完整  | 按 服务器→中间证书 拼接完整 PEM |
| 400401 | 无此证书    | certId 不存在 | 检查 ID 拼写，或证书已删除     |

## 2.6 鉴权错误 [#26-鉴权错误]

| 错误码    | 错误描述             | 详细排查                                         |
| ------ | ---------------- | -------------------------------------------- |
| 401000 | 账号未实名认证          | 控制台→个人中心→实名认证                                |
| 401001 | 签名不匹配            | ① AK/SK 正确性 ② 签名串拼接格式 ③ Base64 编码 ④ 服务器时间    |
| 401002 | 鉴权头无效            | ① 鉴权方式与域名匹配 (api→Qiniu, fusion→QBox) ② 格式含空格 |
| 401003 | access\_token 无效 | QBox token 路径与实际请求路径不一致                      |
| 401004 | 时间戳过期            | 同步 NTP，UTC 偏差 ≤ 30s                          |

## 2.7 权限/限流错误 [#27-权限限流错误]

| 错误码    | 错误描述       | 详细排查            |
| ------ | ---------- | --------------- |
| 403001 | 无操作权限      | 子账号需分配 CDN 管理权限 |
| 403022 | 全局 QPS 超限  | 稍后重试            |
| 403024 | 单用户 QPS 超限 | 降低频率，批量操作，或申请提升 |

## 2.8 服务端错误 [#28-服务端错误]

| 错误码    | 错误描述      | 处理方式                          |
| ------ | --------- | ----------------------------- |
| 500000 | 服务端内部错误   | 记录 X-Reqid，等 1-2 分钟重试，多次失败提工单 |
| 500005 | 服务端查询数据错误 | 稍后重试                          |
| 503001 | 服务暂不可用    | 平台维护，等 5-10 分钟重试              |
| 504001 | 网关超时      | 临时网络波动，立即重试                   |

***

# 3. 通用约束 [#3-通用约束]

## 3.1 QPS 限制 [#31-qps-限制]

| 请求域名                  | QPS  | 超限错误码  | 处理          |
| --------------------- | ---- | ------ | ----------- |
| `api.qiniu.com`       | 10   | 403024 | 批量操作 + 异步调用 |
| `fusion.qiniuapi.com` | 5-10 | 403024 | 同上          |

> 主账号和子账号共享同一 QPS 配额。

## 3.2 操作配额 [#32-操作配额]

| 操作   | 默认每日配额  | 超限错误码  | 提升方式         |
| ---- | ------- | ------ | ------------ |
| 文件刷新 | 500 次/天 | 400034 | 控制台→CDN→配额管理 |
| 目录刷新 | 需开通     | 400035 | 同上 (需先开通)    |
| 资源预取 | 100 次/天 | 400033 | 同上           |

> 配额每日 0 点自动重置。

## 3.3 时间约束 [#33-时间约束]

| 约束项      | 规则                             |
| -------- | ------------------------------ |
| 日期格式     | `yyyy-MM-dd` (如 2026-02-13)    |
| 鉴权时间戳偏差  | ≤ 30 秒                         |
| 日志保留     | 30 天                           |
| 统计数据保留   | 计费数据 180 天，监控数据 90 天，运营统计 90 天 |
| 用量统计时间跨度 | ≤ 31 天                         |
| 运营统计时间跨度 | ≤ 30 天                         |
| 配置生效时间   | 5-10 分钟                        |

## 3.4 格式约束 [#34-格式约束]

| 约束项       | 规则                                                    |
| --------- | ----------------------------------------------------- |
| 请求体       | 紧凑 JSON (无格式化空格/换行)，携带 Content-Type: application/json |
| 刷新/预取 URL | 完整 http\:// 或 https\:// 格式                            |
| SSL 证书    | PEM 格式，含完整证书链                                         |
| 源站测试路径    | 以 / 开头的相对路径                                           |
| 字符编码      | UTF-8                                                 |

***

# 4. 错误排查流程 [#4-错误排查流程]

```
1. 看 HTTP 状态码
   ├─ 5xx → 记录 X-Reqid，等待重试
   └─ 4xx → 继续排查 ↓

2. 看业务错误码
   ├─ 401xxx → 检查鉴权 (AK/SK、签名、域名匹配)
   ├─ 403xxx → 检查权限/QPS
   ├─ 404xxx → 检查资源标识
   └─ 400xxx → 检查参数 ↓

3. 看 error 描述
   └─ 中文描述直接说明原因 (如 "域名未备案""缓存规则未设置全局")

4. 查对应模块文档
   └─ 各模块文档 (03-09) 有专属错误码详细说明
```


# 快速入门 (/products/cdn/3-fusion-api-quick-start)



最近更新时间: 2026-06-04 16:36:40

# 1. 前置准备 [#1-前置准备]

## 1.1 获取 AK/SK [#11-获取-aksk]

登录 [七牛云控制台](https://portal.qiniu.com) → 个人中心 → 密钥管理，获取 AccessKey 和 SecretKey。

## 1.2 两组接入点 [#12-两组接入点]

| 用途        | 接入域名                  | 鉴权方式     | 适用接口        |
| --------- | --------------------- | -------- | ----------- |
| 域名管理 & 配置 | `api.qiniu.com`       | Qiniu 鉴权 | 域名管理、域名配置   |
| 其他所有接口    | `fusion.qiniuapi.com` | QBox 鉴权  | 统计/缓存/证书/日志 |

> **不可混用**。域名管理发到 fusion 会 404，统计接口发到 api 也会 404。
> 鉴权算法详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)。

## 1.3 安装 Python SDK (生成签名) [#13-安装-python-sdk-生成签名]

```bash
pip install qiniu requests
```

## 1.4 签名生成工具函数 [#14-签名生成工具函数]

后续所有示例共用此函数：

```python
from qiniu import Auth, QiniuMacAuth
from urllib.parse import urlencode
import requests, json
from datetime import datetime
from requests.exceptions import RequestException

AK = "<你的AccessKey>"
SK = "<你的SecretKey>"

def call_api(method, path, body=None):
    """api.qiniu.com 接口 (Qiniu 鉴权)"""
    url = f"https://api.qiniu.com{path}"
    auth = QiniuMacAuth(AK, SK)
    headers = {}
    raw = None
    x_qiniu_date = datetime.utcnow().strftime('%Y%m%dT%H%M%SZ')
    headers["X-Qiniu-Date"] = x_qiniu_date
    if body is not None:
        headers["Content-Type"] = "application/json"
        raw = json.dumps(body, separators=(',', ':'))

    token = auth.token_of_request(
        method=method,
        host="api.qiniu.com",
        url=url,
        qheaders=auth.qiniu_headers(headers),
        content_type=headers.get("Content-Type", ""),
        body=raw
    )
    headers["Authorization"] = f"Qiniu {token}"

    try:
        resp = requests.request(method, url, headers=headers, data=raw, timeout=10)
        return resp.status_code, resp.json() if resp.text else {}
    except RequestException as e:
        return -1, {"error": str(e)}

def call_fusion(method, path, body=None, params=None):
    """fusion.qiniuapi.com 接口 (QBox 鉴权)"""
    base = f"https://fusion.qiniuapi.com{path}"
    if params:
        base = f"{base}?{urlencode(params)}"

    auth = Auth(AK, SK)
    token = auth.token_of_request(base, body=None, content_type=None)
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"QBox {token}"
    }

    try:
        resp = requests.request(method, base, headers=headers, json=body, timeout=10)
        return resp.status_code, resp.json() if resp.text else {}
    except RequestException as e:
        return -1, {"error": str(e)}
```

***

# 2. 典型流程 [#2-典型流程]

## 步骤 1：创建域名 [#步骤-1创建域名]

```python
code, body = call_api("POST", "/domain/cdn.example.com", {
    "type": "normal",
    "platform": "web",
    "geoCover": "foreign",
    "protocol": "http",
    "source": {"sourceType": "ip", "sourceIPs": ["1.2.3.4"], "testURLPath": "/index.html"},
    "cache": {"cacheControls": [{"time": 1, "timeunit": 5, "type": "all", "rule": "*"}]}
})
print(code, body)
# 成功: 200 {"code":200}
# 重复: 400 {"code":400062,"error":"重复域名"}
```

> 创建后状态为 processing，5-10 分钟变为 success 才能操作。

## 步骤 2：查询域名状态 [#步骤-2查询域名状态]

```python
code, body = call_api("GET", "/domain/cdn.example.com")
print(body.get("operatingState"))  # processing → success
print(body.get("cname"))           # 用于 DNS 解析的 CNAME 值
```

> 拿到 CNAME 后去 DNS 服务商添加 CNAME 记录指向该值。

## 步骤 3：配置缓存规则 [#步骤-3配置缓存规则]

```python
code, body = call_api("PUT", "/domain/cdn.example.com/cache", {
    "cacheControls": [
        {"time": 30, "timeunit": 0, "type": "suffix", "rule": ".jpg;.png;.css;.js"},
        {"time": 1, "timeunit": 2, "type": "all", "rule": "*"}
    ],
    "ignoreParam": False
})
# timeunit: 0=秒 1=分 2=小时 3=天
# type=all + rule=* 为全局兜底规则 (必须有)
```

## 步骤 4：上传证书 & 开启 HTTPS [#步骤-4上传证书--开启-https]

```python
# 4a. 上传证书
code, body = call_fusion("POST", "/sslcert", {
    "name": "cdn.example.com-2026",
    "commonName": "cdn.example.com",
    "pri": open("private.key").read(),
    "ca": open("fullchain.pem").read()
})
cert_id = body.get("certID")
print(f"证书ID: {cert_id}")

# 4b. 开启 HTTPS
code, body = call_api("PUT", f"/domain/cdn.example.com/sslize", {
    "ssl": {"certId": cert_id, "forceHttps": True, "http2Enable": True}
})
```

## 步骤 5：刷新缓存 [#步骤-5刷新缓存]

```python
code, body = call_fusion("POST", "/v2/tune/refresh", {
    "urls": [
        "https://cdn.example.com/index.html",
        "https://cdn.example.com/style.css"
    ]
})
request_id = body.get("requestId")
print(f"剩余配额: {body.get('urlSurplusDay')}")

# 查询刷新状态
code, body = call_fusion("POST", "/v2/tune/refresh/list", {
    "requestId": request_id
})
for item in body.get("items", []):
    print(f"{item['url']} → {item['state']}")
```

## 步骤 6：查询带宽/流量 [#步骤-6查询带宽流量]

```python
code, body = call_fusion("POST", "/v2/tune/bandwidth", {
    "domains": "cdn.example.com",          # string, 分号分隔
    "startDate": "2026-02-01",
    "endDate": "2026-02-13",
    "granularity": "day"                   # 5min / hour / day
})
print(body.get("data"))
```

## 步骤 7：查询命中率/状态码 [#步骤-7查询命中率状态码]

```python
code, body = call_fusion("POST", "/v2/tune/loganalyze/hitmiss", {
    "domains": ["cdn.example.com"],        # array, 注意和05不同!
    "startDate": "2026-02-01",
    "endDate": "2026-02-13",
    "freq": "1day"                         # 5min / 1hour / 1day (带数字前缀)
})
print(body.get("data"))
```

## 步骤 8：下载访问日志 [#步骤-8下载访问日志]

```python
code, body = call_fusion("POST", "/v2/tune/log/list", {
    "day": "2026-02-12",                   # 仅单日
    "domains": "cdn.example.com"           # string, 分号分隔
})
for domain, logs in body.get("data", {}).items():
    for log in logs:
        print(f"{log['name']}  {log['size']}B  {log['url'][:80]}...")
```

***

# 3. 关键避坑 [#3-关键避坑]

## 3.1 参数类型差异 (最常踩坑) [#31-参数类型差异-最常踩坑]

| 场景   | domains 类型                    | 时间粒度                             | 时间跨度   |
| ---- | ----------------------------- | -------------------------------- | ------ |
| 用量统计 | **string** `"a.com;b.com"`    | granularity: `5min`/`hour`/`day` | ≤ 31 天 |
| 运营统计 | **array** `["a.com","b.com"]` | freq: `5min`/`1hour`/`1day`      | ≤ 30 天 |
| 日志下载 | **string** `"a.com;b.com"`    | 仅单日 day                          | -      |

## 3.2 域名配置 Body 不包层 [#32-域名配置-body-不包层]

```python
# ✅ 正确: 直传字段
call_api("PUT", "/domain/xxx/source", {"sourceType": "domain", ...})
call_api("PUT", "/domain/xxx/cache",  {"cacheControls": [...], "ignoreParam": True})
call_api("PUT", "/domain/xxx/range",  {"enable": "off"})

# ❌ 错误: 多包一层
call_api("PUT", "/domain/xxx/source", {"source": {"sourceType": ...}})   # 400
call_api("PUT", "/domain/xxx/cache",  {"cache": {"cacheControls": ...}}) # 400309
```

## 3.3 高频错误速查 [#33-高频错误速查]

| 错误码    | 含义     | 解法                                                                 |
| ------ | ------ | ------------------------------------------------------------------ |
| 400062 | 重复域名   | 已存在，无需创建                                                           |
| 400030 | 正在处理中  | 等 5-10 分钟                                                          |
| 400317 | 非已下线域名 | 删除前须先下线                                                            |
| 400309 | 缓存未设全局 | cacheControls 须含 type=all 兜底                                       |
| 400331 | 非法参数   | freq 用 `1day` 非 `day`，跨度 ≤ 30 天                                    |
| 400034 | 刷新配额超限 | 每日 500 次，次日恢复                                                      |
| 400033 | 预取配额超限 | 每日 100 次，次日恢复                                                      |
| 401001 | 签名不匹配  | 检查 AK/SK；Qiniu鉴权校验X-Qiniu-Date/Body；QBox鉴权仅签URL+query，勿带入JSON body |
| 403024 | QPS 超限 | api 10 QPS / fusion 5-10 QPS                                       |

***

# 4. curl 速查 [#4-curl-速查]

## 4.1 Qiniu 鉴权 [#41-qiniu-鉴权]

```bash
curl -X GET 'https://api.qiniu.com/domain' \
  -H 'Host: api.qiniu.com' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>'
```

## 4.2 QBox 鉴权 [#42-qbox-鉴权]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/bandwidth' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":"cdn.example.com","startDate":"2026-02-01","endDate":"2026-02-13","granularity":"day"}'
```

***


# 域名管理 (/products/cdn/4-fusion-api-domain-management)



最近更新时间: 2026-06-04 16:37:04

# 1. 快速查阅区 [#1-快速查阅区]

## 1.1 核心接口概览 [#11-核心接口概览]

| 接口功能                      | 请求方法   | 接口路径                    | 核心参数                                | 成功响应                               |
| ------------------------- | ------ | ----------------------- | ----------------------------------- | ---------------------------------- |
| <a href="#P21">创建域名</a>   | POST   | /domain/\<Name>         | type、geoCover、platform、source、cache | `{"code":200}`                     |
| <a href="#P22">创建泛子域名</a> | POST   | /pandomain/\<Name>      | pareDomain、source、testURLPath       | `{"code":200}`                     |
| <a href="#P23">下线域名</a>   | POST   | /domain/\<Name>/offline | -                                   | `{"code":200}` (400013=已下线)        |
| <a href="#P24">上线域名</a>   | POST   | /domain/\<Name>/online  | -                                   | `{"code":200}` (400317=非已下线)       |
| <a href="#P25">删除域名</a>   | DELETE | /domain/\<Name>         | -                                   | `{"code":200}` (须先下线)              |
| <a href="#P26">获取域名信息</a> | GET    | /domain/\<Name>         | -                                   | 直接返回域名对象 (无 code 包装)               |
| <a href="#P27">获取域名列表</a> | GET    | /domain                 | marker、limit                        | `{"domains":[...],"marker":"..."}` |

> 注：`<Name>`为加速服务域名

## 1.2 核心约束 [#12-核心约束]

* **请求域名**: `api.qiniu.com`
* **鉴权方式**: Qiniu 鉴权（详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)）
* **QPS限制**: 10 QPS
* **生效时间**: 5-10 分钟

# 2. 详细接口说明 [#2-详细接口说明]

<div id="P21" />

<span id="create-domain" />

## 2.1 创建域名 [#21-创建域名]

### 基本信息 [#基本信息]

* **请求方法**: POST
* **接口地址**: `https://api.qiniu.com/domain/<Name>`
* **幂等性**: 非幂等
* **前置条件**: 国内/全球加速域名需完成ICP备案

### 请求参数 [#请求参数]

| 参数名        | 类型     | 必填 | 说明     | 示例值                                                                                        |
| ---------- | ------ | -- | ------ | ------------------------------------------------------------------------------------------ |
| type       | string | 是  | 域名类型   | `normal` (普通域名)/ `wildcard` (泛域名)                                                          |
| platform   | string | 是  | 业务类型   | `web` (静态网站) / `vod` (音视频点播)/ `download` (文件下载)/ `dynamic` (动态加速)                          |
| geoCover   | string | 是  | 加速区域   | `china` (中国大陆, 需备案) / `foreign` (海外, 免备案) / `global` (全球, 需备案)                             |
| protocol   | string | 是  | 加速协议   | `http` / `https`                                                                           |
| ipTypes    | uint   | 否  | 加速协议   | IP协议：仅允许ipv4访问，取值为1；同时允许ipv4/ipv6访问，取值为3。不指定IPTypes时，国内/全球域名默认为允许ipv4/ipv6访问，海外域名仅允许ipv4访问 |
| source     | object | 是  | 回源配置   | 参考[源站配置](/products/cdn/5-fusion-api-domain-config#update-source)                           |
| cache      | object | 是  | 缓存规则   | 参考[缓存规则](/products/cdn/5-fusion-api-domain-config#update-cache)                            |
| registerNo | string | 否  | ICP备案号 | geoCover=china/global 时必填                                                                  |

**回源配置 (source) - 七牛存储源示例**:

```json
{
    "sourceType": "qiniuBucket",
    "sourceQiniuBucket": "your-bucket-name",
    "testURLPath": "/test.jpg"
}
```

**缓存规则 (cache) - 必传, 须含全局兜底**:

```json
{
    "cacheControls": [
        {
            "time": 1,
            "timeunit": 5,
            "type": "all",
            "rule": "*"
        }
    ]
}
```

> 不配置cache规则会返回 `{"code":400309,"error":"缓存规则未设置全局或者未遵循源站"}`。

### 请求示例 [#请求示例]

```bash
curl -X POST 'https://api.qiniu.com/domain/test.example.com' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"type":"normal","platform":"web","geoCover":"foreign","protocol":"http","source":{"sourceType":"qiniuBucket","sourceQiniuBucket":"test-bucket","testURLPath":"/test.jpg"},"cache":{"cacheControls":[{"time":1,"timeunit":5,"type":"all","rule":"*"}]}}'
```

### 响应示例 [#响应示例]

**成功** (HTTP 200):

```json
{
    "code": 200
}
```

> 创建成功后通过 `GET /domain/<Name>` 获取 cname 等详细信息。

**失败**:

```json
#示例1
{
    "code": 400309,
    "error": "缓存规则未设置全局或者未遵循源站"
}
#示例2
{
    "code": 400020,
    "error": "域名未备案"
}
#示例3
{
    "code": 400062,
    "error": "重复域名"
}
```

<div id="P22" />

<span id="create-pandomain" />

## 2.2 创建泛子域名 [#22-创建泛子域名]

### 基本信息 [#基本信息-1]

* **请求方法**: POST
* **接口地址**: `https://api.qiniu.com/pandomain/<Name>`
* **前置条件**: 父泛域名必须已创建并上线

### 请求参数 [#请求参数-1]

| 参数名         | 类型     | 必填 | 说明           | 示例值                     |
| ----------- | ------ | -- | ------------ | ----------------------- |
| Name        | string | 是  | 域名（支持一级泛子域名） | `testqiniu.example.com` |
| pareDomain  | string | 是  | 泛子域名所属的泛域名   | `.example.com`          |
| source      | object | 是  | 回源配置         | 同创建域名                   |
| testURLPath | string | 是  | 源站测试路径       | `/test.jpg`             |

### 重要限制 [#重要限制]

* 仅支持一级子域名（如 `app.example.com`）
* 不支持多级嵌套（如 `x.app.example.com`）
* 父泛域名、泛子域名、存储桶必须归属同一账号
* 泛子域名必须回源七牛云存储的bucket。每个泛域名只能创建一级泛子域名，例如：.a.com 的泛域名只能创建 123.a.com的泛子域名

### 请求示例 [#请求示例-1]

```bash
curl -X POST 'https://api.qiniu.com/pandomain/testqiniu.example.com' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"pareDomain":".example.com","source":{"sourceType":"qiniuBucket","sourceQiniuBucket":"test-bucket"},"testURLPath":"/test.jpg"}'
```

### 响应示例 [#响应示例-1]

**成功** (HTTP 200):

```json
{
    "code": 200
}
```

**失败**:

```json
#示例1
{
    "code": 400095,
    "error": "未知的父域名"
}
#示例2
{
    "code": 400412,
    "error": "无效的泛子域名"
}
```

## 2.3 域名状态管理 [#23-域名状态管理]

### 状态流转 [#状态流转]

```
创建 → processing → success(online) ←→ offline → (可删除)
```

| 操作 | 成功             | 已处于目标状态     | 正在处理中  | 前置状态不满足     |
| -- | -------------- | ----------- | ------ | ----------- |
| 下线 | `{"code":200}` | 400013 重复操作 | 400030 | -           |
| 上线 | `{"code":200}` | -           | 400030 | 400317 非已下线 |
| 删除 | `{"code":200}` | -           | 400030 | 400317 须先下线 |

> 400030「正在处理中」表示上一操作 (创建/上下线) 尚未完成，需等待 5-10 分钟后重试。

<div id="P23" />

<span id="offline-domain" />

### 下线域名 [#下线域名]

```bash
curl -X POST 'https://api.qiniu.com/domain/test.example.com/offline' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>'
```

**响应**:

```json
{
    "code": 200
}
```

<div id="P24" />

<span id="online-domain" />

### 上线域名 [#上线域名]

```bash
curl -X POST 'https://api.qiniu.com/domain/test.example.com/online' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>'
```

**响应**:

```json
{
    "code": 200
}
```

<div id="P25" />

<span id="delete-domain" />

### 删除域名 [#删除域名]

**前置条件**: 域名必须处于下线状态，否则返回 400317

```bash
curl -X DELETE 'https://api.qiniu.com/domain/test.example.com' \
  -H 'Host: api.qiniu.com' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>'
```

**响应**:

```json
{
    "code": 200
}
```

## 2.4 域名查询 [#24-域名查询]

<div id="P26" />

<span id="get-domain" />

### 获取域名信息 [#获取域名信息]

```bash
curl -X GET 'https://api.qiniu.com/domain/test.example.com' \
  -H 'Host: api.qiniu.com' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>'
```

**响应示例** (HTTP 200, 直接返回域名对象, 无 code 包装):

```json
{
  "name": "test.example.com",
  "pareDomain": ".example.com",
  "type": "normal",
  "cname": "test-example-com-xxxx.qiniudns.com",
  "testURLPath": "qiniu_do_not_delete.gif",
  "protocol": "http",
  "platform": "web",
  "product": "cdn",
  "geoCover": "china",
  "operationType": "create_domain",
  "operatingState": "success",
  "operatingStateDesc": "",
  "freezeType": "notIcp",
  "createAt": "2017-08-10T12:20:12.046Z",
  "modifyAt": "2017-08-10T12:20:42.979Z",
  "source": {  "sourceType": "qiniuBucket", "sourceQiniuBucket": "..."  },
  "cache": {  "cacheControls": [...],  "ignoreParam": true  },
  "referer": { ... },
  "https": { ... },
  "ipACL": { ... },
  "uaACL": { ... },
  "timeACL": { ... },
  "bsauth": { ... },
  "tagList": None,
  "ipTypes": 3,
  "operTaskId": "",
  "operTaskType": "",
  "operTaskErrCode": 0
}
```

#### 响应参数 [#响应参数]

| 参数                 | 类型        | 说明                                                                                                                                                                                                                                                                                                                                          |   |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| name               | string    | 加速域名                                                                                                                                                                                                                                                                                                                                        |   |
| pareDomain         | string    | 父域名,属于泛子域名字段                                                                                                                                                                                                                                                                                                                                |   |
| cname              | string    | 创建域名成功后七牛生成的域名，用户需要把 `name` cname 到这个域名                                                                                                                                                                                                                                                                                                     |   |
| type               | string    | normal (普通域名)/ wildcard (泛域名)                                                                                                                                                                                                                                                                                                               |   |
| platform           | string    | 业务类型, `web` (静态网站) / `vod` (音视频点播)/ `download` (文件下载)/ `dynamic` (动态加速)                                                                                                                                                                                                                                                                     |   |
| product            | string    | 产品类型 , `cdn`(静态加速)/`dcdn`(全站加速)                                                                                                                                                                                                                                                                                                             |   |
| geoCover           | string    | 加速区域 , `china` (中国大陆, 需备案) / `foreign` (海外, 免备案) / `global` (全球, 需备案)                                                                                                                                                                                                                                                                       |   |
| protocol           | string    | 加速协议 , `http` / `https`                                                                                                                                                                                                                                                                                                                     |   |
| createAt           | string    | 域名创建时间，格式:RFC3339                                                                                                                                                                                                                                                                                                                           |   |
| modifyAt           | string    | 域名最后一次修改时间，格式:RFC3339                                                                                                                                                                                                                                                                                                                       |   |
| freezeType         | string    | 域名冻结类型,`illegal`违法违规、`notIcp`未备案、`accountFrozen`账号冻结、`other`其他                                                                                                                                                                                                                                                                              |   |
| https              | Object    | Https结构请参考 [HTTPS](/products/cdn/5-fusion-api-domain-config#update-httpsconf)                                                                                                                                                                                                                                                               |   |
| cache              | object    | Cache结构请参考 [缓存策略](/products/cdn/5-fusion-api-domain-config#update-cache)                                                                                                                                                                                                                                                                    |   |
| referer            | object    | Referer结构请参考 [referer防盗链](/products/cdn/5-fusion-api-domain-config#update-referer)                                                                                                                                                                                                                                                          |   |
| ipACL              | object    | IPACL结构请参考 [ip黑白名单](/products/cdn/5-fusion-api-domain-config#update-ipacl)                                                                                                                                                                                                                                                                  |   |
| uaACL              | object    | UAACL结构请参考 [ua黑白名单](/products/cdn/5-fusion-api-domain-config#update-uaacl)                                                                                                                                                                                                                                                                  |   |
| timeACL            | object    | TimeACL结构请参考 [时间戳防盗链](/products/cdn/5-fusion-api-domain-config#update-timeacl)                                                                                                                                                                                                                                                              |   |
| bsauth             | object    | Bsauth结构请参考 [回源鉴权](/products/cdn/5-fusion-api-domain-config#update-bsauth)                                                                                                                                                                                                                                                                  |   |
| source             | object    | Source结构请参考 [回源配置](/products/cdn/5-fusion-api-domain-config#update-source)                                                                                                                                                                                                                                                                  |   |
| operationType      | string    | 域名最近一次操作类型: `create_domain`(创建域名)/`offline_domain(下线域名)`/`online_domain`(上线域名)/ `modify_source`(修改源站配置)/`modify_referer`(修改referer配置)/`modify_cache`(修改缓存配置)/ `freeze_domain`(冻结域名)/`unfreeze_domain`(解除冻结域名)/`modify_timeacl`(修改时间戳防盗链)/ `modify_https_conf`(修改https配置/`sslize`(升级https)/`modify_bsauth`(修改回源鉴权) /`offline_bsauth`(删除回源鉴权) |   |
| operatingState     | string    | 域名最近一次的操作状态: `processing`/`success`/`failed`/`frozen`/`offlined`                                                                                                                                                                                                                                                                            |   |
| operatingStateDesc | string    | 域名最近一次的操作状态的描述                                                                                                                                                                                                                                                                                                                              |   |
| ipTypes            | uint      | IP协议：仅允许ipv4访问，取值为1；同时允许ipv4/ipv6访问，取值为3。                                                                                                                                                                                                                                                                                                   |   |
| tagList            | \[]string | 域名的标签列表（废弃）                                                                                                                                                                                                                                                                                                                                 |   |
| operTaskId         | string    | 可操作域名任务ID                                                                                                                                                                                                                                                                                                                                   |   |
| operTaskType       | string    | 域名任务可操作类型，""-无可操作，"redo"-重试，"abandon"-回滚，"all"-重试/回滚                                                                                                                                                                                                                                                                                        |   |
| operTaskErrCode    | string    | 域名任务错误码                                                                                                                                                                                                                                                                                                                                     |   |

<div id="P27" />

<span id="list-domains" />

### 获取域名列表 [#获取域名列表]

```bash
curl -X GET 'https://api.qiniu.com/domain?types=<Types>&certId=<CertId>&sourceTypes=<SourceTypes>&sourceQiniuBucket=<SourceQiniuBucket>&sourceIp=<SourceIp>&marker=<Marker>&limit=<Limit>' \
  -H 'Host: api.qiniu.com' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>'
```

#### 请求参数 [#请求参数-2]

| 参数                | 类型        | 含义                                                                                                                                                                                                                                                                                                                                                             |
| ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Types             | \[]string | 域名类型，可选normal（普通域名）、wildcard（泛域名）、pan（泛子域名）、test（测试域名）中的一个或多个，不填默认查询全部域名。                                                                                                                                                                                                                                                                                      |
| CertId            | string    | 证书ID，不填默认查询全部域名。                                                                                                                                                                                                                                                                                                                                               |
| SourceTypes       | \[]string | 回源类型，可选domain、ip、qiniuBucket、advanced中的一个或多个，不填默认查询全部域名；如果指定了SourceQiniuBucket参数，SourceTypes只能指定为qiniuBucket一种回源类型，否则SourceQiniuBucket参数将不生效；如果指定了SourceIp参数，SourceTypes只能指定为ip一种回源类型，否则SourceIp参数将不生效；同时获取多种回源类型域名的请求url示例：[http://api.qiniu.com/domain?sourceTypes=domain\&sourceTypes=ip。](http://api.qiniu.com/domain?sourceTypes=domain\&sourceTypes=ip。) |
| SourceQiniuBucket | string    | 七牛存储空间名称，不填默认查询全部域名。请求url示例：[http://api.qiniu.com/domain?sourceTypes=qiniuBucket\&sourceQiniuBucket=test。](http://api.qiniu.com/domain?sourceTypes=qiniuBucket\&sourceQiniuBucket=test。)                                                                                                                                                                       |
| SourceIp          | string    | 回源IP, 不填默认查询全部域名。请求url示例：[http://api.qiniu.com/domain?sourceTypes=ip\&sourceIp=1.1.1.1。](http://api.qiniu.com/domain?sourceTypes=ip\&sourceIp=1.1.1.1。)                                                                                                                                                                                                        |
| Marker            | string    | 用于标示从哪个位置开始获取域名列表，不填或空表示从头开始。                                                                                                                                                                                                                                                                                                                                  |
| Limit             | int       | 返回的最大域名个数。1\~1000, 不填默认10                                                                                                                                                                                                                                                                                                                                      |

**响应示例** (HTTP 200, 无 code 包装):

```json
{
  "domains": [
    {
      "name": "test.example.com",
      "cname": "test-example-com-xxxx.qiniudns.com",
      "type": "normal",
      "protocol": "http",
      "geoCover": "foreign",
      "operatingState": "success"
    }
  ],
  "marker": "MTc2NTM3MTY5NDE1MzAwMDAwMA=="
}
```

# 3. 常见问题 [#3-常见问题]

## 3.1 专属错误码 [#31-专属错误码]

| 错误码    | 描述         | 场景                    | 解决方案                                            |
| ------ | ---------- | --------------------- | ----------------------------------------------- |
| 400013 | 重复操作       | 域名已处于目标状态 (如已下线再下线)   | 无需处理                                            |
| 400020 | 域名未备案      | geoCover=china/global | 完成 ICP 备案，或改用 foreign                           |
| 400030 | 正在处理中      | 上一操作未完成               | 等待 5-10 分钟后重试                                   |
| 400041 | 源站测试路径不可访问 | 创建时 testURLPath 不可达   | 确保路径以 / 开头，源站返回 200                             |
| 400062 | 重复域名       | 域名已存在                 | 无需重复创建                                          |
| 400095 | 未知的父域名     | 创建泛子域名                | 检查 pareDomain 格式 (以 . 开头)                       |
| 400309 | 缓存规则未设置全局  | 创建时缺 cache 全局兜底       | cache.cacheControls 须含 type=all                 |
| 400317 | 域名非下线状态    | 上线非下线域名 / 删除未下线域名     | 须先下线再操作                                         |
| 400412 | 无效的泛子域名    | 泛子域名格式错误              | 仅支持一级子域名                                        |
| 500230 | 备案查询服务已关闭  | 创建域名                  | 创建域名区域geoCover=china/global时域名备案号参数RegisterNo必填 |

## 3.2 最佳实践 [#32-最佳实践]

* **创建域名**: cache 全局兜底规则必传，geoCover=foreign 可免备案
* **域名创建后**: 立即配置 DNS 解析指向 cname，5-10 分钟生效
* **状态感知**: 写操作前查询 operatingState，避免 400030 (处理中)
* **删除操作**: 先下线再删除，避免 400317
* **响应格式**: GET 域名接口直接返回域名对象，无 `code` 包装层
* **泛子域名**: 与父泛域名同账号，仅支持一级子域名

> **参考**: 鉴权详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)，错误码详见 [公共错误码&通用约束](/products/cdn/2-fusion-api-error-codes)。


# 域名配置 (/products/cdn/5-fusion-api-domain-config)



最近更新时间: 2026-09-03 10:25:02

# 1. 快速查阅区 [#1-快速查阅区]

## 1.1 核心接口概览 [#11-核心接口概览]

| 接口功能                              | 请求方法 | 接口路径                          | 核心参数                                | 成功响应          |
| --------------------------------- | ---- | ----------------------------- | ----------------------------------- | ------------- |
| [修改加速区域](#update-geocover)        | PUT  | /domain/\<Name>/geocover      | geoCover                            | \{"code":200} |
| [修改源站配置](#update-source)          | PUT  | /domain/\<Name>/source        | sourceType,sourceQiniuBucket        | \{"code":200} |
| [修改 Range 回源](#update-range)      | PUT  | /domain/\<Name>/range         | enable                              | \{"code":200} |
| [修改回源超时](#update-sourcetimeout)   | PUT  | /domain/\<Name>/sourcetimeout | SourceConnTimeout,SourceReadTimeout | \{"code":200} |
| [修改缓存规则](#update-cache)           | PUT  | /domain/\<Name>/cache         | cacheControls                       | \{"code":200} |
| [修改响应头](#update-respheader)       | PUT  | /domain/\<Name>/respheader    | responseHeaderControls              | \{"code":200} |
| [开启 HTTPS](#upgrade-https)        | PUT  | /domain/\<Name>/sslize        | certId,forceHttps,http2Enable       | \{"code":200} |
| [修改 HTTPS 配置](#update-httpsconf)  | PUT  | /domain/\<Name>/httpsconf     | certId,forceHttps,http2Enable       | \{"code":200} |
| [配置 Referer 防盗链](#update-referer) | PUT  | /domain/\<Name>/referer       | refererType,refererValues           | \{"code":200} |
| [配置 IP 黑白名单](#update-ipacl)       | PUT  | /domain/\<Name>/ipacl         | ipACLType,ipACLValues               | \{"code":200} |
| [配置 UA 黑白名单](#update-uaacl)       | PUT  | /domain/\<Name>/uaacl         | ruleType,userAgent                  | \{"code":200} |
| [配置时间戳防盗链](#update-timeacl)       | PUT  | /domain/\<Name>/timeacl       | enable,timeACLKeys,checkUrl         | \{"code":200} |
| [配置回源鉴权](#update-bsauth)          | PUT  | /domain/\<Name>/bsauth        | enable,method,userAuthUrl           | \{"code":200} |

> 注：`<Name>`为加速服务域名

## 1.2 核心约束 [#12-核心约束]

* **请求域名**: `api.qiniu.com`
* **鉴权方式**: Qiniu 鉴权（详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)）
* **QPS限制**: 10 QPS
* **生效时间**: 所有配置修改需要 5-10 分钟生效

# 2. 详细接口说明 [#2-详细接口说明]

<span id="update-geocover" />

## 2.1 修改加速区域 [#21-修改加速区域]

### 基本信息 [#基本信息]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/geocover`
* **生效时间**: 5-10 分钟
* **前置条件**: geoCover 为 china 和 global 时域名需在中国大陆已备案

### 请求参数 [#请求参数]

| 参数名      | 类型     | 必填 | 说明   | 示例值                                          |
| -------- | ------ | -- | ---- | -------------------------------------------- |
| geoCover | string | 是  | 加速区域 | `china(中国大陆)` / `foreign(海外)` / `global(全球)` |

### 请求示例 [#请求示例]

```bash
curl -X PUT 'https://api.qiniu.com/domain/test.example.com/geocover' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"geoCover":"global"}'
```

<span id="update-source" />

## 2.2 修改源站配置 [#22-修改源站配置]

### 基本信息 [#基本信息-1]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/source`

### 请求参数 [#请求参数-1]

| 参数名               | 类型        | 必填 | 说明                                                                                                    |
| ----------------- | --------- | -- | ----------------------------------------------------------------------------------------------------- |
| sourceType        | string    | 是  | 源站类型: `domain`(域名)/`ip`(ip地址)/`qiniuBucket`(七牛云存储，备注：不支持平台是动态加速)/`advanced`(高级)                       |
| sourceHost        | string    | 否  | 回源Host, 普通域名默认`SourceHost`为域名本身, 泛域名默认`SourceHost`为用户请求时的域名                                           |
| sourceIPs         | \[]string | 否  | 回源ip, sourceType为ip时sourceIPs必填                                                                       |
| sourceDomain      | string    | 否  | 回源域名, sourceType为domain时此字段必填                                                                         |
| sourceQiniuBucket | string    | 否  | 回源的七牛云存储的bucket名称, sourceType为qiniuBucket时此字段必填                                                       |
| sourceURLScheme   | string    | 否  | 回源协议,可选值: `http/https`, 回源七牛bucket时本值无效,默认不填是follow请求协议                                               |
| advancedSources   | array     | 否  | 高级回源配置                                                                                                |
| addr              | string    | 否  | 高级回源的回源地址, 可以是IP或者域名; 如需指定端口, 可直接拼接在地址后面(示例: 1.1.1.1:8080), sourceType为`advanced`时advancedSources字段必填 |
| weight            | int       | 否  | 高级回源的回源addr权重, 0 \~ 100, 按照权重比例回源, sourceType为`advanced`时advancedSources字段必填                          |
| backup            | bool      | 否  | 高级回源的回源addr是否为备源地址, sourceType为`advanced`时advancedSources字段必填                                         |
| testURLPath       | string    | 是  | 用于测试的URL Path, 检测源站是否可访问, 大小建议小于1KB, 采用静态资源, 并请不要删除, 后面域名任何配置更改都会测试该资源, 用以保证域名的访问性                    |

**回源配置示例 (七牛存储源)**:

```json
{
  "sourceType": "qiniuBucket",
  "sourceQiniuBucket": "your-bucket-name",
  "testURLPath": "/1235.jpg"
}
```

**回源配置示例 (域名源站)**:

```json
{
  "sourceType": "domain",
  "sourceDomain": "origin.example.com",
  "sourceProtocol": "http",
  "testURLPath": "/1235.jpg"
}
```

**回源配置示例 (IP源站)**:

```json
{
  "sourceType": "ip",
  "sourceIPs": ["1.1.1.1","2.2.2.2"],
  "sourceProtocol": "http",
  "testURLPath": "/1235.jpg"
}
```

**回源配置示例 (高级源站)**:

```json
{
  "sourceType": "advanced",
  "sourceURLScheme": "http",
  "advancedSources": [
        {
            "addr": "1.1.1.1:8080",
            "weight": 1,
            "backup": false
        },
        {
            "addr": "2.2.2.2:8888",
            "weight": 2,
            "backup": true
        }
    ],
    "testURLPath": "/path/1235.jpg"
}
```

### 请求示例 [#请求示例-1]

```bash
curl -X PUT 'https://api.qiniu.com/domain/test.example.com/source' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"sourceType":"qiniuBucket","sourceQiniuBucket":"new-bucket","testURLPath":"/1235.jpg"}'
```

<span id="update-range" />

## 2.3 修改 Range 回源 [#23-修改-range-回源]

### 基本信息 [#基本信息-2]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/range`

### 请求参数 [#请求参数-2]

| 参数名    | 类型     | 必填 | 说明         | 示例值          |
| ------ | ------ | -- | ---------- | ------------ |
| enable | string | 是  | Range 回源开关 | "on" / "off" |

**请求体示例**:

```json
{
    "enable": "off"
}
```

### 请求示例 [#请求示例-2]

```bash
curl -X PUT 'https://api.qiniu.com/domain/test.example.com/range' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"enable":"off"}'
```

### 响应示例 [#响应示例]

**成功** (HTTP 200):

```json
{
    "code": 200
}
```

**失败** (无改动):

```json
{
    "code": 400910,
    "error": "没有改动不能提交"
}
```

<span id="update-sourcetimeout" />

## 2.4 修改回源超时 [#24-修改回源超时]

### 基本信息 [#基本信息-3]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/sourcetimeout`

### 请求参数 [#请求参数-3]

| 参数名               | 类型  | 必填 | 说明                                           | 示例值 |
| ----------------- | --- | -- | -------------------------------------------- | --- |
| SourceConnTimeout | int | 是  | 回源建连超时（秒），0表示使用默认值（默认 5 秒），自定义范围为 5\~30 秒    | 10  |
| SourceReadTimeout | int | 是  | 回源读取超时（秒），0 表示使用默认值（默认 30 秒），自定义范围为 5\~120 秒 | 60  |

### 请求结构 [#请求结构]

```json
{
    "sourceConnTimeout": <SourceConnTimeout>,
    "sourceReadTimeout": <SourceReadTimeout>
}
```

### 响应结构 [#响应结构]

```json
{
    sourceTimeout: {
        "sourceConnTimeout": <SourceConnTimeout>,
        "sourceReadTimeout": <SourceReadTimeout>
    }
}
```

<span id="update-cache" />

## 2.5 修改缓存规则 [#25-修改缓存规则]

### 基本信息 [#基本信息-4]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/cache`

### 请求参数 [#请求参数-4]

Body 直接传 `cacheControls` + `ignoreParam`，不包 cache 层。

**cacheControls 数组中每个元素的字段:**

| 参数名      | 类型     | 必填 | 说明                                                                      | 示例值   |
| -------- | ------ | -- | ----------------------------------------------------------------------- | ----- |
| time     | int    | 是  | 缓存时间，总时间不超 1 年，type=follow 时配 -1                                        | 2     |
| timeunit | int    | 是  | 时间单位: 0(秒) / 1(分钟) / 2(小时) / 3(天) / 4(周) / 5(月) / 6(年)，type=follow 时配 0 | 3     |
| type     | string | 是  | 缓存类型: `path` (路径) / `suffix` (后缀) / `all` (全局) / `follow` (遵循源站)        | "all" |
| rule     | string | 是  | 匹配规则: path 以 / 开头，suffix 以 . 开头，all/follow 填 "\*"                       | "\*"  |

**顶层参数:**

| 参数名           | 类型        | 必填 | 说明                 | 示例值                      |
| ------------- | --------- | -- | ------------------ | ------------------------ |
| cacheControls | array     | 是  | 缓存规则数组             | 见下方示例                    |
| ignoreParam   | bool      | 否  | 是否开启去问号缓存，默认 false | true                     |
| ignoreParams  | \[]string | 否  | 忽略指定参数列表           | \["type","key"]          |
| includeParams | \[]string | 否  | 保留指定参数列表           | \["sourcepath","taskid"] |

> 修改缓存时若缺少 type=all 全局规则，服务端会自动追加默认全局兜底。

**缓存规则配置示例**:

```json
{
    "cacheControls": [
        {
            "time": 1,
            "timeunit": 2,
            "type": "path",
            "rule": "/live"
        },
        {
            "time": 2,
            "timeunit": 3,
            "type": "suffix",
            "rule": ".jpg"
        },
        {
            "time": 3,
            "timeunit": 0,
            "type": "all",
            "rule": "*"
        }
    ],
    "ignoreParam": true,
    "ignoreParams": ["type","key"],
    "includeParams": ["sourcepath","taskid"]
}
```

### 请求示例 [#请求示例-3]

```bash
curl -X PUT 'https://api.qiniu.com/domain/test.example.com/cache' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"cacheControls":[{"time":1,"timeunit":2,"type":"path","rule":"/live"},{"time":2,"timeunit":3,"type":"suffix","rule":".jpg"},{"time":3,"timeunit":0,"type":"all","rule":"*"}],"ignoreParam":true,"ignoreParams": ["type","key"],"includeParams": ["sourcepath","taskid"]}'
```

### 响应示例 [#响应示例-1]

**成功** (HTTP 200):

```json
{
    "code": 200
}
```

**失败** (用错字段名):

```json
{
    "code": 400309,
    "error": "缓存规则未设置全局或者为遵循源站"
}
```

<span id="update-respheader" />

## 2.6 修改响应头 [#26-修改响应头]

### 基本信息 [#基本信息-5]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/respheader`

### 请求参数 [#请求参数-5]

| 参数名   | 类型     | 必填 | 说明                                                                                                                                                                                                                                                                | 示例值           |
| ----- | ------ | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| op    | string | 是  | 对响应头的进行操作的类型，可选"set",“del”，目前不支持"add"                                                                                                                                                                                                                             | set           |
| key   | string | 是  | 匹配响应头的key,可选值：Content-Type,Cache-Control,Content-Disposition,Content-Language,Expires,Access-Control-Allow-Origin,Access-Control-Allow-Methods,Access-Control-Allow-Headers,Access-Control-Max-Age,Access-Control-Expose-Headers,Access-Control-Allow-Credentials | Cache-Control |
| value | string | 是  | 响应头的value,在op为"set"时有效                                                                                                                                                                                                                                            | max-age=3600  |

**响应头配置示例**:

```json
{
  "responseHeaderControls": [
    {
      "op": "set",
      "key": "Cache-Control",
      "value": "max-age=3600"
    },
    {
      "op": "set",
      "key": "Access-Control-Allow-Origin",
      "value": "*"
    }
  ]
}
```

<span id="upgrade-https" />

## 2.7 开启 HTTPS [#27-开启-https]

### 基本信息 [#基本信息-6]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/sslize`
* **前置条件**: 已上传有效的SSL证书

### 请求参数 [#请求参数-6]

| 参数名         | 类型     | 必填 | 说明                           | 示例值                             |
| ----------- | ------ | -- | ---------------------------- | ------------------------------- |
| certId      | string | 是  | 证书id，从上传或者获取证书列表里拿到证书id      | 694d122c30a46002d17c981a        |
| forceHttps  | bool   | 是  | 是否强制https跳转                  | true                            |
| http2Enable | bool   | 是  | http2功能是否启用，false为关闭，true为开启 | true                            |
| tlsVersions | string | 否  | 支持的tls版本                     | TLSv1.0/TLSv1.1/TLSv1.2/TLSv1.3 |

**SSL配置示例**:

```json
{
   "certId": "your-cert-id",
   "forceHttps": true,
   "http2Enable": true,
   "tlsVersions": "TLSv1.0"
}
```

#### 请求示例 [#请求示例-4]

```bash
curl -X PUT 'https://api.qiniu.com/domain/test.example.com/sslize' \
  -H 'Host: api.qiniu.com' \
  -H 'Content-Type: application/json' \
  -H 'X-Qiniu-Date: 20260213T120000Z' \
  -H 'Authorization: Qiniu <AK>:<Sign>' \
  -d '{"certId":"abcdef1234567890","forceHttps":true,"http2Enable":true,"tlsVersions":"TLSv1.0"}'
```

<span id="update-httpsconf" />

## 2.8 修改 HTTPS 配置 [#28-修改-https-配置]

### 基本信息 [#基本信息-7]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/httpsconf`

### 请求参数 [#请求参数-7]

| 参数名         | 类型     | 必填 | 说明          | 示例值                             |
| ----------- | ------ | -- | ----------- | ------------------------------- |
| certId      | string | 是  | 证书ID        | 同升级HTTPS                        |
| forceHttps  | bool   | 否  | 是否强制https跳转 | false                           |
| http2Enable | bool   | 否  | http2功能是否启用 | false                           |
| tlsVersions | string | 否  | 支持的tls版本    | TLSv1.0/TLSv1.1/TLSv1.2/TLSv1.3 |

**SSL证书修改示例**:

```json
{
    "certId": "update-cert-id",
    "forceHttps": true,
    "http2Enable": true,
    "tlsVersions": "TLSv1.0"
}
```

<span id="update-referer" />

## 2.9 配置 Referer 防盗链 [#29-配置-referer-防盗链]

### 基本信息 [#基本信息-8]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/referer`

### 请求参数 [#请求参数-8]

| 参数名           | 类型     | 必填 | 说明                                                | 示例值                 |
| ------------- | ------ | -- | ------------------------------------------------- | ------------------- |
| refererType   | string | 是  | Referer防盗链类型, (""代表关闭本功能, 此时请注意refererValues需要为空) | `black/white/""`    |
| refererValues | array  | 是  | Referer防盗链黑白名单, 支持泛域名和标准域名配置                      | `["*.example.com"]` |
| nullReferer   | bool   | 否  | Referer防盗链, 是否支持空referer, 不填为false                | false               |

**Referer防盗链配置示例**:

```json
{
    "refererType": "white",
    "refererValues": [
        "*.example.com",
        "www.trusted.com"
    ],
    "nullReferer": true
}
```

<span id="update-ipacl" />

## 2.10 配置 IP 黑白名单 [#210-配置-ip-黑白名单]

### 基本信息 [#基本信息-9]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/ipacl`

### 请求参数 [#请求参数-9]

| 参数名         | 类型     | 必填 | 说明                                           | 示例值                |
| ----------- | ------ | -- | -------------------------------------------- | ------------------ |
| ipACLType   | string | 是  | ip黑白名单控制控制类型(""代表关闭本功能,此时请注意ipACLValues需要为空) | `black/white/""`   |
| ipACLValues | array  | 是  | ip黑白名单, 支持IP段和指定IP配置                         | `["127.0.0.1/24"]` |

**IP黑白名单配置示例**:

```json
{
    "ipACLType": "black",
    "ipACLValues": [
        "192.168.1.0/24",
        "172.168.2.50"
    ]
}
```

<span id="update-uaacl" />

## 2.11 配置 UA 黑白名单 [#211-配置-ua-黑白名单]

### 基本信息 [#基本信息-10]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/uaacl`

### 请求参数 [#请求参数-10]

| 参数名       | 类型     | 必填 | 说明         | 示例值                          |
| --------- | ------ | -- | ---------- | ---------------------------- |
| enable    | string | 是  | ua黑白名单开关   | `on/off`                     |
| ruleType  | string | 是  | ua黑白名单控制类型 | `black/white`                |
| userAgent | array  | 是  | ua黑白名单     | `["Mozilla/5.0 (Macintosh"]` |

**UA黑白名单配置示例**:

```json
{
	"enable": "on",
	"ruleType": "black",
	"userAgent":["Mozilla/5.0 (Macintosh"]
}
```

<span id="update-timeacl" />

## 2.12 配置时间戳防盗链 [#212-配置时间戳防盗链]

### 基本信息 [#基本信息-11]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/timeacl`
* **互斥配置**: 不能与回源鉴权同时启用

### 请求参数 [#请求参数-11]

| 参数名         | 类型     | 必填 | 说明                                                                    | 示例值                                                                                                                                           |
| ----------- | ------ | -- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| enable      | bool   | 是  | 时间戳防盗链的开关                                                             | true                                                                                                                                          |
| timeACLKeys | array  | 否  | 时间戳防盗链的加密key列表,key字符长度区间为\[24,40];enable为true时必填2个key,enable为false时不填 | 见下方说明                                                                                                                                         |
| checkUrl    | string | 否  | 根据时间戳防盗链加密算法生成的url,timeACL为true时本项必填,用以验证是否真实了解该时间戳防盗链加密算法            | [https://test.example.com/test/test.jpg?sign=\&lt;SIGN\&gt;\&t=\&lt;T](https://test.example.com/test/test.jpg?sign=\&lt;SIGN\&gt;\&t=\&lt;T)> |

**时间戳防盗链配置示例**:

```json
{
    "enable": true,
    "timeACLKeys": [
        "your-secret-key-1",
        "your-secret-key-2"
    ],
    "checkUrl": "https://test.example.com/test/test.jpg?sign=<SIGN>&t=<T>"
}
```

<span id="update-bsauth" />

## 2.13 配置回源鉴权 [#213-配置回源鉴权]

### 基本信息 [#基本信息-12]

* **请求方法**: PUT
* **接口地址**: `https://api.qiniu.com/domain/<Name>/bsauth`

### 请求参数 [#请求参数-12]

| 参数名                   | 类型     | 必填 | 说明                                                            |
| --------------------- | ------ | -- | ------------------------------------------------------------- |
| enable                | bool   | 是  | 回源鉴权开关                                                        |
| method                | string | 是  | 回源鉴权 HTTP 方法: GET/POST/HEAD                                   |
| timeLimit             | int    | 是  | 鉴权超时时间 (ms)，100-10000                                         |
| userAuthUrl           | string | 是  | 鉴权服务地址                                                        |
| successStatusCode     | int    | 是  | 鉴权通过的 HTTP 状态码，100-10000                                      |
| failureStatusCode     | int    | 是  | 鉴权失败的 HTTP 状态码，100-10000                                      |
| strict                | bool   | 否  | 超时后是否严格判定为鉴权失败                                                |
| isQiniuPrivate        | bool   | 否  | 是否为七牛私有 bucket 鉴权                                             |
| path                  | string | 否  | 匹配回源鉴权的 path (暂不支持)                                           |
| parameters            | string | 否  | 参与鉴权的 URL 参数                                                  |
| userAuthMatchRuleConf | object | 否  | 鉴权对象匹配规则                                                      |
| userAuthReqConf       | object | 否  | 特殊鉴权参数 (body/header/urlquery)                                 |
| userAuthContentType   | string | 否  | MIME 类型: application/json 或 application/x-www-form-urlencoded |

**回源鉴权配置示例**:

```json
{
    "enable": true,
    "method": "GET",
    "timeLimit": 5000,
    "userAuthUrl": "https://auth.example.com/verify",
    "strict": false,
    "successStatusCode": 200,
    "failureStatusCode": 403
}
```

# 3. 常见问题 [#3-常见问题]

## 3.1 专属错误码 [#31-专属错误码]

| 错误码    | 描述                | 解决方案                          |
| ------ | ----------------- | ----------------------------- |
| 400108 | 覆盖冲突              | 加速区域未变更 (geocover 相同值重复提交)    |
| 400309 | 缓存规则未设置全局         | cache 接口包了多余层或用错字段名           |
| 400910 | 没有改动不能提交          | 配置值与当前相同 (range/source 等)     |
| 400324 | 证书不存在/已过期         | 检查 certId 有效性，重新上传有效证书        |
| 400302 | 更改证书失败            | 域名未开启 HTTPS，需先 sslize         |
| 400916 | http协议不允许降级       | 域名未开启 HTTPS，无需降级              |
| 500235 | 该域名未绑定证书          | 需先绑定证书再升级 HTTPS               |
| 400042 | 配置参数错误            | 检查缓存规则/防盗链格式符合平台要求            |
| 400520 | 不能同时设置时间戳防盗链和回源鉴权 | 两者互斥，只能启用其中一个                 |
| 404001 | 域名不存在             | 确认域名已创建且状态为 online/processing |

## 3.2 最佳实践 [#32-最佳实践]

* **配置生效时间**: 所有配置修改需要 5-10 分钟生效，避免频繁调用
* **增量修改**: 可以只传需要修改的配置项，未传项保留原有配置

> **提示**: 详细的鉴权签名生成方法请参考  [鉴权指南](/products/cdn/1-fusion-api-auth-guide),错误码详细说明请参考  [公共错误码&通用约束](/products/cdn/2-fusion-api-error-codes)。


# 用量统计 (/products/cdn/6-fusion-api-usage-stats)



最近更新时间: 2026-06-04 16:37:39

# 1. 快速查阅区 [#1-快速查阅区]

## 1.1核心接口概览 [#11核心接口概览]

| 接口功能                      | 请求方法 | 接口路径                            | 核心参数                                  | 成功响应                        |
| ------------------------- | ---- | ------------------------------- | ------------------------------------- | --------------------------- |
| <a href="#P41">计量带宽查询</a> | POST | `/v2/tune/bandwidth`            | domains、startDate、endDate、granularity | `{"code":200,"data":{...}}` |
| <a href="#P42">计量流量查询</a> | POST | `/v2/tune/flux`                 | domains、startDate、endDate、granularity | `{"code":200,"data":{...}}` |
| <a href="#P43">监控带宽查询</a> | POST | `/v2/tune/monitoring/bandwidth` | domains、startDate、endDate、granularity | `{"code":200,"data":{...}}` |
| <a href="#P44">监控流量查询</a> | POST | `/v2/tune/monitoring/flow`      | domains、startDate、endDate、granularity | `{"code":200,"data":{...}}` |

## 1.2 核心约束 [#12-核心约束]

* **请求域名**: `fusion.qiniuapi.com`
* **鉴权方式**: QBox 鉴权（详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)）
* **QPS限制**: 5-10 QPS
* **数据保留**: 计量数据180天,监控数据90天
* **时间跨度**: startDate 和 endDate 查询跨度 ≤ 31 天，超出返回 400082

## 1.3 参数关键差异 [#13-参数关键差异]

* **domains 为 string 类型 (分号分隔)**，不是数组，传数组会报 400 错误。
* 与[运营统计](/products/cdn/7-fusion-api-analytics#query-request)的 domains 为 array 类型不同，务必区分。

***

<span id="query-billing-request" />

# 2. 公共请求参数 [#2-公共请求参数]

| 参数名         | 类型     | 必填 | 说明                           | 示例值                           |
| ----------- | ------ | -- | ---------------------------- | ----------------------------- |
| domains     | string | 是  | 域名列表，分号分隔，最多 50 个            | `"a.com;b.com"`               |
| startDate   | string | 是  | 开始日期，格式 yyyy-MM-dd           | `"2026-02-01"`                |
| endDate     | string | 是  | 结束日期，格式 yyyy-MM-dd，跨度 ≤ 31 天 | `"2026-02-10"`                |
| granularity | string | 否  | 时间粒度，不传默认 5min               | `"5min"` / `"hour"` / `"day"` |
| Type        | string | 否  | 指定带宽/流量类型，根据接口查询内容设定         | `""` / `"bandwidth"｜"flux"`   |

# 3. 公共响应格式 [#3-公共响应格式]

## 响应内容 [#响应内容]

```json
{
  "code": <code>,
  "error": <error>,
  "time": <time>,
  "data": {
    ...
    <Domain_i>: {
      "china": <Domain_i_China>,
      "oversea": <Domain_i_Oversea>
    },
    ...
  }
}
```

## 响应参数 [#响应参数]

| 参数名                | 类型        | 说明                              |
| ------------------ | --------- | ------------------------------- |
| code               | int       | 响应状态码                           |
| error              | string    | 响应错误描述                          |
| time               | \[]string | 时间点数组，如2026-01-02 00:00:00      |
| data               | map       | 响应数据                            |
| Domain\_i          | string    | 域名                              |
| Domain\_i\_China   | \[]int    | Domain\_i 国内带宽/流量数据，与 time 一一对应 |
| Domain\_i\_Oversea | \[]int    | Domain\_i 海外带宽/流量数据，与 time 一一对应 |

***

# 4. 详细接口说明 [#4-详细接口说明]

<div id="P41" />

<span id="query-billing-bandwidth" />

## 4.1 计量带宽查询 [#41-计量带宽查询]

### 基本信息 [#基本信息]

* **请求方法**: POST
* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/bandwidth`
* **数据用途**: 账单核对，计量维度带宽数据 (bps)

### 请求示例 [#请求示例]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/bandwidth' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":"test.example.com","startDate":"2026-02-01","endDate":"2026-02-10","granularity":"5min"}'
```

### 响应示例 [#响应示例]

**成功** (HTTP 200):

```json
{
    "code": 200,
    "error": "",
    "time": [
        "2026-02-01 00:00:00",
        "2026-02-01 00:05:00"
    ],
    "data": {
        "test.example.com": {
            "china": [
                1252,
                4431
            ],
            "oversea": [
                678,
                414
            ]
        }
    }
}
```

<div id="P42" />

<span id="query-billing-flux" />

## 4.2 计量流量查询 [#42-计量流量查询]

### 基本信息 [#基本信息-1]

* **请求方法**: POST
* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/flux`
* **数据用途**: 账单核对，计量维度流量数据 (byte)

### 请求示例 [#请求示例-1]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/flux' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":"test.example.com","startDate":"2026-02-01","endDate":"2026-02-10","granularity":"day"}'
```

<div id="P43" />

<span id="query-monitoring-bandwidth" />

## 4.3 监控带宽查询 [#43-监控带宽查询]

### 基本信息 [#基本信息-2]

* **请求方法**: POST
* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/monitoring/bandwidth`
* **数据用途**: 实时监控，分钟级带宽数据，时效性优先

### 请求示例 [#请求示例-2]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/monitoring/bandwidth' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":"test.example.com","startDate":"2026-02-10","endDate":"2026-02-10","granularity":"5min"}'
```

<div id="P44" />

<span id="query-monitoring-flow" />

## 4.4 监控流量查询 [#44-监控流量查询]

### 基本信息 [#基本信息-3]

* **请求方法**: POST
* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/monitoring/flow`
* **数据用途**: 实时监控，分钟级流量数据，时效性优先

### 请求示例 [#请求示例-3]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/monitoring/flow' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":"test.example.com","startDate":"2026-02-10","endDate":"2026-02-10","granularity":"5min"}'
```

***

# 5. 常见问题 [#5-常见问题]

## 5.1 专属错误码 [#51-专属错误码]

| 错误码    | 描述           | 场景                                     | 解决方案                    |
| ------ | ------------ | -------------------------------------- | ----------------------- |
| 400    | domains 类型错误 | 传了数组而非字符串                              | domains 必须为 string，分号分隔 |
| 400080 | 开始时间格式错误     | startDate 非 yyyy-MM-dd                 | 修正日期格式                  |
| 400081 | 结束时间格式错误     | endDate 非 yyyy-MM-dd                   | 修正日期格式                  |
| 400082 | 无效的时间范围      | startDate 大于 endDate、跨度超 31 天、或超出数据保留期 | 调整时间范围                  |
| 400032 | 无效域名         | 域名未接入 CDN                              | 确认域名已创建且上线              |

## 5.2 最佳实践 [#52-最佳实践]

* **domains 格式**: 字符串用分号分隔，不是数组，最多 50 个
* **时间范围**: 跨度不超过 31 天，建议按天/按周查询
* **多域名聚合**: 一次查询多域名时，响应按域名分组返回
* **缓存策略**: 计量数据变化低频，建议本地缓存 5-10 分钟

> **参考**: 鉴权详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)，错误码详见 [公共错误码&通用约束](/products/cdn/2-fusion-api-error-codes)。


# 运营统计 (/products/cdn/7-fusion-api-analytics)



最近更新时间: 2026-06-04 16:37:52

# 1. 快速查阅区 [#1-快速查阅区]

## 1.1 核心接口概览 [#11-核心接口概览]

| 接口功能                             | 请求方法 | 接口路径                                | 特殊参数            | 成功响应                        |
| -------------------------------- | ---- | ----------------------------------- | --------------- | --------------------------- |
| <a href="#P41">缓存命中率统计</a>       | POST | `/v2/tune/loganalyze/hitmiss`       | freq            | `{"code":200,"data":{...}}` |
| <a href="#P42">HTTP 状态码统计</a>    | POST | `/v2/tune/loganalyze/statuscode`    | freq、region、isp | `{"code":200,"data":{...}}` |
| <a href="#P43">请求次数统计</a>        | POST | `/v2/tune/loganalyze/reqcount`      | freq、region     | `{"code":200,"data":{...}}` |
| <a href="#P44">UV 独立访客统计</a>     | POST | `/v2/tune/loganalyze/uniquevisitor` | freq            | `{"code":200,"data":{...}}` |
| <a href="#P45">访问次数Top URL统计</a> | POST | `/v2/tune/loganalyze/topcounturl`   | region          | `{"code":200,"data":{...}}` |
| <a href="#P46">访问流量Top URL统计</a> | POST | `/v2/tune/loganalyze/toptrafficurl` | region          | `{"code":200,"data":{...}}` |
| <a href="#P47">访问次数Top IP统计</a>  | POST | `/v2/tune/loganalyze/topcountip`    | region          | `{"code":200,"data":{...}}` |
| <a href="#P48">访问流量Top IP统计</a>  | POST | `/v2/tune/loganalyze/toptrafficip`  | region          | `{"code":200,"data":{...}}` |
| <a href="#P49">区域运营商流量统计</a>     | POST | `/v2/tune/loganalyze/traffic`       | freq、region、isp | `{"code":200,"data":{...}}` |
| <a href="#P410">区域运营商带宽统计</a>    | POST | `/v2/tune/loganalyze/bandwidth`     | freq、region、isp | `{"code":200,"data":{...}}` |
| <a href="#P411">ISP 请求次数统计</a>   | POST | `/v2/tune/loganalyze/ispreqcount`   | freq、region     | `{"code":200,"data":{...}}` |
| <a href="#P412">ISP 流量占比统计</a>   | POST | `/v2/tune/loganalyze/isptraffic`    | freq            | `{"code":200,"data":{...}}` |

## 1.2 核心约束 [#12-核心约束]

* **请求域名**: `fusion.qiniuapi.com`
* **鉴权方式**: QBox 鉴权（详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)）
* **QPS限制**: 5-10 QPS
* **数据保留**: 90 天
* **时间跨度**: ≤ 30 天，超出返回 400331

## 1.3 参数关键差异 [#13-参数关键差异]

* **domains 为 array 类型** (如 `["a.com","b.com"]`)，不是字符串。
* 与[用量统计](/products/cdn/6-fusion-api-usage-stats#query-billing-request)的 domains 为 string 类型 (分号分隔) 不同，务必区分。
* **freq 值格式**: `"5min"` / `"1hour"` / `"1day"`，注意带数字前缀，传 `"day"` 或 `"hour"` 会返回 400331。

***

<span id="query-request" />

# 2. 公共请求参数 [#2-公共请求参数]

| 参数名       | 类型     | 必填     | 说明                           | 示例值                                  |
| --------- | ------ | ------ | ---------------------------- | ------------------------------------ |
| domains   | array  | 是      | 域名数组，最多 100 个                | `["a.com","b.com"]`                  |
| startDate | string | 是      | 开始日期，格式 yyyy-MM-dd           | `"2026-02-01"`                       |
| endDate   | string | 是      | 结束日期，格式 yyyy-MM-dd，跨度 ≤ 30 天 | `"2026-02-10"`                       |
| freq      | string | 部分接口必传 | 时间粒度                         | `"5min"` / `"1hour"` / `"1day"`      |
| region    | string | 部分接口可选 | 区域                           | `"global"` / `"china"` / `"oversea"` |

> Top 类接口 (topcounturl/toptrafficurl/topcountip/toptrafficip) 不传 freq；traffic/bandwidth 接口额外需要 isp 参数。
> 部分参数必传差异参考：<a href="#P52">5.2 接口参数分组</a>；region 可选区域参考：<a href="#P53">5.3 附件: Region 参数列表</a>

# 3. 公共响应格式 [#3-公共响应格式]

## 公共响应参数 [#公共响应参数]

| 参数名   | 类型     | 说明     |
| ----- | ------ | ------ |
| code  | int    | 响应状态码  |
| error | string | 响应错误描述 |
| data  | map    | 响应数据   |

## 公共响应示例 [#公共响应示例]

**示例：**

```json
{
    "code": 200,
    "error": "",
    "data": {
        ...
    }
}
```

***

# 4. 详细接口说明 [#4-详细接口说明]

<div id="P41" />

<span id="query-hitmiss" />

## 4.1 缓存命中率统计 [#41-缓存命中率统计]

### 基本信息 [#基本信息]

* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/loganalyze/hitmiss`
* **数据说明**: 返回 hit/miss 请求次数和流量命中数据

### 请求示例 [#请求示例]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/loganalyze/hitmiss' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":["test.example.com"],"startDate":"2026-02-01","endDate":"2026-02-01","freq":"1day"}'
```

### 响应内容 [#响应内容]

```json
{
   "data" : {
      "points" : [<point1>, <point2>, <point3>, ......],
      "hit" : [<hitCount1>, <hitCount2>, <hitCount3>, ......],
      "miss" : [<missCount1>, <missCount2>, <missCount3>, ......],
      "trafficHit" : [<trafficHitCount1>, <trafficHitCount2>, <trafficHitCount3>, ......],
      "trafficMiss" : [<trafficMissCount1>, <trafficMissCount2>, <trafficMissCount3>, ......]
   },
   "error" : <error>,
   "code" : <code>
}
```

### 响应参数 [#响应参数]

| 参数名               | 类型     | 说明                       |
| ----------------- | ------ | ------------------------ |
| pointN            | string | 时间点，形如 2026-01-02-15-04  |
| hitCountN         | long   | pointN 时间点的命中次数          |
| missCountN        | long   | pointN 时间点的未命中次数         |
| trafficHitCountN  | long   | pointN 时间点的命中流量，单位 Byte  |
| trafficMissCountN | long   | pointN 时间点的未命中流量，单位 Byte |

<div id="P42" />

<span id="query-statuscode" />

## 4.2 HTTP 状态码统计 [#42-http-状态码统计]

### 基本信息 [#基本信息-1]

* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/loganalyze/statuscode`
* **数据说明**: 各 HTTP 状态码 (2xx/3xx/4xx/5xx) 的请求次数

### 请求示例 [#请求示例-1]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/loganalyze/statuscode' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":["test.example.com"],"startDate":"2026-02-10","endDate":"2026-02-13","freq":"1day","region":"global"}'
```

> isp 可选值: `"telecom"` (电信) / `"unicom"` (联通) / `"mobile"` (移动) / `"drpeng"` (鹏博士) / `"tietong"` (铁通) / `"cernet"` (教育网) /`"all"` (所有 ISP)

### 响应内容 [#响应内容-1]

```json
{
   "data" : {
      "codes" : {
         <statusCode> : [<codeCount1>, <codeCount2>, <codeCount3>, ......]
      },
      "points" : [<point1>, <point2>, <point3>, ......]
   },
   "error" : <error>,
   "code" : <code>
}
```

### 响应参数 [#响应参数-1]

| 参数名        | 类型     | 说明                      |
| ---------- | ------ | ----------------------- |
| pointN     | string | 时间点，形如 2026-01-02-15-04 |
| statusCode | string | 状态码                     |
| codeCountN | long   | 状态码在 pointN 时间点的个数      |

<div id="P43" />

<span id="query-reqcount" />

## 4.3 请求次数统计 [#43-请求次数统计]

### 基本信息 [#基本信息-2]

* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/loganalyze/reqcount`
* **数据说明**: 按区域查询 CDN 总请求次数

### 请求示例 [#请求示例-2]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/loganalyze/reqcount' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":["test.example.com"],"startDate":"2026-02-10","endDate":"2026-02-13","freq":"1day","region":"global"}'
```

### 响应内容 [#响应内容-2]

```json
{
   "data" : {
      "reqCount" : [<reqCount1>, <reqCount2>, <reqCount3>, ......],
      "points" : [<point1>, <point2>, <point3>, ......]
   },
   "error" : <error>,
   "code": <code>
}
```

### 响应参数 [#响应参数-2]

| 参数名       | 类型     | 说明                      |
| --------- | ------ | ----------------------- |
| pointN    | string | 时间点，形如 2026-01-02-15-04 |
| reqCountN | long   | pointN 时间点的请求次数         |

<div id="P44" />

<span id="query-unique-visitor" />

## 4.4 UV 独立访客统计 [#44-uv-独立访客统计]

### 基本信息 [#基本信息-3]

* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/loganalyze/uniquevisitor`
* **数据说明**: 每日独立访客数 (UV)

### 请求示例 [#请求示例-3]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/loganalyze/uniquevisitor' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":["test.example.com"],"startDate":"2026-02-10","endDate":"2026-02-13","freq":"1day"}'
```

### 响应内容 [#响应内容-3]

```json
{
   "data" : {
      "uvCount" : [<uvCount1>, <uvCount2>, <uvCount3>, ......],
      "points" : [<point1>, <point2>, <point3>, ......]
   },
   "error" : <error>,
   "code" : <code>
}
```

### 响应参数 [#响应参数-3]

| 参数名      | 类型     | 说明                           |
| -------- | ------ | ---------------------------- |
| pointN   | string | 时间点，形如 2026-01-02-15-04      |
| uvCountN | long   | pointN 时间点的 UniqueVisitor 个数 |

<div id="P45" />

<span id="query-top-count-url" />

## 4.5 访问次数Top URL统计 [#45-访问次数top-url统计]

### 基本信息 [#基本信息-4]

* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/loganalyze/topcounturl`
* **数据说明**: 按访问次数排序的 URL 列表，默认 Top 100

### 请求示例 [#请求示例-4]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/loganalyze/topcounturl' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":["test.example.com"],"startDate":"2026-02-10","endDate":"2026-02-13","region":"global"}'
```

### 响应内容 [#响应内容-4]

```json
{
   "data" : {
      "count" : [<count1>, <count2>, <count3>, ......],
      "urls": [<url1>, <url2>, <url3>, ......]
   },
   "error" : <error>,
   "code": <code>
}
```

### 响应参数 [#响应参数-4]

| 参数名    | 类型     | 说明                      |
| ------ | ------ | ----------------------- |
| urlN   | string | URL，去查询参数               |
| countN | long   | urlN 在查询时间区间内的访问次数，降序排列 |

<div id="P46" />

<span id="query-top-traffic-url" />

## 4.6 访问流量Top URL统计 [#46-访问流量top-url统计]

### 基本信息 [#基本信息-5]

* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/loganalyze/toptrafficurl`
* **数据说明**: 按访问流量排序的 URL 列表

### 请求示例 [#请求示例-5]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/loganalyze/toptrafficurl' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":["test.example.com"],"startDate":"2026-02-10","endDate":"2026-02-13","region":"global"}'
```

### 响应内容 [#响应内容-5]

```json
{
   "data" : {
      "traffic" : [<traffic1>, <traffic2>, <traffic3>, ......],
      "urls": [<url1>, <url2>, <url3>, ......]
   },
   "error" : <error>,
   "code": <code>
}
```

### 响应参数 [#响应参数-5]

| 参数名      | 类型     | 说明                              |
| -------- | ------ | ------------------------------- |
| urlN     | string | URL，去查询参数                       |
| trafficN | long   | urlN 在查询时间区间内的访问流量，单位 Byte。降序排列 |

<div id="P47" />

<span id="query-top-count-ip" />

## 4.7 访问次数Top IP统计 [#47-访问次数top-ip统计]

### 基本信息 [#基本信息-6]

* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/loganalyze/topcountip`
* **数据说明**: 按访问次数排序的客户端 IP 列表

### 请求示例 [#请求示例-6]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/loganalyze/topcountip' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":["test.example.com"],"startDate":"2026-02-10","endDate":"2026-02-13","region":"global"}'
```

### 响应内容 [#响应内容-6]

```json
{
   "data" : {
      "count" : [<count1>, <count2>, <count3>, ......],
      "ips": [<ip1>, <ip2>, <ip3>, ......]
   },
   "error" : <error>,
   "code": <code>
}
```

### 响应参数 [#响应参数-6]

| 参数名    | 类型     | 说明                     |
| ------ | ------ | ---------------------- |
| ipN    | string | IP                     |
| countN | long   | ipN 在查询时间区间内的访问次数，降序排列 |

<div id="P48" />

<span id="query-top-traffic-ip" />

## 4.8 访问流量Top IP统计 [#48-访问流量top-ip统计]

### 基本信息 [#基本信息-7]

* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/loganalyze/toptrafficip`
* **数据说明**: 按访问流量排序的客户端 IP 列表

### 请求示例 [#请求示例-7]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/loganalyze/toptrafficip' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":["test.example.com"],"startDate":"2026-02-10","endDate":"2026-02-13","region":"global"}'
```

### 响应内容 [#响应内容-7]

```json
{
   "data" : {
      "traffic" : [<traffic1>, <traffic2>, <traffic3>, ......],
      "ips": [<ip1>, <ip2>, <ip3>, ......]
   },
   "error" : <error>,
   "code": <code>
}
```

### 响应参数 [#响应参数-7]

| 参数名      | 类型     | 说明                             |
| -------- | ------ | ------------------------------ |
| ipN      | string | IP                             |
| trafficN | long   | ipN 在查询时间区间内的访问流量，单位 Byte。降序排列 |

<div id="P49" />

<span id="query-isp-traffic" />

## 4.9 区域运营商流量统计 [#49-区域运营商流量统计]

### 基本信息 [#基本信息-8]

* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/loganalyze/traffic`
* **数据说明**: 按区域/运营商查询流量数据
* **额外必传**: isp 参数

### 请求示例 [#请求示例-8]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/loganalyze/traffic' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":["test.example.com"],"startDate":"2026-02-10","endDate":"2026-02-13","freq":"1day","region":"china","isp":"telecom"}'
```

> isp 可选值: `"telecom"` (电信) / `"unicom"` (联通) / `"mobile"` (移动) / `"drpeng"` (鹏博士) / `"tietong"` (铁通) / `"cernet"` (教育网) /`"all"` (所有 ISP)

### 响应内容 [#响应内容-8]

```json
{
  "code": <code>,
  "error": <error>,
  "data": {
     "points": [<point1>, <point2>, <point3>, ......],
     "value": [<value1>, <value2>, <value3>, ......]
  }
}
```

### 响应参数 [#响应参数-8]

| 参数名    | 类型     | 说明                      |
| ------ | ------ | ----------------------- |
| pointN | string | 时间点，形如 2026-01-02-15-04 |
| valueN | long   | 在 pointN 时间点的流量         |

<div id="P410" />

<span id="query-isp-bandwidth" />

## 4.10 区域运营商带宽统计 [#410-区域运营商带宽统计]

### 基本信息 [#基本信息-9]

* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/loganalyze/bandwidth`
* **数据说明**: 按区域/运营商查询带宽数据
* **额外必传**: isp 参数 (同 traffic 接口)

### 请求示例 [#请求示例-9]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/loganalyze/bandwidth' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":["test.example.com"],"startDate":"2026-02-10","endDate":"2026-02-13","freq":"1day","region":"china","isp":"telecom"}'
```

> isp 可选值: `"telecom"` (电信) / `"unicom"` (联通) / `"mobile"` (移动) / `"drpeng"` (鹏博士) / `"tietong"` (铁通) / `"cernet"` (教育网) /`"all"` (所有 ISP)

### 响应内容 [#响应内容-9]

```json
{
  "code": <code>,
  "error": <error>,
  "data": {
     "points": [<point1>, <point2>, <point3>, ......],
     "value": [<value1>, <value2>, <value3>, ......]
  },
  "stats": {
    "peak": {
      "time": <peakTime>,
      "value": <peakValue>
    },
    "peak95": {
      "time": <peak95Time>,
      "value": <peak95Value>
    },
    "peak95Average": <peak95Average>,
    "peakAverage": <peakAverage>
  }
}
```

### 响应参数 [#响应参数-9]

| 参数名           | 类型     | 说明                          |
| ------------- | ------ | --------------------------- |
| pointN        | string | 时间点，形如 2026-01-02-15-04     |
| valueN        | long   | 在 pointN 时间点的带宽             |
| peakTime      | string | 峰值的时间点，形如 2026-01-02-15-04  |
| peakValue     | long   | 峰值带宽                        |
| peak95Time    | string | 95峰的时间点，形如 2026-01-02-15-04 |
| peak95Value   | long   | 95峰带宽                       |
| peakAverage   | long   | 各天峰值的平均值                    |
| peak95Average | long   | 各天95峰的平均值                   |

<div id="P411" />

<span id="query-isp-reqcount" />

## 4.11 ISP 请求次数统计 [#411-isp-请求次数统计]

### 基本信息 [#基本信息-10]

* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/loganalyze/ispreqcount`
* **数据说明**: 按运营商查询 CDN 请求次数

### 请求示例 [#请求示例-10]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/loganalyze/ispreqcount' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":["test.example.com"],"startDate":"2026-02-10","endDate":"2026-02-13","freq":"1day","region":"global"}'
```

### 响应内容 [#响应内容-10]

```json
{
   "data" : {
      "ispReq" : {
          <isp>: [<reqCount1>, <reqCount2>, <reqCount3>, ......]
      },
      "points" : [<point1>, <point2>, <point3>, ......]
   },
   "error" : <error>,
   "code": <code>
}
```

### 响应参数 [#响应参数-10]

| 参数名       | 类型     | 说明                                                                                           |
| --------- | ------ | -------------------------------------------------------------------------------------------- |
| pointN    | string | 时间点，形如 2026-01-02-15-04                                                                      |
| isp       | string | ISP 运营商，包括 telecom（电信）、unicom（联通）、 mobile（移动）、drpeng（鹏博士）、tietong（铁通）、cernet（教育网）、others（其他） |
| reqCountN | long   | pointN 时间点的请求次数                                                                              |

<div id="P412" />

<span id="query-isp-traffic-ratio" />

## 4.12 ISP 流量占比统计 [#412-isp-流量占比统计]

### 基本信息 [#基本信息-11]

* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/loganalyze/isptraffic`
* **数据说明**: 各运营商的流量占比

### 请求示例 [#请求示例-11]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/loganalyze/isptraffic' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":["test.example.com"],"startDate":"2026-02-10","endDate":"2026-02-13","freq":"1day"}'
```

### 响应内容 [#响应内容-11]

```json
{
  "code": <code>,
  "error" : <error>,
  "data": {
     "isp1": <value1>,
     "isp2": <value2>
  }
}
```

### 响应参数 [#响应参数-11]

| 参数名    | 类型     | 说明                    |
| ------ | ------ | --------------------- |
| ispN   | string | 运营商                   |
| valueN | float  | 运营商 ispN 对应的流量占总流量的比例 |

***

# 5. 常见问题 [#5-常见问题]

## 5.1 专属错误码 [#51-专属错误码]

| 错误码    | 描述           | 场景                                             | 解决方案              |
| ------ | ------------ | ---------------------------------------------- | ----------------- |
| 400    | domains 类型错误 | 传了字符串而非数组                                      | domains 必须为 array |
| 400331 | 非法参数         | freq 值错误 (传 "day" 而非 "1day")、时间跨度超 30 天、缺少必传参数 | 检查 freq 格式和时间范围   |
| 400080 | 开始时间格式错误     | startDate 非 yyyy-MM-dd                         | 修正日期格式            |
| 400081 | 结束时间格式错误     | endDate 非 yyyy-MM-dd                           | 修正日期格式            |
| 400032 | 无效域名         | 域名未接入 CDN                                      | 确认域名已创建且上线        |

<div id="P52" />

## 5.2 接口参数分组 [#52-接口参数分组]

| 接口            | freq | region | isp |
| ------------- | ---- | ------ | --- |
| hitmiss       | 必传   | -      | -   |
| statuscode    | 必传   | 可选     | 可选  |
| reqcount      | 必传   | 可选     | -   |
| uniquevisitor | 必传   | -      | -   |
| topcounturl   | -    | 可选     | -   |
| toptrafficurl | -    | 可选     | -   |
| topcountip    | -    | 可选     | -   |
| toptrafficip  | -    | 可选     | -   |
| traffic       | 必传   | 必传     | 必传  |
| bandwidth     | 必传   | 必传     | 必传  |
| ispreqcount   | 必传   | 必传     | -   |
| isptraffic    | 必传   | -      | -   |

<div id="P53" />

## 5.3 附件: Region 参数列表 [#53-附件-region-参数列表]

| 参数           | 说明   |
| ------------ | ---- |
| global       | 全球   |
| oversea      | 海外   |
| china        | 中国   |
| shandong     | 山东   |
| jiangsu      | 江苏   |
| zhejiang     | 浙江   |
| anhui        | 安徽   |
| shanghai     | 上海   |
| fujian       | 福建   |
| jiangxi      | 江西   |
| guangdong    | 广东   |
| guangxi      | 广西   |
| hainan       | 海南   |
| henan        | 河南   |
| hunan        | 湖南   |
| hubei        | 湖北   |
| beijing      | 北京   |
| tianjin      | 天津   |
| hebei        | 河北   |
| shanxi       | 山西   |
| neimenggu    | 内蒙古  |
| ningxia      | 宁夏   |
| qinghai      | 青海   |
| gansu        | 甘肃   |
| shaanxi      | 陕西   |
| sichuan      | 四川   |
| guizhou      | 贵州   |
| xinjiang     | 新疆   |
| yunnan       | 云南   |
| chongqing    | 重庆   |
| xizang       | 西藏   |
| liaoning     | 辽宁   |
| jilin        | 吉林   |
| heilongjiang | 黑龙江  |
| hongkong     | 香港   |
| macau        | 澳门   |
| taiwan       | 台湾   |
| unknown      | 未知地区 |

## 5.4 最佳实践 [#54-最佳实践]

* **domains 格式**: 数组类型，与**用量统计**的字符串类型不同
* **freq 格式**: 必须带数字前缀 `"5min"` / `"1hour"` / `"1day"`，传 `"day"` 会 400331
* **时间范围**: 跨度 ≤ 30 天，超出返回 400331
* **traffic/bandwidth/statuscode**: 需额外传 region + isp 参数
* **Top 类接口**: 不传 freq，默认返回 Top 100

> **参考**: 鉴权详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)，错误码详见 [公共错误码&通用约束](/products/cdn/2-fusion-api-error-codes)。


# 缓存管理 (/products/cdn/8-fusion-api-cache-management)



最近更新时间: 2026-06-04 16:38:11

# 1. 快速查阅区 [#1-快速查阅区]

## 1.1 核心接口概览 [#11-核心接口概览]

| 接口功能                      | 请求方法 | 接口路径                     | 核心参数               | 成功响应                           |
| ------------------------- | ---- | ------------------------ | ------------------ | ------------------------------ |
| <a href="#P21">缓存刷新</a>   | POST | `/v2/tune/refresh`       | urls、dirs          | `{"code":200,"taskIds":{...}}` |
| <a href="#P22">刷新任务查询</a> | POST | `/v2/tune/refresh/list`  | requestId / taskId | `{"code":200,"items":[...]}`   |
| <a href="#P23">资源预取</a>   | POST | `/v2/tune/prefetch`      | urls               | `{"code":200,"taskIds":{...}}` |
| <a href="#P24">预取任务查询</a> | POST | `/v2/tune/prefetch/list` | requestId          | `{"code":200,"items":[...]}`   |

## 1.2 核心约束 [#12-核心约束]

* **请求域名**: `fusion.qiniuapi.com`
* **鉴权方式**: QBox 鉴权（详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)）
* **QPS限制**: 刷新+预取请求中 url/dir 总量每秒 ≤ 240
* **生效时间**: 5-10 分钟

## 1.3 每日配额 [#13-每日配额]

| 操作   | 默认配额    | 单次上限 (官网) | 超限错误码           |
| ---- | ------- | --------- | --------------- |
| 文件刷新 | 500 次/天 | 20 个 URL  | 400034          |
| 目录刷新 | 11次/天   | 5 个目录     | 400035 / 400038 |
| 资源预取 | 100 次/天 | 20 个 URL  | 400033          |

> 配额每日 0 点重置，可在控制台申请提升。成功响应中 `urlQuotaDay` / `urlSurplusDay` 返回当日配额和剩余量。

***

# 2. 详细接口说明 [#2-详细接口说明]

<div id="P21" />

<span id="cache-refresh" />

## 2.1 缓存刷新 [#21-缓存刷新]

### 基本信息 [#基本信息]

* **请求方法**: POST
* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/refresh`
* **用途**: 强制 CDN 节点回源拉取最新文件

### 请求参数 [#请求参数]

| 参数名  | 类型    | 必填 | 说明                                   | 示例值                           |
| ---- | ----- | -- | ------------------------------------ | ----------------------------- |
| urls | array | 否  | 文件 URL 列表，完整 http\:// 或 https\:// 格式 | `["http://test.com/a.jpg"]`   |
| dirs | array | 否  | 目录 URL 列表，须以 / 结尾                    | `["http://test.com/static/"]` |

> urls 和 dirs 不能同时为空，至少传一个。

### 请求示例 [#请求示例]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/refresh' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"urls":["http://test.example.com/index.html","http://test.example.com/style.css"],"dirs":["http://test.example.com/static/"]}'
```

### 响应参数 [#响应参数]

| 参数名           | 类型                 | 说明                                   |
| ------------- | ------------------ | ------------------------------------ |
| code          | int                | 响应状态码                                |
| error         | string             | 响应错误码描述                              |
| requestId     | string             | 刷新请求id，只有在任务被接受时才有值                  |
| taskIds       | map\[string]string | URL/DIR 对应的任务 ID，map\[url/dir]taskId |
| invalidUrls   | string array       | 无效的url列表                             |
| invalidDirs   | string array       | 无效的dir列表                             |
| urlQuotaDay   | int                | 每日的刷新url限额                           |
| urlSurplusDay | int                | 每日的当前剩余的刷新url限额                      |
| dirQuotaDay   | int                | 每日的刷新dir限额                           |
| dirSurplusDay | int                | 每日的当前剩余的刷新dir限额                      |

### 响应示例 [#响应示例]

**成功** (HTTP 200):

```json
{
    "code": 200,
    "error": "success",
    "requestId": "698e908943d723411eda9d41",
    "taskIds": {
        "http://test.example.com/index.html": "698e908943d723411eda9d42",
        "http://test.example.com/static/": "698e908943d723411eda9d43"
    },
    "invalidUrls": null,
    "invalidDirs": null,
    "urlQuotaDay": 500,
    "urlSurplusDay": 493,
    "dirQuotaDay": 11,
    "dirSurplusDay": 3
}
```

**失败**:

```json
{
    "code": 400031,
    "error": "invalid url",
    "invalidUrls": [
        "invalid-url"
    ]
}
```

<div id="P22" />

<span id="query-refresh" />

## 2.2 刷新任务查询 [#22-刷新任务查询]

### 基本信息 [#基本信息-1]

* **请求方法**: POST
* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/refresh/list`
* **用途**: 查询刷新任务执行状态
* **查询时间范围**: 近 7 天，默认返回近 3 天记录

### 请求参数 [#请求参数-1]

| 参数名       | 类型     | 必填 | 说明       | 示例值                                        |
| --------- | ------ | -- | -------- | ------------------------------------------ |
| taskIds   | array  | 否  | 任务 ID 列表 | `["698ee3057911048e39e0ac8d"]`             |
| requestId | string | 否  | 请求 ID    | `"698ee3057911048e39e0ac8c"`               |
| isDir     | string | 否  | 是否目录刷新   | `"yes"` / `"no"`                           |
| urls      | array  | 否  | 按 URL 查询 | `["http://test.com/a.jpg"]`                |
| state     | string | 否  | 按状态筛选    | `"success"` / `"failure"` / `"processing"` |
| pageNo    | int    | 否  | 页码       | 0                                          |
| pageSize  | int    | 否  | 每页条数     | 100                                        |
| startTime | string | 否  | 开始日期     | `"2026-02-10"`                             |
| endTime   | string | 否  | 结束日期     | `"2026-02-13"`                             |

> 可选参数不能全部为空，至少传一个。时间范围最多 7 天，startTime/endTime 缺失时默认返回近 3 天。

### 请求示例 [#请求示例-1]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/refresh/list' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"requestId":"698e908943d723411eda9d41"}'
```

### 响应参数 [#响应参数-1]

| 参数名         | 类型     | 说明                                                    |
| ----------- | ------ | ----------------------------------------------------- |
| code        | int    | 响应状态码                                                 |
| error       | string | 响应错误码描述                                               |
| requestId   | string | 记录所在的刷新请求id                                           |
| total       | int    | 当前条件下查询的记录总数                                          |
| pageNo      | int    | 要查询的页号                                                |
| pageSize    | int    | 要返回的页长度                                               |
| currentSize | int    | 当前实际返回的页长度                                            |
| uid         | string | 用户id                                                  |
| taskId      | string | 任务id                                                  |
| isDir       | string | 是否目录刷新，取值为yes／no                                      |
| url         | string | url                                                   |
| progress    | int    | 任务进度，0-100                                            |
| state       | string | 刷新状态，取值为success／processing／failure                    |
| stateDetail | string | 刷新状态描述信息                                              |
| createAt    | string | 当前记录创建时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:05:05 |
| beginAt     | string | 当前记录开始时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:05:25 |
| endAt       | string | 当前记录结束时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:09:05 |

### 响应示例 [#响应示例-1]

**成功** (HTTP 200):

```json
{
  "code": 200,
  "error": "success",
  "total": 2,
  "pageNo": 0,
  "pageSize": 100,
  "currentSize": 2,
  "items": [
    {
      "uid": 1383263287,
      "requestId": "698e908943d723411eda9d41",
      "taskId": "698e908943d723411eda9d42",
      "isDir": "no",
      "url": "https://test.example.com/1235.jpg",
      "progress": 100,
      "state": "success",
      "stateDetail": "",
      "createAt": "2026-02-13 10:46:33",
      "beginAt": "2026-02-13 10:46:33",
      "endAt": "2026-02-13 10:46:35"
    },
    {
      "uid": 1383263287,
      "requestId": "698e908943d723411eda9d41",
      "taskId": "698e908943d723411eda9d43",
      "isDir": "yes",
      "url": "https://test.example.com/static/",
      "progress": 100,
      "state": "success",
      "stateDetail": "",
      "createAt": "2026-02-13 10:46:33",
      "beginAt": "2026-02-13 10:46:33",
      "endAt": "2026-02-13 10:47:35"
    }
  ]
}
```

> state 值: `"success"` (完成) / `"failure"` (失败) / `"processing"` (进行中)

<div id="P23" />

<span id="prefetch" />

## 2.3 资源预取 [#23-资源预取]

### 基本信息 [#基本信息-2]

* **请求方法**: POST
* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/prefetch`
* **用途**: 提前将资源从源站拉取到 CDN 节点缓存

### 请求参数 [#请求参数-2]

| 参数名  | 类型    | 必填 | 说明                                | 示例值                           |
| ---- | ----- | -- | --------------------------------- | ----------------------------- |
| urls | array | 是  | 文件 URL 列表，完整 http\:// 或 https\:// | `["http://test.com/big.mp4"]` |

> 预取仅支持文件，不支持目录。

### 请求示例 [#请求示例-2]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/prefetch' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"urls":["http://test.example.com/large-file.jpg"]}'
```

### 响应参数 [#响应参数-2]

| 参数名         | 类型                 | 说明                           |
| ----------- | ------------------ | ---------------------------- |
| code        | int                | 响应状态码                        |
| error       | string             | 响应错误码描述                      |
| requestId   | string             | 预取请求id，只有在任务被接受时才有值          |
| taskIds     | map\[string]string | URL 对应的任务 ID，map\[url]taskId |
| invalidUrls | string array       | 无效的url列表                     |
| quotaDay    | int                | 每日的预取 url 限额                 |
| surplusDay  | int                | 每日的当前剩余的预取url限额              |

### 响应示例 [#响应示例-2]

**成功** (HTTP 200):

```json
{
  "code": 200,
  "error": "success",
  "requestId": "698ee598ae4f8446dac2b967",
  "taskIds": {
    "http://test.example.com/large-file.jpg": "698ee598ae4f8446dac2b968"
  },
  "invalidUrls": null,
  "quotaDay": 100,
  "surplusDay": 93
}
```

<div id="P24" />

<span id="query-prefetch" />

## 2.4 预取任务查询 [#24-预取任务查询]

### 基本信息 [#基本信息-3]

* **请求方法**: POST
* **接口地址**: `https://fusion.qiniuapi.com/v2/tune/prefetch/list`
* **用途**: 查询预取任务执行状态 (与刷新查询独立)
* **查询时间范围**: 近 7 天

### 请求参数 [#请求参数-3]

| 参数名       | 类型     | 必填 | 说明       | 示例值                                        |
| --------- | ------ | -- | -------- | ------------------------------------------ |
| requestId | string | 否  | 请求 ID    | `"698ee3057911048e39e0ac8c"`               |
| urls      | array  | 否  | 按 URL 查询 | `["http://test.com/a.jpg"]`                |
| state     | string | 否  | 按状态筛选    | `"success"` / `"failure"` / `"processing"` |
| pageNo    | int    | 否  | 页码       | 0                                          |
| pageSize  | int    | 否  | 每页条数     | 100                                        |
| startTime | string | 否  | 开始日期     | `"2026-02-10"`                             |
| endTime   | string | 否  | 结束日期     | `"2026-02-13"`                             |

> 可选参数不能全部为空，至少传一个。时间范围最多 7 天，startTime/endTime 缺失时默认返回近 3 天。

### 请求示例 [#请求示例-3]

```bash
curl -X POST 'https://fusion.qiniuapi.com/v2/tune/prefetch/list' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"requestId":"698ee598ae4f8446dac2b967"}'
```

### 响应参数 [#响应参数-3]

| 参数名         | 类型     | 说明                                                    |
| ----------- | ------ | ----------------------------------------------------- |
| code        | int    | 响应状态码                                                 |
| error       | string | 响应错误码描述                                               |
| requestId   | string | 记录所在的预取请求id                                           |
| total       | int    | 当前条件下查询的记录总数                                          |
| pageNo      | int    | 要查询的页号                                                |
| pageSize    | int    | 要返回的页长度                                               |
| currentSize | int    | 当前实际返回的页长度                                            |
| uid         | string | 用户id                                                  |
| taskId      | string | 任务id                                                  |
| isDir       | string | 是否目录，取值为yes／no                                        |
| url         | string | url                                                   |
| progress    | int    | 任务进度，0-100                                            |
| state       | string | 预取状态，取值为success／processing／failure                    |
| stateDetail | string | 预取状态描述信息                                              |
| midState    | string | 中间状态描述                                                |
| createAt    | string | 当前记录创建时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:05:05 |
| beginAt     | string | 当前记录开始时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:05:25 |
| endAt       | string | 当前记录结束时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:09:05 |

### 响应示例 [#响应示例-3]

**成功** (HTTP 200):

```json
{
    "code": 200,
    "error": "success",
    "total": 1,
    "pageNo": 0,
    "pageSize": 100,
    "currentSize": 1,
    "items": [
        {
            "uid": 1383263287,
            "requestId": "698ee598ae4f8446dac2b967",
            "taskId": "698ee598ae4f8446dac2b968",
            "isDir": "no",
            "url": "http://test.example.com/large-file.jpg",
            "progress": 100,
            "state": "success",
            "stateDetail": "",
            "midState": "success",
            "createAt": "2026-03-18 17:42:10",
            "beginAt": "2026-03-18 17:42:10",
            "endAt": "2026-03-18 17:42:21"
        }
    ]
}
```

***

# 3. 常见问题 [#3-常见问题]

## 3.1 专属错误码 [#31-专属错误码]

| 错误码    | 描述                          | 场景                      | 解决方案            |
| ------ | --------------------------- | ----------------------- | --------------- |
| 400000 | 无效输入                        | urls/dirs 为空数组          | 至少传 1 个 URL     |
| 400031 | invalid url                 | URL 格式错误，非完整 http/https | 检查 URL 完整格式     |
| 400032 | invalid host                | 域名无效                    | 确认域名已接入 CDN     |
| 400033 | prefetch url limit error    | 预取每日配额用完                | 次日恢复，或控制台申请提升   |
| 400034 | refresh url limit error     | 文件刷新每日配额用完              | 同上              |
| 400035 | refresh dir limit error     | 目录刷新配额用完                | 同上              |
| 400036 | invalid request id          | 请求 ID 无效                | 检查 requestId 拼写 |
| 400037 | url has existed             | URL 正在刷新/预取中            | 等待完成后重试         |
| 400038 | refresh dir authority error | 未开通目录刷新                 | 控制台开通           |

## 3.2 最佳实践 [#32-最佳实践]

* **URL 格式**: 完整 http\:// 或 https\://，http/https 均可接受
* **批量提交**: 官网限制单次 20 个 URL / 5 个目录，建议分批
* **配额感知**: 响应中 `urlSurplusDay` 返回当日剩余配额，据此控制提交量
* **任务追踪**: 保存 `requestId`，刷新用 refresh/list 查询，预取用 prefetch/list 查询，二者独立
* **预取场景**: 大文件发布前预取，避免用户首次访问直接回源

> **参考**: 鉴权详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)，错误码详见 [公共错误码&通用约束](/products/cdn/2-fusion-api-error-codes)。


# 证书管理 (/products/cdn/9-fusion-api-cert-management)



最近更新时间: 2026-06-04 16:41:51

# 1. 快速查阅区 [#1-快速查阅区]

## 1.1 核心接口概览 [#11-核心接口概览]

| 接口功能                         | 请求方法   | 接口路径               | 核心参数         | 成功响应                         |
| ---------------------------- | ------ | ------------------ | ------------ | ---------------------------- |
| <a href="#P21">上传 SSL 证书</a> | POST   | `/sslcert`         | name、pri、ca  | `{"certID":"..."}`           |
| <a href="#P22">获取证书列表</a>    | GET    | `/sslcert`         | marker、limit | `{"code":200,"certs":[...]}` |
| <a href="#P23">获取证书详情</a>    | GET    | /sslcert/\<certId> | -            | `{"code":200,"cert":{...}}`  |
| <a href="#P24">删除 SSL 证书</a> | DELETE | /sslcert/\<certId> | -            | `{"code":200}`               |

> 注：`<certId>`为证书ID

## 1.2 核心约束 [#12-核心约束]

* **请求域名**: `fusion.qiniuapi.com`
* **鉴权方式**: QBox 鉴权（详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)）
* **证书格式**: PEM 格式，私钥无密码保护，ca 为完整证书链

***

# 2. 详细接口说明 [#2-详细接口说明]

<div id="P21" />

<span id="upload-cert" />

## 2.1 上传 SSL 证书 [#21-上传-ssl-证书]

### 基本信息 [#基本信息]

* **请求方法**: POST
* **接口地址**: `https://fusion.qiniuapi.com/sslcert`

### 请求参数 [#请求参数]

| 参数名  | 类型     | 必填 | 说明                      | 示例值                                  |
| ---- | ------ | -- | ----------------------- | ------------------------------------ |
| name | string | 是  | 证书名称                    | `"test.example.com-2026"`            |
| pri  | string | 是  | 私钥 (PEM 格式，无密码保护)       | `"-----BEGIN PRIVATE KEY-----\n..."` |
| ca   | string | 是  | 证书链 (PEM 格式，服务器证书+中间证书) | `"-----BEGIN CERTIFICATE-----\n..."` |

### 请求示例 [#请求示例]

```bash
curl -X POST 'https://fusion.qiniuapi.com/sslcert' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"name":"test.example.com-2026","pri":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----","ca":"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"}'
```

### 响应参数 [#响应参数]

| 参数名    | 类型     | 说明   |
| ------ | ------ | ---- |
| certID | string | 证书ID |

### 响应示例 [#响应示例]

**成功** (HTTP 200):

```json
{
    "certID": "694d196ee691b4be3e838346"
}
```

**失败**:

```json
#示例1
{
    "code": 400325,
    "error": "https证书解析失败"
}
#示例2
{
    "code": 400323,
    "error": "证书链验证失败"
}
#示例3
{
    "code": 400324,
    "error": "证书私钥不匹配"
}
```

<div id="P22" />

<span id="list-certs" />

## 2.2 获取证书列表 [#22-获取证书列表]

### 基本信息 [#基本信息-1]

* **请求方法**: GET
* **接口地址**: `https://fusion.qiniuapi.com/sslcert`

### 请求参数 (URL Query) [#请求参数-url-query]

| 参数名    | 类型     | 必填 | 说明         | 示例值  |
| ------ | ------ | -- | ---------- | ---- |
| marker | string | 否  | 分页标记，首次传空  | `""` |
| limit  | int    | 否  | 每页数量，默认 10 | `20` |

### 请求示例 [#请求示例-1]

```bash
curl -X GET 'https://fusion.qiniuapi.com/sslcert?marker=&limit=20' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Authorization: QBox <AK>:<Sign>'
```

### 响应参数 [#响应参数-1]

| 参数名          | 类型        | 说明                 |
| ------------ | --------- | ------------------ |
| marker       | string    | 标示下一次从哪个位置开始获取证书列表 |
| certid       | string    | 证书 ID              |
| name         | string    | 证书名称               |
| common\_name | string    | 通用名称               |
| dnsnames     | \[]string | DNS 域名             |
| not\_before  | int       | 生效时间 (Unix 时间戳)    |
| not\_after   | int       | 过期时间 (Unix 时间戳)    |
| create\_time | int       | 创建时间 (Unix 时间戳)    |

### 响应示例 [#响应示例-1]

**成功** (HTTP 200):

```json
{
  "code": 200,
  "error": "",
  "certs": [
    {
      "certid": "694d196ee691b4be3e838346",
      "name": "私有证书",
      "common_name": "test.example.com",
      "dnsnames": ["test.example.com", "test2.example.com"],
      "not_before": 1766620800,
      "not_after": 1774396799,
      "create_time": 1766660462
    }
  ],
  "marker": "2"
}
```

<div id="P23" />

<span id="get-cert" />

## 2.3 获取证书详情 [#23-获取证书详情]

### 基本信息 [#基本信息-2]

* **请求方法**: GET
* **接口地址**: `https://fusion.qiniuapi.com/sslcert/<certId>`

### 请求参数 [#请求参数-1]

| 参数名    | 类型     | 说明   |
| ------ | ------ | ---- |
| certId | string | 证书ID |

### 请求示例 [#请求示例-2]

```bash
curl -X GET 'https://fusion.qiniuapi.com/sslcert/694d196ee691b4be3e838346' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Authorization: QBox <AK>:<Sign>'
```

### 响应参数 [#响应参数-2]

| 参数名          | 类型        | 说明              |
| ------------ | --------- | --------------- |
| name         | string    | 证书名称            |
| common\_name | string    | 通用名称            |
| dnsnames     | \[]string | DNS 域名          |
| not\_before  | int       | 生效时间 (Unix 时间戳) |
| not\_after   | int       | 过期时间 (Unix 时间戳) |
| create\_time | int       | 创建时间 (Unix 时间戳) |
| pri          | string    | 证书私钥 (PEM 格式)   |
| ca           | string    | 证书内容 (PEM 格式)   |

### 响应示例 [#响应示例-2]

**成功** (HTTP 200):

```json
{
  "code": 200,
  "error": "",
  "cert": {
    "certid": "694d196ee691b4be3e838346",
    "name": "私有证书",
    "common_name": "test.example.com",
    "dnsnames": ["xxx.example.com"],
    "not_before": 1766620800,
    "not_after": 1774396799,
    "pri": "-----BEGIN PRIVATE KEY-----\n...(完整私钥)...",
    "ca": "-----BEGIN CERTIFICATE-----\n...(完整证书链)..."
  }
}
```

<div id="P24" />

<span id="delete-cert" />

## 2.4 删除 SSL 证书 [#24-删除-ssl-证书]

### 基本信息 [#基本信息-3]

* **请求方法**: DELETE
* **接口地址**: `https://fusion.qiniuapi.com/sslcert/<certId>`
* **前置条件**: 证书未绑定任何域名

### 请求参数 [#请求参数-2]

| 参数名    | 类型     | 说明   |
| ------ | ------ | ---- |
| certId | string | 证书ID |

### 请求示例 [#请求示例-3]

```bash
curl -X DELETE 'https://fusion.qiniuapi.com/sslcert/694d196ee691b4be3e838346' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Authorization: QBox <AK>:<Sign>'
```

### 响应示例 [#响应示例-3]

**成功** (HTTP 200):

```json
{
    "code": 200
}
```

**失败**:

```json
#示例1
{
    "code": 400401,
    "error": "无此证书"
}
#示例2
{
    "code": 400326,
    "error": "证书已被使用"
}
#示例3
{
    "code": 400611,
    "error": "证书已绑定域名"
}
#示例4
{
    "code": 404908,
    "error": "无权操作该证书"
}
#示例5
{
    "code": 400911,
    "error": "证书已绑定存储域名"
}
```

***

# 3. 常见问题 [#3-常见问题]

## 3.1 专属错误码 [#31-专属错误码]

| 错误码    | 描述            | 场景           | 解决方案          |
| ------ | ------------- | ------------ | ------------- |
| 400322 | https 证书有效期太短 | 上传时证书有效期不足   | 更换较长有效期证书     |
| 400323 | 证书链验证失败       | 上传时证书链不完整    | 拼接 服务器+中间证书   |
| 400324 | 证书私钥不匹配       | pri 与 ca 不对应 | 检查私钥和证书配对     |
| 400325 | 证书解析失败        | PEM 格式错误/已过期 | 检查格式和有效期      |
| 400326 | 证书已被使用        | 删除时有域名绑定     | 先解绑再删除        |
| 400329 | https 证书过期    | 上传时证书已过期     | 更换有效证书        |
| 400401 | 无此证书          | certId 不存在   | 检查 certId     |
| 400500 | 超过用户绑定证书最大额度  | 证书数量超限       | 删除旧证书         |
| 400611 | 证书已绑定 CDN 域名  | 删除时证书已绑定 CDN | 先解绑 CDN 域名再删除 |
| 400911 | 证书已绑定存储域名     | 删除时证书已绑定存储   | 先解绑存储域名再删除    |
| 404906 | https 证书解码失败  | PEM 编码错误     | 检查证书编码格式      |
| 404908 | 无权操作该证书       | 证书不属于当前账号    | 确认证书归属        |

## 3.2 最佳实践 [#32-最佳实践]

* **证书上传**: PEM 格式，pri 无密码，ca 包含完整链 (服务器+中间证书)
* **证书更新**: 先上传新证书获取 certID，再用[域名配置](/products/cdn/5-fusion-api-domain-config#upgrade-https)的 httpsconf/sslize 接口更换
* **泛域名证书**: `*.example.com` 可绑定多个同前缀域名，无需重复上传
* **过期管理**: 定期查列表检查 not\_after，提前更新

> **参考**: 鉴权详见 [鉴权指南](/products/cdn/1-fusion-api-auth-guide)，错误码详见 [公共错误码&通用约束](/products/cdn/2-fusion-api-error-codes)。


# 服务保障协议(SLA) (/products/cdn/0-fusion-cdn-sla)



最近更新时间: 2026-07-17 15:34:49

# 1. 服务内容 [#1-服务内容]

七牛云 CDN（内容分发网络 Content Delivery Network）服务将源站内容分发至全国所有的节点，将用户网页 / 图片等资源自动分发到用户购买了七牛云服务的 CDN 节点中，从而缩短用户查看对象的延迟，提高用户访问网站的响应速度与网站的可用性，解决网络带宽小、用户访问量大、网点分布不均等问题。

# 2. 定义 [#2-定义]

* 服务：指七牛云 CDN 根据本协议向开发者提供的付费服务（未付费情况，不适用本协议）。
* 网页/图片等小文件：指用户使用七牛云 CDN 服务的域名下所有后缀为.html 、.css、.png、.jpg 、.gif 等静态文件。
* 下载内容：指用户使用七牛云 CDN 服务的域名下所有供用户下载的文件。
* 点播流媒体内容：指用户使用七牛云 CDN 服务的域名下所有互联网常用的流媒体格式文件。
* 动态内容：指用户使用七牛云 CDN 服务的域名下所有文件后缀为.asp、.jsp、.php、.cgi 、.perl 、API 接口等动态文件。
* 服务周期：以一个自然月做为一个服务周期，如果不满一个月则按一个月计算。
* 服务区域：中国大陆地区。
* 服务周期总分钟数：按照每月每周 7（七）天每天 24（二十四）小时计算。
* 失败请求：因 CDN 系统原因导致的域名返回的 5XX 请求和因为 CDN 服务故障导致用户正常请求未能到达 CDN 服务器端的请求视为失败请求。因 CDN 服务故障导致的用户正常请求未能到达 CDN 服务器端的失败请求，将通过故障前 7 天内用户域名的平均请求数计算。
* 有效请求：客户在七牛云服务账号下所有 CDN 的域名加速服务，在 CDN 服务器收到的请求视为有效请求。
* 每 5 分钟错误率：每 5 分钟错误率=（每 5 分钟失败请求数/每 5 分钟有效请求总数）\* 100 %
* 不可用时间：CDN 在连续的 10 分钟或更长时间出现每 5 分钟错误率大于 0.05 % 的情况，方计为不可用时间。
* 月度服务费用：客户在一个自然月中在七牛云账号下 CDN 产品服务费用总额。

# 3. 指标项 [#3-指标项]

## 3.1 服务可用性 [#31-服务可用性]

* 七牛云 CDN 保证用户购买的服务的“服务可用性”达到 99.9 %，即每月服务不可用时间累计小于 44 分钟。
  服务可用性=（1 - 服务不可用时间/服务周期总时间）× 100%
* 服务可用性按服务周期统计，一个服务周期为一个自然月，如不满一个月不计算为一个服务周期。
* 统计对象为某一七牛云账户下的所有开启 CDN 服务的域名（月请求量小于 100 万的域名除外）。
* 七牛云 CDN 服务的不可用时间不包括日常系统维护时间、由用户原因、第三方原因或不可抗力导致的不可用时间。

## 3.2 持久性 [#32-持久性]

七牛云 CDN 提供的是缓存服务，节点上保存的数据，按访问热度自动淘汰, 不会永久保存。

## 3.3 私密性 [#33-私密性]

用户在七牛云 CDN 服务创建的加速域名等资源，在未经用户合法授权的情况下，其他用户无法对其配置进行更改。七牛云为用户分配最多 2 对 Access Key ID/Secret Access Key 密钥对，从七牛云服务访问接口上进行权限控制和隔离，保障用户数据的私密性。

## 3.4可审查性 [#34可审查性]

依据现行法律法规或根据政府监管部门监管、安全合规、审计或取证调查等原因的需要，在符合流程和手续完备的情况下，七牛云可以提供用户所使用的服务的相关信息。

## 3.5 服务资源调配能力 [#35-服务资源调配能力]

七牛云 CDN 为用户提供内容分发与加速服务，并支持安全防护能力，保障用户源站安全。七牛云 CDN 服务采用弹性扩容机制，可根据业务访问情况自动扩展带宽及存储资源，一般情况下无需用户进行容量配置。为保障资源准备及服务稳定性，如客户预计业务流量将出现大规模增长（预计峰值带宽较上月计费带宽增长超过30%，或预计新增带宽超过50Gbps，两者满足任一条件），应至少提前3个工作日通知七牛云服务团队；国家法定节假日、大型促销活动、重大赛事等重大业务场景（包括但不限于春晚、国庆、双十一、世界杯等），应至少提前1个月通知。

如客户未按上述要求提前通知，七牛云将在现有资源条件下提供服务，并可支持不超过上月计费带宽30%（含）的临时增长。对于超过该增长范围的业务流量，七牛云不保证能够及时完成资源扩容，因此产生的服务能力下降或可用性影响，不属于本 SLA 承担范围。

## 3.6 故障恢复能力及客服保证 [#36-故障恢复能力及客服保证]

七牛云 CDN 为用户提供全天候的运行维护，并以在线自助工单系统、客服电话报障等方式提供技术支持。七牛云具备完善的故障监控、自动告警、快速定位、快速恢复等一系列故障应急响应机制。

客服咨询电话：400-101-8589；服务时间：7\*24 小时。

## 3.7 网络接入性能 [#37-网络接入性能]

七牛云 CDN 对用户不限制公网出口带宽，七牛云在全国部署数百个缓存节点，保障用户的网络接入质量。

## 3.8 服务计量准确性 [#38-服务计量准确性]

七牛云 CDN 服务具备准确、透明的计量计费系统。七牛云 CDN 根据用户的实际使用量据实结算，价格及计费模式见七牛云官网。

# 4. 服务赔偿条款 [#4-服务赔偿条款]

## 4.1 赔偿范围 [#41-赔偿范围]

因七牛云设备故障、设计缺陷或操作不当导致用户所购买的 CDN 服务无法正常使用，七牛云将对不可用时间进行赔偿，但不包括以下原因所导致的服务不可用时间：

* 七牛云预先通知用户后进行系统维护所引起的，包括割接、维修、升级和模拟故障演练；
* 任何七牛云所属设备以外的网络、设备故障或配置调整引起的；
* 用户的应用程序或数据信息受到黑客攻击而引起的；
* 用户维护不当或保密不当致使数据、口令、密码等丢失或泄漏所引起的；
* 用户自行升级操作系统所引起的；
* 用户的应用程序或安装活动所引起的；
* 用户的疏忽或由用户授权的操作所引起的；
* 不可抗力以及意外事件引起的；
* 其他非七牛云原因所造成的不可用。

## 4.2 赔偿方案 [#42-赔偿方案]

七牛云对用户存在故障的每个域名按不可用时间进行 10 倍赔偿，赔付金额 = 发生故障的域名故障前 24 小时平均每分钟费用 × 故障不可用时间 × 10 倍。

* 赔偿只针对使用 CDN 服务已产生费用的用户，以代金券的形式赔偿，不折算现金返还。
* 故障不可用时间 = 故障解决时间 - 故障开始时间，不可用时间按分钟计算。
* 如果用户没有使用到 24 小时，按实际使用时长计算平均每分钟费用。
* 赔付金额不超过客户对该故障域名所消费的费用平均值（故障当月前12个月费用折算平均值）或故障当月客户消费的月度服务费用的25%（服务不满12个月，不包含本月）。

## 4.3 赔偿申请时限 [#43-赔偿申请时限]

客户可在每月第五个工作日之后对上个自然月没有达到可用性的情况提出赔偿申请。赔偿申请必须限于在CDN服务没有达到可用性的相关月份结束后两个月内提出；超出申请时限的赔偿申请将不被受理。

# 5. 免责声明 [#5-免责声明]

详见[《七牛云服务用户协议》](https://www.qiniu.com/user-agreement)中的"免责声明"相关条款内容。

# 6. 其他 [#6-其他]

* 本协议一经公布立即生效，七牛云有权随时对协议内容进行修改。如用户不同意七牛云对本协议相关内容所做的修改，用户有权停止使用七牛云 CDN 服务。若用户继续使用七牛云 CDN 服务，则视为用户接受七牛云对本协议相关内容所做的修改。
* 本协议项下七牛云 CDN 服务对于用户所有的通知均可通过网页公告、站内信、电子邮件、手机短信或其他形式等方式进行；该通知于发送之日视为已送达收件人。
* 本协议的订立、执行和解释及争议的解决均应适用中国法律并受中国法院管辖。如双方就本协议内容或其执行发生任何争议，双方应尽量友好协商解决；协商不成时，任何一方均可向上海市浦东新区人民法院提起诉讼。
* 本协议构成双方对本协议之约定事项及其他有关事宜的完整协议，除本协议规定的之外，未赋予本协议各方其他权利。
* 如本协议中的任何协议无论因何种原因完全或部分无效或不具有执行力，本协议的其余协议仍应有效并且有约束力。


# 什么是内容审核 (/products/censor/0-censor-introduction)



最近更新时间: 2026-05-08 16:04:25

# 背景 [#背景]

随着互联网的不断发展和智能设备的大规模普及，网络上的应用功能越来越多，受众群体也越来越广，在互联网文化内容极大丰富的同时，也产生了各种各样的难以控制的危险因素，具体包括色情、涉政、暴恐等各类违反社会稳定和谐、甚至危害国家安全的内容。随着政府对于不良信息监管日渐严格，每个网站和平台都在严肃对待和处理这些危险因素，而传统人力审核的方式处理网络上每天新产生的图片和视频变成了一个不可能完成的任务。

# 产品定位 [#产品定位]

七牛云利用多年积累的深度学习技术，加上在存储和多媒体处理上的经验，对图片、视频等提供鉴黄、鉴暴恐、政治敏感人物识别等内容审核服务，无论是内容审核的准确性、识别率、响应速度都在行业树立了标杆。
内容审核产品支持两种使用方式：

1. 针对七牛云存储的文件，提供portal界面一键开启审核设置的功能，并让用户直观地看到审核结果和进行相应操作，保护您的产品运营安全；
2. 对于文件不存储在七牛云上的客户，同时提供内容审核 API 的方式进行调用；

七牛云存储内容审核

针对七牛云存储用户，提供一键式的图片、视频内容审核服务。您可以将保存在七牛云存储中的图片、视频进行鉴黄、鉴暴恐、政治敏感人物识别等内容审核服务，对增量违规数据提供自动封禁功能。提供审核结果的自助复核功能，用户可以对图片、视频进行删除、封禁和通过等操作。详情请参考 [内容审核操作指南](/products/censor/0-incremental-review)。

内容审核API

内容审核API主要提供图片、视频文件的鉴黄、鉴暴恐和政治敏感人物识别，用户的资源无须存储在七牛云存储中，只要是公网可访问的文件都可以调用内容审核API。详情请参考 API 接口文档： [图片内容审核 API](/products/censor/image-censor)、[视频内容审核 API](/products/censor/video-censor)

# 应用场景 [#应用场景]

无论您的应用是APP还是网站，都可以使用内容安全审核服务，达到保障内容安全，降低业务运营风险的目的。具体的应用场景包括社交平台、媒体平台、电商网站、社区论坛等。


# 产品核心功能、优势及服务 (/products/censor/1-core-function)



最近更新时间: 2026-05-08 11:12:53

# 产品核心功能 [#产品核心功能]

## 鉴黄 [#鉴黄]

七牛云图像鉴黄利用超大规模数据所提供的知识来对深度神经网络进行引导，训练出多个极具泛化能力的网络模型，同时基于蒸馏学习的思想对模型复杂度和参数规模进行了大幅压缩，快速准确的识别出色情、低俗的图片和视频，解决直播、电商、社交等领域的违规内容问题。

## 鉴暴恐 [#鉴暴恐]

七牛云鉴暴恐通过海量暴恐图片和视频数据源，依托分布式深度学习平台，能准确地对图片视频进行暴恐分类，具体支持血腥类，爆炸类，恐怖主义，战争军队，枪支刀具，各种旗帜等不同类型。

## 政治人物识别 [#政治人物识别]

七牛云政治人物识别基于海量人脸库和专业审核人员的审核标准，利用分布式深度学习平台，识别正常、漫画、负面涉政人物的违规信息，降低违规风险，覆盖涉政人物1700余个，具体包括国内外元首，副国级以上领导人，落马官员，反华势力和劣迹艺人等。

# 产品优势 [#产品优势]

\*\* 性价比高：\*\* 智能机器审核在节省97%以上的人力成本的同时，达到99%以上的准确率，支持秒级返回结果。同时，七牛云内容审核产品依托于 AVA 深度学习平台不断快速迭代，优化算法。

\*\* 使用便捷：\*\* 一次接入即可提供图片、视频等形式内容审核，覆盖鉴黄、鉴暴恐、涉政等风险防范。更支持其他公有云资源的API调用接入。

\*\* 对风险理解更专业：\*\* 与多地的监管部门合作，并成立联合实验室，能让七牛云的内容审核更加贴近真实使用场景，从而提供更加专业的算法和产品。

# 产品服务 [#产品服务]

七牛云内容审核服务提供标准审核流程，无论客户的资源在何处，都可以提供内容安全保障。如果客户资源在七牛云，更能形成审核业务闭环，减少处理流程和操作步骤。
![](/docs-assets/products/censor/%280-product-introduction%29/1-core-function/FiAtqybUvd5e2G_5HhxlzWyKfErT-df28caf3b55b.webp)


# 内容审核操作 (/products/censor/0-incremental-review)



最近更新时间: 2026-08-18 11:57:42

对象存储 Kodo 支持针对存储用户，提供一键式的图片、音频、视频内容审核服务。

您可以将保存在七牛云存储中的存量、增量数据进行鉴黄、鉴暴恐、政治敏感人物识别等内容审核服务，对违规数据提供自动封禁功能。提供审核结果的自助复核功能，用户可以对图片、视频进行删除、封禁和通过等操作。

<br />

# **说明** [#说明]

* 更多空间内容审核概念介绍，请参考[什么是内容审核](/products/censor/0-censor-introduction)。
* 内容审核可能导致的相关费用，请参考[内容审核产品价格](/products/censor/pricing/0-censor-price)。

<br />

# **操作步骤** [#操作步骤]

1.登录 Kodo 控制台进入[空间管理](https://portal.qiniu.com/kodo/bucket)界面
2\. 单击存储安全栏下的**内容审核**进入内容审核界面，如图1。您可点击**增量审核**或**存量审核**，切换查询的任务类型。
图1：
![image.png](/docs-assets/products/censor/%282-quick-start%29/0-incremental-review/FrjW3YdmxiEgUGPkr003ziIb9X3o-dd70469c4622.webp)
3\. 如您在增量审核页面，您可在列表中查看到当前所有已设置的空间增量审核任务及其状态。如图2，将鼠标移动至目标任务栏的**查看**时，将展示该任务详情。
图2:
![image.png](/docs-assets/products/censor/%282-quick-start%29/0-incremental-review/FtGPmi4v5mYL_kUEIXlmFqii6wB0-9174b937f845.webp)
4\. 在图1中，在目标任务栏单击**管理**，将跳转至内容审核-增量审核界面，如图3。您可在此页面进一步管理该任务。
图3:
![image.png](/docs-assets/products/censor/%282-quick-start%29/0-incremental-review/FoGMus0CAo0hdVst82HUsZtusLtg-b2fd0014625a.webp)
5\. 在图1中，单击**新建任务**，将快捷跳转至新建增量任务界面，如图4。请参考 [存量审核](/products/censor/2-censor-portal-batch) 完成新建存量审核任务。
图4:
![image.png](/docs-assets/products/censor/%282-quick-start%29/0-incremental-review/Fgct8GUbHcB7kFUPABUPva_VPdqn-85ef250428de.webp)
6\. 如您切换至存量审核页面，相关操作也可参考上述步骤2-4。


# 使用限制 (/products/censor/0-products-limited)



最近更新时间: 2026-05-08 11:18:21

# 产品服务区域 [#产品服务区域]

目前，内容审核服务对于七牛云存储的区域有一些限制。

| 存储区域 | 存量图片 | 存量视频 | 存量音频 | 增量图片 | 增量视频 | 增量音频 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| 华东   | 支持   | 支持   | 支持   | 支持   | 支持   | 支持   |
| 华北   | 支持   | 支持   | 支持   | 支持   | 支持   | 支持   |
| 华南   | 支持   | 支持   | 支持   | 支持   | 支持   | 支持   |
| 东南亚  | 不支持  | 不支持  | 不支持  | 不支持  | 不支持  | 不支持  |
| 北美   | 不支持  | 不支持  | 不支持  | 不支持  | 不支持  | 不支持  |

# 审核文件适用规格 [#审核文件适用规格]

可处理的图片文件：

* 图片大小不超过10M
* 图片尺寸不小于32x32，不超过4999x4999
* RGB通道数为3和3以内的图片，不能包含alpha通道
* 图片格式支持 png、jpg、jpeg、bmp、webp、tiff 和 gif

可处理的视频文件：

* 视频大小不超过1G。
* 视频格式支持 mp4、flv、mov、avi、wmv、ts和mpg。
* 支持用户设定截帧频率，但单个视频最大截帧数为3000帧。如根据截帧频率计算出来的截帧数大于3000帧，则会按最大3000帧对整个视频进行均匀截帧。


# 增量审核 (/products/censor/1-censor-portal-stream)



最近更新时间: 2026-05-08 15:18:49

增量审核适用于 对上传到对象存储的资源进行实时审核 的场景。开启增量审核后，能帮助用户您在秒级时间内审核新增的资源，并支持及时地对违规资源进行自动封禁，保障业务安全。

# 适用需求场景 [#适用需求场景]

* 用户有新资源上传到七牛对象存储
* 用户需要在资源上传后实时进行内容审核
* 用户需要做审核的资源，无前缀要求、属于指定的前缀下或者过滤排除指定的前缀
* 用户需要对违规资源做自动封禁 或者 有人力在机器审核完成后进行人工审核

# 使用限制须知 [#使用限制须知]

* 目前增量审核支持华东、华南、华北三个区域，不支持东南亚、北美等海外区域
* 视频增量审核截帧保存只支持华东存储空间，不支持其他区域的空间
* 支持只对指定前缀下的特定文件类型的文件进行增量审核，不支持指定文件后缀或类型
* 支持前缀过滤，被过滤的前缀下的文件将`不会`触发增量审核
* 关于审核文件限制，请参考：[审核文件适用规格](/products/censor/0-products-limited#2)
* 支持的审核能力如下表：

| 文件类型 | 支持审核类型                                                                                     |
| ---- | ------------------------------------------------------------------------------------------ |
| 图片   | 涉黄、暴恐、敏感人物、广告、不良场景、[异常检测](/products/dora/image-processing-api/13-abnormal-image-detection) |
| 视频   | 涉黄、暴恐、敏感人物、广告                                                                              |
| 音频   | 反垃圾                                                                                        |

# 开启增量审核 [#开启增量审核]

打开并登陆内容审核控制台 [https://portal.qiniu.com/censor](https://portal.qiniu.com/censor)，点击侧边栏的 存储空间审核 -> 增量审核，点击 新建任务 按钮

![create-1.png](/docs-assets/products/censor/%283-development-guidelines%29/1-censor-portal-stream/FvDkgaPPHe_IJJyalk5ttBN63GUP-68babed1ba2b.webp)

填写增量审核配置

![create-2.png](/docs-assets/products/censor/%283-development-guidelines%29/1-censor-portal-stream/FmC-iG4AkGSzxrPZ3Q7Ifo7DYjC-97f827b1bde0.webp)

各个配置项说明如下：

| 配置项    | 必输                    | 默认        | 说明                                                                                                                                   |
| ------ | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 存储空间   | 存储空间必输，前缀可选           |           | 需要开启增量审核的存储空间。开通后，新上传的资源，若符合审核条件，则会触发内容审核。可填写前缀，只对指定前缀下的资源进行审核。比如填写 2019/，则只会审核前缀 2019/ 下的资源。若需要审核该空间的所有资源，不填前缀即可。`保存后将无法修改，请仔细检查确认` |
| 前缀过滤   | 可选                    |           | 需要过滤掉特定前缀的资源，该前缀下的资源将`不会`触发增量审核                                                                                                      |
| 文件类型   | 必选                    |           | 图片/视频/音频。关于具体支持格式请参考：[审核文件适用规格](/products/censor/0-products-limited#2)。`保存后将无法修改，请仔细检查确认`                                            |
| 审核范围   | 必选                    | 增量审核，不可修改 |                                                                                                                                      |
| 审核类型   | 必选，至少开启一项             |           | 涉黄/暴恐/敏感人物/广告/反垃圾                                                                                                                    |
| 自动禁用   | 可选，但自动禁用与回调地址必须至少填选一项 |           | 开启自动禁用，后违规文件将会被自动禁用，无法公开访问。如需访问禁用资源请参考：[文档私有资源下载](/products/kodo/development-guidelines/download-process/1-download-private)         |
| 视频截帧   | 必输                    | 1 秒/帧     | 当文件类型为视频时，需要设置视频截帧频率，默认1 秒/帧。若视频长度为60秒，截帧频率为1 秒/帧，则会截成60张图片进行图片审核。截帧数字越小，审核准确率越高                                                     |
| 截帧存放地址 | 存储空间必选，前缀可选           |           | 文件类型为视频时，需要设置视频截帧保存的空间和前缀，只支持保存到华东区域的空间。建议设置为非业务空间，与业务空间隔离。设置前缀可将视频截帧保存到特定的前缀下，比如 2019/，则截帧图片会保存到前缀 2019/ 下                          |
| 回调地址   | 可选，但自动禁用与回调地址必须至少填选一项 |           | 完成增量审核后，会将结果发送到该地址。进行复核操作时会将复核结果发送到该地址。详情请参考：[增量审核回调](/products/censor/scenarios/1-incremental-audit-callback)                       |
| 私有队列   | 必选                    |           | 多媒体队列。若无队列，可点击右侧「添加队列」创建。参考：[关于七牛的流媒体队列](/faq/dora/av-processing/2500-streaming-media-queue-about-seven-cows)                        |

核对任务配置，确认无误后，点击保存开启增量审核任务

`如需开通华东区域以外的视频增量审核，请参照填写以上信息，提交工单/联系技术支持申请开通`

# 查看配置 [#查看配置]

在增量任务列表，点击任务卡片上的 更多 -> 查看任务 来查看任务的详细配置

![view-1.png](/docs-assets/products/censor/%283-development-guidelines%29/1-censor-portal-stream/FrKE_nNQR3cyHBq7E765hT9kjSpb-c99ac2d9bf9a.webp)

![view-2.png](/docs-assets/products/censor/%283-development-guidelines%29/1-censor-portal-stream/Fo0fONNvOMn-hvI37LlaoM0Tuioy-c38ecf728861.webp)

# 修改配置 [#修改配置]

在增量任务列表，点击任务卡片上的 更多 -> 修改任务 来修改任务的配置，配置内容同 开启增量审核

![edit-1.png](/docs-assets/products/censor/%283-development-guidelines%29/1-censor-portal-stream/FrBvoNLAuosfuYAkFoSZfRWjPA-d-fb7bcc64380e.webp)

可在任务卡片上的 更多 -> 历史记录 中查看修改的记录

![history-1.png](/docs-assets/products/censor/%283-development-guidelines%29/1-censor-portal-stream/Ftin1V1BhIq2F2Em11afy8cZH1DY-4897f1850376.webp)

![history-2.png](/docs-assets/products/censor/%283-development-guidelines%29/1-censor-portal-stream/FrZAbgXR2K09YR-wf-x0757448wY-6d41b7bab250.webp)

# 关闭任务 [#关闭任务]

`关闭审核任务会导致资源漏检，增加运营风险，请谨慎操作`

在增量任务列表，点击任务卡片上的 更多 -> 关闭任务，确认后将关闭增量审核任务

![close-1.png](/docs-assets/products/censor/%283-development-guidelines%29/1-censor-portal-stream/Frcdr-HCrfZKEgUJ80Qdel3VSZ_K-3dd4169d9261.webp)

# 结果复核 [#结果复核]

点击 结果复核 进入结果复核界面。请参考：[审核结果复核](/products/censor/6-censor-portal-review)

![review-1.png](/docs-assets/products/censor/%283-development-guidelines%29/1-censor-portal-stream/FpK6QviL4bcZbykXNCITYKPaCHUR-68f525dde98f.webp)

`将复核结果设为违规将自动封禁存储空间中的资源，设为正常则将自动解封资源。`

对于增量任务，在进行复核操作时会触发对应的回调。回调地址使用设置审核任务时填写的回调地址；如果审核任务没有设置回调地址，则没有回调。回调的数据格式为：

```json
{
	"type":"KODO",
	"set_id":"xxxxxxxx",
	"bucket":"用户bucket",
	"uri_get":"qiniu:///bucket/key",
	"from":"BLOCK",
	"to":"PASS"
}
```

# 数据统计 [#数据统计]

点击 数据统计 进入数据统计界面，查看审核结果分布的情况。请参考：[审核结果数据统计](/products/censor/4-censor-portal-stats)

![stats-1.png](/docs-assets/products/censor/%283-development-guidelines%29/1-censor-portal-stream/FsQ_lAHKcntkEUsYRDco_ipCxuhT-b4579580ab84.webp)

# 计费说明 [#计费说明]

计费方式：

| 文件类型 | 说明                                                               |
| ---- | ---------------------------------------------------------------- |
| 图片   | 按审核的图片数和审核类型数计费，如：同时开启审核类型 涉黄 和 敏感人物，则费用为 图片数 \* （涉黄单价 + 敏感人物单价） |
| 视频   | 按审核的视频截帧数和审核类型数计费                                                |
| 音频   | 按音频时长和审核类型数计费                                                    |

价格：[机器智能审核阶梯计费方式](/products/censor/pricing/0-censor-price)、[机器智能审核资源包](/products/censor/pricing/1-censor-plus-manual)


# 存量审核 (/products/censor/2-censor-portal-batch)



最近更新时间: 2026-05-08 15:19:04

存量审核适用于 对已保存在对象存储中的资源进行内容审核 的场景。开启存量审核后，能帮助用户扫描空间中已存在的资源文件，并提供一份详细的审核结果，同时支持审核结果复核，以保障业务安全。

# 适用需求场景 [#适用需求场景]

* 用户的资源已保存在对象存储中
* 用户需要对已存在的资源进行内容审核，扫描资源是否违规
* 用户需要做审核的资源，无前缀要求、属于指定的前缀下或者过滤排除指定的前缀
* 用户有人力在机器审核完成后进行人工审核

# 使用限制须知 [#使用限制须知]

* 存量审核开通后，不支持后续修改配置，请在开通时仔细检查确认信息
* 存量审核开通后，不支持用户直接操作停止关闭，请在开通时仔细检查确认信息。如需操作，请提工单/联系技术支持
* 目前存量审核支持华东、华南、华北三个区域，不支持东南亚、北美等海外区域
* 审核结果文件和视频截帧保存只支持华东的存储空间，不支持保存到其他区域
* 支持只对指定前缀下的特定文件类型的文件进行内容审核，不支持指定文件后缀或类型
* 支持前缀过滤，被过滤的前缀下的文件将`不会`触发存量审核
* 关于审核文件限制，请参考：[审核文件适用规格](/products/censor/0-products-limited#2)
* 支持的审核能力如下表：

| 文件类型 | 支持审核类型                                                                                     |
| ---- | ------------------------------------------------------------------------------------------ |
| 图片   | 涉黄、暴恐、敏感人物、广告、不良场景、[异常检测](/products/dora/image-processing-api/13-abnormal-image-detection) |
| 视频   | 涉黄、暴恐、敏感人物、广告                                                                              |
| 音频   | 反垃圾                                                                                        |

# 开启存量审核 [#开启存量审核]

打开并登陆内容审核控制台 [https://portal.qiniu.com/censor](https://portal.qiniu.com/censor)，点击侧边栏的 存储空间审核 -> 存量审核，点击 新建任务 按钮

![create-1.png](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/FqJzvee5a6H6eAZwV1qkipqGcktY-b1e0ceab5291.webp)

填写存量审核配置

`存量审核开启后，不支持用户自行操作停止和后续修改配置，请在开启时仔细确认检查信息。如需操作请提工单/联系技术支持`

![create-2.png](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/FlLnYwIc9n0hlLXFfSgr6rZNS2-c01f9c532d35.webp)

各个配置项说明如下：

| 配置项    | 必输          | 默认        | 说明                                                                                                                           |
| ------ | ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 存储空间   | 存储空间必输，前缀可选 |           | 需要开启存量审核的存储空间。开启后将扫描该存储空间，对符合审核条件的资源进行内容审核。可填写前缀，只对指定前缀下的资源进行审核。比如填写 2019/，则只会审核前缀 2019/ 下的资源。若需要审核该空间的所有资源，不填前缀即可           |
| 前缀过滤   | 可选          |           | 需要过滤掉特定前缀的资源，该前缀下的资源将`不会`触发存量审核                                                                                              |
| 文件类型   | 必选          |           | 图片/视频/音频。关于具体支持格式，参考：[审核文件适用规格](/products/censor/0-products-limited#2)                                                       |
| 审核范围   | 必选          | 存量审核，不可修改 |                                                                                                                              |
| 审核类型   | 必选，至少开启一项   |           | 涉黄/暴恐/敏感人物/广告                                                                                                                |
| 视频截帧   | 必输          | 1 秒/帧     | 当文件类型为视频时，需要设置视频截帧频率，默认1 秒/帧。若视频长度为60秒，截帧频率为1 秒/帧，则会截成60张图片进行图片审核。截帧数字越小，审核准确率越高                                             |
| 截帧存放地址 | 存储空间必选，前缀可选 |           | 文件类型为视频时，需要设置视频截帧保存的空间和前缀，只支持保存到华东区域的空间。建议设置为非业务空间，与业务空间隔离。设置前缀可将视频截帧保存到特定的前缀下，比如 2019/，则截帧图片会保存到前缀 2019/ 下                  |
| 结果存放地址 | 存储空间必选，前缀可选 |           | 设置存量审核结果保存的空间和前缀，存量审核的结果将会以文本文件的格式存放在该存储空间下，只支持保存到华东区域的空间。建议设置为非业务空间，与业务空间隔离。设置前缀可将结果文件保存到特定前缀下，比如 2019/，则结果文件会保存到前缀 2019/ 下 |

核对任务配置，确认无误后，点击保存开启存量审核任务。

`如需开通华东区域以外的视频存量审核，请参照填写以上信息，提交工单/联系技术支持申请开通`

# 查看进度 [#查看进度]

可以直接在存量任务列表上看到存量任务执行的进度

![存量进度](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/FmoSq7JGiJzI5HuTg1WmgwME_l4l-7f5e487e5324.webp)

# 查看配置 [#查看配置]

点击 更多 -> 查看任务 查看任务配置

![view-1.png](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/FlgpbpaUQz2_GRFIypT9QwTpvq3T-e17c43226912.webp)

![view-2.png](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/Fo9o9HOcmG4oqHB1YjBBMj90ce4K-f09c30c7b1ff.webp)

# 处理存量结果 [#处理存量结果]

如果需要对存量的结果进行处理，可以点击 更多 -> 存量结果 进行操作。目前支持封禁、 删除、导出 三种操作。

![存量结果](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/FulPWntbkWP9sHmRsWeEQV4RLoRC-ecc7b59dcc54.webp)

## 结果预览 [#结果预览]

`操作前请先通过 结果复核 确认审核结果是否正确，符合预期，避免误封/误删资源。`

在 结果预览 子菜单下能预览过滤条件筛选后的存量结果记录。结果以原始记录的格式给出，见 `存量结果格式`。

然后勾选下方的 选择所有过滤结果，然后进行批量操作。目前支持封禁、 删除、导出 三种操作。

![结果预览界面](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/Fm97D_9CQuhPLTuXsWIzHO9JrYmS-a83a73b73204.webp)

各个操作说明如下：

| 操作 | 说明                                                                        |
| -- | ------------------------------------------------------------------------- |
| 封禁 | 将过滤后的结果对应的文件进行封禁，封禁后的文件不可直接访问，但仍保存在存储空间中。                                 |
| 删除 | 将过滤后的结果对应的文件直接从存储空间中删除，`不可恢复，谨慎操作`。                                       |
| 导出 | 当结果数量不多时，直接下载过滤后的结果保存到本地，进行后续操作；当有大量结果时，需要将过滤后的结果保存到存储空间，然后从存储空间下载进行后续操作。 |

如：如需封禁所有审核结果为 违规 的文件，则可以在 审核结果 中选择 违规，然后勾选 选择所有过滤结果，最后点击 封禁 按钮

![封禁违规资源](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/Fq7qAwxF95KJHLH4a8bUg8TZTq-E-7b52e6243d8e.webp)

## 操作记录 [#操作记录]

用户对存量结果进行的操作会保存到操作记录中。

用户可以查看操作执行的进度，完成后可以下载结果/日志。

`操作记录仅保存近7天数据，请及时查看。`

![操作记录](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/FqyaEBBkZ9INKLAnsByZN78MFAWU-5e809c97bbbe.webp)

## 结果文件 [#结果文件]

直接下载存量的原始结果，原始结果格式见 `存量结果格式`。

![result-1.png](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/FpmE27LG0-q8zx_EPBz2qv8BHr7E-25c1bacae716.webp)

点击每行后方的 **下载** 可以下载单个结果文件；也可勾选，然后点击表格上方的 **下载** 进行批量下载

![下载存量结果](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/FippHq70ER7Wd2VVtgCRbssEAMa2-b6f227178c56.webp)

当结果文件较多时，`推荐`使用命令行工具 [qshell](/products/kodo/0-qshell) 的 [qdownload](https://github.com/qiniu/qshell/blob/master/docs/qdownload.md) 命令批量下载，具体方法见页面窗口

![qshell 下载](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/Fg-i7PreoPm4fHgS6vh9k_XvvVI5-176bd2e22039.webp)

下载文件后，用户可以通过读取结果文件进行批量操作，如：通过对象存储 API 进行清除或封禁资源等。请参考：

* [资源删除接口](/products/kodo/rs/3-delete)
* [资源封禁接口](/products/kodo/rs/11-modify-the-file-status)

## 存量结果格式 [#存量结果格式]

下载的存量结果文件格式是 .gz 的压缩文件，需要用户解压缩后才能查看内容。解压后的文件是文本文件，可用一般的文本编辑器查看

样例：

```
qiniu://uid@zone/bucket/key1	{"code":200,"mimetype":"image","result":{"code":200,"message":"OK","suggestion":"pass","scenes":{"pulp":{"suggestion":"pass","result":{"label":"normal","score":0.98726}}}}}
qiniu://uid@zone/bucket/key2	{"code":200,"mimetype":"image","result":{"code":200,"message":"OK","suggestion":"pass","scenes":{"pulp":{"suggestion":"pass","result":{"label":"normal","score":0.91785}}}}}
qiniu://uid@zone/bucket/key3	{"code":200,"mimetype":"image","result":{"code":200,"message":"OK","suggestion":"pass","scenes":{"pulp":{"suggestion":"pass","result":{"label":"normal","score":0.96497}}}}}
qiniu://uid@zone/bucket/key4	{"code":200,"mimetype":"image","result":{"code":200,"message":"OK","suggestion":"pass","scenes":{"pulp":{"suggestion":"pass","result":{"label":"normal","score":0.95022}}}}}
qiniu://uid@zone/bucket/key5	{"code":200,"mimetype":"image","result":{"code":200,"message":"OK","suggestion":"pass","scenes":{"pulp":{"suggestion":"pass","result":{"label":"normal","score":0.9697}}}}}
qiniu://uid@zone/bucket/key6	{"code":200,"mimetype":"image","result":{"code":200,"message":"OK","suggestion":"pass","scenes":{"pulp":{"suggestion":"pass","result":{"label":"normal","score":0.94184}}}}}
```

每一行为一个文件的结果，包含 文件名 和 审核结果，以 `tab` 分隔

字段说明如下：

| 字段   | 说明                                                        |
| ---- | --------------------------------------------------------- |
| 文件名  | 七牛协议的文件名，格式为 qiniu://`{用户id}`@`{存储空间区域}`/`{存储空间}`/`{文件名}` |
| 审核结果 | json 格式，字段说明见下表                                           |

审核结果字段如下：

| 字段                                   | 值                                             | 说明                              |
| ------------------------------------ | --------------------------------------------- | ------------------------------- |
| code                                 |                                               | http code                       |
| mimetype                             | image 图片 / video 视频 / audio 音频                | 文件类型                            |
| result                               |                                               | 审核结果                            |
| result.code                          |                                               | http code                       |
| result.message                       |                                               | 错误信息                            |
| result.suggestion                    | pass 正常 / block 违规 / review 疑似                | 最终的审核结果                         |
| result.scenes                        |                                               | 包含各审核类型的结果，包含的 key 为存量任务开启的审核类型 |
| result.scenes.`{scene}`.suggestion   | pass 正常 / block 违规 / review 疑似                | 审核类型 `${scene}` 的结果             |
| result.scenes.`{scene}`.result       |                                               | 审核类型 `${scene}` 的结果详情           |
| result.scenes.`{scene}`.result.label | 参考 [审核标签说明](/products/censor/3-censor-params) | 审核类型 `${scene}` 的结果标签           |
| result.scenes.`{scene}`.result.score |                                               | 审核类型 `${scene}` 的结果分数           |

# 结果复核 [#结果复核]

点击 结果复核 进入结果复核界面。请参考：[审核结果复核](/products/censor/6-censor-portal-review)

![review-1.png](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/FpK6QviL4bcZbykXNCITYKPaCHUR-68f525dde98f.webp)

`将复核结果设为违规将自动封禁存储空间中的资源，设为正常则将自动解封资源。`

# 数据统计 [#数据统计]

点击 数据统计 进入数据统计界面，查看审核结果分布的情况。请参考：[审核结果数据统计](/products/censor/4-censor-portal-stats)

![stats-1.png](/docs-assets/products/censor/%283-development-guidelines%29/2-censor-portal-batch/FsQ_lAHKcntkEUsYRDco_ipCxuhT-b4579580ab84.webp)

# 计费说明 [#计费说明]

计费方式：

| 文件类型 | 说明                                                               |
| ---- | ---------------------------------------------------------------- |
| 图片   | 按审核的图片数和审核类型数计费，如：同时开启审核类型 涉黄 和 敏感人物，则费用为 图片数 \* （涉黄单价 + 敏感人物单价） |
| 视频   | 按审核的视频截帧数和审核类型数计费                                                |
| 音频   | 按音频时长和审核类型数计费                                                    |

价格：[机器智能审核阶梯计费方式](/products/censor/pricing/0-censor-price)、[机器智能审核资源包](/products/censor/pricing/1-censor-plus-manual)


# 概览页面 (/products/censor/3-censor-portal-overview)



最近更新时间: 2026-05-08 15:38:43

用户可以在内容审核的概览页面查看内容审核服务的基本使用情况，包括：

* 存储空间统计，增量/存量审核开启的空间数和任务数
* API 统计，各文件类型的 API 调用情况和各个结果的数量
* 用量统计，会根据用量产生对应的费用和账单

![overview.png](/docs-assets/products/censor/%283-development-guidelines%29/3-censor-portal-overview/FqDTV22hHTFUDkzxIOVL9hFMNxY6-816f12f37712.webp)


# 数据统计 (/products/censor/4-censor-portal-stats)



最近更新时间: 2026-05-08 15:38:28

在数据统计页面，用户可以查看最多 30 天的统计数据，可以查看一个文件类型或者是其细分场景下的审核结果分布情况。

![stats-1.png](/docs-assets/products/censor/%283-development-guidelines%29/4-censor-portal-stats/FsQ_lAHKcntkEUsYRDco_ipCxuhT-b4579580ab84.webp)

![stats-2.png](/docs-assets/products/censor/%283-development-guidelines%29/4-censor-portal-stats/FuRAuh_JXIv32LfF7J3qsamFeZIS-a1793606a431.webp)


# 直播云审核 (/products/censor/5-censor-portal-pili)



最近更新时间: 2026-05-08 15:19:18

直播云审核适用于 已经使用七牛直播云服务并且需要对直播流进行内容审核 的场景。开启审核任务后，能自动检测发现直播空间中的直播流并进行内容审核。

直播云审核相比直播鉴黄能支持更多的审核类型，能力更加全面、更加灵活。`若同时开启，则会同时产生费用。`

# 适用需求场景 [#适用需求场景]

* 用户已经使用七牛直播云服务
* 用户需要对直播空间中的直播流实时进行内容审核，检查直播流是否违规
* 用户需要自行制定策略和标准，根据内容审核返回的结果决定是否中断视频直播流
* 用户有人力在机器审核完成后进行人工审核

# 使用限制须知 [#使用限制须知]

* 直播云审核和直播鉴黄是独立的服务，`若同时开启，则会同时产生费用`
* 直播云审核只能针对整个直播空间开启，会自动检测发现空间中的所有流，不支持过滤
* 审核产生的视频截帧和音频片段只支持保存到华东的存储空间，不支持保存到其他区域
* 支持的审核能力如下表：

| 文件类型   | 支持审核类型        |
| ------ | ------------- |
| 图片（截帧） | 涉黄、暴恐、敏感人物、广告 |
| 音频     | 反垃圾           |

# 开启直播云审核 [#开启直播云审核]

打开并登陆内容审核控制台 [https://portal.qiniu.com/censor](https://portal.qiniu.com/censor)，点击侧边栏的 直播云审核 -> 直播空间审核，点击 新建任务 按钮

![create-1.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/FhGw9zCPCQ7P4QS4C0KHv5sU7hxR-a2896eedfeb8.webp)

填写直播空间审核配置

![Screenshot at May 28 14-10-51.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/Fr2NaOhTRZ0yWAdNV6QxzKYgZ3eL-fa4bda1d0851.webp)

各个配置项说明如下：

| 配置项    | 必输                         | 默认    | 说明                                                                                                |
| ------ | -------------------------- | ----- | ------------------------------------------------------------------------------------------------- |
| 直播空间   | 必选                         |       | 需要开启内容审核的直播空间。开启后能自动检测发现直播空间中的直播流并进行内容审核                                                          |
| 截帧审核类型 | 可选，但截帧审核类型和音频审核类型当中至少要勾选一项 |       | 涉黄/暴恐/敏感人物/广告                                                                                     |
| 截帧间隔   | 必输                         | 1 秒/帧 | 当勾选了截帧审核类型后需要设置截帧间隔，默认1 秒/帧。若截帧间隔为1 秒/帧，将每隔1秒从直播流中截帧进行审核。数字越小，从视频流中截帧的频率越高，审核准确率越高                |
| 截帧存放地址 | 存储空间必选，前缀可选                |       | 当勾选了截帧审核类型后需要设置视频截帧保存的空间和前缀，只支持保存到华东区域的空间。建议设置为非业务空间，与业务空间隔离。设置前缀可将截帧保存到特定的前缀下                    |
| 截帧回调规则 | 必选                         | 仅违规疑似 | 默认只会将截帧审核为违规或疑似的结果回调给用户；如需包含正常的结果，可选择全部结果                                                         |
| 音频审核类型 | 可选，但截帧审核类型和音频审核类型当中至少要勾选一项 |       | 反垃圾                                                                                               |
| 音频存放地址 | 存储空间必选，前缀可选                |       | 当勾选了音频审核类型后需要设置音频片段保存的空间和前缀，只支持保存到华东区域的空间，建议设置为非业务空间，与业务空间隔离。设置前缀可将音频保存到特定的前缀下                    |
| 音频回调规则 | 必选                         | 仅违规疑似 | 默认只会将音频审核为违规或疑似的结果回调给用户；如需包含正常的结果，可选择全部结果                                                         |
| 回调地址   | 可选                         |       | 填写后会将审核结果实时发送到该地址，用户可以根据审核结果决定进一步操作，如：中断直播流。回调格式参考：[直播审核回调](/products/censor/1-api-live-censor#4) |

核对任务配置，确认无误后，点击保存开启直播空间审核任务。

# 查看详情 [#查看详情]

可在任务列表上，点击 查看详情 查看对应的任务配置

![view-1.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/FhWH4lA1iIuIdiIjzWK095w8GZO0-e5063835b7af.webp)

![view-2.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/Fht-BFDVtetVWVeuvPl76LOW4J6G-c18c441026f9.webp)

# 关闭任务 [#关闭任务]

`关闭审核任务会导致资源漏检，增加运营风险，请谨慎操作`

可在任务列表上，点击 关闭任务 来停止直播空间审核。

![close.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/Fu17nzNEZZIKt_n7AO8rGCRy-Yws-cbe92006cedd.webp)

# 修改任务配置 [#修改任务配置]

目前控制台上不支持直接修改任务的操作。用户可以先关闭任务，然后用新的配置对同一直播空间重新开启任务。

# 直播空间结果复核 [#直播空间结果复核]

在内容审核控制台上可以查看、复核直播空间中所有视频直播流的审核结果。在直播空间任务上点击 结果复核 查看所有直播流的审核结果。可以通过左上角的 切换按钮 分别查看截帧和音频的结果。请参考：[审核结果复合](/products/censor/6-censor-portal-review)

![1.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/FtDusorVwNl5CO91GVmAZz_SslVY-f4dbe1dccbac.webp)

![review-3.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/Fg-pcFKZ6DSCUCIFgoQwoJwTtjsP-1f26fefc108c.webp)

在复核详情中会显示该 截帧/音频 所属的直播空间和直播流，点击 直播空间 可跳转到直播空间的结果复核，点击 直播流 可以跳转到单个直播流的结果复核

![2.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/FuPVKXa81fePav-qSWFcJcjcPouK-0f208615e9c4.webp)

# 直播流结果复核 [#直播流结果复核]

在内容审核控制台上可以查看、复核直播空间中的每个视频直播流的审核结果。在直播空间任务上点击 直播空间名字 进入直播流任务列表，点击 结果复核 查看审核结果。可以通过左上角的 切换按钮 分别查看截帧和音频的结果。请参考：[审核结果复合](/products/censor/6-censor-portal-review)

![review-1.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/FuhOMgIozWWtcBYK9gOim9rPlVel-91d061afafe3.webp)

![review-2.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/FstKT3I1GsSOdxLpWZu67jE2oL7b-2607d4c1528c.webp)

![review-3.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/Fg-pcFKZ6DSCUCIFgoQwoJwTtjsP-1f26fefc108c.webp)

在复核详情中会显示该 截帧/音频 所属的直播空间和直播流，点击 直播空间 可跳转到直播空间的结果复核，点击 直播流 可以跳转到单个直播流的结果复核

![2.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/FuPVKXa81fePav-qSWFcJcjcPouK-0f208615e9c4.webp)

# 直播空间数据统计 [#直播空间数据统计]

在内容审核控制台上可以查看直播空间中的所有视频直播流的结果分布情况。在直播空间任务上点击 数据统计 查看审核结果分布的情况。请参考：[审核结果数据统计](/products/censor/4-censor-portal-stats)

![pili-stats.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/Fh1HW-8_FbEVOIFiu_T16KM6N7CX-2b9005fe74e3.webp)

![stats-2.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/FvpvHxaBIwPnMToT9THu1lAQlsfY-6cd4f3fb1c50.webp)

# 直播流数据统计 [#直播流数据统计]

在内容审核控制台上可以查看直播空间中的每个视频直播流的结果分布情况。在直播空间任务上点击 直播空间名字 进入直播流任务列表，点击 数据统计 查看审核结果分布的情况。请参考：[审核结果数据统计](/products/censor/4-censor-portal-stats)

![stats-1.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/FhlsLGnYEU21TeMaQ50q_d7yEyh4-dddad77f8c3d.webp)

![stats-2.png](/docs-assets/products/censor/%283-development-guidelines%29/5-censor-portal-pili/FvpvHxaBIwPnMToT9THu1lAQlsfY-6cd4f3fb1c50.webp)

# 计费说明 [#计费说明]

计费方式：

| 文件类型   | 说明                                                                         |
| ------ | -------------------------------------------------------------------------- |
| 图片（截帧） | 若开启了截帧审核，则按审核的截帧数和审核类型数计费，如：同时开启审核类型 涉黄 和 敏感人物，则费用为 截帧数 \* （涉黄单价 + 敏感人物单价） |
| 音频     | 若开启了音频审核，则按审核的音频时长和审核类型数计费                                                 |

价格：[机器智能审核阶梯计费方式](/products/censor/pricing/0-censor-price)、[机器智能审核资源包](/products/censor/pricing/1-censor-plus-manual)


# 结果复核 (/products/censor/6-censor-portal-review)



最近更新时间: 2026-05-08 15:21:37

内容审核平台提供可视化的界面展示审核结果，用户可以查看审核结果，并根据审核结果进行复核操作。

`我们不承诺永久保存数据，目前只保留近七天数据，请及时复核。`

# 审核结果复核 [#审核结果复核]

打开并登陆内容审核控制台 [https://portal.qiniu.com/censor](https://portal.qiniu.com/censor)

对调用内容审核 API 的资源进行复核，可直接通过侧边栏 API 审核 -> 对应的审核 API 直接进入。直播审核需要选择对应的直播任务进行复核。关于调用内容审核 API，请参考：[内容审核 API 文档](/products/censor/image-censor)

![复核](/docs-assets/products/censor/%283-development-guidelines%29/6-censor-portal-review/FiyTW0ZKImoc4K_AcqmZ68655-2d-b8994cbdf7cb.webp)

![直播复核](/docs-assets/products/censor/%283-development-guidelines%29/6-censor-portal-review/FrFRwK-MZb5E2sQGZOrDmjV9TnCH-2f165598b4f2.webp)

对增量/存量任务审核的资源进行复核，请查看 [增量审核](/products/censor/1-censor-portal-stream)/[存量审核](/products/censor/2-censor-portal-batch) 的操作指南。

对直播云审核的资源进行复核，请查看 [直播云审核](/products/censor/5-censor-portal-pili) 的操作指南。

对多媒体工作流的资源进行复核，请查看 [多媒体工作流审核](/products/censor/6-censor-portal-review) 的操作指南。

我们通过不同的颜色来标识审核结果：

* `红色` 代表 `违规`
* `黄色` 代表 `疑似`
* `绿色` 代表 `正常`

在列表界面时我们将不显示审核结果为正常的审核类型，但可以在详情中查看所有审核类型的结果。

根据相关部门的标准，七牛云在审核结果中对每个文件给出了管控建议：

* 违规，指审核结果为违规的文件，等待客户进行处理，一般建议是在复核时将复核结果设为违规
* 疑似，指审核结果为疑似的文件，需要客户根据自身业务类型确认，确认后进行合适的处理。如果确定是违规则将复核结果设为违规，如果确定不是违规，则可以忽略或将复核结果设为正常
* 正常，指审核结果为正常的文件，一般不需要用户做任何操作

# 设置筛选条件 [#设置筛选条件]

复核界面支持设置以下筛选条件，可以通过按钮展开/收起筛选条件

![筛选条件](/docs-assets/products/censor/%283-development-guidelines%29/6-censor-portal-review/FkxYf27rcscMMeclNzPHz1fhUqqO-3f8b50191b2a.webp)

| 条件        | 说明                                                                                  |
| --------- | ----------------------------------------------------------------------------------- |
| 审核结果      | 内容审核的审核结果                                                                           |
| 审核类型      | 当只选择了审核类型时，会筛选出使用了该审核类型的结果 <br /> 当选择了审核类型 + 审核结果过时，会筛选出审核类型的结果为审核结果的结果             |
| 时间        | 审核结果的创建时间                                                                           |
| 复核结果      | 如果进行了人工复核，则可以通过复核结果筛选结果                                                             |
| entry\_id | 可以通过返回中的 entry\_id 进行精确筛选，不支持与其他条件组合使用；参考 [内容审核返回](/products/censor/image-censor#4) |
| 资源        | 可以通过审核资源的 url 链接进行筛选，为精确匹配，不支持与其他条件组合使用                                             |

# 选择条目 [#选择条目]

在结果复核页面上，当需要批量操作时，用户可以通过以下几种方式选择条目：

1. 单选框勾选，适合条目数较少且比较分散时使用；
2. 拖拽选择，适合条目数较多且分布连续时使用；
3. 全选，选择当前页面上所有`未复核`的资源（`已复核的资源不会被再次选中`）。可以与以上两种方式结合使用，例如：当存在少量违规资源时，用户可以先通过以上两种方式对违规资源进行复核操作，再通过全选将其余资源的复核结果设为正常。

![选择](/docs-assets/products/censor/%283-development-guidelines%29/6-censor-portal-review/FiBVMaGByx6BekyOtnk-yD0WULxa-1c743f03e625.webp)

页面上会显示已选择的条目数量，方便用户核对、确认。

![选择条目数](/docs-assets/products/censor/%283-development-guidelines%29/6-censor-portal-review/FonQBE06riiaH9B3tc82s5ZjPnqz-ce468e1c0c4e.webp)

# 查看详情 [#查看详情]

对于图片、视频文件，点击缩略图卡片则可显示复核详情。

![查看详情](/docs-assets/products/censor/%283-development-guidelines%29/6-censor-portal-review/Fku8INbbYRdU_wnx3imdWK4ciY5U-310538345d5c.webp)

对于音频、文本文件，点击表格行后方的详情按钮可显示复核详情。

![查看详情](/docs-assets/products/censor/%283-development-guidelines%29/6-censor-portal-review/FkHeWOsHeGdBPBmQHg4Gs2danQFq-80bd5501b164.webp)

# 复核操作 [#复核操作]

可以通过对 卡片/表格行 进行勾选 或 勾选全选 来选中多个结果，然后点击 正常 或 封禁 按钮来进行批量操作。

![复核](/docs-assets/products/censor/%283-development-guidelines%29/6-censor-portal-review/Fm4TtDK04T-ch2GS9PBXLUPkQlC-2da9d5bed0f3.webp)

也可以在 结果详情 中，仔细确认结果后，点击弹出框下方的 正常 或 封禁 按钮对单个审核结果进行复核。

![复核](/docs-assets/products/censor/%283-development-guidelines%29/6-censor-portal-review/FhlqjrWJ4k2mR0v9D0PreRfNyPvo-52314baf0c4a.webp)

# 封禁/删除文件 [#封禁删除文件]

对于**增量/存量**结果的复核，在将复核结果设为违规时能同时选择将对应的文件 封禁/删除（`不可恢复，谨慎操作`）；删除后会显示 **文件已删除**，`无法在复核界面直接预览该文件内容`。

![封禁/删除文件](/docs-assets/products/censor/%283-development-guidelines%29/6-censor-portal-review/Fg27NAQP_vTiJ7Ckp4wt2uj51Mbg-0e2d3ca76cbe.webp)

![显示文件已删除](/docs-assets/products/censor/%283-development-guidelines%29/6-censor-portal-review/FomdEoxUOdi_ObeMn2e1eAmtSyx9-773c4a4860bc.webp)

# 导出文件列表 [#导出文件列表]

![导出](/docs-assets/products/censor/%283-development-guidelines%29/6-censor-portal-review/Fq6VHYINM3DGh2O5eSyF39bBMScL-03f48e2dd762.webp)

用户可以在页面上导出文件列表，然后进行批量操作，如：通过对象存储 API 进行清除或封禁资源等。请参考：

* [资源删除接口](/products/kodo/rs/3-delete)
* [资源封禁接口](/products/kodo/rs/11-modify-the-file-status)


# 策略配置 (/products/censor/7-censor-settings)



最近更新时间: 2026-05-08 15:39:00

`如需对审核策略进行自定义配置，请联系技术支持开通本功能`

![审核策略配置](/docs-assets/products/censor/%283-development-guidelines%29/7-censor-settings/FliKHhh7v6IYa1zX0l2Ux9wd8i8V-d8292b069da3.webp)

目前内容审核可以开启/关闭以下审核类型的审核策略：

# 涉黄 [#涉黄]

| 标签 | 说明                 |
| -- | ------------------ |
| 色情 | 明显色情行为、露点、全裸等内容    |
| 性感 | 女性露沟背腰腹、男性裸露上半身等内容 |

# 暴恐 [#暴恐]

| 标签   | 说明               |
| ---- | ---------------- |
| 违规标识 | 非法组织旗帜、标志等       |
| 国家标识 | 国旗国徽、党旗党徽等政治象征标识 |
| 暴恐场景 | 血腥、焚烧、恐怖等不适场景    |
| 管控器械 | 枪支弹药、管控刀具等管控器械   |

# 敏感人物 [#敏感人物]

| 标签   | 说明      |
| ---- | ------- |
| 政要   | 国内外政要领导 |
| 英烈   | 革命英烈    |
| 劣迹艺人 | 劣迹艺人    |
| 非法分子 | 非法分子    |

# 广告 [#广告]

| 标签   | 说明                       |
| ---- | ------------------------ |
| 图文违规 | 图中文本包含涉政、涉黄、辱骂、违禁品、暴恐等内容 |
| 广告   | 图中文本内容包含网址、联系方式等内容       |
| 二维码  | 二维码                      |


# 自助审核 (/products/censor/8-human-review)



最近更新时间: 2026-05-08 15:17:12

自助审核适用于对机审结果有人工复核需求的客户。
使用自助审核，用户能灵活配置人工复核流程和进审数据，并且与 iam 子账号深度集成，支持多轮审核，支持多人同时审核，灵活的回调以及扩展关联资源配置。

# 基本概念 [#基本概念]

审核任务：自助审核中的基础单位，可以进行关联审核数据、分配人员等操作。

任务通道：对应审核任务中不同步骤的数据集合，人员分配的具体单位。

# 审核任务 [#审核任务]

![自助审核任务](/docs-assets/products/censor/%283-development-guidelines%29/8-human-review/Fl15jUWOE-cI8vplFqd8Hs3ZNrFz-1ba39c4c8069.webp)

审核任务是自助审核中的基础单位，新建任务后，可以进行关联资源和人员分配等操作。

## 新建任务 [#新建任务]

新建任务需要完成以下步骤

### 基本设置 [#基本设置]

![基本设置](/docs-assets/products/censor/%283-development-guidelines%29/8-human-review/FppirDybHElKw2gFPGmKlMZy74-W-37c89759af7a.webp)

审核任务的基本信息

| 字段   | 选项          | 说明                                   |
| ---- | ----------- | ------------------------------------ |
| 文件类型 | 图片/视频/文本/音频 | 审核任务所支持的文件类型，不同文件类型会有不同的复核操作，创建后不可修改 |
| 任务名称 |             | 任务名称，有意义的命名将有助于后续的运营管理               |

### 模式设置 [#模式设置]

![模式设置](/docs-assets/products/censor/%283-development-guidelines%29/8-human-review/FqY8DDTWnjCN7D4iYC-j2trQSquW-2a27e3bdb914.webp)

选择自助审核的模式，目前支持以下模式：

#### 快速审核模式 [#快速审核模式]

简单的流程配置，通过一轮人工复查，快速确认及修正机审结果。

支持根据机审结果过滤进审数据。

并且根据进审数据的设置，该模式包含以下任务通道：

* 高危审核
* 低危审核
* 正常审核

复核后，流程结束，复核结果作为自助审核的最终结果。

#### 严格审核模式 [#严格审核模式]

通过三轮人工审核，最大限度保证审核的准确性。

支持根据机审结果过滤进审数据。

并且根据进审数据的设置，该模式包含以下任务通道：

* 高危/低危/正常一审
* 高危/低危/正常二审
* 专家终审

当一审和二审复核结果一致时，则流程结束，二审结果作为自助审核的最终结果；

当一审和二审复核结果不一致时，则需要进行专家终审；

专家终审后，流程结束，专家终审作的结果为自助审核的最终结果。

#### 自定义审核模式 [#自定义审核模式]

请联系技术支持人员，定制适合业务场景的审核模式。

| 字段     | 选项                   | 说明                                             |
| ------ | -------------------- | ---------------------------------------------- |
| 审核模式   | 快速审核模式/严格审核模式/自定义模式  | 参考上述                                           |
| 进审数据设置 | 机审结果违规/机审结果疑似/机审结果正常 | 选择审核模式后，可以根据机审结果过滤进审数据，可多选，默认为 机审结果违规 和 机审结果疑似 |
| 回调地址   |                      | 填写回调地址后，自助审核的最终结果将通过改地址回调给用户                   |

### 其他设置 [#其他设置]

![其他设置](/docs-assets/products/censor/%283-development-guidelines%29/8-human-review/FiWMryjCxxmmZFFRB2tS8oUPZTkV-7ec2028690e5.webp)

#### 对象存储 [#对象存储]

当进审的数据来源为对象存储时，可以设置根据审核的最终结果 解封/封禁/删除 资源。

| 字段   | 选项          | 说明                                                                                                 |
| ---- | ----------- | -------------------------------------------------------------------------------------------------- |
| 启用设置 |             | 开启审核任务的对象存储设置                                                                                      |
| 结果正常 | 无/解封文件      | 无：不进行任何操作 <br /> 解封文件：当审核的最终结果为正常时，解封已经封禁的文件                                                       |
| 结果违规 | 无/解封文件/删除文件 | 无：不进行任何操作 <br /> 解封文件：当审核的最终结果为违规时，封禁文件，封禁后的文件不可直接访问 <br /> 删除文件：当审核的最终结果为违规时，删除文件，`删除后不可恢复，请谨慎操作` |

## 关闭任务 [#关闭任务]

`关闭审核任务会导致资源漏检，增加运营风险，请谨慎操作。`

可以关闭确定不再使用的审核任务。关闭后，将不会有新的数据进入。

## 开启任务 [#开启任务]

已关闭的任务在确认配置后，可以直接保存重新开启。

# 关联资源 [#关联资源]

![关联资源](/docs-assets/products/censor/%283-development-guidelines%29/8-human-review/FhWWqn6VX8HUEFRp8lMtgQKWJkh6-56e59d1fa2f6.webp)

新建任务后，需要关联资源后数据才能进入审核任务，进行复核。

目前支持与以下资源关联：

* [内容审核 API](/products/censor/image-censor)
* [存储空间审核/增量任务](/products/censor/1-censor-portal-stream)

关联关系为一对一多，即一个审核任务可与多个资源关联，但每个资源只能与一个任务关联。当选择了已与其他任务关联的资源时，保存时会提示确认重新关联资源，确认后即可取消原有的关联，并与当前任务关联。

# 人员分配 [#人员分配]

![人员分配](/docs-assets/products/censor/%283-development-guidelines%29/8-human-review/FlM1706pVAu_1H2h5-opw7RHisTB-988f804d2796.webp)

自助审核与 iam 子账号系统深度集成。已开通 iam 子账号的用户，可以对任务进行人员分配，将任务的各个通道分配给 iam 子账号，支持同一通道多人同时复核。

子账号权限设置见 [内容审核 iam](/products/censor/0-censor-iam)

# 复核 [#复核]

![复核](/docs-assets/products/censor/%283-development-guidelines%29/8-human-review/FhJHGYTYoJpKLIuWv5P9uDHFjz5G-8eec652859af.webp)

用户可以从图片复核、视频复核、文本复核和音频复核分别进入不同文件类型的复核界面。

如果用户被分配了多个任务通道，则首先需要选择复核的任务通道。红点表示当前该任务/通道有待复核的数据。

用户可以通过 正常 和 违规 按钮设置当前数据的复核结果。

可以通过开关设置点击复核按钮后是否需要二次确认，关闭二次确认能减少点击次数提高复核效率，但无法防止误操作。

同时用户也可以通过快捷键复核。`快捷键无需二次确认`。具体快捷键可以点击快捷键按钮查看。

完成复核后会自动获取下一条待复核数据。若当前无数据，则会提示无更多数据，此时用户还可以通过点击下一条尝试刷新获取更多数据。

右下方会提示当前剩余待复核的数据数量。

## 视频复核 [#视频复核]

![视频复核](/docs-assets/products/censor/%283-development-guidelines%29/8-human-review/FhAfvwdTveLwCPz77GAMMRrDFsgi-678bc8a9ac73.webp)

视频复核左侧为视频机审的截帧，用户可以通过机审结果过滤筛选截帧，更快速有效地判定结果。点击截帧的时间戳可以跳转到视频对应的位置。

## 音频复核 [#音频复核]

![视频复核](/docs-assets/products/censor/%283-development-guidelines%29/8-human-review/Fnex0PQ8dtfqBv5rgRNIt70DfYUp-67518bbd5980.webp)

音频复核左侧为音频对应的文本，通过颜色标识高亮违规内容。


# 接入准备 (/products/censor/0-censor-preparation)



最近更新时间: 2026-05-08 17:09:42

您在使用内容审核API之前，需要做三个准备工作：

1.注册七牛云账号。如果您已有七牛云账号，请跳过此步骤。
2.获取需要进行内容审核的文件外链url。
3.生成七牛鉴权。如果您对七牛云 bucket 中的文件，采用`<fop>`的方式调用，请跳过此步骤。

# 1. 注册七牛云账号 [#1-注册七牛云账号]

请用户打开[七牛云官网](https://www.qiniu.com/)，点击注册，个人账号或企业账号均可。我们会在一个工作日内完成实名认证。注册成功后，登录[七牛云开发者平台](https://portal.qiniu.com/signin)。

# 2. 获取文件url [#2-获取文件url]

对于非七牛云 bucket的文件，请用户准备好文件的url。对于存储在七牛云 bucket 中的文件，请参考如下操作获取文件的外链url:

1.如果用户未将图片上传到七牛云 bucket，请根据[对象存储快速入门](/products/kodo/0-console-quickstart)建立 bucket 并将图片上传。

2.获取单个文件 url：

点击“复制外链”获取选定图片 url

![image.png](/docs-assets/products/censor/%284-api-docs%29/0-censor-preparation/FkoKBTStnuJ2f0yb_buhIJZvDrfC-1307191a31d5.webp)

3.批量获取文件 url 可通过[命令行工具](/products/kodo/0-qshell#9)来完成。

# 3. 生成七牛鉴权 [#3-生成七牛鉴权]

内容审核API支持如下方式调用：

* 基于API URL发起HTTP/HTTPS POST请求。采用该方式时，您首先需要获取七牛接口鉴权签名，根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证，方法详见[接口鉴权](/products/kodo/development-guidelines/security/access-token)。


# API调用直播审核 (/products/censor/1-api-live-censor)



最近更新时间: 2026-08-18 11:58:55

本文介绍了 API 调用直播内容审核和回调使用须知，帮助您正确使用此 API 进行直播内容审核，支持基于 API URL 发起 HTTP/HTTPS POST 请求的方式调用。

**注意**

* 直播流格式支持`rtmp`、`hls`、`flv`等主流协议
* 支持用户设定图片截帧频率

# 功能描述 [#功能描述]

直播内容审核 API 主要用于检测或识别直播中的不良信息，并给出审核结果管控建议。支持的审核类型包括：直播鉴黄、直播鉴暴恐、直播敏感人物识别、直播语音违规内容识别。

## 使用步骤 [#使用步骤]

* 创建任务
* 审核结果回调
* 查询审核结果
* 查询任务
* 列取任务
* 关闭任务

# 公共参数 [#公共参数]

请求地址：[http://ai.qiniuapi.com/v3/live/censor](http://ai.qiniuapi.com/v3/live/censor)

**请求 Header**

| 字段            | 取值                                                                                                                                                                         |
| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | application/json                                                                                                                                                           |
| Authorization | Qiniu \< AccessKey> :\< Sign> <br />注意: 用户请根据 AccessKey 和 SecretKey 后生成鉴权，以便进行身份验证， `&lt;Sign&gt;` 的取值请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken)。 |

# 创建任务 [#创建任务]

请求方式：POST

请求 url：[http://ai.qiniuapi.com/v3/live/censor](http://ai.qiniuapi.com/v3/live/censor)

**请求参数**

| 字段                           | 类型       | 必选 | 说明                                                                                                                         |
| :--------------------------- | :------- | :- | :------------------------------------------------------------------------------------------------------------------------- |
| data.id                      | string   | N  | 直播流标示, , 可以包含小写字母、数字、短划线、中划线, 不超过 128 字符                                                                                   |
| data.uri                     | string   | Y  | 直播流地址，目前支持`rtmp`、`hls`、`flv`等。                                                                                             |
| data.info                    | json 结构体 | N  | 直播流附加信息，通过回调透传给客户                                                                                                          |
| params.hook\_url             | string   | N  | 回调地址，七牛将会向你设置的 URL 发起 `Content-Type: application/json` 的 `POST` 请求。                                                        |
| params.hook\_auth            | boolean  | N  | true/false，默认为 false，设置回调请求中加入请求头 authorization，用于回调服务器鉴权。                                                                 |
| params.image.is\_on          | boolean  | N  | true/false，默认为 false。图片审核和音频审核必须开启一个。                                                                                      |
| params.image.scenes          | array    | N  | 图片审核类型，如果图片审核开启，则为必填字段，没有默认值，可选项：`pulp` `terror` `politician` `ads`。                                                       |
| params.image.interval\_msecs | int      | N  | 截帧频率，如果图片审核开启，则为必填字段，单位：毫秒，取值范围为 1000 ～ 60000（即 1s\~60s）。                                                                  |
| params.image.saver.bucket    | string   | N  | 如果开启图片审核，则为必填字段，直播图片截帧文件存入的 bucket，目前只支持存入七牛云华东的 bucket。如何创建七牛云 bucket，请参见[文档](/products/kodo/0-console-quickstart#step1)。 |
| params.image.saver.prefix    | string   | N  | 保存的图片截帧文件的前缀。                                                                                                              |
| params.image.hook\_rule      | int      | N  | 图片审核结果回调规则，0/1。默认为 0，返回判定结果违规的审核结果；设为 1 时，返回所有审核结果。                                                                        |
| params.audio.is\_on          | boolean  | N  | true/false，默认为 false。图片审核和音频审核必须开启一个。                                                                                      |
| params.audio.scenes          | array    | N  | 音频审核类型，如果音频审核开启，则为必填字段，没有默认值，目前可选项：`antispam`。                                                                             |
| params.audio.saver.bucket    | string   | N  | 如果开启音频审核，则为必填字段，直播音频截帧文件存入的 bucket，目前只支持存入七牛云华东的 bucket。如何创建七牛云 bucket，请参见[文档](/products/kodo/0-console-quickstart#step1)。 |
| params.image.saver.prefix    | string   | N  | 保存的音频截帧文件的前缀。                                                                                                              |
| params.audio.hook\_rule      | string   | N  | 音频审核结果回调规则，0/1。默认为 0，返回判定结果违规的审核结果；设为 1 时，返回所有审核结果。                                                                        |

> 示例
>
> ```
> POST /v3/live/censor HTTP/1.1
> Host: ai.qiniuapi.com
> Content-Type: application/json
> Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=
>
> &#123;
>     "data": &#123;
>         "id": "live-censor",
>         "uri": "rtmp://pili-live-rtmp.qiniu.co/live/censor",
>         "info": &#123;
>             "live_id": "example"
>         &#125;
>     &#125;,
>     "params": &#123;
>         "image": &#123;
>             "is_on": true,
>             "scenes": [
>                 "pulp",
>                 "terror",
>                 "politician"
>             ],
>             "interval_msecs": 1000,
>             "saver": &#123;
>                 "bucket": "live",
>                 "prefix": "image/"
>             &#125;,
>             "hook_rule": 0
>         &#125;,
>         "audio": &#123;
>             "is_on": true,
>             "scenes": [
>                 "antispam"
>             ],
>             "saver": &#123;
>                 "bucket": "live",
>                 "prefix": "audio/"
>             &#125;,
>             "hook_rule": 0
>         &#125;,
>         "hook_url": "http://requestbin.fullcontact.com/1mhqoh41",
>         "hook_auth": true
>     &#125;
> &#125;
> ```

注意： 请把 Authorization 换成您的账号七牛鉴权 QiniuToken

**返回参数说明**

| 参数       | 类型     | 说明                          |
| :------- | :----- | :-------------------------- |
| code     | int    | 请求处理结果的状态码，200 表示成功，否则表示异常。 |
| message  | string | 请求处理信息。                     |
| data.job | string | 唯一标识该直播审核任务的 ID。            |

> 示例
>
> ```
> HTTP/1.1 200 OK
> Content-Type: application/json
>
> &#123;
>     "code": 200,
>     "message": "ok",
>     "data": &#123;
>        "job": "example_id"
>     &#125;
> &#125;
> ```

# 审核结果回调 [#审核结果回调]

**请求 Header**

| 字段           | 取值               |
| :----------- | :--------------- |
| Content-Type | application/json |

**请求参数**

| 字段                | 取值       | 说明                                |
| :---------------- | :------- | :-------------------------------- |
| job               | string   | 唯一标识该直播审核任务的 ID。                  |
| live.id           | string   | 该直播流的 ID。                         |
| live.uri          | string   | 该直播流的地址。                          |
| live.info         | json 结构体 | 该直播流附加信息。                         |
| error.timestamp   | int      | 错误信息的时间戳。                         |
| error.message     | string   | 回调的错误信息。                          |
| image.code        | int      | 处理状态：200 调用成功。                    |
| image.message     | string   | 与 code 对应的状态描述信息。                 |
| image.job         | string   | 唯一标识该直播审核任务的 ID。                  |
| image.url         | string   | 图片的 URL。                          |
| image.timestamp   | int      | 图片的时间戳。                           |
| image.result      | json 结构体 | 该图片资源的审核返回结果，详情请查看*表. 资源的审核返回结果*。 |
| audio.code        | int      | 处理状态：200 调用成功。                    |
| audio.message     | string   | 与 code 对应的状态描述信息。                 |
| audio.job         | string   | 唯一标识该直播审核任务的 ID。                  |
| audio.url         | string   | 音频段的 URL。                         |
| audio.start       | int      | 音频开始的时间戳。                         |
| audio.end         | int      | 音频结束的时间戳。                         |
| audio.audio\_text | string   | 该音频资源的语言识别文本。                     |
| audio.result      | json 结构体 | 该音频资源的审核返回结果，详情请查看*表. 资源的审核返回结果*。 |

> 示例
>
> ```
> &#123;
>     "job": "example_id",
>     "live": &#123;
>         "id": "live-censor",
>         "uri": "rtmp://pili-live-rtmp.qiniu.co/live/censor?sign=live",
>         "info": &#123;
>             "live_id": "example"
>         &#125;
>     &#125;,
>     "error": &#123;
>         "timestamp": 1596845288,
>         "message": "example error msg"
>     &#125;,
>     "image": &#123;
>         "code": 200,
>         "message": "ok",
>         "job": "example_id",
>         "timestamp": 1596845288,
>         "url": "qiniu://11111111@z0/image_save_bucket_name/image_cut_file_key.jpg",
>         "result": &#123;
>             "suggestion": "pass",
>             "scenes": &#123;
>                 "pulp": &#123;
>                     "suggestion": "pass",
>                     "details": [
>                         &#123;
>                             "suggestion": "pass",
>                             "label": "normal",
>                             "score": 0.99
>                         &#125;,
>                         &#123;&#125;
>                     ]
>                 &#125;
>             &#125;
>         &#125;
>     &#125;,
>     "audio": &#123;
>         "code": 200,
>         "message": "ok",
>         "job": "example_id",
>         "start": 1596845288,
>         "end": 1596881288,
>         "url": "qiniu://11111111@z0/audio_save_bucket_name/audio_cut_file_key.aac",
>         "audio_text": "直播审核",
>         "result": &#123;
>             "suggestion": "pass",
>             "scenes": &#123;
>                 "pulp": &#123;
>                     "suggestion": "pass",
>                     "details": [
>                         &#123;
>                             "suggestion": "pass",
>                             "label": "normal",
>                             "text": "直播",
>                             "score": 0.99
>                         &#125;,
>                         &#123;
>                             "suggestion": "pass",
>                             "label": "normal",
>                             "text": "审核",
>                             "score": 0.88
>                         &#125;
>                     ]
>                 &#125;
>             &#125;
>         &#125;
>     &#125;
> &#125;
> ```

# 查询审核结果 [#查询审核结果]

请求方式： POST

请求 url： [http://ai.qiniuapi.com/v3/live/censor/query](http://ai.qiniuapi.com/v3/live/censor/query)

**请求参数**

| 参数          | 类型     |  必选 | 说明                                              |
| :---------- | :----- | :-: | :---------------------------------------------- |
| job         | string |  Y  | 唯一标识该直播审核任务的 ID。                                |
| suggestions | array  |  N  | 查询过滤条件，默认为空，即查询全部。可选项：pass/review/block。        |
| start       | int    |  Y  | 查询结果开始时间，数值为开始时间的时间戳。                           |
| end         | int    |  N  | 查询结果结束时间，默认值为开始时间加 10min; 结束时间和开始时间的差值最大为 10min |

> 示例
>
> ```
> POST /v3/live/censor/query HTTP/1.1
> Host: ai.qiniuapi.com
> Content-Type: application/json
> Authorization: Qiniu &lt;AccessKey&gt;:&lt;Sign&gt;
>
> &#123;
>     "job": "example_id",
>     "suggestions": ["review", "block"],
>     "start": 1614153600,
>     "end": 1614154200
> &#125;
> ```

**返回参数说明**

| 字段               | 取值       | 说明                                   |
| :--------------- | :------- | :----------------------------------- |
| data.marker      | string   | 返回游标信息，用于下一次拉取。如果没有剩余条目则返回空字符串。      |
| data.items.image | json 结构体 | 直播图片审核的返回结果，详情请查看*表. 直播审核图片信息的返回结果*。 |
| data.items.audio | json 结构体 | 直播音频审核的返回结果，详情请查看*表. 直播审核音频信息的返回结果*。 |

*表. 直播审核图片信息的返回结果*

| 字段              | 取值       | 说明                                |
| :-------------- | :------- | :-------------------------------- |
| image.code      | int      | 处理状态：200 调用成功。                    |
| image.message   | string   | 与 code 对应的状态描述信息。                 |
| image.job       | int      | 唯一标识该直播审核任务的 ID。                  |
| image.url       | string   | 图片的 URL。                          |
| image.timestamp | int      | 图片的时间戳。                           |
| image.result    | json 结构体 | 该图片资源的审核返回结果，详情请查看*表. 资源的审核返回结果*。 |

*表. 直播审核音频信息的返回结果*

| 字段                | 取值       | 说明                                |
| :---------------- | :------- | :-------------------------------- |
| audio.code        | int      | 处理状态：200 调用成功。                    |
| audio.message     | string   | 与 code 对应的状态描述信息。                 |
| audio.job         | int      | 唯一标识该直播审核任务的 ID。                  |
| audio.url         | string   | 音频段的 URL。                         |
| audio.start       | int      | 音频开始的时间戳。                         |
| audio.end         | int      | 音频结束的时间戳。                         |
| audio.audio\_text | string   | 该音频资源的语言识别文本。                     |
| audio.result      | json 结构体 | 该音频资源的审核返回结果，详情请查看*表. 资源的审核返回结果*。 |

*表. 资源的审核返回结果*

| 字段                                                   | 取值       | 说明                                                                                                                                                                                                                                     |
| :--------------------------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| result.suggestion                                    | string   | 直播的审核结果管控建议说明<br />根据内容审核中各种审核类型的返回结果，系统会将审核结果转换成对应的管控建议，取值包括：\[“block”, ”review”, ”pass”]。<br />suggestion=block：表示系统确认审核内容违规，建议您将其删除。<br />suggestion=review：表示系统无法确认审核内容是否违规，建议您进行人工复核。<br />suggestion=pass：表示系统确认审核内容正常，建议您忽略该文件。 |
| result.scenes. `&lt;type&gt;`                        | json 结构体 | 审核类型，目前支持 "pulp", "terror"，"politician"，"antispam"。                                                                                                                                                                                    |
| result.scenes. `&lt;type&gt;` .suggestion            | string   | 该审核类型的结果管控建议，参见 result.suggestion。                                                                                                                                                                                                     |
| result.scenes. `&lt;type&gt;` .details\[]            | array    | 该审核类型的资源审核结果数组。                                                                                                                                                                                                                        |
| result.scenes. `&lt;type&gt;` .details\[].suggestion | string   | 该审核类型的资源审核结果管控建议，参见 result.suggestion。                                                                                                                                                                                                 |
| result.scenes. `&lt;type&gt;` .details\[].label      | string   | 该审核类型的截帧审核结果标签，具体请参见[内容审核](/products/censor/3-censor-params)的 label/group。                                                                                                                                                             |
| result.scenes. `&lt;type&gt;` .details\[].group      | string   | 该审核类型的截帧审核结果分组信息，具体请参见[内容审核](/products/censor/3-censor-params)的 label/group。                                                                                                                                                           |
| result.scenes. `&lt;type&gt;` .details\[].score      | float    | 该审核类型的截帧审核结果置信度。                                                                                                                                                                                                                       |
| result.scenes. `&lt;type&gt;` .details\[].text       | string   | 音频审核违规内容结果字段。                                                                                                                                                                                                                          |

> 示例
>
> ```
> &#123;
>     "code": 200,
>     "message": "ok",
>     "data": &#123;
>         "marker": "",
>         "items": &#123;
>             "image": [
>                 &#123;
>                     "code": 200,
>                     "message": "ok",
>                     "job": "example_id",
>                     "timestamp": 1596845288,
>                     "url": "qiniu://11111111@z0/image_save_bucket_name/image_cut_file_key.jpg",
>                     "result": &#123;
>                         "suggestion": "pass",
>                         "scenes": &#123;
>                             "pulp": &#123;
>                                 "suggestion": "pass",
>                                 "details": [
>                                     &#123;
>                                         "suggestion": "pass",
>                                         "label": "normal",
>                                         "score": 0.99
>                                     &#125;,
>                                     &#123;&#125;
>                                 ]
>                             &#125;
>                         &#125;
>                     &#125;
>                 &#125;,
>                 &#123;&#125;
>             ],
>             "audio": [
>                 &#123;
>                     "code": 200,
>                     "message": "ok",
>                     "job": "example_id",
>                     "start": 1596845288,
>                     "end": 1596881288,
>                     "url": "qiniu://11111111@z0/audio_save_bucket_name/audio_cut_file_key.aac",
>                     "audio_text": "直播审核",
>                     "result": &#123;
>                         "suggestion": "pass",
>                         "scenes": &#123;
>                             "antispam": &#123;
>                                 "suggestion": "pass",
>                                 "details": [
>                                     &#123;
>                                         "suggestion": "pass",
>                                         "label": "normal",
>                                         "text": "直播",
>                                         "score": 0.99
>                                     &#125;,
>                                     &#123;
>                                         "suggestion": "pass",
>                                         "label": "normal",
>                                         "text": "审核",
>                                         "score": 0.88
>                                     &#125;
>                                 ]
>                             &#125;
>                         &#125;
>                     &#125;
>                 &#125;,
>                 &#123;&#125;
>             ]
>         &#125;
>     &#125;
> &#125;
> ```

# 查询任务 [#查询任务]

请求方式： POST

请求 url： [http://ai.qiniuapi.com/v3/live/censor/jobinfo](http://ai.qiniuapi.com/v3/live/censor/jobinfo)

**请求参数**

| 参数  | 类型     |  必选 | 说明               |
| :-- | :----- | :-: | :--------------- |
| job | string |  Y  | 唯一标识该直播审核任务的 ID。 |

> 示例
>
> ```
> POST /v3/live/censor/jobinfo HTTP/1.1
> Host: ai.qiniuapi.com
> Content-Type: application/json
> Authorization: Qiniu &lt;AccessKey&gt;:&lt;Sign&gt;
>
> &#123;
>     "job": "example_id"
> &#125;
> ```

**返回参数说明**

| 字段                                | 取值       | 说明                                    |
| :-------------------------------- | :------- | :------------------------------------ |
| code                              | int      | 请求处理结果的状态码，200 表示成功，否则表示异常。           |
| message                           | string   | 请求处理结果的提示信息。                          |
| data.id                           | string   | 直播审核任务标示                              |
| data.data.id                      | string   | 直播流标示                                 |
| data.data.uri                     | string   | 直播流地址                                 |
| data.data.info                    | json 结构体 | 直播流附加信息                               |
| data.params.hook\_url             | string   | 回调地址                                  |
| data.params.hook\_auth            | boolean  | 回调鉴权是否开启                              |
| data.params.image.is\_on          | boolean  | 直播图片审核是否开启                            |
| data.params.image.scenes          | array    | 图片审核类型                                |
| data.params.image.interval\_msecs | int      | 截帧频率                                  |
| data.params.image.saver.bucket    | string   | 截帧文件存入的 bucket                        |
| data.params.image.saver.prefix    | string   | 保存图片截帧文件前缀。                           |
| data.params.image.hook\_rule      | int      | 图片审核结果回调规则                            |
| data.params.audio.is\_on          | boolean  | 音频审核是否开启                              |
| data.params.audio.scenes          | array    | 音频审核类型                                |
| data.params.audio.saver.bucket    | string   | 音频截帧文件存入的 bucket                      |
| data.params.image.saver.prefix    | string   | 保存音频截帧文件前缀。                           |
| data.params.audio.hook\_rule      | string   | 音频审核结果回调规则                            |
| data.message                      | string   | 任务状态相关信息                              |
| data.status                       | string   | 任务状态， `waiting/doing/stop/finished` 。 |
| data.created\_at                  | string   | 任务创建时间戳                               |
| data.updated\_at                  | string   | 任务更新时间戳                               |

> 示例
>
> ```
> &#123;
>     "code": 200,
>     "message": "ok",
>     "data": &#123;
>         "id": "example_id",
>         "data": &#123;
>             "id": "",
>             "uri": "",
>             "info": &#123;&#125;
>         &#125;,
>         "params": &#123;
>             "hook_url": "",
>             "hook_auth": false,
>             "image": &#123;
>                 "is_on": true,
>                 "scenes": [
>                     "pulp",
>                     "terror"
>                 ],
>                 "interval_msecs": 1000,
>                 "saver": &#123;
>                     "bucket": "",
>                     "prefix": ""
>                 &#125;,
>                 "hook_rule": 0
>             &#125;,
>             "audio": &#123;
>                 "is_on": true,
>                 "scenes": [
>                     "antispam"
>                 ],
>                 "saver": &#123;
>                     "bucket": "",
>                     "prefix": ""
>                 &#125;,
>                 "hook_rule": 0
>             &#125;
>         &#125;,
>         "message": "",
>         "status": "doing",
>         "created_at": 1596845288,
>         "updated_at": 1596845888
>     &#125;
> &#125;
> ```

# 列取任务 [#列取任务]

请求方式： POST

请求 url： [http://ai.qiniuapi.com/v3/live/censor/list](http://ai.qiniuapi.com/v3/live/censor/list)

**请求参数**

| 参数     | 类型     |  必选 | 说明                                    |
| :----- | :----- | :-: | :------------------------------------ |
| start  | int    |  Y  | 查询时间段开始时间戳。                           |
| end    | int    |  Y  | 查询时间段结束时间戳。                           |
| status | string |  Y  | 任务状态， `waiting/doing/stop/finished` 。 |
| limit  | int    |  N  | 查询审核结果条数，默认为 10，最大 100 条。             |
| marker | string |  N  | 上一次请求返回的标记，作为本次请求的起点信息。可选，默认值为空字符串。   |

> 示例
>
> ```
> POST /v3/live/censor/list HTTP/1.1
> Host: ai.qiniuapi.com
> Content-Type: application/json
> Authorization: Qiniu &lt;AccessKey&gt;:&lt;Sign&gt;
>
> &#123;
>     "start": 1596845288,
>     "end": 1596881288,
>     "status": "doing",
>     "limit": 100,
>     "marker": ""
> &#125;
> ```

**返回参数说明**

| 字段                                         | 取值       | 说明                                    |
| :----------------------------------------- | :------- | :------------------------------------ |
| code                                       | int      | 请求处理结果的状态码，200 表示成功，否则表示异常。           |
| message                                    | string   | 请求处理结果的提示信息。                          |
| data.marker                                | string   | 返回游标信息，用于下一次拉取。如果没有剩余条目则返回空字符串。       |
| data.items\[]                              | array    | 直播审核任务查询结果。                           |
| data.items\[].id                           | string   | 直播审核任务标示                              |
| data.items\[].data.id                      | string   | 直播流标示                                 |
| data.items\[].data.uri                     | string   | 直播流地址                                 |
| data.items\[].data.info                    | json 结构体 | 直播流附加信息                               |
| data.items\[].params.hook\_url             | string   | 回调地址                                  |
| data.items\[].params.hook\_auth            | boolean  | 回调鉴权是否开启                              |
| data.items\[].params.image.is\_on          | boolean  | 直播图片审核是否开启                            |
| data.items\[].params.image.scenes          | array    | 图片审核类型                                |
| data.items\[].params.image.interval\_msecs | int      | 截帧频率                                  |
| data.items\[].params.image.saver.bucket    | string   | 截帧文件存入的 bucket                        |
| data.items\[].params.image.saver.prefix    | string   | 保存图片截帧文件前缀。                           |
| data.items\[].params.image.hook\_rule      | int      | 图片审核结果回调规则                            |
| data.items\[].params.audio.is\_on          | boolean  | 音频审核是否开启                              |
| data.items\[].params.audio.scenes          | array    | 音频审核类型                                |
| data.items\[].params.audio.saver.bucket    | string   | 音频截帧文件存入的 bucket                      |
| data.items\[].params.image.saver.prefix    | string   | 保存音频截帧文件前缀。                           |
| data.items\[].params.audio.hook\_rule      | string   | 音频审核结果回调规则                            |
| data.items\[].message                      | string   | 任务状态相关的处理信息。                          |
| data.items\[].status                       | string   | 任务状态， `waiting/doing/stop/finished` 。 |
| data.items\[].created\_at                  | string   | 任务创建时间戳                               |
| data.items\[].updated\_at                  | string   | 任务更新时间戳                               |

> 示例
>
> ```
> &#123;
>     "code": 200,
>     "message": "ok",
>     "data": &#123;
>         "items": [
>             &#123;
>                 "id": "example_id",
>                 "data": &#123;
>                     "id": "",
>                     "uri": "",
>                     "info": &#123;&#125;
>                 &#125;,
>                 "params": &#123;
>                     "hook_url": "",
>                     "hook_auth": false,
>                     "image": &#123;
>                         "is_on": true,
>                         "scenes": [
>                             "pulp",
>                             "terror"
>                         ],
>                         "interval_msecs": 1000,
>                         "saver": &#123;
>                             "bucket": "",
>                             "prefix": ""
>                         &#125;,
>                         "hook_rule": 0
>                     &#125;,
>                     "audio": &#123;
>                         "is_on": true,
>                         "scenes": [
>                             "antispam"
>                         ],
>                         "saver": &#123;
>                             "bucket": "",
>                             "prefix": ""
>                         &#125;,
>                         "hook_rule": 0
>                     &#125;
>                 &#125;,
>                 "message": "",
>                 "status": "doing",
>                 "created_at": 1596845288,
>                 "updated_at": 1596845888
>             &#125;,
>             &#123;&#125;
>         ],
>         "marker": ""
>     &#125;
> &#125;
> ```

# 关闭任务 [#关闭任务]

请求方式： POST

请求 url： [http://ai.qiniuapi.com/v3/live/censor/close](http://ai.qiniuapi.com/v3/live/censor/close)

**请求参数**

| 参数  | 类型     |  必选 | 说明               |
| :-- | :----- | :-: | :--------------- |
| job | string |  Y  | 唯一标识该直播审核任务的 ID。 |

> 示例
>
> ```
> POST /v3/live/censor/close HTTP/1.1
> Host: ai.qiniuapi.com
> Content-Type: application/json
> Authorization: Qiniu &lt;AccessKey&gt;:&lt;Sign&gt;
>
> &#123;
>     "job": example_id"
> &#125;
> ```
>
> ```
> &#123;
>     "code": 200,
>     "message": "ok"
> &#125;
> ```


# API调用文本审核 (/products/censor/2-api-text-censor)



最近更新时间: 2026-06-11 11:45:39

本文介绍了 API 调用文本内容审核使用须知，帮助您正确使用此 API 进行文本内容审核，支持基于 API URL 发起 HTTP/HTTPS POST 请求的方式调用。

# 使用限制 [#使用限制]

* 文本长度不超过 2000 字

# 功能描述 [#功能描述]

文本内容审核 API 主要用于检测或识别文本中的不良信息，并给出审核结果管控建议。支持的审核类型包括: 文本反垃圾。
1、不支持白名单配置，加白需要您自己根据返回内容去处理；
2、如需拉黑特定文本内容，可以将需要拉黑的文本词库整理好之后 [提交工单](https://support.qiniu.com/tickets) 反馈技术支持人工处理。

**审核类型 scenes 与相应的 label**

在提交内容审核任务时，您需要指定审核类型 **scenes** ；而在返回结果中，则包含了您指定的类型对应的 label 结果分类参数。

| 审核类型  | 说明             | scenes   | label/group                                                                                                                                                |
| :---- | :------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 文本反垃圾 | 识别文本中是否包含垃圾信息。 | antispam | normal：正常文本<br />spam：含垃圾信息<br />ad：广告<br />politics：涉政<br />terrorism：暴恐<br />abuse：辱骂<br />porn：色情<br />flood：灌水<br />contraband：违禁<br />meaningless：无意义 |

# 请求参数 [#请求参数]

目前，支持提交文本内容进行同步审核。

**请求方式** POST

**请求接口** [http://ai.qiniuapi.com/v3/text/censor](http://ai.qiniuapi.com/v3/text/censor)

**请求Header**

| 字段            | 取值                                                                                                                                                               |
| :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | application/json                                                                                                                                                 |
| Authorization | Qiniu \<AccessKey>:\<Sign> <br />注意: 用户请根据AccessKey和SecretKey后生成鉴权，以便进行身份验证。`&lt;Sign&gt;`的取值请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken) |

**请求参数**

| 字段            | 类型           | 是否必选 | 说明                       |
| :------------ | :----------- | :--- | :----------------------- |
| data.text     | string       | Y    | 文本内容。                    |
| params.scenes | string array | Y    | 审核类型，必填字段，可选项：`antispam` |

# 返回参数 [#返回参数]

| 字段                                                   | 取值           | 说明                                                                                                                                                                                                                                    |
| :--------------------------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| code                                                 | int          | 处理状态：200 调用成功                                                                                                                                                                                                                         |
| message                                              | string       | 与 code 对应的状态描述信息                                                                                                                                                                                                                      |
| result.suggestion                                    | string       | 文本审核结果管控建议说明<br /> 根据内容审核中各种审核类型的返回结果，系统会将审核结果转换成对应的管控建议，取值包括：block/review/pass。<br />  suggestion=block：表示系统确认审核内容违规，建议您将其删除。<br /> suggestion=review：表示系统无法确认审核内容是否违规，建议您进行人工复核。<br /> suggestion=pass：表示系统确认审核内容正常，建议您忽略该文件。<br /> |
| result.scenes.`&lt;scene&gt;`                        | json 结构体     | 审核类型，目前支持：`antispam`                                                                                                                                                                                                                  |
| result.scenes.`&lt;scene&gt;`.suggestion             | string       | 该审核类型的结果管控建议，参见result.suggestion                                                                                                                                                                                                      |
| result.scenes.`&lt;scene&gt;`.details\[]             | object array | 该审核类型的详细信息数组                                                                                                                                                                                                                          |
| result.scenes.`&lt;scene&gt;`.details\[].label       | string       | 该审核类型返回的标签，具体请参见上文中**审核类型scenes与相应的label**                                                                                                                                                                                            |
| result.scenes.`&lt;scene&gt;`.details\[].score       | float        | 该审核类型结果置信度                                                                                                                                                                                                                            |
| result.scenes.`&lt;scene&gt;`.details\[].description | string       | 违规内容描述                                                                                                                                                                                                                                |

# 示例 [#示例]

## 请求示例 [#请求示例]

```http
POST /v3/text/censor HTTP/1.1
Host: ai.qiniuapi.com
Content-Type: application/json
Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=
{
    "data": {
        "text": "七牛文本审核示例"
    },
    "params": {
        "scenes": [
            "antispam"
        ]
    }
}
```

**注意：** 请把 Authorization 换成您的账号七牛鉴权 QiniuToken

## 返回示例 [#返回示例]

```json
{
    "message": "OK",
    "code": 200,
    "result": {
        "scenes": {
            "antispam": {
                "details": [
                    {
                        "score": 0.99985,
                        "label": "normal"
                    }
                ],
                "suggestion": "pass"
            }
        },
        "suggestion": "pass"
    }
}
```


# 参数说明 (/products/censor/3-censor-params)



最近更新时间: 2021-10-25 11:43:46

# 审核标签说明 [#审核标签说明]

**审核类型scenes与相应的label/group**

| 审核类型     | 说明             | scenes     | label/group                                                                                                                                                                                                                                                                                                           |
| :------- | :------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 图片鉴黄     | 识别图片中的色情、性感内容。 | pulp       | normal：正常图片，无色情内容<br />sexy：性感图片<br />pulp：色情图片                                                                                                                                                                                                                                                                       |
| 图片鉴暴恐    | 识别图片中的暴恐内容。    | terror     | bloodiness：血腥<br />self\_burning：自焚<br />beheaded：斩首类<br />march\_crowed：人群聚集类<br />fight\_police：警民冲突<br />fight\_person：民众肢体接触<br />illegal\_flag：违规旗帜类<br />guns：枪<br />knives：刀<br />anime\_bloodiness：动漫血腥类<br />anime\_knives：二次元刀<br />anime\_guns：二次元枪<br />politics：涉政<br />violence：暴恐<br />normal：正常<br /> |
| 图片敏感人物识别 | 识别图片中的敏感人物人脸。  | politician | 图片敏感人物识别的label返回的是敏感人物的姓名；<br />group返回的是该敏感人物所属的分组，目前支持的分组有：<br />domestic\_statesman：国内政要<br />foreign\_statesman：国外政要<br />chinese\_martyr：革命英烈<br />affairs\_official\_gov：落马官员（政府）<br />affairs\_official\_ent：落马官员（企事业）<br />terrorist：恐怖分子<br />affairs\_celebrity：劣迹艺人<br />politics：涉政人物<br />               |
| 图片广告识别   | 识别图片中的广告内容。    | ads        | 图片广告识别的label有：<br />summary\_ads：文字广告<br /> qr\_code：二维码<br />bar\_code：一维码                                                                                                                                                                                                                                           |
| 图片不良场景识别 | 识别图片中的不良场景内容。  | behavior   | 图片不良场景识别的label有：<br />behavior：不良场景<br /> normal: 正常                                                                                                                                                                                                                                                                  |
| 音频违规识别   | 识别音频中的违规内容。    | antispam   | 音频违规识别的label有：<br />porn：色情 <br />politics：涉政 <br />abuse：辱骂 <br />ad：广告 <br />normal：正常                                                                                                                                                                                                                              |

# 审核资源说明 [#审核资源说明]

**qiniu 协议**

协议格式: `qiniu:///<bucket>/<key>`


# API调用音频审核 (/products/censor/4-audio-censor)



最近更新时间: 2021-10-25 11:45:38

　　本文介绍了异步调用音频内容审核 `/v3/audio/censor` 的接口，帮助您正确使用此 API 进行音频内容审核，支持基于API URL发起HTTP/HTTPS POST请求的方式调用。

# 使用限制 [#使用限制]

* 音频大小不超过200M。
* 音频格式支持 MP3、WAV、AAC、WMA、OGG、M4A、AMR、AUDIO、M3U8。
* 接口响应时间依赖音频的下载时间。请保证被审核音频所在的存储服务稳定可靠，建议您使用七牛云存储或者CDN缓存等。

# 功能描述 [#功能描述]

音频内容审核 API 主要用于检测或识别音频中的不良信息，并给出审核结果管控建议。支持的审核类型包括：音频反垃圾。

**审核类型 scenes 与相应的 label**

在提交内容审核任务时，您需要指定审核类型 **scenes** ；而在返回结果中，则包含了您指定的类型对应的 label 结果分类参数。

| 审核类型  | 说明             | scenes   | label                                                                      |
| :---- | :------------- | :------- | :------------------------------------------------------------------------- |
| 音频反垃圾 | 识别音频中是否包含垃圾信息。 | antispam | normal：正常文本<br />politics：涉政<br />porn：色情<br />abuse：辱骂<br />contraband：违禁 |

# 请求说明 [#请求说明]

请求方式：POST

请求url：[http://ai.qiniuapi.com/v3/audio/censor](http://ai.qiniuapi.com/v3/audio/censor)

**请求Header**

| 字段            | 取值                                                                                                                                                                                        |
| :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | application/json                                                                                                                                                                          |
| Authorization | Qiniu \< AccessKey> :\< Sign> <br />注意: 用户请根据 AccessKey 和 SecretKey 后生成鉴权，以便进行身份验证， `Sign` 的取值以及 `Authorization` 签名方法请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken)。 |

**请求参数**

| 字段                | 类型      | 是否必选 | 说明                                                                       |
| :---------------- | :------ | :--- | :----------------------------------------------------------------------- |
| data.uri          | string  | Y    | 音频URL地址，目前支持http、https和[qiniu协议](/products/censor/3-censor-params#2)的资源。 |
| data.id           | string  | N    | 调用者设置的音频唯一标识，异步处理的返回结果中会带上该信息。                                           |
| params.scenes     | array   | Y    | 审核类型，必填字段，当前唯一可选项： `antispam` 。                                          |
| params.hook\_url  | string  | N    | 音频检测结束后的回调地址。                                                            |
| params.hook\_auth | Boolean | N    | true/false，默认为false，设置回调请求中加入请求头authorization，用于回调服务器鉴权                  |

**请求示例**

```
POST /v3/audio/censor HTTP/1.1
Host: ai.qiniuapi.com
Content-Type: application/json
Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=

{
    "data": {
        "uri": "http://xxx.mp3",
        "id": "audio-censor-demo"
    },
    "params": {
        "scenes": [
            "antispam"
        ],
        "hook_url":"http://xxx.com"
    }
}
```

注意： 请把 Authorization 换成您的账号七牛鉴权 QiniuToken

## 系统接受到请求后，会立即返回异步任务 id，音频审核结果通过任务 id 获得。 [#系统接受到请求后会立即返回异步任务-id音频审核结果通过任务-id-获得]

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": <id>
}
```

| 参数   | 类型     |  必选 | 说明                     |
| :--- | :----- | :-: | :--------------------- |
| `id` | string |  是  | 服务器返回的，唯一标识该音频审核任务的ID。 |

# 通过任务id获取音频审核结果 [#通过任务id获取音频审核结果]

**请求语法**

```
GET /v3/jobs/audio/<id> HTTP/1.1
Host: ai.qiniuapi.com
Authorization: Qiniu <AccessKey>:<Sign>
```

**注意：** 需要在请求的 head 部分添加[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken)，以进行用户身份验证。

| 参数   | 类型     |  必选 | 说明                   |
| :--- | :----- | :-: | :------------------- |
| `id` | string |  是  | 服务器返回的，唯一标识该音频任务的ID。 |

**返回参数说明**

| 字段          | 取值      | 说明                                      |
| :---------- | :------ | :-------------------------------------- |
| id          | string  | 服务器返回的，唯一标识该音频任务的ID。                    |
| status      | string  | 任务状态， `WAITING/DOING/FINISHED/FAILED` 。 |
| request     | json结构体 | 音频审核请求中的body。                           |
| response    | json结构体 | 音频内容审核的返回结果，详情请查看 `*表. 音频内容审核的返回结果*` 。  |
| error       | string  | 任务错误信息。                                 |
| created\_at | string  | 任务创建时间，如：2021-05-18T15:03:04.123Z。      |
| updated\_at | string  | 任务更新时间，如：2021-05-18T15:03:14.123Z。      |

*表. 音频内容审核的返回结果*

| 字段                                                           | 取值      | 说明                                                                                                                                                                                                                                     |
| :----------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code                                                         | int     | 处理状态：200 调用成功                                                                                                                                                                                                                          |
| message                                                      | string  | 与code对应的状态描述信息                                                                                                                                                                                                                         |
| audio\_text                                                  | string  | 音频文本                                                                                                                                                                                                                                   |
| result.suggestion                                            | string  | 音频的审核结果管控建议说明<br />根据内容审核中各种审核类型的返回结果，系统会将审核结果转换成对应的管控建议，取值包括：\[“block”, ”review”, ”pass”]。<br />suggestion=block：表示系统确认审核内容违规，建议您将其删除。<br />suggestion=review：表示系统无法确认审核内容是否违规，建议您进行人工复核。<br />suggestion=pass：表示系统确认审核内容正常，建议您忽略该文件。 |
| result.scenes. `&lt;type&gt;`                                | json结构体 | 审核类型, 目前仅支持 `antispam`                                                                                                                                                                                                                 |
| result.scenes. `&lt;type&gt;` .suggestion                    | string  | 该审核类型的结果管控建议，参见result.suggestion                                                                                                                                                                                                       |
| result.scenes. `&lt;type&gt;` .cuts\[]                       | array   | 该审核类型的音频段审核结果数组                                                                                                                                                                                                                        |
| result.scenes. `&lt;type&gt;` .cuts\[].suggestion            | string  | 该审核类型的音频段审核结果管控建议，参见result.suggestion                                                                                                                                                                                                  |
| result.scenes. `&lt;type&gt;` .cuts\[].start\_time           | int     | 该审核类型的音频段在原始音频中的起始位移，单位s                                                                                                                                                                                                               |
| result.scenes. `&lt;type&gt;` .cuts\[].end\_time             | int     | 该审核类型的音频段在原始音频中的结束位移，单位s                                                                                                                                                                                                               |
| result.scenes. `&lt;type&gt;` .cuts\[].audio\_text           | string  | 该审核类型的音频段文本                                                                                                                                                                                                                            |
| result.scenes. `&lt;type&gt;` .cuts\[].details\[]            | array   | 该审核类型的音频段审核详细信息数组                                                                                                                                                                                                                      |
| result.scenes. `&lt;type&gt;` .cuts\[].details\[].suggestion | string  | 该审核类型的音频段审核结果详细的结果管控建议，参见result.suggestion                                                                                                                                                                                             |
| result.scenes. `&lt;type&gt;` .cuts\[].details\[].label      | string  | 该审核类型的音频段审核结果标签                                                                                                                                                                                                                        |
| result.scenes. `&lt;type&gt;` .cuts\[].details\[].score      | string  | 该审核类型的音频段审核结果置信度                                                                                                                                                                                                                       |

**返回示例**

```
{
    "id":"5c416b7afb09fe00089e37be",
    "request":{
        "data":{
            "uri":"http://xxx.mp3",
             "id":"audio-censor-demo"
        },
        "params":{
            "scenes":[
                "antispam"
            ],
            "hook_url":"http://xxx.com"
        }
    },
    "status":"FINISHED",
    "result":{
        "code":200,
        "message":"OK",
        "audio_text":"当地时间八月二十八号...当务之急是...",
        "result":{
            "suggestion":"block",
            "scenes":{
                "antispam":{
                    "suggestion":"block",
                    "cuts":[
                        {
                            "suggestion":"block",
                            "start_time":0,
                            "end_time":20,
                            "audio_text":"当地时间八月二十八号...",
                            "details":[
                                {
                                    "suggestion":"block",
                                    "label":"politics",
                                    "score":0.9991
                                }
                            ]
                        },
                        {
                            "suggestion":"block",
                            "start_time":20,
                            "end_time":42,
                            "audio_text":"当务之急是...",
                            "details":[
                                {
                                    "suggestion":"block",
                                    "label":"politics",
                                    "score":0.982
                                }
                            ]
                        }
                    ]
                }
            }
        }
    },
    "created_at":"2021-05-18T15:03:04.123Z",
    "updated_at":"2021-05-18T15:03:14.123Z"
}
```

# 音频审核结果回调 [#音频审核结果回调]

## 使用限制须知 [#使用限制须知]

* API调用音频审核支持不设置回调
* 若设置了回调，进行了一次API调用音频审核，则触发一次回调
* 若回调失败，会重试三次

## API调用音频审核回调格式 [#api调用音频审核回调格式]

| 字段          | 取值      | 说明                                      |
| :---------- | :------ | :-------------------------------------- |
| id          | string  | 服务器返回的，唯一标识该音频审核任务的ID。                  |
| request     | json结构体 | 音频审核请求中的body。                           |
| status      | string  | 任务状态， `WAITING/DOING/FINISHED/FAILED` 。 |
| response    | json结构体 | 音频审核返回结果，详情请查看 *表. 音频内容审核的返回结果*         |
| error       | string  | 任务错误信息。                                 |
| created\_at | string  | 任务创建时间，如：2021-05-18T15:03:04。           |
| updated\_at | string  | 任务更新时间，如：2021-05-18T15:03:14。           |

**返回示例**

```
{
    "id":"5c416b7afb09fe00089e37bf",
    "request":{
        "data":{
            "uri":"http://xxx.mp3",
            "id":"audio-censor-demo"
        },
        "params":{
            "scenes":[
                "antispam"
            ],
            "hook_url":"http://xxx.com"
        }
    },
    "status":"FINISHED",
    "response":{
        "code":200,
        "message":"OK",
        "audio_text":"当地时间八月二十八号...当务之急是...",
        "result":{
            "suggestion":"block",
            "scenes":{
                "antispam":{
                    "suggestion":"block",
                    "cuts":[
                        {
                            "suggestion":"block",
                            "start_time":0,
                            "end_time":20,
                            "audio_text":"当地时间八月二十八号...",
                            "details":[
                                {
                                    "suggestion":"block",
                                    "label":"politics",
                                    "score":0.9991
                                }
                            ]
                        },
                        {
                            "suggestion":"block",
                            "start_time":20,
                            "end_time":42,
                            "audio_text":"当务之急是...",
                            "details":[
                                {
                                    "suggestion":"block",
                                    "label":"politics",
                                    "score":0.982
                                }
                            ]
                        }
                    ]
                }
            }
        }
    },
    "created_at":"2021-05-18T15:03:04",
    "updated_at":"2021-05-18T15:03:14"
}
```


# 内容审核 iam (/products/censor/0-censor-iam)



最近更新时间: 2026-05-08 15:39:23

对于已经开通 IAM 子账号功能的用户，可以通过 `访问管理` 控制子账号使用内容审核产品的权限。

# 开通内容审核服务 [#开通内容审核服务]

在 `访问管理` > `策略管理` 中，新建策略 / 编辑已有策略时，将 `内容审核` 加入到服务列表中。

![开通服务](/docs-assets/products/censor/%285-best-practices%29/0-censor-iam/FlOjZZkiJTQlfmUHSyJtbYB5J_U7-fd32090dd46e.webp)

![设置权限](/docs-assets/products/censor/%285-best-practices%29/0-censor-iam/Fn_Tn8tibhU5ZVPlyqIe9P-aWfAh-ceb1a997b478.webp)

# 查看存储空间审核任务 [#查看存储空间审核任务]

开通 `查看存储空间审核任务` 功能后，子账号将可以查看存储空间审核任务的列表、数据统计、查看审核结果并进行复核

`注意`：为了能正确使用存 查看存储空间审核任务 功能，子账号需要同时开通以下 对象存储 的功能

|功能|说明|
\|-|-|-|
\| 读取文件| 子账号只能查看自身拥有读取文件功能的存储空间的审核任务，其他审核任务不可见 |
\| 禁用/启用文件 | 子账号在复核 或 批量封禁存量任务结果 时，需要开启对应存储空间的 禁用/启用文件 功能，否则会失败 |
\| 删除文件 | 子账号在复核删除文件 或 批量删除存量任务结果 时，需要开启对应存储空间的 删除文件 功能，否则会失败 |

# 管理存储空间审核任务 [#管理存储空间审核任务]

开通 `管理存储空间审核任务` 功能后，子账号将可以新建/修改/关闭审核任务

`注意`：为了能正确使用存 管理存储空间审核任务 功能，子账号需要同时开通以下 对象存储 的功能

|功能|说明|
\|-|-|-|
\| 读取文件| 子账号只能对自身拥有读取文件功能的存储空间开启审核任务，否则会失败 |
\| 禁用/启用文件 | 开通增量审核任务并设置自动封禁时，子账号需要开启对应存储空间的 禁用/启用文件 功能，否则会失败 |
\| 上传文件 | 开通视频审核任务或存量审核任务时，子账号需要开启截帧/结果保存对应存储空间的 上传文件 功能，否则会失败 |

# 调用内容审核 API [#调用内容审核-api]

开通 `调用内容审核 API` 功能后，子账号可以使用自身的 AK/SK 调用内容审核 API。参考[调用内容审核 API](/products/censor/image-censor)

# 查看内容审核 API 结果 [#查看内容审核-api-结果]

开通 `查看内容审核 API 结果` 功能后，子账号可以在控制台上查看内容审核 API 调用的结果并进行复核。

# 自助审核 [#自助审核]

开通 `自助审核` 功能后，子账号可以在控制台上进行自助复核。

# 管理自助审核任务 [#管理自助审核任务]

开通 `管理自助审核任务` 功能后，子账号可以在控制台上管理自助审核任务，包括以下操作：

* 新建/修改/关闭/开启自助审核任务
* 对自助审核任务进行资源关联
* 对自助审核任务进行人员分配

`注意`：关联资源时，需要对应资源的读权限。参考：[查看存储空间审核任务](#1)


# 动态加速升级全站加速 (/products/dcdn/0-dynamic-acceleration-upgraded-to-total-station)



最近更新时间: 2022-02-21 18:49:47

自2022年03月01日起，动态加速全面升级为全站加速DCDN。

全站加速在动态加速的基础上融合静态加速的能力，通过资源动静态分离、智能缓存、路由优化等核心技术一站式解决动静态资源混合站点内容分发慢的问题。您可通过配置静态缓存规则，实现纯动态加速的业务场景。本次升级主要影响包括（红色部分需要您重新适配）：

## 页面功能 [#页面功能]

1. CDN产品页面保留网页/下载/点播平台的域名业务，动态加速域名统一迁移至在DCDN产品页面进行管理，若创建动态加速域名请移步DCDN产品页面；
2. DCDN产品页面，新增「缓存配置」模块，默认关闭，即动态加速不缓存；打开后配置静态缓存规则，命中规则遵循静态边缘缓存逻辑，未命中部门使用最优线路动态回源，实现全站加速的效果。
3. DCDN支持IAM功能， &#x2A;*`若您有动态加速域名且对动态加速域名进行了IAM授权，本次升级影响原来的授权，需对DCDN服务域名重新授权`** ，可前往 [策略管理处](https://portal.qiniu.com/iam/policy/create) ，其他场景域名授权不受影响。

## 配置说明 [#配置说明]

1. 本次迁移不影响域名默认配置，若您的动态加速域名有特殊静态缓存规则，原配置依旧保留不影响线上业务，但不在控制台展示。为方便管理，建议您在控制台重新配置缓存规则，新规则将覆盖老规则；
2. 接口层面，DCDN提供了新接口，原有接口依旧适配，若您有动态加速业务，建议对接新接口；

## 账单说明 [#账单说明]

1. 计费项\
   升级前，动态加速计费项包括：基础流量费用（动态）、动态请求次数费用，若您申请配置过特殊静态缓存规则，产生的静态流量计入CDN流量计费项；\
   升级后，全站加速计费项包括：基础流量费用（动态和静态）、动态请求次数费用；\
   其中，DCDN 流量、 动态加速流量、CDN静态流量价格相同，理论上不影响客户费用，若因流量过大产生了阶梯计费差，可联系商务单独处理；
2. 价格\
   基础流量、动态请求次数单价不变，可参考 [官网](https://www.qiniu.com/prices/qcdn) ；
3. 资源包\
   本次升级不影响历史融合资源包的抵扣，购买资源包可前往 [商城](https://qmall.qiniu.com/template/NTI?spec_combo=MTk0OA) 选购。

## 常见问题 [#常见问题]

**Q：使用了动态加速域名，并且特殊配置了静态缓存规则，2月份对账时， CDN 账单流量与控制台查询的流量有出入。**\
A：升级前动态加速域名产生的静态流量计入到 CDN ，故2月份账单中的 CDN 静态流量计费项包含了动态加速域名产生的静态流量。升级后新逻辑调整为动态加速域名产生的静态流量计入到 DCDN （原动态加速流量计费项），故升级后控制台/接口查询历史 CDN 流量时，调用接口走新的逻辑，查询的结果不包含动态加速域名产生的静态流量。2月份账单对账时，应结合控制台/接口查询到的 CDN 静态流量、DCDN 静态流量来与 CDN 流量账单进行比对。升级后的账单与控制台查询用量预期一致。

**Q：网页/下载/点播平台域名是否可以转为全站加速域名。**\
A：控制台不支持直接转换，可提交工单联系售后人员进行处理。以下几点还请关注：

* 由于网页/下载/点播平台域名和全站加速域名的默认缓存规则不同，转换前后缓存规则有所变化，需要您重新适配；
* 全站加速和普通CDN域名实现逻辑有区别，功能支持情况有所区别，建议您先前往DCDN控制台了解功能支持情况；


# 产品概述 (/products/dcdn/0-dcdn-overview)



最近更新时间: 2022-03-14 11:05:32

## 产品简介 [#产品简介]

七牛全站加速 DCDN 在CDN静态加速的基础上融合了动态加速的能力，通过资源动静态分离、智能缓存、路由优化等核心技术一站式解决动静态资源混合站点内容分发慢的问题。适用于动态资源或动静态资源混合的加速场景。

<br />

## 产品架构 [#产品架构]

![image.png](/docs-assets/products/dcdn/%281-product-introduction%29/0-dcdn-overview/Fu1hQp-Aj9fD3ybYGY0RG8IU87Jo-fe4585a6335d.webp)


# 功能特性 (/products/dcdn/1-dcdn-features)



最近更新时间: 2022-03-14 11:05:39

# 动静混合加速 [#动静混合加速]

采用动静混合智能分离技术，自动识别动静态资源，静态资源边缘缓存高效分发，动态资源决策最优链路回源，实现资源精准加速。

# 资源覆盖全球 [#资源覆盖全球]

沉淀多年 CDN 管控经验，精选核心高质量节点，实现覆盖全球的边缘节点架构体系，国内无盲区覆盖各地、各运营商，海外广泛覆盖70多个国家和地区。

# 智能调度系统 [#智能调度系统]

基于全网请求来源的智能调度系统，支持 DNS、HttpDNS、Http302 调度模式，有效提高访问响应速度，防止劫持，实现全网实时精准调度调度。

# 私有协议优化 [#私有协议优化]

使用私有传输协议作为 DCDN 内部数据交换的基础，确保客户资源安全、快速的传输到各个节点，实现客户内容高效、可靠的进行分发。

# 链路优化 [#链路优化]

七牛自研探测 AGENT，精确探测点到点之间的链路质量，凭借特有的链路决策算法，可以保证边缘节点到源站之间的所有链路最优。

# 立体品控 [#立体品控]

基于权威 APM 的全网覆盖「性能监控」和七牛自研的监控数据为基础上自研的全网「实时可用性监控」，打造七牛 DCDN 立体品控体系。


# 计费说明 (/products/dcdn/0-dcdn-billing-instructions)



最近更新时间: 2026-04-30 15:28:06

七牛云 DCDN 计费组成包括：**动态请求数计费**和**流量计费**。

# 1. 动态请求数计费 [#1-动态请求数计费]

## 1.1 价格说明 [#11-价格说明]

动态加速请求次数不分区域，全球统一价格。

| 动态请求数   | 动态请求数       | 动态请求数     |
| ------- | ----------- | --------- |
| 名目      | 请求数         | 价格        |
| 动态加速请求数 | 第 0 次至 5 万次 | 免费        |
| 动态加速请求数 | 第 5 万次及以上   | 0.19 元/万次 |

<br />

## 1.2 计费方式 [#12-计费方式]

默认后付费按量计费。

## 1.3 细则说明 [#13-细则说明]

* 该计费项仅对动态请求计费，静态请求不额外收费。
* 请求次数以每万次请求为单位进行计算，不足万按万计算。

# 2. 流量计费 [#2-流量计费]

## 2.1 价格说明 [#21-价格说明]

七牛云 DCDN 默认按国内海外[不同区域阶梯流量价格](https://www.qiniu.com/prices/qcdn)计费，当月分别超额累进，每个自然月为一个累计周期。其他计费方式请联系七牛商务（400-101-8589 转 2 号线）或工单咨询。
**2.1.1 国内流量价格**

| 名目                       | 流量阶梯 （元/GB）     | 价格   |
| ------------------------ | --------------- | ---- |
| HTTP 下载流量/动态加速 HTTP 流量   |                 |      |
| HTTP 下载流量/动态加速 HTTP 流量   | 第 0 GB 至 100 TB | 0.24 |
| HTTP 下载流量/动态加速 HTTP 流量   | 第 100 TB 至 1 PB | 0.19 |
| HTTP 下载流量/动态加速 HTTP 流量   | 第 1PB 以上        | 0.14 |
| HTTPS 下载流量/动态加速 HTTPS 流量 | 第 0 GB 至 100 TB | 0.28 |
| HTTPS 下载流量/动态加速 HTTPS 流量 | 第 100 TB 至 1 PB | 0.23 |
| HTTPS 下载流量/动态加速 HTTPS 流量 | 第 1PB 以上        | 0.18 |

**2.1.2 海外流量价格**

| 名目                       | 流量阶梯 （元/GB）      | 亚洲（港澳台/东南亚/印度）         | 亚洲（其他地区）               | 欧洲/北美洲                 | 南美洲                    | 大洋洲与其他                 |
| ------------------------ | ---------------- | ---------------------- | ---------------------- | ---------------------- | ---------------------- | ---------------------- |
| HTTP 下载流量/动态加速 HTTP 流量   |                  |                        |                        |                        |                        |                        |
| HTTP 下载流量/动态加速 HTTP 流量   | 第 0 GB 至 10 TB   | 0.76                   | 0.50                   | 0.34                   | 0.76                   | 0.94                   |
| HTTP 下载流量/动态加速 HTTP 流量   | 第 10 TB 至 50 TB  | 0.66                   | 0.44                   | 0.30                   | 0.66                   | 0.82                   |
| HTTP 下载流量/动态加速 HTTP 流量   | 第 50 TB 至 100 TB | 0.57                   | 0.38                   | 0.26                   | 0.57                   | 0.71                   |
| HTTP 下载流量/动态加速 HTTP 流量   | 第 100TB 以上       | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 |
| HTTPS 下载流量/动态加速 HTTPS 流量 | 第 0 GB 至 10 TB   | 0.91                   | 0.60                   | 0.40                   | 0.91                   | 1.12                   |
| HTTPS 下载流量/动态加速 HTTPS 流量 | 第 10 TB 至 50 TB  | 0.79                   | 0.52                   | 0.36                   | 0.79                   | 0.98                   |
| HTTPS 下载流量/动态加速 HTTPS 流量 | 第 50 TB 至 100TB  | 0.68                   | 0.45                   | 0.31                   | 0.68                   | 0.85                   |
| HTTPS 下载流量/动态加速 HTTPS 流量 | 第 100TB 以上       | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 | 请联系我们 400-101-8589 转 1 |

<br />

## 2.2 计费方式 [#22-计费方式]

针对流量计费，七牛云 DCDN 提供两种付费方式，即后付费按量计费和预付费资源包，默认计费方式为后付费按量计费。

<br />

**2.2.1 按量后付费**
您可使用[CDN价格计算器](https://www.qiniu.com/prices/qcdn?tab=calc)进行用量预估；

**2.2.2 按资源包预付费**
七牛云 DCDN 可与 CDN 共用融合资源包，同时共享每月各分区 10GB HTTP 下载流量的免费额度，历史已购买的融合资源包支持抵扣。购买时请根据域名的加速范围选择类型：[CDN 中国大陆资源包](https://qmall.qiniu.com/template/NTI?spec_combo=MTk0OA) 或 [CDN 海外资源包](https://qmall.qiniu.com/template/NTU?ref=category\&spec_combo=MjEzNA)

（1）资源包类型
“CDN 下行通用流量”适用于 http 和 https 的静态或全站加速下行流量，其中 http 和 https 协议按照1: 1.15 的系数抵扣，https 协议不额外收取静态加速请求次数费用。

> **如何理解系数？** 实际使用 https 流量100GB，相当于抵扣资源包流量115GB。资源包的额度可以理解成诸如“点数”的概念，同单位的不同商品需要抵扣的点数不同。

> **按什么顺序抵扣？** 当资源包额度充足时（账单额度\<资源包余量），资源包可全部抵扣金额；当资源包额度不够时（账单额度\<资源包余量），按以下顺序抵扣：静态加速 HTTP、静态加速 HTTPS、动态加速 HTTP、动态加速 HTTPS。

（2）可用区域
可根据域名的实际加速区域选择资源包的可用区域；如果加速区域为全球，可能同时产生国内流量和海外流量。

（3）可用时段
为方便不同类型的用户优化 CDN 成本，七牛提供以下几种时段的资源包：

* **全时段流量包**：全时段指每天 0:00 - 24:00
* **日间时段流量包**：日间时段指每天 09:00 - 18:00
* **闲时流量包**：闲时段指每天 00:00 - 09:00

叠加使用规则和抵扣顺序参考 <a href="#Q3">资源包可以叠加使用吗？抵扣顺序是什么？</a>

（4）用量额度（用量预估）
可根据历史用量和实际使用需求预估资源包大小，建议可预估一年用量购买。

（5）分配方式
一次性分配资源包的流量在生效期内均可使用。

（6）余量查询
七牛云按量付费资源采取月结算模式，按量计费预估明细仅为预估账单和余额预扣除，没有实际完成扣除，所以资源包使用情况最终以月账单更新为准，我们可通过以下方法预估资源包使用情况：

* [资源包管理](https://portal.qiniu.com/financial/orders/respack-mgr/current)，查看估算资源包的使用情况
* [按量计费预估明细](https://portal.qiniu.com/financial/bills/estimated-consume)，查看本月资源包抵扣明细

注：按量计费预估明细每日8点更新一次，非实时动态更新，更新用量的使用时间截止为本日0点。

# 3. 常见问题 [#3-常见问题]

<div id="Q1" />

**Q：开启 HTTPS 以后如何收费？**
域名开启 HTTPS 配置以后，该域名下所有流量（包括 HTTPS 和 HTTP 请求）即开始按照 HTTPS 协议的价格进行收费。静态加速下 HTTPS 协议不额外收请求次数费用。对于月中升级为 https 的用户，本月计量都按照https计算。
默认配置下可兼容 HTTP 和 HTTPS 两种协议的请求，如需强制 HTTPS 访问，请在控制台开启“强制 HTTPS 访问”配置。

<div id="Q2" />

**Q：欠费以后还可以继续使用吗？**
欠费以后，无法新增域名和修改域名。更多信息请见：
[欠费状态下各产品的限制功能](/account/0-owe-the-protection-limit-function)
[新版欠费流程](/faq/account-finance/account-problem/5996-new-owe-the-process-description)

<div id="Q3" />

**Q：资源包可以叠加使用吗？抵扣顺序是什么？**
资源包可叠加购买，出账时将按照以下规则进行抵扣：

<img src="/docs-assets/products/dcdn/%282-buying-guide%29/0-dcdn-billing-instructions/FiDJc7qCvgUYYjQ_YpRpljIwEbwY-c8e4366c8a08.webp" width="500" />

<div id="Q4" />

**Q：使用量超出资源包后如何计费？**
在资源包生效期间内，若当月用量超出可用资源包额度，出账时将优先抵扣完资源包额度，超出部分再按照官网 [CDN 后付费价格 ](https://www.qiniu.com/prices)结算。

<div id="Q5" />

**Q：今天8点后购买的资源包，为什么没有进行抵扣？**
按量计费预估明细 每日8点更新，更新用量的使用时间是截止本日0点，非实时动态更新，当月生效的资源包，您可以在购买后第二天，在财务中心查看按量计费预估明细账单。


# 控制台指南 (/products/dcdn/0-dcdn-guide-to-the-console)



最近更新时间: 2026-04-30 15:36:21

欢迎查看 DCDN 帮助文档。您可以在任意时间地点使用七牛云全站加速，以提供稳定快速的网络访问质量。使用七牛云全站资源加速的整个流程共分以下几步：

* [注册七牛云](#step1)
* [添加自定义域名](#step2)
* [配置域名](#step3)
* [配置CNAME](#step4)

七牛云为空间资源提供测试域名，该类域名的源站为域名所在空间，默认缓存设置时间 1个月，无法自定义配置，也无法用于全站加速产品，建议您添加自定义域名使用。

为了顺利完成快速入门，您需要一个七牛云账号。如果您还没有七牛云账号，请通过以下步骤创建七牛云账号。

<a id="step1" />

# 1. 注册七牛云 [#1-注册七牛云]

（1）打开 [七牛管理控制台](https://portal.qiniu.com/)，选择 **注册**。
（2）遵循在线使用说明，完成实名认证。

<a id="step2" />

# 2. 添加自定义域名 [#2-添加自定义域名]

## 2.1 配置要求 [#21-配置要求]

配置域名不产生任何费用，要求具备：

* 已备案域名，且允许做域名解析，可在[域名信息备案系统](http://beian.miit.gov.cn/state/outPortal/loginPortal.action)查询
* 账号已完成实名认证；

## 2.2 配置入口 [#22-配置入口]

方式1：登陆[七牛管理控制台](https://portal.qiniu.com/signin)，选择 **添加加速域名** 。

<img src="/docs-assets/products/dcdn/%283-quick-start%29/0-dcdn-guide-to-the-console/FiGZuHq4bmuWl8Kc4TrshPzvCsQC-02352dd14486.webp" width="600" />

<img />

**方式2**:登陆[七牛管理控制台](https://portal.qiniu.com/signin)，点击 **产品与方案** ，选择 **全站加速**，点击添加域名。

<img src="/docs-assets/products/dcdn/%283-quick-start%29/0-dcdn-guide-to-the-console/FnMEnJxvZjHVdx6eHH3nG309XEN3-eebaf21c5ef8.webp" width="600" />

<img />

<img src="/docs-assets/products/dcdn/%283-quick-start%29/0-dcdn-guide-to-the-console/FnxvN16bei0iOwjsqM1m-lHokaJ-398ff0a614f4.webp" width="600" />

<img />

**注意**：如果您界面上方显示的是 **未完成实名认证** ，如下图所示：

<img src="/docs-assets/products/dcdn/%283-quick-start%29/0-dcdn-guide-to-the-console/Fj7_zEw1dLUwApw57tXGgqtqdjwX-6baa3e46ae81.webp" width="600" />

<img />

此时您需要在 **个人中心** 进行实名认证

<img src="/docs-assets/products/dcdn/%283-quick-start%29/0-dcdn-guide-to-the-console/FnyEISZbsazeBtdjJQ0riPXw4oIr1-3cc2f4eeda16.webp" width="600" />

<img />

## 2.3 配置项说明 [#23-配置项说明]

（1）**域名类型**

* 普通域名，是指您的主域名下的子域名。例如主域名qiniu.com，developer.qiniu.com是其二级域名，a.developer.qiniu.com是其三级域名,.....,这些都属于普通域名。
* 泛域名，是指域名\*.主域名，配置成功后可任意指定前缀进行访问；可基于该泛域名创建多个泛子域名来指定不同源站，例如泛域名 \*.qiniu.com。

（2）**加速域名**：要求填写**已备案**的域名
（3）**通信协议**：支持http或https通信协议
如果您选择 https协议，您还需上传有效期≥30天的 HTTPS 证书。（注：为不影响正常使用，证书到期后请及时续期）
（4）**覆盖范围**：分为国内、海外、全球，根据业务范围选择节点覆盖区域。不同区域流量价格不同，可参考[官网价格](https://www.qiniu.com/prices/qcdn)。
（5） **IP协议**

* IPv4/IPv6，同时支持IPv4和IPv6的请求，该协议支持国内/全球，海外默认仅支持ipv4，海外IPv6的需求可联系[工单](https://support.qiniu.com/tickets/new)配置。
* IPv4，仅支持IPv4请求，不支持IPv6请求。

（6）**源站配置**

* 源站域名，填写您的源站域名，不能与**加速域名**相同。**源站测试**中需要您填写您需要加速的资源名，通过源站测试，表明源站配置正确。
* IP地址，填写您源站的IP地址，**源站测试**中需要您填写您需要加速的资源名，通过源站测试，表明源站配置正确。

（7）**缓存配置**

* 关闭，默认关闭状态，即纯动态加速场景，不做任何缓存。
* 开启，适用动静态资源混合的场景，开启后可配置不同后缀或目录的静态缓存规则，命中规则部分遵循静态边缘缓存逻辑，未命中部分使用最优链路动态回源。

（8）**忽略 URL 参数**

* 关闭，默认关闭状态，完全按照参数缓存
* 开启，适用于提高边缘命中率且URL「?」后的参数不影响文件内容的场景。可配置「忽略全部参数」或「忽略指定参数」，静态资源会去除 URL「?」后的全部参数或指定参数进行缓存。

## 2.4 点击「创建」，提交配置 [#24-点击创建提交配置]

<a id="step3" />

# 3. 配置域名 [#3-配置域名]

若除创建域名的基础配置外，您还有其他配置需求，**返回域名管理**，在域名管理页面单击目标域名对应配置，此时您可以设置：

* [回源配置](/products/dcdn/configuration/1-dcdn-back-to-the-source-configuration)
* [缓存配置](/products/dcdn/configuration/2-dcdn-cache-configuration)
* [访问控制](/products/dcdn/configuration/dcdn-access-control-configuration/1-dcdn-ip-black-and-white-list)
* [HTTPS配置](/products/dcdn/configuration/3-dcdn-https-configuration)
* [HTTP响应头](/products/dcdn/configuration/4-dcdn-the-http-response-header-configuration)

<img src="/docs-assets/products/dcdn/%283-quick-start%29/0-dcdn-guide-to-the-console/Fi98wMxdmDLtz6D6NXYw09znaULC-8dc9e68d4e62.webp" width="600" />

<img />

<img src="/docs-assets/products/dcdn/%283-quick-start%29/0-dcdn-guide-to-the-console/FjGUcMZY39wNkELLnswAz2aIGQGV-070c1707d5f7.webp" width="600" />

<img />

<img src="/docs-assets/products/dcdn/%283-quick-start%29/0-dcdn-guide-to-the-console/FjdxfoOpbYyd3aIxryemYAUnN7I7-182d15504b92.webp" width="600" />

<img />

<img src="/docs-assets/products/dcdn/%283-quick-start%29/0-dcdn-guide-to-the-console/FmPHbPFDR239ZPtaU0gFzZnxPYf9-21cf086274ce.webp" width="600" />

<img />

<img src="/docs-assets/products/dcdn/%283-quick-start%29/0-dcdn-guide-to-the-console/FvH7JePyttkDJoQ4AopicHf3ysc6-60266fb91622.webp" width="600" />

<img />

<a id="step4" />

# 4. 配置CNAME [#4-配置cname]

(1)获取cname地址
方式1：创建加速域名成功后，七牛云会提供cname地址。
方式2：在 **域名管理** 界面选择创建好的 【域名】 ，点击 【配置】 ，提供的cname在红框中标注。

<img src="/docs-assets/products/dcdn/%283-quick-start%29/0-dcdn-guide-to-the-console/FpcFUopDNT0-BzQ1y338ajmtoTgE-35f7f230f986.webp" width="600" />

<img />

（2）配置cname，详情见文档[如何配置域名的CNAME](/faq/cdn/domain-name-configuration-problem/1322-how-to-configure-cname-domain-name)。


# 刷新预取 (/products/dcdn/0-dcdn-refresh-the-prefetch)



最近更新时间: 2026-08-28 16:39:26

刷新分为刷新文件、刷新目录两种方式，刷新文件是以文件为单位将缓存在DCDN节点上对应的资源进行清除。刷新目录是以目录为单位，将目录下的所有缓存在DCDN节点上的文件进行清除。文件预取是以文件为单位进行资源预热。

<br />

# 操作说明 [#操作说明]

登录**七牛管理控制台**后，进入**DCDN控制台**，选择【刷新预取】，进入配置界面：

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/0-dcdn-refresh-the-prefetch/Fo7XcVLKNm2E66wlD0_0MtqVpKtt-867644dd0ca3.webp" width="600" />

<img />

### 1. 文件刷新 [#1-文件刷新]

选择【文件刷新】后，在输入框中输入需要刷新的URL。提交后，您可以在页面中看到今日剩余的目录刷新量。

* 输入时，多个记录请用回车换行分隔；
* 每个 URL 应当以 `http://` 或 `https:// `开头,如 `http://www.example.com/index.html`;
* 文件刷新每天限额 500 个，单次提交文件刷新最多20个。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/0-dcdn-refresh-the-prefetch/FmSYzsqc9SmJ7R6ipRoLpw4AJyNs-30551daf4c09.webp" width="600" />

<img />

### 2. 刷新目录 [#2-刷新目录]

选择【刷新目录】后，在输入框中输入需要刷新的目录，提交后，您可以在页面中看到今日剩余的目录刷新量。

* 输入时，多个记录请用回车换行分隔；
* 目录必须以 `「/」` 结尾例如：`http://www.example.com/`；
* 目录刷新每天限额 10 个。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/0-dcdn-refresh-the-prefetch/Fl4MhnXz2JpeDafousIcSgXfoU6D-fdfeeb3df846.webp" width="600" />

<img />

### 3. 文件预取 [#3-文件预取]

选择【文件预取】后，输入框中输入需要预取的文件路径，提交后，您可以在页面中看到今日剩余的目录刷新量。

* 输入时，多个记录请用回车换行分隔；
* 每个 URL 应当以 `http://` 或 `https:// `开头，如 `http://www.example.com/index.html`
* 文件预取每天限额 100 个，单次提交文件刷新最多20个。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/0-dcdn-refresh-the-prefetch/FqNLYsIVZRJ6bge1yawft_j5mf6Y-a803056635c7.webp" width="600" />

<img />

### 4. 操作记录 [#4-操作记录]

选择【操作记录】可以查询最近14天左右提交的刷新或预取的操作记录，可以查询具体的URL，以及提交时间、操作类型、状态信息，状态信息包含：正在处理、成功、失败三种类型。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/0-dcdn-refresh-the-prefetch/Fuh1jHgBdfOhopm006GJVCp3MWUc-2dc39ad686d1.webp" width="600" />

<img />


# 日志下载 (/products/dcdn/1-dcdn-log-download)



最近更新时间: 2026-08-28 16:39:26

日志下载可以查询域名日志列表，下载所需的日志数据，。您可以登录**七牛开发者平台**选择**DCDN控制台**，进行下载。

<br />

# 操作说明 [#操作说明]

登录**七牛开发者平台**后，进入**DCDN控制台**，选择【日志下载】，进入管理页面，选择要获取日志的时间及对应的域名，点击【查看日志】，获取可下载的日志，点击【下载】即可。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/1-dcdn-log-download/FnpyH4edMvBdFRt3sj8Ga4PWCEht-6a0905af7394.webp" width="600" />

<img />

注意事项：
（1）日志默认保留时间为 30 天；
（2）日志生成大概延迟 6 小时；
（3）备选域名列表最多只展示 100 个，其余域名可通过前缀搜索；
（4）如果日志文件过大，您可以参见[API](/products/dcdn/4-dcdn-download-the-log)文档下载日志。
（5）日志大概延迟6小时，举例：1月18日0点-1点的日志，会在1月18日8点-10点左右可下载。
（6）日志文件默认按小时下载，如果单小时内日志过大会进行切分(分片大小128MB)，日志文件采用gzip压缩。

# 日志字段说明 [#日志字段说明]

<br />

将下载好的日志数据包解压，以文本方式查看日志文件，可以看到各字段信息以空格隔开。部分信息如下图所示。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/1-dcdn-log-download/FiqOIe-XJvleRwnpFlR2FNxfmusJ-e4f33863857d.webp" width="800" />

<img />

<br />

日志中对应的字段顺序及含义如下表所示：
顺序|日志内容|说明
\-|-
1|客户端IP|ClientIP
2|命中情况|Hit/Miss/UNKNOWN
3|响应时长(ms)|ResponseTime(ms)
4|请求时间|\[Time Zone]
5|请求方法|Method
6|请求URL|URL
7|请求协议|Protocol
8|状态码|StatusCode
9|响应大小(Byte)|TrafficSize(Byte)
10|referer|Referer
11|用户代理|UserAgent


# 域名归属校验 (/products/dcdn/2-domain-verify-introduce)



最近更新时间: 2026-08-28 16:39:26

每个域名仅需做一次归属权校验，子域名无需重复校验。校验方法有两种：

* DNS解析验证
* 文件验证

# DNS解析验证 [#dns解析验证]

通过配置待加速域名的txt记录的方式，通过域名校验，具体方式如下

1. 通过 [https://portal.qiniu.com/dcdn/domain/create](https://portal.qiniu.com/dcdn/domain/create) 创建域名，提交之后系统会判断该域名是否曾经校验过。若校验过则会进入域名创建结果页。若未校验过则会进入域名验证页，如下：

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/2-domain-verify-introduce/FoAUgKZHkKO-cqKzodq-gOHLwAe4-1c0bf0be8fb2.webp)

2. 在您的域名解析服务商，添加TXT记录

3. 等待TXT解析生效，返回CDN控制台，单击「点击验证」，完成验证
   若如果系统提示“验证失败”，请检查TXT记录是否正确填写，并等待DNS记录生效后重新验证

# 文件验证 [#文件验证]

通过在域名源站上传验证文件，并保证外网的可访问性，具体方式如下

1. 在域名验证页面点击「文件验证」，进入获取验证的页面，如下图：

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/2-domain-verify-introduce/FmUlnyxTSwW04JKO5A2Nta4XX1FM-b6570a1a959a.webp)
2\. 点击下载验证文件

3. 将验证文件上传到源站服务器的根目录，并确保通过域名根目录可访问
   例如：配置加速域名verify.qiniu.com，需要将文件上传到qiniu.com所在的服务器源站，并确保 [http://qiniu.com/verification.html](http://qiniu.com/verification.html) 的外网访问性，我们将根据该文件的访问结果判断是否验证通过

4. 单击「点击验证」，完成验证

以上所有功能均可通过接口完成，详见：[/products/dcdn/9-domain-verify-information](/products/dcdn/9-domain-verify-information)


# 告警服务 (/products/dcdn/3-dcdn-the-alarm-service)



最近更新时间: 2026-08-28 16:39:26

告警服务帮助用户对全站加速流量、带宽、命中率、状态码等指标进行监控，包括告警配置和告警联系人两个模块。在告警配置模块中，针对每个域名，用户可以配置各项告警的触发条件。在告警联系人模块中，用户可以设置接收人、接收人组和Webhook，当某个告警条件被触发后，相应的接收者会收到邮件和短信通知。

<br />

# 告警配置 [#告警配置]

登陆[**七牛管理控制台**](https://portal.qiniu.com/signin)，进入[**全站加速控制台**](https://portal.qiniu.com/dcdn/overview)，选择【告警配置】。

<br />

## 搜索告警规则 [#搜索告警规则]

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/3-dcdn-the-alarm-service/FqvYZtpW6AIs4vGgdiURHGuEAcOv-d4cb3b8d87b6.webp)

* 在域名告警规则界面，右上角搜索框输入规则名称或域名搜索相关告警规则。
* 支持规则名称和域名两个维度的搜索。
* 域名维度的搜索结果为关联该域名的所有告警规则。

<br />

## 新建告警规则 [#新建告警规则]

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/3-dcdn-the-alarm-service/FoO_1vouyqD-pME2SyZFQRETtJbQ-6dc103f1fefd.webp)

* 新建告警规则：在域名告警规则界面，左上角点击【新建告警规则】，可为新域名配置告警。
* 规则名称：告警规则的名称。
* 监控指标配置：用户根据业务需要配置监控指标，具体指标信息参考下表。<br />

<table>
  <tbody><tr><td align="center"><b>监控指标</b></td><td align="center"><b>选项</b></td><td align="center"><b>计量单位</b></td></tr><tr><td align="center">状态码</td><td align="center">高于/低于/环比波动/环比上升/环比下降</td><td align="center">百分比</td></tr><tr><td align="center">流量命中率</td><td align="center">高于/低于/环比波动/环比上升/环比下降</td><td align="center">百分比</td></tr><tr><td align="center">请求命中率</td><td align="center">高于/低于//环比波动/环比上升/环比下降</td><td align="center">百分比</td></tr><tr><td rowspan="2" align="center">带宽</td><td align="center">高于/低于</td><td align="center">Mbps</td></tr><tr><td align="center">环比波动/环比上升/环比下降</td><td align="center">百分比</td></tr><tr><td rowspan="2" align="center">流量</td><td align="center">高于/低于</td><td align="center">GB</td></tr><tr><td align="center">环比波动/环比上升/环比下降</td><td align="center">百分比</td></tr></tbody>
</table>

说明：
（1）每条告警规则可配置的监控指标数量不超过 10 条，如有需要配置超过 10 条的，请[**提交工单**](https://support.qiniu.com/tickets/new/form?category=%E9%85%8D%E7%BD%AE%E9%97%AE%E9%A2%98\&space=CDN)申请开通高级告警服务；
（2）可以通过配置监控指标持续数据点的数量，避免因为业务抖动导致的频繁的无效的告警；“持续1个数据点”即第一个达到告警阈值的5分钟数据点则告警，“持续2个数据点”即连续2个5分钟数据点都达到告警阈值才告警，“持续3/4/5个数据点”以此类推；
（3）多项监控指标之间支持【且】或【或】两种关系；多项监控指标关系为【且】时，只有所有监控指标都达到告警阈值才会触发告警；多项监控指标关系为【或】时，任何一项监控指标达到告警阈值就会触发告警。

* 监控接收人：用户可以选择接收人、接收人组或Webhook；若没有目标接收人，可点击【新建接收人】，创建好目标接收人后，点击【新建接收人】旁边的刷新按钮，即可以选择目标接收人。
* 监控域名：非必选项，可以先创建告警规则，再添加监控域名；选择监控域名，支持模糊搜索。

<br />

## 修改告警规则 [#修改告警规则]

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/3-dcdn-the-alarm-service/FrjdDmSg_3OQY4fnECVSMpZ-k9-u-aa727bdfa2ef.webp)

* 在域名告警规则界面，查找到目标告警规则，在操作列点击【编辑】，告警规则参数的修改同【新建告警规则】。
* 修改规则名称会自动创建一条新的告警规则，原告警规则不变。
* 修改告警规则，告警规则会自动变为启用状态。

<br />

## 启停告警规则 [#启停告警规则]

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/3-dcdn-the-alarm-service/Fi4PSljRwJqUDQqm6Baf2G2P75eM-4e58c16c9914.webp)

* 在域名告警规则界面，查找到目标告警规则，在告警启停列点击对应按钮，实现告警规则的启用或停用。

<br />

## 删除告警规则 [#删除告警规则]

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/3-dcdn-the-alarm-service/FpTNTwxO0prjU6plrXLS9q-Lx-Hd-40e3171dcaec.webp)

* 在域名告警规则界面，查找到目标告警规则，在告警启停列点击【删除】；勾选多条目标告警规则，点击告警列表右上角的【批量删除】。
* 删除告警规则需要先解绑关联的所有域名，否则无法删除。

<br />

## 查看告警规则 [#查看告警规则]

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/3-dcdn-the-alarm-service/FqTdhdGAwLRVw2yLMfbXnbrSmZ1N-b7f9a0c505ee.webp)

* 在域名告警规则界面，查找到目标告警规则，在操作列点击【查看】。

# 告警联系人 [#告警联系人]

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/3-dcdn-the-alarm-service/Fij04j6nIRv2aBCGcujn51bhUAYJ-a727a57fc8fe.webp)
您可以前往[**消息中心**](https://portal.qiniu.com/notification/recipient/user)进行设置，也可以通过上方导航栏的【消息】按钮进入消息中心进行设置。


# 服务保障协议(SLA) (/products/dcdn/0-dcdn-service-agreement-sla)



最近更新时间: 2026-08-31 11:35:14

# 1. 服务内容 [#1-服务内容]

七牛云全站加速服务 （Dynamic Route for Content Delivery Network，简称"DCDN"） 在 CDN 基础上融合动态加速的能力，静态资源自动分发缓存至七牛云服务节点，动态资源选择最优路径回源，从而缩短用户查看对象的延迟，提高用户访问网站的响应速度与网站的可用性，解决网络带宽小、用户访问量大、网点分布不均等问题。

# 2. 定义 [#2-定义]

* 服务：指七牛云 CDN 根据本协议向开发者提供的付费服务（未付费情况，不适用本协议）。
* 动态资源：指用户使用七牛云 DCDN 服务的域名下所有文件后缀为.asp、.jsp、.php、.cgi 、.perl 、API 接口等动态文件。
* 静态资源：指网页/图片/下载内容/点播流媒体内容等文件。
* 服务周期：以一个自然月做为一个服务周期，如果不满一个月则按一个月计算。
* 服务区域：中国大陆地区。
* 服务周期总分钟数：按照每月每周 7（七）天每天 24（二十四）小时计算。
* 失败请求：因 DCDN 系统原因导致的域名返回的 5XX 请求和因为 DCDN 服务故障导致用户正常请求未能到达 DCDN 服务器端的请求视为失败请求。因 DCDN 服务故障导致的用户正常请求未能到达 DCDN 服务器端的失败请求，将通过故障前 7 天内用户域名的平均请求数计算。
* 有效请求：客户在七牛云服务账号下所有 DCDN 的域名加速服务，在 DCDN 服务器收到的请求视为有效请求。
* 每 5 分钟错误率：每 5 分钟错误率=（每 5 分钟失败请求数/每 5 分钟有效请求总数）\* 100 %
* 不可用时间：DCDN 在连续的 10 分钟或更长时间出现每 5 分钟错误率大于 0.05 % 的情况，方计为不可用时间。
* 月度服务费用：客户在一个自然月中在七牛云账号下 DCDN 产品服务费用总额。

# 3. 指标项 [#3-指标项]

## 3.1 服务可用性 [#31-服务可用性]

* 七牛云 DCDN 保证用户购买的服务的“服务可用性”达到 99.9 %，即每月服务不可用时间累计小于 44 分钟。
  服务可用性计算公式：域名服务周期内正常服务时间 / 域名服务周期内可服务总时间。
* 服务可用性按服务周期统计，一个服务周期为一个自然月，如不满一个月不计算为一个服务周期。
* 统计对象为某一七牛云账户下的所有开启 DCDN 服务的域名（月请求量小于 100 万的域名除外）。
* 七牛云 DCDN 服务的不可用时间不包括日常系统维护时间、由用户原因、第三方原因或不可抗力导致的不可用时间。

## 3.2 私密性 [#32-私密性]

用户在七牛云 DCDN 服务创建的加速域名等资源，在未经用户合法授权的情况下，其他用户无法对其配置进行更改。七牛云为用户分配最多 2 对 Access Key ID/Secret Access Key 密钥对，从七牛云服务访问接口上进行权限控制和隔离，保障用户数据的私密性。

## 3.3 可审查性 [#33-可审查性]

依据现行法律法规或根据政府监管部门监管、安全合规、审计或取证调查等原因的需要，在符合流程和手续完备的情况下，七牛云可以提供用户所使用的服务的相关信息。

## 3.4 服务资源调配能力 [#34-服务资源调配能力]

七牛云 DCDN 为用户提供内容分发与加速服务，并支持安全防护能力，保障用户源站安全。七牛云 DCDN 服务采用弹性扩容机制，可根据业务访问情况自动扩展带宽及存储资源，一般情况下无需用户进行容量配置。为保障资源准备及服务稳定性，如客户预计业务流量将出现大规模增长（预计峰值带宽较上月计费带宽增长超过30%，或预计新增带宽超过50Gbps，两者满足任一条件），应至少提前3个工作日通知七牛云服务团队；国家法定节假日、大型促销活动、重大赛事等重大业务场景（包括但不限于春晚、国庆、双十一、世界杯等），应至少提前1个月通知。

如客户未按上述要求提前通知，七牛云将在现有资源条件下提供服务，并可支持不超过上月计费带宽30%（含）的临时增长。对于超过该增长范围的业务流量，七牛云不保证能够及时完成资源扩容，因此产生的服务能力下降或可用性影响，不属于本 SLA 承担范围。

## 3.5 故障恢复能力及客服保证 [#35-故障恢复能力及客服保证]

七牛云 DCDN 为用户提供全天候的运行维护，并以在线自助工单系统、客服电话报障等方式提供技术支持。七牛云具备完善的故障监控、自动告警、快速定位、快速恢复等一系列故障应急响应机制。

客服咨询电话：400-101-8589；服务时间：7\*24 小时。

## 3.6 网络接入性能 [#36-网络接入性能]

七牛云 DCDN 对用户不限制公网出口带宽，七牛云在全国部署数百个缓存节点，保障用户的网络接入质量。

## 3.7 服务计量准确性 [#37-服务计量准确性]

七牛云 DCDN 服务具备准确、透明的计量计费系统。七牛云 DCDN 根据用户的实际使用量据实结算，价格及计费模式见七牛云官网。

# 4. 服务赔偿条款 [#4-服务赔偿条款]

## 4.1 赔偿范围 [#41-赔偿范围]

因七牛云设备故障、设计缺陷或操作不当导致用户所购买的 DCDN 服务无法正常使用，七牛云将对不可用时间进行赔偿，但不包括以下原因所导致的服务不可用时间：

* 七牛云预先通知用户后进行系统维护所引起的，包括割接、维修、升级和模拟故障演练；
* 任何七牛云所属设备以外的网络、设备故障或配置调整引起的；
* 用户的应用程序或数据信息受到黑客攻击而引起的；
* 用户维护不当或保密不当致使数据、口令、密码等丢失或泄漏所引起的；
* 用户自行升级操作系统所引起的；
* 用户的应用程序或安装活动所引起的；
* 用户的疏忽或由用户授权的操作所引起的；
* 不可抗力以及意外事件引起的；
* 其他非七牛云原因所造成的不可用。

## 4.2 赔偿方案 [#42-赔偿方案]

七牛云对用户存在故障的每个域名按不可用时间进行 10 倍赔偿，赔付金额 = 发生故障的域名故障前 24 小时平均每分钟费用 × 故障不可用时间 × 10 倍。

* 赔偿只针对使用 DCDN 服务已产生费用的用户，以代金券的形式赔偿，不折算现金返还。
* 故障不可用时间 = 故障解决时间 - 故障开始时间，不可用时间按分钟计算。
* 如果用户没有使用到 24 小时，按实际使用时长计算平均每分钟费用。
* 赔付金额不超过客户对该故障域名所消费的费用平均值（故障当月前12个月费用折算平均值）或故障当月客户消费的月度服务费用的25%（服务不满12个月，不包含本月）。

## 4.3 赔偿申请时限 [#43-赔偿申请时限]

客户可在每月第五个工作日之后对上个自然月没有达到可用性的情况提出赔偿申请。赔偿申请必须限于在DCDN服务没有达到可用性的相关月份结束后两个月内提出；超出申请时限的赔偿申请将不被受理。

# 5. 免责声明 [#5-免责声明]

详见[《七牛云服务用户协议》](https://www.qiniu.com/user-agreement)中的"免责声明"相关条款内容。

# 6. 其他 [#6-其他]

* 本协议一经公布立即生效，七牛云有权随时对协议内容进行修改。如用户不同意七牛云对本协议相关内容所做的修改，用户有权停止使用七牛云 DCDN 服务。若用户继续使用七牛云 DCDN 服务，则视为用户接受七牛云对本协议相关内容所做的修改。
* 本协议项下七牛云 DCDN 服务对于用户所有的通知均可通过网页公告、站内信、电子邮件、手机短信或其他形式等方式进行；该通知于发送之日视为已送达收件人。
* 本协议的订立、执行和解释及争议的解决均应适用中国法律并受中国法院管辖。如双方就本协议内容或其执行发生任何争议，双方应尽量友好协商解决；协商不成时，任何一方均可向上海市浦东新区人民法院提起诉讼。
* 本协议构成双方对本协议之约定事项及其他有关事宜的完整协议，除本协议规定的之外，未赋予本协议各方其他权利。
* 如本协议中的任何协议无论因何种原因完全或部分无效或不具有执行力，本协议的其余协议仍应有效并且有约束力。


# 接入方式 (/products/dcdn/0-dcdn-access)



最近更新时间: 2022-04-18 14:37:53

# 对外域名 [#对外域名]

Host: `api.qiniu.com`

# 授权 [#授权]

Authorization: `QBox <AccessToken>`

详细描述见[文档](/products/dcdn/0-dcdn-access#accesstoken)。

# API 请求格式 [#api-请求格式]

* RESTful api, 具体格式参考每个API定义
* `POST方法，需要带请求头 Content-Type:application/json，请留意`

# API 响应格式 [#api-响应格式]

* 响应成功的格式

```
HTTP/1.1 200 OK
{
    // 如果API下面包含有body的响应，会列出body的结构，否则说明响应不包含body
}

```

* 响应错误的格式

```
HTTP/1.1 4xx/5xx
{
	"code":<Code>, // 错误码在每个API下面都有列出, code为6位数字码，前三位与http code一致
	"error":<ErrorMessage>
}

```


# 证书相关 (/products/dcdn/1-dcdn-certificate-of-relevant)



最近更新时间: 2024-07-01 15:33:42

# 上传证书 [#上传证书]

```
用户上传证书的接口, 注意我们不会自动补全证书链，需要用户自己补全

```

## 请求包 [#请求包]

```
POST /sslcert
Content-Type: application/json
Authorization: QBox <AccessToken>

{
		"name": <Name>,
		"common_name": <CommonName>,
		"pri": <Pri>,
		"ca": <Ca>
}

```

### 参数解释 [#参数解释]

| 参数         | 类型     | 含义   |
| ---------- | ------ | ---- |
| Name       | string | 证书名称 |
| CommonName | string | 通用名称 |
| Pri        | string | 证书私钥 |
| Ca         | string | 证书内容 |

## 返回包 [#返回包]

```
	{
		"certID": <CertID>

	}

```

### 参数解释 [#参数解释-1]

| 参数     | 类型     | 含义   |
| ------ | ------ | ---- |
| CertID | string | 证书ID |

**错误码**

| 错误码    | 含义           |
| ------ | ------------ |
| 400500 | 超过用户绑定证书最大额度 |
| 404906 | https证书解码失败  |
| 400323 | 验证https证书链失败 |
| 400322 | https证书有效期太短 |
| 400329 | https证书过期    |

# 删除证书 [#删除证书]

```
用户删除证书的接口

```

## 请求包 [#请求包-1]

```
DELETE /sslcert/<CertID>
Content-Type: application/json
Authorization: QBox <AccessToken>

```

### 参数解释 [#参数解释-2]

| 参数     | 类型     | 含义   |
| ------ | ------ | ---- |
| CertID | string | 证书ID |

## 返回包 [#返回包-1]

```
{}

```

**错误码**

| 错误码    | 含义         |
| ------ | ---------- |
| 400401 | 无此证书       |
| 404908 | 无权操作该证书    |
| 400611 | 证书已绑定CDN域名 |
| 400911 | 证书已绑定存储域名  |

# 获取证书 [#获取证书]

```
用户获取单个证书的接口

```

## 请求包 [#请求包-2]

```
GET /sslcert/<CertID>
Content-Type: application/x-www-form-urlencoded
Authorization: QBox <QBoxToken>

```

### 参数解释 [#参数解释-3]

| 参数     | 类型     | 含义   |
| ------ | ------ | ---- |
| CertID | string | 证书ID |

## 返回包 [#返回包-2]

```
{
	"name": <Name>,
        "common_name": <CommonName>,
        "dnsnames": <DNSNames>,
        "not_before": <NotBefore>,
         "not_after": <NotAfter>,
	"pri": <Pri>,
	"ca": <Ca>,
        "create_time": <CreateTime>
}

```

### 参数解释 [#参数解释-4]

| 参数         | 类型        | 含义    |
| ---------- | --------- | ----- |
| Name       | string    | 证书名称  |
| CommonName | string    | 通用名称  |
| DNSNames   | \[]string | DNS域名 |
| NotBefore  | int       | 生效时间  |
| NotAfter   | int       | 过期时间  |
| Pri        | string    | 证书私钥  |
| Ca         | string    | 证书内容  |
| CreateTime | int       | 创建时间  |

**错误码**

| 错误码    | 含义      |
| ------ | ------- |
| 400401 | 无此证书    |
| 404908 | 无权操作该证书 |

# 获取证书列表 [#获取证书列表]

```
用户获取证书列表的接口

```

## 请求包 [#请求包-3]

```
GET /sslcert?product=<Product>&marker=<Marker>&limit=<Limit>
Content-Type: application/x-www-form-urlencoded
Authorization: QBox <QBoxToken>

```

### 参数解释 [#参数解释-5]

| 参数      | 类型     | 含义                           |
| ------- | ------ | ---------------------------- |
| Product | string | 全站加速证书列表固定传参"dcdn"           |
| Marker  | string | 用于标示从哪个位置开始获取证书列表。不填或空表示从头开始 |
| Limit   | int    | 返回的最大证书个数。默认 100             |

## 返回包 [#返回包-3]

```
{
	marker: <Marker>,
	"certs":[{
            "certid": <CertID>,
            "name": <Name>,
            "common_name": <CommonName>,
            "dnsnames": <DNSNames>,
            "not_before": <NotBefore>,
             "not_after": <NotAfter>,
            "create_time": <CreateTime>
        }]
}

```

### 参数解释 [#参数解释-6]

| 参数         | 类型        | 含义                   |
| ---------- | --------- | -------------------- |
| Marker     | string    | 用于标示下一次从哪个位置开始获取证书列表 |
| CertID     | string    | 证书ID                 |
| Name       | string    | 证书名称                 |
| CommonName | string    | 通用名称                 |
| DNSNames   | \[]string | DNS域名                |
| NotBefore  | int       | 生效时间                 |
| NotAfter   | int       | 过期时间                 |
| CreateTime | int       | 创建时间                 |

**错误码**

| 错误码    | 含义      |
| ------ | ------- |
| 404908 | 无权操作该证书 |


# 域名管理 (/products/dcdn/2-dcdn-domain-name-related)



最近更新时间: 2026-09-03 11:18:42

# 创建域名 [#创建域名]

```
用户创建全站加速普通及泛域名接口
```

## 请求包 [#请求包]

```
POST /domain/<Name> HTTP/1.1
Content-Type: application/json
Authorization: QBox <AccessToken>
{
	// 基本配置
	"type": <Type>,
	"platform": <Platform>,
	"geoCover": <GeoCover>,
	"protocol": <Protocol>,
        "ipTypes": <IpTypes>,
	// 回源配置
	"source": <Source>,
	// 缓存配置
	"cache": <Cache>,
	// 备案号
	"registerNo": <RegisterNo>
}
```

### 参数解释 [#参数解释]

**基本参数**

| 参数         | 类型                                           | 必填                      | 含义                                                                                          |
| ---------- | -------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
| Name       | string                                       | 是                       | 域名, 如果是泛域名，必须以点号 . 开头                                                                       |
| Type       | string                                       | 是                       | 域名类型: `normal`(普通域名)/`wildcard`(泛域名)                                                        |
| Platform   | string                                       | 是                       | 平台类型: 固定值 `dynamic`(动态加速)                                                                   |
| GeoCover   | string                                       | 是                       | 地域: `china`/`foreign`/`global`                                                              |
| Protocol   | string                                       | 是                       | 协议: `http`/`https`                                                                          |
| Source     | 请参考 [回源配置](/products/dcdn/3-dcdn-function#2) | 是                       | 回源参数                                                                                        |
| Cache      | 请参考 [缓存策略](/products/dcdn/3-dcdn-function#5) | 备注：平台是动态加速是“否”，其他平台为“是” | 缓存参数                                                                                        |
| RegisterNo | string                                       | 否                       | 当创建域名返回`code: 500230` 或者返回的内容提示为`备案查询服务已关闭`，需要API调用者在本参数输入域名的备案号                            |
| IpTypes    | uint                                         | 否                       | IP协议：仅允许ipv4访问，取值为1；同时允许ipv4/ipv6访问，取值为3。不指定IPTypes时，国内/全球域名默认为允许ipv4/ipv6访问，海外域名仅允许ipv4访问。 |

**错误码**

| 错误码    | 含义                     |
| ------ | ---------------------- |
| 400001 | 非法域名                   |
| 400005 | 未知的协议                  |
| 400020 | 域名未备案                  |
| 400040 | 非法的回源域名                |
| 400044 | 非法的回源host              |
| 400041 | 未知的回源ip                |
| 400008 | 无此bucket               |
| 400345 | 共享bucket不能绑定域名         |
| 400043 | 未知的高级回源参数              |
| 400022 | 未知的测试url               |
| 400002 | 未知的回源类型                |
| 400093 | 非法的域名类型                |
| 400060 | 未知的referer防盗链类型        |
| 400061 | 未知的referer防盗链参数        |
| 400091 | 缓存参数有误                 |
| 400309 | 缓存规则未设置全局或者为遵循源站       |
| 400204 | 时间戳防盗链key值数目不够         |
| 400031 | 非法的url                 |
| 400203 | 已禁用的用户                 |
| 400541 | 获取用户信息失败               |
| 401000 | 未实名认证的用户               |
| 400801 | 未知的vendor              |
| 400003 | 未知的平台类型                |
| 400004 | 未知覆盖                   |
| 404911 | 非法的路径                  |
| 404912 | 非法的正则表达式               |
| 400520 | 不能同时设置时间戳防盗链和回源鉴权      |
| 400200 | 未知的bucket              |
| 400521 | 非法的回源鉴权地址              |
| 400522 | 非法的回源鉴权http方法          |
| 400523 | 非法的回源鉴权http code       |
| 400524 | 非法的回源鉴权超时时间            |
| 400525 | 非法的回源鉴权url参数           |
| 400401 | 无此证书                   |
| 400324 | https证书解码失败            |
| 400325 | https证书解析失败            |
| 400321 | https证书还未生效            |
| 400329 | https证书过期              |
| 400326 | https证书与域名不匹配          |
| 400327 | 解析https证书密钥失败          |
| 400328 | https证书与密钥不匹配          |
| 400323 | 验证https证书链失败           |
| 400549 | 只有https域名才能使用强制https跳转 |
| 400621 | 泛域名及其子域名不能使用私有bucket   |
| 400005 | 未知的协议                  |
| 400332 | 未知的回源协议                |
| 400932 | 域名所有权验证失败              |
| 500219 | 查询证书内部错误               |
| 500005 | 数据查询内部出错               |
| 500230 | 备案查询服务已关闭              |
| 500000 | 未知内部错误                 |

## 请求示例 [#请求示例]

```
POST /domain/testqiniu.qbox.net HTTP/1.1
Authorization: QBox 0tf5awMVxwf8WrEvrjtbiZrdRZRJU-91JgCqTOC8:6oxDOtOXVEfcR8PPuAscmWjVRS8=
Content-Type: application/json
Host: api.qiniu.com
{
  "protocol": "http",
  "platform": "web",
  "geocover": "china",
  "type": "normal",
  "ipTypes": 3,
  "source": {
    "sourceType": "bucket",
    "sourceQiniuBucket": "test",
    "testURLPath": "qiniu_do_not_delete.gif"
  },
  "cache": {
    "cacheControls": [
      {
        "time": 0,
        "timeunit": 0,
        "type": "suffix",
        "rule": ".m3u8;.js"
      },
      {
        "time": 1,
        "timeunit": 5,
        "type": "all",
        "rule": "*"
      }
    ],
    "ignoreParam": true
  }
```

# 上线域名 [#上线域名]

```
用户上线普通及泛域名接口
```

## 请求包 [#请求包-1]

```
POST /domain/<Name>/online
Content-Type: application/json
Authorization: QBox <AccessToken>
```

**错误码**

| 错误码    | 含义           |
| ------ | ------------ |
| 404001 | 无此域名         |
| 400001 | 未知的域名        |
| 400064 | 无权处理该域名      |
| 400093 | 非法的域名类型      |
| 400013 | 重复操作         |
| 400030 | 正在处理中        |
| 400066 | 域名状态为失败      |
| 400018 | 非法的cname     |
| 400397 | cname和其他域名冲突 |
| 500004 | 更新数据内部出错     |
| 500923 | 域名已冻结        |
| 500005 | 数据查询内部出错     |
| 500235 | 该域名未绑定证书     |

# 下线域名 [#下线域名]

```
用户下线普通及泛域名接口
```

## 请求包 [#请求包-2]

```
POST /domain/<Name>/offline
Content-Type: application/json
Authorization: QBox <AccessToken>
```

**错误码**

| 错误码    | 含义           |
| ------ | ------------ |
| 404001 | 无此域名         |
| 400001 | 未知的域名        |
| 400064 | 无权处理该域名      |
| 400093 | 非法的域名类型      |
| 400013 | 重复操作         |
| 400030 | 正在处理中        |
| 400066 | 域名状态为失败      |
| 400018 | 非法的cname     |
| 400397 | cname和其他域名冲突 |
| 400923 | 域名已冻结        |
| 500005 | 数据查询内部出错     |

# 删除域名 [#删除域名]

```
用户删除普通及泛域名接口
```

## 请求包 [#请求包-3]

```
DELETE /domain/<Name>
Content-Type: application/json
Authorization: QBox <AccessToken>
```

**错误码**

| 错误码    | 含义            |
| ------ | ------------- |
| 404001 | 无此域名          |
| 400001 | 未知的域名         |
| 400064 | 无权处理该域名       |
| 400013 | 重复操作          |
| 400030 | 正在处理中         |
| 400317 | 非已下线的域名       |
| 400066 | 域名状态为失败       |
| 400515 | 该泛域名还含有活跃的子域名 |
| 500005 | 数据查询内部出错      |

# 获取域名信息 [#获取域名信息]

```
用户获取域名信息接口，所有域名适用
```

## 请求包 [#请求包-4]

```
GET /domain/<Name>
Content-Type: application/x-www-form-urlencoded
Authorization: QBox <AccessToken>
```

## 返回包 [#返回包]

```
{
	"name": <Name>,
	"type": <Type>,
	"cname": <CName>,
	"testURLPath": <TestURLPath>,
	"platform": <Platform>,
	"geoCover": <GeoCover>,
	"protocol": <Protocol>,
        "ipTypes": <IpTypes>,
        "tagList": <TagList>,
        "kvTagList": <KvTagList>
	"source": <Source>,
	"cache": <Cache>,
	"referer": <Referer>,
	"ipACL": <IPACL>,
	"operationType": <OperationType>,
	"operatingState": <OperatingState>,
	"operatingStateDesc": <OperatingStateDesc>,
	"createAt": <CreateAt>,
	"modifyAt": <ModifyAt>,
	"pareDomain": <PareDomain>,
	"https": <Https>,
}
```

### 参数解释 [#参数解释-1]

基本参数 [请参考](#basic)

| 参数                 | 类型        | 含义                                                                                                                                                                                                                                                                  |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CName              | string    | 创建域名成功后七牛生成的域名，用户需要把 `Name` cname 到这个域名                                                                                                                                                                                                                             |
| Referer            | object    | Referer结构请参考 [referer防盗链](/products/dcdn/2-dcdn-domain-name-related#3)                                                                                                                                                                                              |
| IPACL              | object    | IPACL结构请参考 [ip黑白名单](/products/dcdn/2-dcdn-domain-name-related#4)                                                                                                                                                                                                    |
| Source             | object    | Source结构请参考 [回源配置](/products/dcdn/2-dcdn-domain-name-related#2)                                                                                                                                                                                                     |
| Cache              | object    | Cache结构请参考 [缓存策略](/products/dcdn/2-dcdn-domain-name-related#1)                                                                                                                                                                                                      |
| OperationType      | string    | 域名最近一次操作类型: `create_domain`/`offline_domain`/`online_domain`/ `modify_source`/`modify_referer`/`modify_cache`/ `freeze_domain`/`unfreeze_domain`/`modify_timeacl`(修改时间戳防盗链)/ `modify_https_crt`/`sslize`(升级HTTPS)/`modify_bsauth`(修改回源鉴权) /`offline_bsauth`(删除回源鉴权) |
| OperatingState     | string    | 域名最近一次的操作状态: `processing`/`success`/`failed`/`frozen`/`offlined`                                                                                                                                                                                                    |
| OperatingStateDesc | string    | 域名最近一次的操作状态的描述                                                                                                                                                                                                                                                      |
| CreateAt           | string    | 域名创建时间，格式:RFC3339                                                                                                                                                                                                                                                   |
| ModifyAt           | string    | 域名最后一次修改时间，格式:RFC3339                                                                                                                                                                                                                                               |
| PareDomain         | string    | 父域名,属于泛子域名字段                                                                                                                                                                                                                                                        |
| Https              | Object    | Https结构请参考 [HTTPS](/products/dcdn/2-dcdn-domain-name-related#7)                                                                                                                                                                                                     |
| IpTypes            | uint      | IP协议：仅允许ipv4访问，取值为1；同时允许ipv4/ipv6访问，取值为3。                                                                                                                                                                                                                           |
| TagList            | \[]string | 域名的标签列表（废弃）                                                                                                                                                                                                                                                         |
| kvTagList          | \[]Object | 域名的Key-Value标签列表                                                                                                                                                                                                                                                    |

**错误码**

| 错误码    | 含义       |
| ------ | -------- |
| 404001 | 无此域名     |
| 400001 | 未知的域名    |
| 400014 | 无权获取该域名  |
| 500005 | 数据查询内部出错 |

# 获取域名列表 [#获取域名列表]

```
用户获取域名列表接口，所有域名适用
```

## 请求包 [#请求包-5]

```
GET /domain?product=<Product>&types=<Types>&certId=<CertId>&sourceTypes=<SourceTypes>&sourceQiniuBucket=<SourceQiniuBucket>&sourceIp=<SourceIp>&marker=<Marker>&limit=<Limit>
Content-Type: application/x-www-form-urlencoded
Authorization: QBox <AccessToken>
```

### 参数解释 [#参数解释-2]

| 参数                | 类型        | 含义                                                                                                                                                                                                                                                                                                                                                             |
| ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Product           | string    | 全站加速固定传参 "dcdn"。                                                                                                                                                                                                                                                                                                                                               |
| Types             | \[]string | 域名类型，可选normal（普通域名）、wildcard（泛域名）、pan（泛子域名）、test（测试域名）中的一个或多个，不填默认查询全部域名。                                                                                                                                                                                                                                                                                      |
| CertId            | string    | 证书ID，不填默认查询全部域名。                                                                                                                                                                                                                                                                                                                                               |
| SourceTypes       | \[]string | 回源类型，可选domain、ip、qiniuBucket、advanced中的一个或多个，不填默认查询全部域名；如果指定了SourceQiniuBucket参数，SourceTypes只能指定为qiniuBucket一种回源类型，否则SourceQiniuBucket参数将不生效；如果指定了SourceIp参数，SourceTypes只能指定为ip一种回源类型，否则SourceIp参数将不生效；同时获取多种回源类型域名的请求url示例：[http://api.qiniu.com/domain?sourceTypes=domain\&sourceTypes=ip。](http://api.qiniu.com/domain?sourceTypes=domain\&sourceTypes=ip。) |
| SourceQiniuBucket | string    | 七牛存储空间名称，不填默认查询全部域名。请求url示例：[http://api.qiniu.com/domain?sourceTypes=qiniuBucket\&sourceQiniuBucket=test。](http://api.qiniu.com/domain?sourceTypes=qiniuBucket\&sourceQiniuBucket=test。)                                                                                                                                                                       |
| SourceIp          | string    | 回源IP, 不填默认查询全部域名。请求url示例：[http://api.qiniu.com/domain?sourceTypes=ip\&sourceIp=1.1.1.1。](http://api.qiniu.com/domain?sourceTypes=ip\&sourceIp=1.1.1.1。)                                                                                                                                                                                                        |
| Marker            | string    | 用于标示从哪个位置开始获取域名列表，不填或空表示从头开始。                                                                                                                                                                                                                                                                                                                                  |
| Limit             | int       | 返回的最大域名个数。1\~1000, 不填默认为 10                                                                                                                                                                                                                                                                                                                                  |

## 返回包 [#返回包-1]

```
{
	"marker": <Marker>,
	"domains": [
		{
			"name": <Name>,
			"type": <Type>,
			"cname": <CName>,
			"testURLPath": <TestURLPath>,
			"platform": <Platform>,
			"geoCover": <GeoCover>,
			"protocol": <Protocol>,
			"operatingState": <OperatingState>,
			"operatingStateDesc": <OperatingStateDesc>,
			"createAt": <CreateAt>,
			"modifyAt": <ModifyAt>,
		},
		...
	]
}
```

### 参数解释 [#参数解释-3]

基本参数 [请参考](#basic)

| 参数             | 类型        | 含义                                                               |
| -------------- | --------- | ---------------------------------------------------------------- |
| Marker         | string    | 用于标示下一次从哪个位置开始获取域名列表                                             |
| CName          | string    | 创建域名成功后七牛生成的域名，用户需要把 `Name` cname 到这个域名                          |
| TestURLPath    | string    | 域名的测试资源，需要保证这个资源是可访问的                                            |
| IpTypes        | uint      | IP协议：仅允许ipv4访问，取值为1；同时允许ipv4/ipv6访问，取值为3。                        |
| TagList        | \[]string | 域名的标签列表 （废弃）                                                     |
| KvTagList      | \[]Object | 域名的Key-Value标签列表                                                 |
| OperatingState | string    | 域名最近一次的操作状态: `processing`/`success`/`failed`/`frozen`/`offlined` |
| CreateAt       | string    | 域名创建时间，格式:RFC3339                                                |
| ModifyAt       | string    | 域名最后一次修改时间，格式:RFC3339                                            |

**错误码**

| 错误码    | 含义          |
| ------ | ----------- |
| 400021 | 非法的参数marker |
| 500005 | 数据查询内部出错    |


# 域名配置 (/products/dcdn/3-dcdn-function)



最近更新时间: 2026-09-03 10:25:26

# 修改加速区域 [#修改加速区域]

```
用户修改全站加速普通域名及泛域名区域覆盖接口
```

## 请求包 [#请求包]

```
PUT /domain/<Name>/geocover
Content-Type: application/json
Authorization: QBox <AccessToken>
{
    "geoCover": <GeoCover>
}
```

### 参数解释 [#参数解释]

| 参数       | 类型     | 必填 | 含义                                   |
| -------- | ------ | -- | ------------------------------------ |
| Name     | string | 是  | 域名                                   |
| GeoCover | string | 是  | 地域: china/foreign/global（中国大陆/海外/全球） |

**错误码**

| 错误码    | 含义                  |
| ------ | ------------------- |
| 400001 | 非法域名                |
| 400004 | 未知覆盖                |
| 400108 | 覆盖冲突                |
| 400020 | 域名未备案               |
| 400030 | 正在处理中               |
| 400064 | 无权处理该域名             |
| 400066 | 域名状态为失败             |
| 400078 | 未备案的海外域名，对七牛资源的使用错误 |
| 400093 | 非法的域名类型             |
| 400313 | 域名有手动配置的时间戳防盗链      |
| 400923 | 域名已冻结               |
| 400998 | 域名已下线               |
| 404001 | 无此域名                |
| 500000 | 未知内部错误              |
| 500005 | 数据查询内部出错            |
| 500930 | 不能操作已删除的域名          |

# 修改源站 [#修改源站]

## 结构 [#结构]

```
PUT /domain/<Name>/source
Content-Type: application/json
Authorization: QBox <AccessToken>
	{
        sourceType: <SourceType>,
          sourceHost: <SourceHost>,
        sourceIPs: [<SourceIP>, ...],
        sourceDomain: <SourceDomain>,
        sourceQiniuBucket: <SourceQiniuBucket>,
        sourceURLScheme: <SourceURLScheme>,
        advancedSources: [
            {
                addr: <ASAddr>,
                weight: <ASWeight>,
                backup: <ASBackup>
            }
        ],
        testURLPath: <TestURLPath>
	}
```

| 参数              | 类型     | 必填 | 含义                                                                                                  |
| --------------- | ------ | -- | --------------------------------------------------------------------------------------------------- |
| SourceType      | string | 是  | 源站类型: `domain`(域名)/`ip`(ip地址)/`advanced`(高级)                                                        |
| SourceHost      | string | 否  | 回源Host, 普通域名默认`SourceHost`为域名本身，泛域名默认`SourceHost`为用户请求时的域名                                          |
| SourceIP        | string | 否  | 回源ip, sourceType为ip时sourceIPs`必填`                                                                   |
| SourceDomain    | string | 否  | 回源域名, sourceType为domain时此字段`必填`                                                                     |
| SourceURLScheme | string | 否  | 回源协议, 可选值: `http`/`https`, 回源七牛bucket时本值无效,默认不填是follow请求协议                                          |
| ASAddr          | string | 否  | 高级回源的回源地址, 可以是IP或者域名；如需指定端口，可直接拼接在地址后面(示例: 1.1.1.1:8080), sourceType为advanced时advancedSources字段`必填` |
| ASWeight        | int    | 否  | 高级回源的回源addr权重, 0 \~ 100, 按照权重比例回源，sourceType为advanced时advancedSources字段`必填`                         |
| ASBackup        | bool   | 否  | 高级回源的回源addr是否为备源地址，sourceType为advanced时advancedSources字段`必填`                                        |
| TestURLPath     | string | 是  | 用于测试的URL Path, 检测源站是否可访问, 大小建议`小于1KB`，采用静态资源，并请`不要删除`, 后面域名任何配置更改都会测试该资源, 用以保证域名的访问性                |

## 注意 [#注意]

* 高级回源模式中如配置了主备回源域名时，只有所有的主源都访问不了，才会访问备源
* 高级回源模式中如设置了源站权重，请求概率=权重/权重总和，eg：有两个主线路A和B，A权重1 和 B权重3，那么四次请求，1次是A，3次是B

# 修改Range回源 [#修改range回源]

```
用户修改普通域名及泛域名Range回源接口
```

## 请求包 [#请求包-1]

```
PUT /domain/<Name>/range
Content-Type: application/json
Authorization: QBox <AccessToken>
{
	"enable": <Enable>
}
```

### 参数解释 [#参数解释-1]

| 参数     | 类型     | 必填 | 含义               |
| ------ | ------ | -- | ---------------- |
| Enable | string | 是  | Range回源开关：on/off |

**错误码**

| 错误码    | 含义         |
| ------ | ---------- |
| 404001 | 无此域名       |
| 400001 | 未知的域名      |
| 400064 | 无权处理该域名    |
| 400200 | 未知的bucket  |
| 400008 | 无此bucket   |
| 400013 | 重复操作       |
| 400030 | 正在处理中      |
| 400066 | 域名状态为失败    |
| 400998 | 域名已下线      |
| 500923 | 域名已冻结      |
| 500930 | 删除中的域名     |
| 400957 | 无效的Range配置 |

## 请求示例 [#请求示例]

```
PUT /domain/testqiniu.qbox.net/range HTTP/1.1
Authorization: QBox 0tf5awMVxwf8WrEvrjtbiZrdRZRJU-91JgCqTOC8:6oxDOtOXVEfcR8PPuAscmWjVRS8=
Content-Type: application/json
Host: api.qiniu.com
{
  "enable": "on"
}
```

# 修改回源超时 [#修改回源超时]

```
调整 CDN 回源节点到源站的超时时间
```

## 请求包 [#请求包-2]

```
PUT /domain/<Name>/sourcetimeout
Content-Type: application/json
Authorization: QBox <AccessToken>
{
    "sourceConnTimeout": <SourceConnTimeout>,
    "sourceReadTimeout": <SourceReadTimeout>
}
```

### 参数解释 [#参数解释-2]

| 参数名               | 类型  | 必填 | 说明                                           | 示例值 |
| ----------------- | --- | -- | -------------------------------------------- | --- |
| SourceConnTimeout | int | 是  | 回源建连超时（秒）必须填写为0 ，0 表示使用默认值（默认 5 秒），暂不支持调整    | 0   |
| SourceReadTimeout | int | 是  | 回源读取超时（秒），0 表示使用默认值（默认 30 秒），自定义范围为 5\~120 秒 | 60  |

## 请求示例 [#请求示例-1]

```
PUT /domain/testqiniu.qbox.net/range HTTP/1.1
Authorization: QBox 0tf5awMVxwf8WrEvrjtbiZrdRZRJU-91JgCqTOC8:6oxDOtOXVEfcR8PPuAscmWjVRS8=
Content-Type: application/json
Host: api.qiniu.com
{
    "sourceConnTimeout": 10,
    "sourceReadTimeout": 60
}
```

# 缓存策略 [#缓存策略]

## 结构 [#结构-1]

```
PUT /domain/<Name>/cache
Content-Type: application/json
Authorization: QBox <AccessToken>
    {
        cacheControls: [
            {
                time: <CCTime>,
                timeunit: <CCTimeUnit>,
                type: <CCType>,
                rule: <CCRule>
            }
        ],
        ignoreParam: <IgnoreParam>
    }
```

| 参数          | 类型     | 必填 | 含义                                                                                                                |
| ----------- | ------ | -- | ----------------------------------------------------------------------------------------------------------------- |
| CCTime      | int    | 是  | 缓存时间，注意不论哪种时间单位，总时间都不能超过1年,type为follow，本字段配为 -1                                                                   |
| CCTimeUnit  | int    | 是  | 缓存时间单位：0(秒)/1(分钟)/2(小时)/3(天)/4(周)/5(月)/6(年)，type为follow，本字段配为0                                                    |
| CCType      | string | 是  | 缓存类型：`all`(默认全局规则)/`path`(路径匹配)/`suffix`(后缀匹配)/`follow`(遵循源站)                                                     |
| CCRule      | string | 是  | 缓存路径规则：以分号;分割的字符串，每个里面类型一致，比如CCType为path的话，这里每个分号分割的都是以`/`开头，suffix的话，以点号`.`开头，如果是`all`类型，或者`follow`，统一只要填一个星号`*` |
| IgnoreParam | bool   | 是  | 是否开启去问号缓存，默认为false                                                                                                |

## 注意 [#注意-1]

* 缓存配置优先级依从配置数组的前后顺序依次从高到低
* `全局配置要放到最后`，不然自定义规则缓存配置优先级最低
* 如果是遵循源站配置`follow`，只能有一条，即全部遵循源站

## 例子 [#例子]

```
	// .abc, .jpg后缀文件缓存1分钟，/def, /auth 目录下文件不缓存，全局缓存一个月
	// url参数不缓存
	{
        cacheControls: [
            {
                time: 1,
                timeunit: 1,
                type: "suffix",
                rule: ".abc;.jpg"
			},
			{
                time: 0,
                timeunit: 0,
                type: "path",
                rule: "/def;/auth"
			},
			{
                time: 1,
                timeunit: 5,
                type: "all",
                rule: "*"
			},
        ],
        ignoreParam: true
	}
```

```
	// 遵循源站
	{
        cacheControls: [
            {
                time: 0,
                timeunit: 0,
                type: "follow",
                rule: "*"
			}
        ],
        ignoreParam: false
	}
```

# referer 防盗链 [#referer-防盗链]

## 结构 [#结构-2]

### 请求结构 [#请求结构]

```
PUT /domain/<Name>/referer
Content-Type: application/json
Authorization: QBox <AccessToken>

{
    refererType: <RefererType>,
    refererValues: [<RefererValue>,...],
    nullReferer: <NullReferer>
}
```

| 参数           | 类型     | 必填 | 含义                                |
| ------------ | ------ | -- | --------------------------------- |
| RefererType  | string | 是  | Referer防盗链类型： `black`/`white`     |
| RefererValue | string | 是  | Referer防盗链黑白名单                    |
| NullReferer  | bool   | 否  | Referer防盗链, 是否支持空referer，不填为false |

### 响应结构 [#响应结构]

```
{
     refererType: <RefererType>,
     refererValues: [<RefererValue>, ...],
     nullReferer: <NullReferer>
}
```

| 参数           | 类型     | 含义                            |
| ------------ | ------ | ----------------------------- |
| RefererType  | string | Referer防盗链类型： `black`/`white` |
| RefererValue | string | Referer防盗链黑白名单                |
| NullReferer  | bool   | Referer防盗链, 是否支持空referer      |

## 注意 [#注意-2]

* 请求结构和响应结构不同, 请求结构是指`创建域名`和`修改referer防盗链`的请求采用的结构，响应结构是指, 获取`域名信息`和`获取域名列表`中返回结果中采用的结构

# IP黑白名单 [#ip黑白名单]

## 结构 [#结构-3]

### 请求结构 [#请求结构-1]

```
PUT /domain/<Name>/ipacl
Content-Type: application/json
Authorization: QBox <AccessToken>
{
    ipACLType: <IpACLType>,
    ipACLValues: [<IpACLValue>,...],
}
```

| 参数         | 类型     | 必填 | 含义                                                                          |
| ---------- | ------ | -- | --------------------------------------------------------------------------- |
| IpACLType  | string | 是  | ip黑白名单控制控制类型, `black`/`white`/`""`；其中空字符串`""`代表关闭本功能，此时请注意`ipACLValues`需要为空 |
| IpACLValue | string | 是  | ip黑白名单，ip格式为：127.0.0.1/24                                                   |

### 响应结构 [#响应结构-1]

```
{
    ipACLType: <IpACLType>,
    ipACLValues: [<IpACLValue>, ...]
}
```

| 参数          | 类型     | 含义                          |
| ----------- | ------ | --------------------------- |
| ipACLType   | string | ip黑白名单控制类型, `black`/`white` |
| IpACLValues | string | ip黑白名单, ip格式为：127.0.0.1/24  |

## 注意 [#注意-3]

* 请求结构和响应结构不同, 请求结构是指`创建域名`和`修改ip黑白名单`的请求采用的结构，响应结构是指, 获取`域名信息`和`获取域名列表`中返回结果中采用的结构

# UA黑白名单 [#ua黑白名单]

## 结构 [#结构-4]

### 请求结构 [#请求结构-2]

```
PUT /domain/<Name>/uaacl
Content-Type: application/json
Authorization: QBox <AccessToken>
{
    enable: <Enable>,
    ruleType: <RuleType>,
    userAgent: [<UserAgent>, ...]
}
```

| 参数        | 类型     | 含义                          |
| --------- | ------ | --------------------------- |
| Enable    | string | ua黑白名单开关, `on`/`off`        |
| RuleType  | string | ua黑白名单控制类型, `black`/`white` |
| UserAgent | string | ua黑白名单                      |

### 响应结构 [#响应结构-2]

```
{
    enable: <Enable>,
    ruleType: <RuleType>,
    userAgent: [<UserAgent>, ...]
}
```

| 参数        | 类型     | 含义                          |
| --------- | ------ | --------------------------- |
| Enable    | string | ua黑白名单开关, `on`/`off`        |
| RuleType  | string | ua黑白名单控制类型, `black`/`white` |
| UserAgent | string | ua黑白名单                      |

## 注意 [#注意-4]

* 请求结构和响应结构不同, 请求结构是指`创建域名`和`修改ua黑白名单`的请求采用的结构，响应结构是指, 获取`域名信息`和`获取域名列表`中返回结果中采用的结构

# 修改响应头 [#修改响应头]

```
修改CDN返回给用户的响应头
```

## 请求包 [#请求包-3]

```
PUT /domain/<Name>/respheader
Content-Type: application/json
Authorization: QBox <AccessToken>
{
    responseHeaderControls: [
        {
            op: <op>
            key: <key>
            value: <value>
        }...
    ]
}
```

### 参数解释 [#参数解释-3]

| 参数    | 类型     | 必填 | 含义                                                                                                                                                                                                                                                                 |
| ----- | ------ | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Name  | string | 是  | 域名                                                                                                                                                                                                                                                                 |
| op    | string | 是  | 对响应头的进行操作的类型，可选"set"、"del"，目前不支持"add"                                                                                                                                                                                                                              |
| key   | string | 是  | 匹配响应头的key，可选值：Content-Type,Cache-Control,Content-Disposition,Content-Language,Expires,Access-Control-Allow-Origin,Access-Control-Allow-Methods,Access-Control-Allow-Headers,Access-Control-Max-Age,Access-Control-Expose-Headers,Access-Control-Allow-Credentials。 |
| value | string | 是  | 响应头的value，在op为"set"时有效                                                                                                                                                                                                                                             |

**错误码**

| 错误码    | 含义         |
| ------ | ---------- |
| 404001 | 无此域名       |
| 400001 | 未知的域名      |
| 400064 | 无权处理该域名    |
| 400008 | 无此bucket   |
| 400013 | 重复操作       |
| 400030 | 正在处理中      |
| 400066 | 域名状态为失败    |
| 400998 | 域名已下线      |
| 400923 | 域名已冻结      |
| 400084 | 无效的响应头key  |
| 400085 | 无效的响应头操作请求 |
| 400086 | 重复的响应头key  |
| 500930 | 删除中的域名     |
| 500005 | 数据查询内部出错   |

# 开启HTTPS [#开启https]

```
HTTP升级为HTTPS
```

## 请求包 [#请求包-4]

```
PUT /domain/<Name>/sslize
Content-Type: application/json
Authorization: QBox <AccessToken>
{
	"certid":<CertID>,
	"forceHttps": <ForceHttps>,
	"http2Enable": <Http2Enable>,
	"tlsversions": [<TlsVersion>,...]
}
```

### 参数解释 [#参数解释-4]

| 参数          | 类型     | 含义                                       |
| ----------- | ------ | ---------------------------------------- |
| CertID      | string | 证书id，从上传或者获取证书列表里拿到证书id                  |
| ForceHttps  | bool   | 是否强制https跳转                              |
| Http2Enable | bool   | http2功能是否启用，false为关闭，true为开启             |
| TlsVersion  | string | 支持的tls版本，TLSv1.0/TLSv1.1/TLSv1.2/TLSv1.3 |

**错误码**

| 错误码    | 含义            |
| ------ | ------------- |
| 400331 | 非法参数          |
| 404001 | 无此域名          |
| 400001 | 未知的域名         |
| 400064 | 无权处理该域名       |
| 400008 | 无此bucket      |
| 400392 | 非法的域名cname    |
| 400013 | 重复操作          |
| 400030 | 正在处理中         |
| 400066 | 域名状态为失败       |
| 400401 | 无此证书          |
| 400324 | https证书解码失败   |
| 400325 | https证书解析失败   |
| 400321 | https证书还未生效   |
| 400329 | https证书过期     |
| 400326 | https证书与域名不匹配 |
| 400327 | 解析https证书密钥失败 |
| 400328 | https证书与密钥不匹配 |
| 400323 | 验证https证书链失败  |
| 400550 | 非法的证书id       |
| 500219 | 查询证书内部错误      |
| 500005 | 数据查询内部出错      |

# 修改THHPS配置 [#修改thhps配置]

```
修改THHPS配置
```

## 请求包 [#请求包-5]

```
PUT /domain/<Name>/httpsconf
Content-Type: application/json
Authorization: QBox <AccessToken>
{
	"certId": <CertID>,
	"forceHttps": <ForceHttps>,
	"http2Enable": <Http2Enable>
        "tlsversions": [<TlsVersion>,...]
}
```

### 参数解释 [#参数解释-5]

| 参数          | 类型     | 含义                                       |
| ----------- | ------ | ---------------------------------------- |
| CertID      | string | 证书id，从上传或者获取证书列表里拿到证书id                  |
| ForceHttps  | bool   | 是否强制https跳转                              |
| Http2Enable | bool   | http2功能是否启用，false为关闭，true为开启             |
| TlsVersion  | string | 支持的tls版本，TLSv1.0/TLSv1.1/TLSv1.2/TLSv1.3 |

**错误码**

| 错误码    | 含义            |
| ------ | ------------- |
| 400331 | 非法参数          |
| 404001 | 无此域名          |
| 400001 | 未知的域名         |
| 400064 | 无权处理该域名       |
| 400008 | 无此bucket      |
| 400392 | 非法的域名cname    |
| 400013 | 重复操作          |
| 400030 | 正在处理中         |
| 400066 | 域名状态为失败       |
| 400401 | 无此证书          |
| 400324 | https证书解码失败   |
| 400325 | https证书解析失败   |
| 400321 | https证书还未生效   |
| 400329 | https证书过期     |
| 400326 | https证书与域名不匹配 |
| 400327 | 解析https证书密钥失败 |
| 400328 | https证书与密钥不匹配 |
| 400323 | 验证https证书链失败  |
| 500219 | 查询证书内部错误      |
| 500005 | 数据查询内部出错      |

# 创建新的域名标签 [#创建新的域名标签]

```
在账户下添加新的域名标签
```

## 请求包 [#请求包-6]

```
POST /domain/tag HTTP/1.1
Content-Type: application/json
Authorization: QBox <AccessToken>
{
	tag: <Tag>,
        tagKey: <TagKey>,
        tagValue: <TagValue>,
	product: <Product>
}
```

### 参数解释 [#参数解释-6]

| 参数       | 类型     | 必填 | 含义                             |
| -------- | ------ | -- | ------------------------------ |
| Tag      | string | 否  | 域名标签（废弃）                       |
| TagKey   | string | 是  | 域名标签Key                        |
| TagValue | string | 是  | 域名标签Value                      |
| Product  | string | 是  | 产品类型: `cdn`(静态加速)/`dcdn`(全站加速) |

**错误码**

| 错误码    | 含义           |
| ------ | ------------ |
| 400331 | 非法参数         |
| 400925 | 账号域名标签数量达到上限 |
| 400927 | 域名标签已存在      |
| 500004 | 更新数据内部出错     |
| 500005 | 数据查询内部出错     |

## 请求示例 [#请求示例-2]

```
POST /domain/tag HTTP/1.1
Authorization: QBox 0tf5awMVxwf8WrEvrjtbiZrdRZRJU-91JgCqTOC8:6oxDOtOXVEfcR8PPuAscmWjVRS8=
Content-Type: application/json
Host: api.qiniu.com
{
    "tagKey": "图片",
    "tagValue": "高清",
    "product": "cdn"
}
```

# 设置域名标签 [#设置域名标签]

```
选取账户下定义好的标签，为域名配置标签列表
```

## 请求包 [#请求包-7]

```
PUT /domain/<Domain>/tags HTTP/1.1
Content-Type: application/json
Authorization: QBox <AccessToken>
{
	kvTagList: <TagList>
}
```

### 参数解释 [#参数解释-7]

| 参数        | 类型        | 必填 | 含义              |
| --------- | --------- | -- | --------------- |
| kvTagList | \[]Object | 是  | Key-Value格式标签列表 |

**错误码**

| 错误码    | 含义           |
| ------ | ------------ |
| 400331 | 非法参数         |
| 404001 | 无此域名         |
| 400064 | 无权处理该域名      |
| 400926 | 单个域名标签数量达到上限 |
| 500004 | 更新数据内部出错     |
| 500005 | 数据查询内部出错     |

## 请求示例 [#请求示例-3]

```
PUT /domain/<Domain>/tags HTTP/1.1
Authorization: QBox 0tf5awMVxwf8WrEvrjtbiZrdRZRJU-91JgCqTOC8:6oxDOtOXVEfcR8PPuAscmWjVRS8=
Content-Type: application/json
Host: api.qiniu.com
{
    "kvTagList": [{"key":"图片","value":"高清"}]
}
```

# 获取所有域名标签 [#获取所有域名标签]

```
获取账户下定义的域名标签
```

## 请求包 [#请求包-8]

```
GET /domain/all/tags?product=<Product>
Content-Type: application/x-www-form-urlencoded
Authorization: QBox <AccessToken>
```

### 参数解释 [#参数解释-8]

| 参数      | 类型     | 必填 | 含义                             |
| ------- | ------ | -- | ------------------------------ |
| Product | string | 是  | 产品类型: `cdn`(静态加速)/`dcdn`(全站加速) |

**错误码**

| 错误码    | 含义       |
| ------ | -------- |
| 400331 | 非法参数     |
| 500005 | 数据查询内部出错 |


# 日志下载 (/products/dcdn/4-dcdn-download-the-log)



最近更新时间: 2022-04-18 14:37:53

日志下载接口可以查询域名日志列表，获取日志的下载外链，只提供 30 个自然日内的日志下载，例如当前日期为 2016-08-31，则只提供 2016-08-01 \~ 2016-08-30 的日志。

日志文件默认按小时下载，如果单小时内日志过大会进行切分(分片大小128MB)，日志文件采用gzip压缩。
日志大概延迟6小时，举例：1月18日0点-1点的日志，会在1月18日8点-10点左右可下载。

<a id="access-domain" />

# 访问域名 [#访问域名]

```
Host: fusion.qiniuapi.com
```

<a id="interface-address" />

# 接口地址 [#接口地址]

```
/v2/tune/log/list
```

<a id="log-authenticated" />

# 认证授权 [#认证授权]

```
Authorization: <access_token>
```

access\_token 详细描述请查阅[这里](/products/kodo/development-guidelines/security/access-token)。

<a id="log-request-message" />

# 请求报文 [#请求报文]

<a id="log-request-syntax" />

## 请求语法 [#请求语法]

```
POST /v2/tune/log/list
Content-Type: application/json

{
    "day":<Day>,
    "domains": <Domains>
}
```

<a id="log-request-body" />

## 请求内容 [#请求内容]

| 参数                | 类型     | 必须 | 描述               |
| ----------------- | ------ | -- | ---------------- |
| `&lt;Day&gt;`     | string | 是  | 日期，例如 2016-07-01 |
| `&lt;Domains&gt;` | string | 是  | 域名列表，以英文分号 ; 分割  |

<a id="log-response-message" />

# 响应报文 [#响应报文]

<a id="log-response-status" />

## 响应状态码 [#响应状态码]

| HTTP状态码 | 含义             | 说明                             |
| :------ | :------------- | :----------------------------- |
| 200     | success        | 成功                             |
| 400     | invalid params | 请求参数格式错误                       |
| 401     | bad token      | 认证授权失败（包括密钥信息不正确；数字签名错误；授权已超时） |
| 400032  | invalid host   | 请求中存在无效的域名，请确保域名格式正确           |
| 500000  | internal error | 服务器内部错误                        |

<a id="log-response-body" />

## 响应内容 [#响应内容]

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "code":<Code>,
    "error": <Error>,
    "data": {
            ...
            <Domain_i>:[
                ...
                {
                    "name":<Name>,
                    "size":<Size>,
                    "mtime":<Mtime>,
                    "url":<Url>,
                },
                ...
            ],
            ...
    }
}
```

| 参数               | 类型     | 说明                                         |
| :--------------- | :----- | :----------------------------------------- |
| Code             | int    | HTTP 状态码，整型，见[响应状态码](#log-response-status) |
| Error            | string | 自定义错误码描述，字符串                               |
| data             | map    | 日志数据                                       |
| Domain\_i        | string | 域名，字符串                                     |
| Domain\_i\_Name  | string | 文件名，字符串                                    |
| Domain\_i\_Size  | int64  | 文件大小，单位为 Byte                              |
| Domain\_i\_Mtime | int64  | 文件修改时间，Unix 时间戳                            |
| Domain\_i\_Url   | string | 下载链接，字符串                                   |

<a id="log-samples" />

# 示例 [#示例]

<a id="log-request-sample" />

## 请求示例 [#请求示例]

```
POST https://fusion.qiniuapi.com/v2/tune/log/list
Content-Type: application/json

{
    "day":"2016-07-01",
    "domains": "log-test1.qiniu.com;log-test2.qiniu.com"
}
```

<a id="log-response-sample" />

## 响应示例 [#响应示例]

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "log-test1.qiniu.com": [
            {
                "name":"log-test1.qiniu.com_2016-07-01-00_00.gz",
                "size": 88490306,
                "mtime": 1466274440,
                "url": "https://fusionlog.qiniu.com/log-test1.qiniu.com_2016-07-01-00_00.gz?e=1561008052&token=557TpseUM8ovpfUhaw8gfa2DQ0104ZScM-BTIcBx:8AUwyRCO6nwb8vTH_LNKg4016Ec"
            }
        ],
        "log-test2.qiniu.com": [
            {
                "name":"log-test2.qiniu.com_2016-07-01-00_00.gz",
                "size": 73280873,
                "mtime": 1466273259,
                "url": "https://fusionlog.qiniu.com/log-test2.qiniu.com_2016-07-01-00_00.gz?e=1561008052&token=336DepseUM8ovpfUhaw8gfa2DQ0104ZScM-BTIcBx:8AUwyRCO6nwb8vTH_LNKg3879Wd"
            }
        ]
    }
}
```

<a id="download-log-tool" />

# 日志格式 [#日志格式]

```
IP 命中率 响应时间 请求时间 请求方法 请求URL	请求协议 状态码 响应大小 referer 用户代理
ClientIP Hit/Miss ResponseTime [Time Zone] Method URL Protocol StatusCode TrafficSize Referer UserAgent
```


# 流量带宽 (/products/dcdn/5-dcdn-traffic-bandwidth)



最近更新时间: 2026-08-31 11:35:01

<a id="access-domain" />

# 访问域名 [#访问域名]

```
Host: fusion.qiniuapi.com
```

<a id="traffic-bandwidth-authenticated" />

# 认证授权 [#认证授权]

```
Authorization: QBox <access_token>
```

access\_token 详细描述请查阅[这里](/products/kodo/development-guidelines/security/access-token)。

<a id="batch-bandwidth" />

# 批量查询计费带宽 [#批量查询计费带宽]

<a id="bandwidth-interface-address" />

## 接口地址 [#接口地址]

```
/v2/dcdn/bandwidth
```

<a id="bandwidth-instruction" />

### 说明 [#说明]

* 返回的数据包含开始日期和结束日期
* 带宽的单位为 bps
* data 只包含有流量的域名

<a id="bandwidth-request-syntax" />

## 请求语法 [#请求语法]

```
POST /v2/dcdn/bandwidth
Content-Type: application/json

{
    "startDate": <StartDate>,
    "endDate": <EndDate>,
    "granularity": <Granularity>,
    "domains": <Domains>
}
```

<a id="bandwidth-request-body" />

## 请求内容 [#请求内容]

| 参数          | 类型     | 必要性 | 说明                                                                                     |
| ----------- | ------ | --- | -------------------------------------------------------------------------------------- |
| StartDate   | string | 必须  | 开始日期，例如：2016-07-01                                                                     |
| EndDate     | string | 必须  | 结束日期，例如：2016-07-03                                                                     |
| Granularity | string | 必须  | 粒度，取值：5min ／ hour ／day                                                                 |
| Domains     | string | 必须  | 域名列表，以 ；分割                                                                             |
| Type        | string | 非必须 | 指定带宽数据类型, `""`或`"bandwidth"`查询全站加速带宽数据，`"dynbandwidth"`查询因动态加速产生的带宽数据, 未启用动态加速功能可忽略该参数 |

<a id="bandwidth-response-status" />

## 响应状态码 [#响应状态码]

| HTTP状态码 | 含义                 | 说明                                                                    |
| :------ | :----------------- | :-------------------------------------------------------------------- |
| 200     | success            | 成功                                                                    |
| 400031  | invalid params     | 请求参数非法。 e.g. `"Type"`参数指定了除`""`(空)/`"bandwidth"`/`"dynbandwidth"`以外的值 |
| 400032  | invalid host       | 请求中存在无效的域名，请确保域名格式正确                                                  |
| 400080  | invalid start time | 开始时间格式错误                                                              |
| 400081  | invalid end time   | 截止时间格式错误                                                              |
| 400082  | invalid time range | 时间范围错误，请确保开始时间早于结束时间，且时间范围不超过 31 天                                    |
| 500000  | internal error     | 服务端内部错误，请联系技术支持                                                       |

<a id="bandwidth-response-body" />

## 响应内容 [#响应内容]

```
200 OK HTTP/1.1

{
  "code": <Code>,
  "error": <Error>,
  "time": <Time>,
  "data": {
    ...
    <Domain_i>: {
      "china": <Domain_i_China>,
      "oversea": <Domain_i_Oversea>,
    },
    ...
  }
}
```

| 参数                 | 类型        | 说明                                               |
| :----------------- | :-------- | :----------------------------------------------- |
| Code               | int       | HTTP 状态码，整型，见[响应状态码](#bandwidth-response-status) |
| Error              | string    | 自定义错误码描述，字符串                                     |
| Time               | \[]string | 时间点数组                                            |
| data               | map       | 带宽数据                                             |
| Domain\_i          | string    | 域名                                               |
| Domain\_i\_China   | \[]int    | Domain\_i 国内带宽数据，与 Time 一一对应                     |
| Domain\_i\_Oversea | \[]int    | Domain\_i 海外带宽数据，与 Time 一一对应                     |

<a id="bandwidth-sample" />

## 示例 [#示例]

```
200 OK HTTP/1.1

{
  "code": 200,
  "error": "",
  "time": ["2016-07-01 00:00:00","2016-07-01 00:05:00", ...],
  "data": {
    "a.com": {
      "china": [8888, 9999, 10000, ...],
      "oversea": [3333, 4444, 5000, ...],
    },
    "b.com": {
      "china": [8888, 9999, 10000, ...],
      "oversea": [3333, 4444, 5000, ...],
    }
  }
}
```

<a id="batch-flux" />

# 批量查询计费流量 [#批量查询计费流量]

<a id="flux-interface-address" />

## 接口地址 [#接口地址-1]

```
/v2/dcdn/flux
```

<a id="flux-instruction" />

### 说明 [#说明-1]

* 返回的数据包含开始日期和结束日期
* 流量的单位为 byte
* data 只包含有流量的域名

<a id="flux-request-syntax" />

## 请求语法 [#请求语法-1]

```
POST /v2/dcdn/flux
Content-Type: application/json

{
    "startDate": <StartDate>,
    "endDate": <EndDate>,
    "granularity": <Granularity>,
    "domains": <Domains>
}
```

<a id="flux-request-body" />

## 请求内容 [#请求内容-1]

| 参数          | 类型     | 必要性 | 说明                                                                 |
| ----------- | ------ | --- | ------------------------------------------------------------------ |
| StartDate   | string | 必须  | 开始日期，例如：2016-07-01                                                 |
| EndDate     | string | 必须  | 结束日期，例如：2016-07-03                                                 |
| Granularity | string | 必须  | 粒度，取值：5min ／ hour ／day                                             |
| Domains     | string | 必须  | 域名列表，以 ；分割                                                         |
| Type        | string | 非必须 | `""`或`"flux"`查询全站加速流量数据，`"dynflux"`查询因动态加速产生的流量数据, 未启用动态加速功能可忽略该参数 |

<a id="flux-response-status" />

## 响应状态码 [#响应状态码-1]

| HTTP状态码 | 含义                 | 说明                                                                    |
| :------ | :----------------- | :-------------------------------------------------------------------- |
| 200     | success            | 成功                                                                    |
| 400031  | invalid params     | 请求参数非法。 e.g. `"Type"`参数指定了除`""`(空)/`"bandwidth"`/`"dynbandwidth"`以外的值 |
| 400032  | invalid host       | 请求中存在无效的域名，请确保域名格式正确                                                  |
| 400080  | invalid start time | 开始时间格式错误                                                              |
| 400081  | invalid end time   | 截止时间格式错误                                                              |
| 400082  | invalid time range | 时间范围错误，请确保开始时间早于结束时间，且时间范围不超过 30 天                                    |
| 500000  | internal error     | 服务端内部错误，请联系技术支持                                                       |

<a id="flux-response-body" />

## 响应内容 [#响应内容-1]

```
200 OK HTTP/1.1

{
  "code": <Code>,
  "error": <Error>,
  "time": <Time>,
  "data": {
    ...
    <Domain_i>: {
      "china": <Domain_i_China>,
      "oversea": <Domain_i_Oversea>,
    },
    ...
  }
}
```

| 参数                 | 类型        | 说明                                          |
| :----------------- | :-------- | :------------------------------------------ |
| Code               | int       | HTTP 状态码，整型，见[响应状态码](#flux-response-status) |
| Error              | string    | 自定义错误码描述，字符串                                |
| Time               | \[]string | 时间点数组                                       |
| data               | map       | 流量数据                                        |
| Domain\_i          | string    | 域名                                          |
| Domain\_i\_China   | \[]int    | Domain\_i 国内流量数据，与 Time 一一对应                |
| Domain\_i\_Oversea | \[]int    | Domain\_i 海外流量数据，与 Time 一一对应                |

<a id="flux-sample" />

## 示例 [#示例-1]

```
200 OK HTTP/1.1

{
  "code": 200,
  "error": "",
  "time": ["2016-07-01 00:00:00","2016-07-01 00:05:00", ...],
  "data": {
    "a.com": {
      "china": [8888, 9999, 10000, ...],
      "oversea": [3333, 4444, 5000, ...],
    },
    "b.com": {
      "china": [8888, 9999, 10000, ...],
      "oversea": [3333, 4444, 5000, ...],
    }
  }
}
```

# 批量查询动态请求数 [#批量查询动态请求数]

<a id="flux-interface-address" />

## 接口地址 [#接口地址-2]

```
/v2/dcdn/dynreqcount
```

<a id="flux-instruction" />

### 说明 [#说明-2]

* 返回的数据包含开始日期和结束日期
* 动态请求数单位为 次
* data 只包含有流量的域名(依据动态加速请求日志)

<a id="flux-request-syntax" />

## 请求语法 [#请求语法-2]

```
POST /v2/dcdn/dynreqcount
Content-Type: application/json

{
    "startDate": <StartDate>,
    "endDate": <EndDate>,
    "granularity": <Granularity>,
    "domains": <Domains>
}
```

<a id="flux-request-body" />

## 请求内容 [#请求内容-2]

| 参数          | 类型     | 必要性 | 说明                                                   |
| ----------- | ------ | --- | ---------------------------------------------------- |
| StartDate   | string | 必须  | 开始日期，例如：2016-07-01                                   |
| EndDate     | string | 必须  | 结束日期，例如：2016-07-03                                   |
| Granularity | string | 必须  | 粒度，取值：5min ／ hour ／day                               |
| Domains     | string | 必须  | 域名列表，以 ；分割                                           |
| Type        | string | 非必须 | 数据类型, `""`或`"dynreqcount"`查询因动态加速产生的动态请求数, 其他值视为非法参数 |

<a id="flux-response-status" />

## 响应状态码 [#响应状态码-2]

| HTTP状态码 | 含义                 | 说明                                                              |
| :------ | :----------------- | :-------------------------------------------------------------- |
| 200     | success            | 成功                                                              |
| 400031  | invalid params     | 请求内容参数`"Type"`非法. e.g `"Type"`参数指定了除`""`(空)/`"dynreqcount"`之外的值 |
| 400032  | invalid host       | 请求中存在无效的域名，请确保域名格式正确                                            |
| 400080  | invalid start time | 开始时间格式错误                                                        |
| 400081  | invalid end time   | 截止时间格式错误                                                        |
| 400082  | invalid time range | 时间范围错误，请确保开始时间早于结束时间，且时间范围不超过 30 天                              |
| 500000  | internal error     | 服务端内部错误，请联系技术支持                                                 |

<a id="flux-response-body" />

## 响应内容 [#响应内容-2]

```
200 OK HTTP/1.1

{
  "code": <Code>,
  "error": <Error>,
  "time": <Time>,
  "data": {
    ...
    <Domain_i>: {
      "china": <Domain_i_China>,
      "oversea": <Domain_i_Oversea>,
    },
    ...
  }
}
```

| 参数                 | 类型        | 说明                                          |
| :----------------- | :-------- | :------------------------------------------ |
| Code               | int       | HTTP 状态码，整型，见[响应状态码](#flux-response-status) |
| Error              | string    | 自定义错误码描述，字符串                                |
| Time               | \[]string | 时间点数组                                       |
| data               | map       | 流量数据                                        |
| Domain\_i          | string    | 域名                                          |
| Domain\_i\_China   | \[]int    | Domain\_i 国内流量数据，与 Time 一一对应                |
| Domain\_i\_Oversea | \[]int    | Domain\_i 海外流量数据，与 Time 一一对应                |

<a id="flux-sample" />

## 示例 [#示例-2]

```
200 OK HTTP/1.1

{
  "code": 200,
  "error": "",
  "time": ["2019-01-01 00:00:00","2019-01-01 00:05:00", ...],
  "data": {
    "a.com": {
      "china": [8888, 9999, 10000, ...],
      "oversea": [3333, 4444, 5000, ...],
    },
    "b.com": {
      "china": [8888, 9999, 10000, ...],
      "oversea": [3333, 4444, 5000, ...],
    }
  }
}
```

<a id="batch-monitoring-bandwidth" />

# 批量查询监控带宽 [#批量查询监控带宽]

<a id="monitoring-bandwidth-interface-address" />

## 接口地址 [#接口地址-3]

```
/v2/tune/monitoring/bandwidth
```

<a id="monitoring-bandwidth-instruction" />

### 说明 [#说明-3]

* 返回的数据包含开始日期和结束日期
* 带宽的单位为 bps
* data 只包含有流量的域名
* 监控接口侧重于全站加速服务实时统计带宽数据的实效性，不保证数据与账单完全一致
* 支持查询3个月之内的带宽数据，/v2/dcdn/bandwidth接口无此限制

<a id="monitoring-bandwidth-request-syntax" />

## 请求语法 [#请求语法-3]

```
POST /v2/tune/monitoring/bandwidth
Content-Type: application/json

{
    "startDate": <StartDate>,
    "endDate": <EndDate>,
    "granularity": <Granularity>,
    "domains": <Domains>
}
```

<a id="monitoring-bandwidth-request-body" />

## 请求内容 [#请求内容-3]

| 参数          | 类型     | 必要性 | 说明                                                                                     |
| ----------- | ------ | --- | -------------------------------------------------------------------------------------- |
| StartDate   | string | 必须  | 开始日期，例如：2016-07-01                                                                     |
| EndDate     | string | 必须  | 结束日期，例如：2016-07-03                                                                     |
| Granularity | string | 必须  | 粒度，取值：5min ／ hour ／day                                                                 |
| Domains     | string | 必须  | 域名列表，以 ；分割                                                                             |
| Type        | string | 非必须 | 指定带宽数据类型, `""`或`"bandwidth"`查询全站加速带宽数据，`"dynbandwidth"`查询因动态加速产生的带宽数据, 未启用动态加速功能可忽略该参数 |

<a id="monitoring-bandwidth-response-status" />

## 响应状态码 [#响应状态码-3]

| HTTP状态码 | 含义                 | 说明                                                                    |
| :------ | :----------------- | :-------------------------------------------------------------------- |
| 200     | success            | 成功                                                                    |
| 400031  | invalid params     | 请求参数非法。 e.g. `"Type"`参数指定了除`""`(空)/`"bandwidth"`/`"dynbandwidth"`以外的值 |
| 400032  | invalid host       | 请求中存在无效的域名，请确保域名格式正确                                                  |
| 400080  | invalid start time | 开始时间格式错误                                                              |
| 400081  | invalid end time   | 截止时间格式错误                                                              |
| 400082  | invalid time range | 时间范围错误，请确保开始时间早于结束时间，且时间范围不超过 31 天                                    |
| 500000  | internal error     | 服务端内部错误，请联系技术支持                                                       |

<a id="monitoring-bandwidth-response-body" />

## 响应内容 [#响应内容-3]

```
200 OK HTTP/1.1

{
  "code": <Code>,
  "error": <Error>,
  "time": <Time>,
  "data": {
    ...
    <Domain_i>: {
      "china": <Domain_i_China>,
      "oversea": <Domain_i_Oversea>,
    },
    ...
  }
}
```

| 参数                 | 类型        | 说明                                               |
| :----------------- | :-------- | :----------------------------------------------- |
| Code               | int       | HTTP 状态码，整型，见[响应状态码](#bandwidth-response-status) |
| Error              | string    | 自定义错误码描述，字符串                                     |
| Time               | \[]string | 时间点数组                                            |
| data               | map       | 带宽数据                                             |
| Domain\_i          | string    | 域名                                               |
| Domain\_i\_China   | \[]int    | Domain\_i 国内带宽数据，与 Time 一一对应                     |
| Domain\_i\_Oversea | \[]int    | Domain\_i 海外带宽数据，与 Time 一一对应                     |

<a id="monitoring-bandwidth-sample" />

## 示例 [#示例-3]

```
200 OK HTTP/1.1

{
  "code": 200,
  "error": "",
  "time": ["2016-07-01 00:00:00","2016-07-01 00:05:00", ...],
  "data": {
    "a.com": {
      "china": [8888, 9999, 10000, ...],
      "oversea": [3333, 4444, 5000, ...],
    },
    "b.com": {
      "china": [8888, 9999, 10000, ...],
      "oversea": [3333, 4444, 5000, ...],
    }
  }
}
```

<a id="monitoring-batch-flux" />

# 批量查询监控流量 [#批量查询监控流量]

<a id="fmonitoring-lux-interface-address" />

## 接口地址 [#接口地址-4]

```
/v2/tune/monitoring/flow
```

<a id="monitoring-flux-instruction" />

### 说明 [#说明-4]

* 返回的数据包含开始日期和结束日期
* 流量的单位为 byte
* data 只包含有流量的域名
* 监控接口侧重于全站加速服务实时统计流量数据的实效性，不保证数据与账单完全一致
* 支持查询3个月之内的流量数据，/v2/dcdn/flux接口无此限制

<a id="monitoring-flux-request-syntax" />

## 请求语法 [#请求语法-4]

```
POST /v2/tune/monitoring/flow
Content-Type: application/json

{
    "startDate": <StartDate>,
    "endDate": <EndDate>,
    "granularity": <Granularity>,
    "domains": <Domains>
}
```

<a id="monitoring-flux-request-body" />

## 请求内容 [#请求内容-4]

| 参数          | 类型     | 必要性 | 说明                                                                 |
| ----------- | ------ | --- | ------------------------------------------------------------------ |
| StartDate   | string | 必须  | 开始日期，例如：2016-07-01                                                 |
| EndDate     | string | 必须  | 结束日期，例如：2016-07-03                                                 |
| Granularity | string | 必须  | 粒度，取值：5min ／ hour ／day                                             |
| Domains     | string | 必须  | 域名列表，以 ；分割                                                         |
| Type        | string | 非必须 | `""`或`"flux"`查询全站加速流量数据，`"dynflux"`查询因动态加速产生的流量数据, 未启用动态加速功能可忽略该参数 |

<a id="monitoring-flux-response-status" />

## 响应状态码 [#响应状态码-4]

| HTTP状态码 | 含义                 | 说明                                                                    |
| :------ | :----------------- | :-------------------------------------------------------------------- |
| 200     | success            | 成功                                                                    |
| 400031  | invalid params     | 请求参数非法。 e.g. `"Type"`参数指定了除`""`(空)/`"bandwidth"`/`"dynbandwidth"`以外的值 |
| 400032  | invalid host       | 请求中存在无效的域名，请确保域名格式正确                                                  |
| 400080  | invalid start time | 开始时间格式错误                                                              |
| 400081  | invalid end time   | 截止时间格式错误                                                              |
| 400082  | invalid time range | 时间范围错误，请确保开始时间早于结束时间，且时间范围不超过 30 天                                    |
| 500000  | internal error     | 服务端内部错误，请联系技术支持                                                       |

<a id="monitoring-flux-response-body" />

## 响应内容 [#响应内容-4]

```
200 OK HTTP/1.1

{
  "code": <Code>,
  "error": <Error>,
  "time": <Time>,
  "data": {
    ...
    <Domain_i>: {
      "china": <Domain_i_China>,
      "oversea": <Domain_i_Oversea>,
    },
    ...
  }
}
```

| 参数                 | 类型        | 说明                                                     |
| :----------------- | :-------- | :----------------------------------------------------- |
| Code               | int       | HTTP 状态码，整型，见[响应状态码](#monitoring-flux-response-status) |
| Error              | string    | 自定义错误码描述，字符串                                           |
| Time               | \[]string | 时间点数组                                                  |
| data               | map       | 流量数据                                                   |
| Domain\_i          | string    | 域名                                                     |
| Domain\_i\_China   | \[]int    | Domain\_i 国内流量数据，与 Time 一一对应                           |
| Domain\_i\_Oversea | \[]int    | Domain\_i 海外流量数据，与 Time 一一对应                           |

<a id="monitoring-flux-sample" />

## 示例 [#示例-4]

```
200 OK HTTP/1.1

{
  "code": 200,
  "error": "",
  "time": ["2016-07-01 00:00:00","2016-07-01 00:05:00", ...],
  "data": {
    "a.com": {
      "china": [8888, 9999, 10000, ...],
      "oversea": [3333, 4444, 5000, ...],
    },
    "b.com": {
      "china": [8888, 9999, 10000, ...],
      "oversea": [3333, 4444, 5000, ...],
    }
  }
}
```


# 日志分析 (/products/dcdn/6-dcdn-log-analysis)



最近更新时间: 2023-06-13 17:42:51

# 访问域名 [#访问域名]

```
Host: fusion.qiniuapi.com
```

# 认证授权 [#认证授权]

```
Authorization: QBox <access_token>
```

access\_token 详细描述请查阅[这里](/products/kodo/development-guidelines/security/access-token/0-historical-document-management-certificate)。

<a id="statuscode" />

# 自定义状态码 [#自定义状态码]

| HTTP 状态码 | 含义             | 说明      |
| -------- | -------------- | ------- |
| 200      | success        | 成功      |
| 400054   | invalid domain | 域名不合法   |
| 400331   | invalid params | 请求参数错误  |
| 500000   | internal error | 服务端内部错误 |

# 区域运营商流量查询 [#区域运营商流量查询]

接口地址

```
/v1/dcdn/loganalyze/traffic
```

请求语法

```
POST /v1/dcdn/loganalyze/traffic HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
  "domains": [<domain1>, <domain2>, <domain3>, ......],
  "freq": <freq>,
  "regions": [<region1>, <region2>, <region3>, ......],
  "isp": <isp>,
  "startDate": <startDate>,
  "endDate": <endDate>
}
```

| 参数        | 类型     | 说明                                                                                           |
| --------- | ------ | -------------------------------------------------------------------------------------------- |
| domainN   | string | 域名列表，总数不超过100条                                                                               |
| freq      | string | 粒度，可选项为 5min、1hour、1day                                                                      |
| regionN   | string | 区域，选项见 <a href="#region">Region 参数列表</a>                                                     |
| isp       | string | ISP运营商，比如all(所有 ISP)，telecom(电信)，unicom(联通)，mobile(中国移动)，drpeng(鹏博士)，tietong(铁通)，cernet(教育网) |
| startDate | string | 开始时间，格式为：2006-01-02。起止最大间隔为31天                                                               |
| endDate   | string | 结束时间，格式为：2006-01-02。起止最大间隔为31天                                                               |

返回包

```
200 OK

{
  "code": <code>,
  "error": <error>,
  "data": {
     "points": [<point1>, <point2>, <point3>, ......],
     "value": [<value1>, <value2>, <value3>, ......]
  }
}
```

| 参数     | 类型     | 说明                               |
| ------ | ------ | -------------------------------- |
| code   | int    | <a href="#statuscode">自定义状态码</a> |
| error  | string | 自定义错误描述                          |
| pointN | string | 时间点，形如 2006-01-02-15-04          |
| valueN | long   | 在 pointN 时间点的流量                  |

注：如果同时查询中国和上海的数据，结果是两者的累加。

# 区域运营商带宽查询 [#区域运营商带宽查询]

接口地址

```
/v1/dcdn/loganalyze/bandwidth
```

请求语法

```
POST /v1/dcdn/loganalyze/bandwidth HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
  "domains": [<domain1>, <domain2>, <domain3>, ......],
  "freq": <freq>,
  "regions": [<region1>, <region2>, <region3>, ......],
  "isp": <isp>,
  "startDate": <startDate>,
  "endDate": <endDate>
}
```

| 参数        | 类型     | 说明                                                                                           |
| --------- | ------ | -------------------------------------------------------------------------------------------- |
| domainN   | string | 域名列表，总数不超过100条                                                                               |
| freq      | string | 粒度，可选项为 5min、1hour、1day                                                                      |
| regionN   | string | 区域，选项见 <a href="#region">Region 参数列表</a>                                                     |
| isp       | string | ISP运营商，比如all(所有 ISP)，telecom(电信)，unicom(联通)，mobile(中国移动)，drpeng(鹏博士)，tietong(铁通)，cernet(教育网) |
| startDate | string | 开始时间，格式为：2006-01-02。起止最大间隔为31天                                                               |
| endDate   | string | 结束时间，格式为：2006-01-02。起止最大间隔为31天                                                               |

返回包

```
200 OK

{
  "code": <code>,
  "error": <error>,
  "data": {
     "points": [<point1>, <point2>, <point3>, ......],
     "value": [<value1>, <value2>, <value3>, ......]
  },
  "stats": {
    "peak": {
      "time": <peakTime>,
      "value": <peakValue>
    },
    "peak95": {
      "time": <peak95Time>,
      "value": <peak95Value>
    },
    "peak95Average": <peak95Average>,
    "peakAverage": <peakAverage>
  }
}
```

| 参数            | 类型     | 说明                               |
| ------------- | ------ | -------------------------------- |
| code          | int    | <a href="#statuscode">自定义状态码</a> |
| error         | string | 自定义错误描述                          |
| pointN        | string | 时间点，形如 2006-01-02-15-04          |
| valueN        | long   | 在 pointN 时间点的带宽                  |
| peakTime      | string | 峰值的时间点，形如 2006-01-02-15-04       |
| peakValue     | long   | 峰值带宽                             |
| peak95Time    | string | 95峰的时间点，形如 2006-01-02-15-04      |
| peak95Value   | long   | 95峰带宽                            |
| peakAverage   | long   | 各天峰值的平均值                         |
| peak95Average | long   | 各天95峰的平均值                        |

注：如果同时查询中国和上海的数据，结果是两者的累加。

# 批量查询状态码 [#批量查询状态码]

接口地址

```
/v1/dcdn/loganalyze/statuscode
```

请求语法

```
POST /v1/dcdn/loganalyze/statuscode HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
    "domains": [<domain1>, <domain2>, <domain3>, ......],
    "freq": <freq>,
    "regions": [<region1>, <region2>, <region3>, ......],
    "isp": <isp>,
    "startDate": <startDate>,
    "endDate": <endDate>
}
```

请求内容

| 参数        | 类型     | 说明                                                                                           |
| --------- | ------ | -------------------------------------------------------------------------------------------- |
| domainN   | string | 域名列表，总数不超过100条                                                                               |
| freq      | string | 粒度，可选项为 5min、1hour、1day                                                                      |
| regionN   | string | 区域，选项见 <a href="#region">Region 参数列表</a>                                                     |
| isp       | string | ISP运营商，比如all(所有 ISP)，telecom(电信)，unicom(联通)，mobile(中国移动)，drpeng(鹏博士)，tietong(铁通)，cernet(教育网) |
| startDate | string | 开始时间，格式为：2006-01-02。起止最大间隔为31天                                                               |
| endDate   | string | 结束时间，格式为：2006-01-02。起止最大间隔为31天                                                               |

响应内容

```
HTTP/1.1 200 OK
Content-Type: application/json

{
   "data" : {
      "codes" : {
         <statusCode> : [<codeCount1>, <codeCount2>, <codeCount3>, ......]
      },
      "points" : [<point1>, <point2>, <point3>, ......]
   },
   "error" : <error>,
   "code" : <code>
}
```

| 参数         | 类型     | 说明                               |
| ---------- | ------ | -------------------------------- |
| code       | int    | <a href="#statuscode">自定义状态码</a> |
| error      | string | 自定义错误描述                          |
| pointN     | string | 时间点，形如 2006-01-02-15-04          |
| statusCode | string | 状态码                              |
| codeCountN | long   | 状态码在 pointN 时间点的个数               |

# 批量查询命中率 [#批量查询命中率]

接口地址

```
/v1/dcdn/loganalyze/hitmiss
```

请求语法

```
POST /v1/dcdn/loganalyze/hitmiss HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
    "domains": [<domain1>, <domain2>, <domain3>, ......],
    "freq": <freq>,
    "startDate": <startDate>,
    "endDate": <endDate>
}
```

请求内容

| 参数        | 类型     | 说明                             |
| --------- | ------ | ------------------------------ |
| domainN   | string | 域名列表，总数不超过100条                 |
| freq      | string | 粒度，可选项为 5min、1hour、1day        |
| startDate | string | 开始时间，格式为：2006-01-02。起止最大间隔为31天 |
| endDate   | string | 结束时间，格式为：2006-01-02。起止最大间隔为31天 |

响应内容

```
HTTP/1.1 200 OK
Content-Type: application/json

{
   "data" : {
      "points" : [<point1>, <point2>, <point3>, ......],
      "hit" : [<hitCount1>, <hitCount2>, <hitCount3>, ......],
      "miss" : [<missCount1>, <missCount2>, <missCount3>, ......],
      "trafficHit" : [<trafficHitCount1>, <trafficHitCount2>, <trafficHitCount3>, ......],
      "trafficMiss" : [<trafficMissCount1>, <trafficMissCount2>, <trafficMissCount3>, ......]
   },
   "error" : <error>,
   "code" : <code>
}
```

| 参数                | 类型     | 说明                               |
| ----------------- | ------ | -------------------------------- |
| code              | int    | <a href="#statuscode">自定义状态码</a> |
| error             | string | 自定义错误描述                          |
| pointN            | string | 时间点，形如 2006-01-02-15-04          |
| hitCountN         | long   | pointN 时间点的命中次数                  |
| missCountN        | long   | pointN 时间点的未命中次数                 |
| trafficHitCountN  | long   | pointN 时间点的命中流量，单位 Byte          |
| trafficMissCountN | long   | pointN 时间点的未命中流量，单位 Byte         |

# 批量查询请求次数 [#批量查询请求次数]

接口地址

```
/v1/dcdn/loganalyze/reqcount
```

请求语法

```
POST /v1/dcdn/loganalyze/reqcount HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
    "domains": [<domain1>, <domain2>, <domain3>, ......],
    "freq": <freq>,
    "region": <region>,
    "startDate": <startDate>,
    "endDate": <endDate>
}
```

请求内容

| 参数        | 类型     | 说明                                        |
| --------- | ------ | ----------------------------------------- |
| domainN   | string | 域名列表，总数不超过100条                            |
| freq      | string | 粒度，可选项为 5min、1hour、1day                   |
| region    | string | 区域，可选项见 <a href="#region">Region 参数列表</a> |
| startDate | string | 开始时间，格式为：2006-01-02。起止最大间隔为31天            |
| endDate   | string | 结束时间，格式为：2006-01-02。起止最大间隔为31天            |

响应内容

```
HTTP/1.1 200 OK
Content-Type: application/json

{
   "data" : {
      "reqCount" : [<reqCount1>, <reqCount2>, <reqCount3>, ......],
      "points" : [<point1>, <point2>, <point3>, ......]
   },
   "error" : "success",
   "code" : 0
}
```

| 参数        | 类型     | 说明                               |
| --------- | ------ | -------------------------------- |
| code      | int    | <a href="#statuscode">自定义状态码</a> |
| error     | string | 自定义错误描述                          |
| pointN    | string | 时间点，形如 2006-01-02-15-04          |
| reqCountN | long   | pointN 时间点的请求次数                  |

# 批量查询 ISP 请求次数 [#批量查询-isp-请求次数]

接口地址

```
/v1/dcdn/loganalyze/ispreqcount
```

请求语法

```
POST /v1/dcdn/loganalyze/ispreqcount HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
    "domains": [<domain1>, <domain2>, <domain3>, ......],
    "freq": <freq>,
    "region": <region>,
    "startDate": <startDate>,
    "endDate": <endDate>
}
```

请求内容

| 参数        | 类型     | 说明                                        |
| --------- | ------ | ----------------------------------------- |
| domainN   | string | 域名列表，总数不超过100条                            |
| freq      | string | 粒度，可选项为 5min、1hour、1day                   |
| region    | string | 区域，可选项见 <a href="#region">Region 参数列表</a> |
| startDate | string | 开始时间，格式为：2006-01-02。起止最大间隔为31天            |
| endDate   | string | 结束时间，格式为：2006-01-02。起止最大间隔为31天            |

响应内容

```
HTTP/1.1 200 OK
Content-Type: application/json

{
   "data" : {
      "ispReq" : {
          <isp>: [<reqCount1>, <reqCount2>, <reqCount3>, ......]
      },
      "points" : [<point1>, <point2>, <point3>, ......]
   },
   "error" : "success",
   "code" : 0
}
```

| 参数        | 类型     | 说明                                                                                            |
| --------- | ------ | --------------------------------------------------------------------------------------------- |
| code      | int    | <a href="#statuscode">自定义状态码</a>                                                              |
| error     | string | 自定义错误描述                                                                                       |
| pointN    | string | 时间点，形如 2006-01-02-15-04                                                                       |
| isp       | string | ISP 运营商，包括  telecom（电信）、unicom（联通）、 mobile（移动）、drpeng（鹏博士）、tietong（铁通）、cernet（教育网）、others（其他） |
| reqCountN | long   | pointN 时间点的请求次数                                                                               |

# 批量查询 ISP 流量占比 [#批量查询-isp-流量占比]

接口地址

```
/v1/dcdn/loganalyze/isptraffic
```

请求语法

```
POST /v1/dcdn/loganalyze/isptraffic HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
  "domains": [<domain1>, <domain2>, <domain3>, ......],
  "regions": [<region1>, <region2>, <region3>, ......],
  "startDate": <startDate>,
  "endDate": <endDate>
}
```

| 参数        | 类型     | 说明                                       |
| --------- | ------ | ---------------------------------------- |
| domainN   | string | 域名列表，总数不超过100条                           |
| regionN   | string | 区域，选项见 <a href="#region">Region 参数列表</a> |
| startDate | string | 开始时间，格式为：2006-01-02。起止最大间隔为31天           |
| endDate   | string | 结束时间，格式为：2006-01-02。起止最大间隔为31天           |

返回包

```
200 OK

{
  "code": <code>,
  "error": <error>,
  "data": {
     "isp1": <value1>,
     "isp2": <value2>
  }
}
```

| 参数     | 类型     | 说明                               |
| ------ | ------ | -------------------------------- |
| code   | int    | <a href="#statuscode">自定义状态码</a> |
| error  | string | 自定义错误描述                          |
| ispN   | string | 运营商                              |
| valueN | float  | 运营商 ispN 对应的流量占总流量的比例            |

注：如果同时查询中国和上海的数据，会出现重复计算。

# 批量请求访问次数 Top IP [#批量请求访问次数-top-ip]

接口地址

```
/v1/dcdn/loganalyze/topcountip
```

请求语法

```
POST /v1/dcdn/loganalyze/topcountip HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
    "domains": [<domain1>, <domain2>, <domain3>, ......],
    "region": <region>,
    "startDate": <startDate>,
    "endDate": <endDate>
}
```

请求内容

| 参数        | 类型     | 说明                                        |
| --------- | ------ | ----------------------------------------- |
| domainN   | string | 域名列表，总数不超过100条                            |
| region    | string | 区域，可选项见 <a href="#region">Region 参数列表</a> |
| startDate | string | 开始时间，格式为：2006-01-02。起止最大间隔为31天            |
| endDate   | string | 结束时间，格式为：2006-01-02。起止最大间隔为31天            |

响应内容

```
HTTP/1.1 200 OK
Content-Type: application/json

{
   "data" : {
      "count" : [<count1>, <count2>, <count3>, ......],
      "ips": [<ip1>, <ip2>, <ip3>, ......]
   },
   "error" : "success",
   "code" : 0
}
```

| 参数     | 类型     | 说明                               |
| ------ | ------ | -------------------------------- |
| code   | int    | <a href="#statuscode">自定义状态码</a> |
| error  | string | 自定义错误描述                          |
| ipN    | string | IP                               |
| countN | long   | ipN 在查询时间区间内的访问次数，降序排列           |

# 批量请求访问流量 Top IP [#批量请求访问流量-top-ip]

接口地址

```
/v1/dcdn/loganalyze/toptrafficip
```

请求语法

```
POST /v1/dcdn/loganalyze/toptrafficip HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
    "domains": [<domain1>, <domain2>, <domain3>, ......],
    "region": <region>,
    "startDate": <startDate>,
    "endDate": <endDate>
}
```

请求内容

| 参数        | 类型     | 说明                                        |
| --------- | ------ | ----------------------------------------- |
| domainN   | string | 域名列表，总数不超过100条                            |
| region    | string | 区域，可选项见 <a href="#region">Region 参数列表</a> |
| startDate | string | 开始时间，格式为：2006-01-02。起止最大间隔为31天            |
| endDate   | string | 结束时间，格式为：2006-01-02。起止最大间隔为31天            |

响应内容

```
HTTP/1.1 200 OK
Content-Type: application/json

{
   "data" : {
      "traffic" : [<traffic1>, <traffic2>, <traffic3>, ......],
      "ips": [<ip1>, <ip2>, <ip3>, ......]
   },
   "error" : "success",
   "code" : 0
}
```

| 参数       | 类型     | 说明                              |
| -------- | ------ | ------------------------------- |
| code     | int    | 0 表示数据返回成功, 1 表示没有数据，2 表示其他未知错误 |
| error    | string | 自定义错误描述                         |
| ipN      | string | IP                              |
| trafficN | long   | ipN 在查询时间区间内的访问流量，单位 Byte。降序排列  |

# 批量请求访问次数 Top URL [#批量请求访问次数-top-url]

接口地址

```
/v1/dcdn/loganalyze/topcounturl
```

请求语法

```
POST /v1/dcdn/loganalyze/topcounturl HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
    "domains": [<domain1>, <domain2>, <domain3>, ......],
    "region": <region>,
    "startDate": <startDate>,
    "endDate": <endDate>
}
```

请求内容

| 参数        | 类型     | 说明                                        |
| --------- | ------ | ----------------------------------------- |
| domainN   | string | 域名列表，总数不超过100条                            |
| region    | string | 区域，可选项见 <a href="#region">Region 参数列表</a> |
| startDate | string | 开始时间，格式为：2006-01-02。起止最大间隔为31天            |
| endDate   | string | 结束时间，格式为：2006-01-02。起止最大间隔为31天            |

响应内容

```
{
   "data" : {
      "count" : [<count1>, <count2>, <count3>, ......],
      "urls": [<url1>, <url2>, <url3>, ......]
   },
   "error" : "success",
   "code" : 0
}
```

| 参数     | 类型     | 说明                               |
| ------ | ------ | -------------------------------- |
| code   | int    | <a href="#statuscode">自定义状态码</a> |
| error  | string | 自定义错误描述                          |
| urlN   | string | URL，去查询参数                        |
| countN | long   | urlN 在查询时间区间内的访问次数，降序排列          |

# 批量请求访问流量 Top URL [#批量请求访问流量-top-url]

接口地址

```
/v1/dcdn/loganalyze/toptrafficurl
```

请求语法

```
POST /v1/dcdn/loganalyze/toptrafficurl HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
    "domains": [<domain1>, <domain2>, <domain3>, ......],
    "region": <region>,
    "startDate": <startDate>,
    "endDate": <endDate>
}
```

请求内容

| 参数        | 类型     | 说明                                        |
| --------- | ------ | ----------------------------------------- |
| domainN   | string | 域名列表，总数不超过100条                            |
| region    | string | 区域，可选项见 <a href="#region">Region 参数列表</a> |
| startDate | string | 开始时间，格式为：2006-01-02。起止最大间隔为31天            |
| endDate   | string | 结束时间，格式为：2006-01-02。起止最大间隔为31天            |

响应内容

```
HTTP/1.1 200 OK
Content-Type: application/json

{
   "data" : {
      "traffic" : [<traffic1>, <traffic2>, <traffic3>, ......],
      "urls": [<url1>, <url2>, <url3>, ......]
   },
   "error" : "success",
   "code" : 0
}
```

| 参数       | 类型     | 说明                               |
| -------- | ------ | -------------------------------- |
| code     | int    | <a href="#statuscode">自定义状态码</a> |
| error    | string | 自定义错误描述                          |
| urlN     | string | URL，去查询参数                        |
| trafficN | long   | urlN 在查询时间区间内的访问流量，单位 Byte。降序排列  |

# 批量查询 UniqueVisitor [#批量查询-uniquevisitor]

接口地址

```
/v1/dcdn/loganalyze/uniquevisitor
```

请求语法

```
POST /v1/dcdn/loganalyze/uniquevisitor HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
    "domains": [<domain1>, <domain2>, <domain3>, ......],
    "freq": <freq>,
    "startDate": <startDate>,
    "endDate": <endDate>
}
```

请求内容

| 参数        | 类型     | 说明                             |
| --------- | ------ | ------------------------------ |
| domainN   | string | 域名列表，总数不超过100条                 |
| freq      | string | 粒度，可选项为 1hour、1day             |
| startDate | string | 开始时间，格式为：2006-01-02。起止最大间隔为31天 |
| endDate   | string | 结束时间，格式为：2006-01-02。起止最大间隔为31天 |

响应内容

```
HTTP/1.1 200 OK
Content-Type: application/json

{
   "data" : {
      "uvCount" : [<uvCount1>, <uvCount2>, <uvCount3>, ......],
      "points" : [<point1>, <point2>, <point3>, ......]
   },
   "error" : <error>,
   "code" : <code>
}
```

| 参数       | 类型     | 说明                               |
| -------- | ------ | -------------------------------- |
| code     | int    | <a href="#statuscode">自定义状态码</a> |
| error    | string | 自定义错误描述                          |
| pointN   | string | 时间点，形如 2006-01-02-15-04          |
| uvCountN | string | pointN 时间点的 UniqueVisitor 个数     |

<a id="region" />

# Region 参数列表 [#region-参数列表]

| 参数           | 说明   |
| ------------ | ---- |
| global       | 全球   |
| oversea      | 海外   |
| china        | 中国   |
| shandong     | 山东   |
| jiangsu      | 江苏   |
| zhejiang     | 浙江   |
| anhui        | 安徽   |
| shanghai     | 上海   |
| fujian       | 福建   |
| jiangxi      | 江西   |
| guangdong    | 广东   |
| guangxi      | 广西   |
| hainan       | 海南   |
| henan        | 河南   |
| hunan        | 湖南   |
| hubei        | 湖北   |
| beijing      | 北京   |
| tianjin      | 天津   |
| hebei        | 河北   |
| shanxi       | 山西   |
| neimenggu    | 内蒙古  |
| ningxia      | 宁夏   |
| qinghai      | 青海   |
| gansu        | 甘肃   |
| shaanxi      | 陕西   |
| sichuan      | 四川   |
| guizhou      | 贵州   |
| xinjiang     | 新疆   |
| yunnan       | 云南   |
| chongqing    | 重庆   |
| xizang       | 西藏   |
| liaoning     | 辽宁   |
| jilin        | 吉林   |
| heilongjiang | 黑龙江  |
| hongkong     | 香港   |
| macau        | 澳门   |
| taiwan       | 台湾   |
| unknown      | 未知地区 |


# 缓存刷新与查询 (/products/dcdn/7-dcdn-cache-refresh-with-the-query)



最近更新时间: 2022-04-28 23:56:37

缓存刷新，是指将缓存过的客户资源在 CDN 节点内设置为过期状态；当用户再次发起访问时，节点回源站拉取所需资源，并重新缓存在节点上。具体做法是客户提交资源 url 到 CDN，由 CDN 来操作刷新。

<a id="access-domain" />

# 访问域名 [#访问域名]

```
Host: fusion.qiniuapi.com
```

<a id="refresh-authenticated" />

# 认证授权 [#认证授权]

```
Authorization: <access_token>
```

access\_token 详细描述请查阅[这里](/products/kodo/development-guidelines/security/access-token)。

<a id="interface-address" />

## 接口地址 [#接口地址]

```
/v2/tune/refresh
```

<a id="refresh-request-message" />

# 刷新 [#刷新]

<a id="refresh-request-syntax" />

## 请求语法 [#请求语法]

```
POST /v2/tune/refresh HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
    "urls":[<url1>, <url2>, <url3>, ...],
    "dirs":[<dir1>, <dir2>, <dir3>, ...],
    "product":"dcdn",
}
```

<a id="refresh-request-body" />

## 请求内容 [#请求内容]

| 参数      | 类型     | 必要性 | 说明                                                                                                             |
| :------ | :----- | :-- | :------------------------------------------------------------------------------------------------------------- |
| urlN    | array  | 可选  | 要刷新的单个url列表，总数不超过60条；单个url，即一个具体的url，例如：`http://bar.foo.com/index.html`                                        |
| dirN    | array  | 可选  | 要刷新的目录url列表，总数不超过10条；目录dir，即表示一个目录级的url，例如：`http://bar.foo.com/dir/`，也支持在尾部使用通配符，例如：`http://bar.foo.com/dir/*` |
| product | string | 必选  | 此处填写固定值 dcdn                                                                                                   |

<a id="refresh-request-attentions" />

### 注意事项 [#注意事项]

* 请输入资源 url 完整的绝对路径，由 http\:// 或 https\:// 开始。
* 资源 url 不支持通配符，例如：不支持 `http://www.test.com/abc/\*.\*`。
* 进行目录刷新时，资源 url 需要以 / 结尾，例如：`http://www.test.com/abc/`。
* 带参数的 url 刷新，根据其域名缓存配置是否忽略参数缓存决定刷新结果。如果配置了时间戳防盗链的资源 url 提交时刷新需要去掉 sign 和 t 参数。
* 请求数量限制，以下限制达到任意一个即触发限制：
  * 每秒钟刷新请求和[预取请求](/products/dcdn/7-dcdn-cache-refresh-with-the-query)中的url、dir的总量限制为 240。
  * 每个请求中 url 的条数限制为 60 条。
  * 每个请求中 dir 的条数限制为 10 条。

<a id="refresh-response-status" />

## 响应状态码 [#响应状态码]

| HTTP状态码 | 含义                           | 说明                                                                   |
| :------ | :--------------------------- | :------------------------------------------------------------------- |
| 200     | success                      | 成功                                                                   |
| 400031  | invalid url                  | 请求中存在无效的 url，请确保 url 格式正确                                            |
| 400032  | invalid host                 | 请求中存在无效的域名，请确保域名格式正确                                                 |
| 400034  | refresh url limit error      | 请求次数超出当日刷新限额                                                         |
| 400036  | invalid request id           | 无效的请求 id                                                             |
| 400037  | url has existed              | url 正在刷新中                                                            |
| 400038  | refresh dir authority error  | 没有刷新目录的权限， 如果需要请联系[技术支持](https://support.qiniu.com/tickets/category) |
| 403024  | single user QPS Rate limited | 请求达到单用户QPS限制，请重试或联系我们                                                |
| 403022  | server QPS Rate limited      | 请求达到全局QPS限制，请联系我们                                                    |
| 500000  | internal error               | 服务端内部错误，请联系[技术支持](https://support.qiniu.com/tickets/category)        |

<a id="refresh-response-body" />

## 响应内容 [#响应内容]

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": <custom code>,
    "error": <error string>,
    "requestId": <request id>,
    "taskIds": <task id map>,
    "invalidUrls": [<url1>, <url2>, <url3>, ...],
    "invalidDirs": [<dir1>, <dir2>, <dir3>, ...],
    "urlQuotaDay": <url quota one day >,
    "urlSurplusDay": <url surplus one day >,
    "dirQuotaDay": <dir quota one day >,
    "dirSurplusDay": <dir surplus one day >,
}
```

| 参数            | 类型                 | 说明                                            |
| :------------ | :----------------- | :-------------------------------------------- |
| code          | int                | 自定义错误码，整型，见[自定义状态码](#refresh-response-status) |
| error         | string             | 自定义错误码描述，字符串                                  |
| requestId     | string             | 刷新请求id，只有在任务被接受时才有值                           |
| taskIds       | map\[string]string | URL/DIR 对应的任务 ID，map\[url/dir]taskId          |
| invalidUrls   | string array       | 无效的url列表                                      |
| invalidDirs   | string array       | 无效的dir列表                                      |
| urlQuotaDay   | int                | 每日的刷新url限额                                    |
| urlSurplusDay | int                | 每日的当前剩余的刷新url限额                               |
| dirQuotaDay   | int                | 每日的刷新dir限额                                    |
| dirSurplusDay | int                | 每日的当前剩余的刷新dir限额                               |

<a id="response-attention" />

### 注意事项 [#注意事项-1]

* 在请求成功时 code 为 200，requestId、urlQuotaDay、urlSurplusDay、dirQuotaDay、dirSurplusDay才会有有效值，否则为空。
* 在请求失败时 code 为非 200，error 中包含描述信息。

<a id="refresh-samples" />

## 刷新示例 [#刷新示例]

下面是命令行示例：

```
请求命令示例：
第一步生成token：
echo "/v2/tune/refresh" |openssl dgst -binary -hmac "用户SK" -sha1 |base64 | tr + - | tr / _      回车
生成的token

第二步发起请求：
curl -X POST -H "Authorization: QBox <用户AK>:<生成的token>" http://fusion.qiniuapi.com/v2/tune/refresh -d '{"urls":["<用户url>"],"product":"dcdn"}' -H 'Content-Type: application/json'

响应内容示例：
{"code":200,"error":"success","requestId":"575d1930f9537d3f2600003d","invalidUrls":null,"invalidDirs":null,"urlQuotaDay":100,"urlSurplusDay":99,"dirQuotaDay":10,"dirSurplusDay":10}
```

<a id="refreshlist-address" />

# 刷新查询 [#刷新查询]

<a id="refreshlist-interface-address" />

## 接口地址 [#接口地址-1]

```
/v2/tune/refresh／list
```

<a id="refresh-list-syntax" />

## 请求语法 [#请求语法-1]

```
POST http://<Host>/v2/tune/refresh/list
Authorization:<access_token>

{
    "requestId": <request id>,
    "taskId": <task id>,
    "isDir": <dir flag>,
    "urls":[<url1>, <url2>, <url3>, ...],
    "state": <state>,
    "pageNo": <page no>,
    "pageSize": <page size>,
    "startTime": <startTime>,
    "endTime": <endTime>,
    "product":"dcdn",
}
```

<a id="refresh-list-body" />

## 请求内容 [#请求内容-1]

| 参数        | 类型     | 必要性 | 说明                                      |
| :-------- | :----- | :-- | :-------------------------------------- |
| requestId | string | 可选  | 指定要查询记录所在的刷新请求id                        |
| taskId    | string | 可选  | 指定查询的单个任务 id                            |
| isDir     | string | 可选  | 指定是否查询目录，取值为 yes/no，默认不填则为两种类型记录都查询     |
| urls      | string | 可选  | 要查询的url列表，每个url可以是文件url，也可以是目录url       |
| state     | string | 可选  | 指定要查询记录的状态，取值processing／success／failure |
| pageNo    | int    | 可选  | 要求返回的页号，默认为0                            |
| pageSize  | int    | 可选  | 要求返回的页长度，默认为100                         |
| startTime | string | 可选  | 指定查询的开始日期，格式2006-01-01                  |
| endTime   | string | 可选  | 指定查询的结束日期，格式2006-01-01                  |
| product   | string | 必选  | 此处填写固定值 dcdn                            |

### 注意事项 [#注意事项-2]

* 输入参数可选部分全部为空时，服务端返回无效参数错误。
* 查询的时间范围：当天至当天的前6天（共7天）。
* startTime和endTime任一缺失的情况下，查询默认返回近3天的操作记录。

<a id="refreshlist-response-status" />

## 响应状态码 [#响应状态码-1]

| HTTP状态码 | 含义               | 说明        |
| :------ | :--------------- | :-------- |
| 200     | success          | 成功        |
| 400000  | invalid input    | 无效的输入参数   |
| 500000  | internal error   | 服务端内部错误   |
| 500005  | query data error | 服务端查询数据错误 |

<a id="refreshlist-response-body" />

## 响应内容 [#响应内容-1]

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": <custom code>,
	"error": <error string>,
    "total": <total count>,
    "pageNo": <page no>,
    "pageSize": <page size>,
    "currentSize": <current size>,
	"items": [{
		"uid": <user uid>,
		"requestId": <request id>,
		"url": <url>,
		"state": <state>,
		"stateDetail": <stateDetail>,
		"createAt": <create time>,
		"beginAt": <begin time>,
		"endAt": <end time>,
	}, ...],
}
```

| 参数          | 类型     | 说明                                                     |
| :---------- | :----- | :----------------------------------------------------- |
| code        | int    | 自定义错误码，整型，见[自定义状态码](#refreshlist-response-status)      |
| error       | string | 自定义错误码描述，字符串                                           |
| total       | int    | 当前条件下查询的记录总数                                           |
| pageNo      | int    | 要查询的页号                                                 |
| pageSize    | int    | 要返回的页长度                                                |
| currentSize | int    | 当前实际返回的页长度                                             |
| uid         | string | 用户id                                                   |
| requestId   | string | 记录所在的刷新请求id                                            |
| url         | string | url                                                    |
| state       | string | 刷新状态，取值为success／processing／failure                     |
| stateDetail | string | 刷新状态描述信息                                               |
| createAt    | string | 当前记录创建时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:05:05  |
| beginAt     | string | 当前记录开始时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:05:25。 |
| endAt       | string | 当前记录结束时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:09:05  |

<a id="refreshlist-samples" />

## 刷新查询示例 [#刷新查询示例]

下面是命令行示例：

```
请求命令示例：
第一步生成token：
echo "/v2/tune/refresh/list" |openssl dgst -binary -hmac "用户SK" -sha1 |base64 | tr + - | tr / _      回车
生成的token

第二步发起请求：
curl -X POST -H "Authorization: QBox <用户AK>:<生成的token>" http://fusion.qiniuapi.com/v2/tune/refresh/list -d '{"urls":["<用户url>"，"pageNo":<page no>,"pageSize":<page size>],"product":"dcdn"}' -H 'Content-Type: application/json'

响应内容示例：
{"code":200,"error":"success","total":1,"pageNo":0,"pageSize":10,"currentSize":1,"items":[{"uid":1100000009,"requestId":"57edce1a23232391821e303b","url":"http://www.test.com/test01","state":"success","stateDetail":"","createAt":"2015-09-30 10:29:46","beginAt":"2015-09-30 10:29:48","endAt":"2015-09-30 10:30:08"}]}

```


# 文件预取与查询 (/products/dcdn/8-dcdn-file-prefetching-and-query)



最近更新时间: 2022-04-18 14:37:53

文件预取，也可称为预加热或预缓存，是指客户新资源提前由 CDN 拉取到 CDN 缓存节点。具体做法是客户提交资源 url 到 CDN，由 CDN 来操作预取。

<a id="access-domain" />

# 访问域名 [#访问域名]

```
Host: fusion.qiniuapi.com
```

<a id="prefetch-authenticated" />

# 认证授权 [#认证授权]

```
Authorization: <access_token>
```

access\_token 详细描述请查阅[这里](/products/kodo/development-guidelines/security/access-token)。

<a id="prefetch-request-message" />

# 预取 [#预取]

<a id="interface-address" />

## 接口地址 [#接口地址]

```
/v2/tune/prefetch
```

<a id="prefetch-request-syntax" />

## 请求语法 [#请求语法]

```
POST /v2/tune/prefetch HTTP/1.1
Authorization:<access_token>
Content-Type: application/json

{
    "urls": [<url1>, <url2>, <url3>, ......],
    "product": "dcdn"
}
```

<a id="prefetch-request-body" />

## 请求内容 [#请求内容]

| 参数      | 类型     | 必要性 | 说明                                                                    |
| :------ | :----- | :-- | :-------------------------------------------------------------------- |
| urlN    | array  | 必选  | 要预取的单个url列表，总数不超过60条；单个url，即一个具体的url，例如：`http://bar.foo.com/test.zip` |
| product | string | 必选  | 此处填写固定值 dcdn                                                          |

<a id="request-attention" />

### 注意事项 [#注意事项]

* 请输入资源 url 完整的绝对路径，由 http\:// 或 https\:// 开始。
* 资源 url 不支持通配符，例如：不支持 `http://www.test.com/abc/\*.\*`。
* 请求数量限制，以下限制达到任意一个即触发限制：
  * 每秒钟预取请求和[刷新请求](/products/dcdn/8-dcdn-file-prefetching-and-query)中的 url、dir 的总量限制为 240。
  * 每个请求中 url 的条数限制为 60 。

<a id="prefetch-response-status" />

## 响应状态码 [#响应状态码]

| HTTP状态码 | 含义                           | 说明                           |
| :------ | :--------------------------- | :--------------------------- |
| 400031  | invalid url                  | 请求中存在无效的 url，请确保提交的 url 格式正确 |
| 400032  | invalid host                 | 请求中存在无效的域名，请确保域名格式正确         |
| 400033  | prefetch url limit error     | 请求次数超出当日预取限额                 |
| 400036  | invalid request id           | 无效的请求 id                     |
| 400037  | url has existed              | url 正在预取中                    |
| 403024  | single user QPS Rate limited | 请求达到单用户QPS限制，请重试或联系我们        |
| 403022  | server QPS Rate limited      | 请求达到全局QPS限制，请联系我们            |
| 500000  | internal error               | 服务端内部错误，请联系技术支持              |

<a id="prefetch-response-body" />

## 响应内容 [#响应内容]

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": <custom code>,
    "error": <error string>,
    "requestId": <request id>,
    "invalidUrls": [<url1>, <url2>, <url3>, ...],
    "quotaDay": <quota one day >,
    "surplusDay": <surplus one day >,
}
```

| 参数          | 类型           | 说明                                              |   |
| ----------- | ------------ | ----------------------------------------------- | - |
| code        | int          | HTTP 状态码，整型，见[响应状态码](#prefetch-response-status) |   |
| error       | string       | HTTP 状态码说明，字符串                                  |   |
| requestId   | string       | 预取请求 id，只有在任务被接受时才有值                            |   |
| invalidUrls | string array | 无效的 url 列表                                      |   |
| quotaDay    | int          | 每日的预取 url 限额                                    |   |
| surplusDay  | int          | 每日的当前剩余的预取 url 限额                               |   |

<a id="response-attention" />

### 注意事项 [#注意事项-1]

* 在请求成功时 code 为 200，requestId、quotaDay、surplusDay 才会有有效值，否则为空。
* 在请求失败时 code 为非 200，error 中包含描述信息。

<a id="prefetch-samples" />

## 预取示例 [#预取示例]

下面是命令行示例：

```
请求命令示例：
第一步生成token：
echo "/v2/tune/prefetch" |openssl dgst -binary -hmac "用户SK" -sha1 |base64 | tr + - | tr / _      回车
生成的token

第二步请求数据：
curl -X POST -H "Authorization: QBox <用户AK>:<生成的token>" http://fusion.qiniuapi.com/v2/tune/prefetch -d '{"urls":["<用户url>"], "product":"dcdn"}' -H 'Content-Type: application/json'

响应内容示例：
{"code":200,"error":"success","requestId":"577471ace3ab3a030c058972","invalidUrls":null,"quotaDay":100,"surplusDay":99}
```

<a id="prefetch-interface-address" />

# 预取查询 [#预取查询]

<a id="prefetchlist-interface-address" />

## 接口地址 [#接口地址-1]

```
/v2/tune/prefetch/list
```

<a id="prefetchlist-request-syntax" />

## 请求语法 [#请求语法-1]

```
POST http://<Host>/v2/tune/prefetch/list
Authorization:<access_token>

{
    "requestId": <request id>,
    "urls":[<url1>, <url2>, <url3>, ...],
    "state": <state>,
    "pageNo": <page no>,
    "pageSize": <page size>,
    "startTime": <startTime>,
    "endTime": <endTime>,
    "product": "dcdn",
}
```

<a id="prefetchlist-request-body" />

## 请求内容 [#请求内容-1]

| 参数        | 类型     | 必要性 | 说明                                       |
| :-------- | :----- | :-- | :--------------------------------------- |
| requestId | string | 可选  | 指定要查询记录所在的预取请求id。                        |
| urls      | string | 可选  | 要查询的url列表                                |
| state     | string | 可选  | 指定要查询记录的状态，取值processing／success／failure。 |
| pageNo    | int    | 可选  | 要求返回的页号，默认为0。                            |
| pageSize  | int    | 可选  | 要求返回的页长度，默认为100。                         |
| startTime | string | 可选  | 指定查询的开始日期，格式2006-01-01                   |
| endTime   | string | 可选  | 指定查询的结束日期，格式2006-01-01                   |
| product   | string | 必选  | 此处填写固定值 dcdn                             |

### 注意事项 [#注意事项-2]

* 输入参数可选部分全部为空时，服务端返回无效参数错误。
* 查询的时间范围：当天至当天的前6天（共7天)。
* startTime和endTime任一缺失的情况下，查询默认返回近3天的操作记录。

<a id="prefetchlist-response-status" />

## 响应状态码 [#响应状态码-1]

| HTTP状态码 | 含义               | 说明        |
| :------ | :--------------- | :-------- |
| 200     | success          | 成功        |
| 400000  | invalid input    | 无效的输入参数   |
| 500000  | internal error   | 服务端内部错误   |
| 500005  | query data error | 服务端查询数据错误 |

<a id="prefetchlist-response-body" />

## 响应内容 [#响应内容-1]

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": <custom code>,
	"error": <error string>,
    "total": <total count>,
    "pageNo": <page no>,
    "pageSize": <page size>,
    "currentSize": <current size>,
	"items": [{
		"uid": <user uid>,
		"requestId": <request id>,
		"url": <url>,
		"state": <state>,
		"stateDetail": <stateDetail>,
		"createAt": <create time>,
		"beginAt": <begin time>,
		"endAt": <end time>,
	}, ...],
}
```

| 参数          | 类型     | 说明                                                     |
| :---------- | :----- | :----------------------------------------------------- |
| code        | int    | 自定义错误码，整型，见[自定义状态码](#prefetchlist-response-status)     |
| error       | string | 自定义错误码描述，字符串                                           |
| total       | int    | 当前条件下查询的记录总数                                           |
| pageNo      | int    | 要查询的页号                                                 |
| pageSize    | int    | 要返回的页长度                                                |
| currentSize | int    | 当前实际返回的页长度                                             |
| uid         | int    | 用户id                                                   |
| requestId   | string | 记录所在的预取请求id                                            |
| url         | string | url                                                    |
| state       | string | 预取状态，取值为success/processing／failure                     |
| stateDetail | string | 预取状态描述信息                                               |
| createAt    | string | 当前记录创建时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:05:05  |
| beginAt     | string | 当前记录开始时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:05:25。 |
| endAt       | string | 当前记录结束时间，格式为xxxx-xx-xx xx:xx:xx，例如2015-11-01 16:09:05。 |

<a id="prefetchlist-samples" />

## 预取查询示例 [#预取查询示例]

下面是命令行示例：

```
请求命令示例：
第一步生成token：
echo "/v2/tune/prefetch/list" |openssl dgst -binary -hmac "用户SK" -sha1 |base64 | tr + - | tr / _      回车
生成的token

第二步请求数据：
curl -X POST -H "Authorization: QBox <用户AK>:<生成的token>" http://fusion.qiniuapi.com/v2/tune/prefetch/list -d '{"urls":["<用户url>","pageNo":<page no>,"pageSize":<page size>],"product":"dcdn"}' -H 'Content-Type: application/json'

响应内容示例：
{"code":200,"error":"success","total":1,"pageNo":0,"pageSize":10,"currentSize":1,"items":[{"uid":1100000009,"requestId":"57edcafafawwqtqt211e303b","url":"http://www.test.com/test01","state":"success","stateDetail":"","createAt":"2015-09-11 10:29:46","beginAt":"2015-11-30 10:29:48","endAt":"2015-11-30 10:30:08"}]}


```


# 域名归属校验 (/products/dcdn/9-domain-verify-information)



最近更新时间: 2022-08-02 17:18:16

# 获取域名验证信息 [#获取域名验证信息]

```
用户获取域名所有权验证信息接口
```

## 请求包 [#请求包]

```
GET /domain/<Name>/verify/info?product=<Product>
Authorization: QBox <QBoxToken>
Content-Type: application/x-www-form-urlencoded
```

### 参数解释 [#参数解释]

| 参数      | 类型     | 必填 | 含义                             |
| ------- | ------ | -- | ------------------------------ |
| Name    | string | 是  | 需要验证的域名                        |
| Product | string | 是  | 产品类型: `cdn`(静态加速)/`dcdn`(全站加速) |

## 返回包 [#返回包]

```
{
    domain: <Domain>,
    dns: <OwnerVerifyDnsInfo>,
    file: <OwnerVerifyFileInfo>,
    state: <State>
}
```

### 参数解释 [#参数解释-1]

| 参数     | 类型     | 含义                                                    |
| ------ | ------ | ----------------------------------------------------- |
| Domain | string | 用户需要验证的主域名,比如创建加速域名cdn.qiniu.com,需要验证主域名qiniu.com的所有权 |
| Dns    | object | DNS验证信息,用户需要在域名所属的DNS服务商上配置DNS解析完成验证                  |
| File   | object | 文件验证信息,用户需要在主域名所在服务器的根目录下配置验证文件                       |
| State  | string | 验证状态: `no_need`(不需要验证)/`doing`(待验证)/`success`(验证通过)   |

### DNS验证信息 [#dns验证信息]

| 参数          | 类型     | 含义   |
| ----------- | ------ | ---- |
| Host        | string | 主机记录 |
| RecordType  | string | 记录类型 |
| RecordValue | string | 记录值  |

### 文件验证信息 [#文件验证信息]

| 参数        | 类型     | 含义   |
| --------- | ------ | ---- |
| FileName  | string | 文件名称 |
| FileValue | string | 文件内容 |

**错误码**

| 错误码    | 含义       |
| ------ | -------- |
| 400079 | 未知的顶级域名  |
| 500005 | 数据查询内部出错 |

# 验证域名所有权 [#验证域名所有权]

```
用户验证域名所有权接口
```

## 请求包 [#请求包-1]

```
POST /domain/<Name>/verify/check HTTP/1.1
Content-Type: application/json
Authorization: QBox <QBoxToken>

{
	"type": <Type>,
	"product": <Product>
}
```

### 参数解释 [#参数解释-2]

| 参数      | 类型     | 必填 | 含义                              |
| ------- | ------ | -- | ------------------------------- |
| Name    | string | 是  | 域名, 如果是泛域名，必须以点号 . 开头           |
| Product | string | 是  | 产品类型: `cdn`(静态加速)/`dcdn`(全站加速)  |
| Type    | string | 是  | 验证类型: `dns`(DNS验证)/`file`(文件验证) |

## 返回包 [#返回包-1]

```
{}
```

**错误码**

| 错误码    | 含义                                                 |
| ------ | -------------------------------------------------- |
| 400000 | 未知的输入参数                                            |
| 400079 | 未知的顶级域名                                            |
| 400937 | 尚未查看域名验证值(未调用获取域名验证信息接口的情况下，直接调用验证域名所有权接口，会返回该错误码) |
| 400932 | 域名所有权验证失败                                          |
| 500004 | 更新数据内部出错                                           |
| 500005 | 数据查询内部出错                                           |

## 请求示例 [#请求示例]

```
POST /domain/testqiniu.qbox.net/verify/check HTTP/1.1
Authorization: QBox 0tf5awMVxwf8WrEvrjtbiZrdRZRJU-91JgCqTOC8:6oxDOtOXVEfcR8PPuAscmWjVRS8=
Host: api.qiniu.com

{
    "type": "dns"
}
```


# 更新动态 (/products/dora/0-update-the-dynamic1)



最近更新时间: 2021-07-22 15:53:32

智能多媒体服务的更新动态，&#x2A;*[点击此处查看](https://www.qiniu.com/product-news)**


# 什么是智能多媒体服务 (/products/dora/0-dora-product-introduction)



最近更新时间: 2026-04-30 18:02:41

智能多媒体服务（DORA），是一种零运维、高可用、高性能的多媒体数据处理服务。提供图片处理、音视频转码、水印、截图、瘦身等基础功能，并基于海量数据深度学习，对媒体内容实现智能审核、智能识别。

* 智能多媒体服务包括Web控制台、多媒体API、Open API，您可以通过它们使用多媒体处理服务。
* 基于容器技术打造了易扩展、易部署、高自由度的自定义多媒体数据处理平台，与七牛智能多媒体API服务无缝兼容使用。

# **如何使用媒体处理** [#如何使用媒体处理]

您可以通过以下几种方式来使用和管理媒体处理服务。

## 1）智能多媒体控制台 [#1智能多媒体控制台]

智能多媒体平台，是为了给您提供更好的多媒体处理服务体验，通过控制台几个简单步骤，将计算原子和逻辑条件进行灵活配置，精准打造云上自动生产线，有效提升视频处理效率。请参见[控制台介绍](/products/dora/console-guide/5-an-overview-of-the)。

## 2）智能多媒体API [#2智能多媒体api]

提供图片裁剪、缩放、格式转化、水印、原图保护和防盗链，音视频转码、切片和拼接等基础的多媒体处理服务，以及图片智能识别等服务，请参见[API文档]()。

## 3）Open API [#3open-api]

作为一个开放的应用平台，欢迎各种图片、音视频、以及其他智能多媒体处理与识别的第三方应用提供方接入，为七牛存储中的海量数据，提供增值的数据处理与识别服务，请参见[Open API 介绍](/products/dora/introduction-to-the-third-party-data-processing/0-the-third-party-data-processing)。

# **产品优势** [#产品优势]

媒体处理具有高性价比、强大的转码能力、专业的转码算法、功能丰富、高可定制、易用的媒体工作流等产品优势，请参见[产品优势](/products/dora/2-product-advantage1)。

# **功能特性** [#功能特性]

媒体处理提供转码、水印、截图、锐智转码、图片处理、文件处理、内容安全、内容识别、第三方服务等功能特性，请参见[功能特性](/products/dora/1-features_introduction)。

# **产品定价** [#产品定价]

媒体处理服务的基础计费项包括：音视频处理时长、服务接口请求次数。根据您的实际使用情况，对各计费项进行单独计量计费，不使用不计费，请参见[价格概览](https://www.qiniu.com/prices/dora?source=dora\&ref=developer.qiniu.com)。


# 功能特性 (/products/dora/1-features_introduction)



最近更新时间: 2026-04-30 18:09:58

智能多媒体服务的核心能力特性如下所示：

# 转码 [#转码]

| 类别   | 说明                                                                                                                         |
| ---- | -------------------------------------------------------------------------------------------------------------------------- |
| 封装格式 | 封装格式，具体细节请参考[支持转换的封装格式](/faq/dora/av-processing/1320-avthumb-parameters-formats-format-and-explanation)。                   |
| 转封装  | 不改变视频的编码方式，仅改变封装格式。支持音视频转封装为 MP4、M3U8、FLV 等格式。                                                                             |
| 视频编码 | 编码标准：h264、h265，默认为h264。具体细节请参考[支持转换的视频编码格式](/faq/dora/av-processing/1385-avthumb-parameter-vcodec-format-and-explanation)。 |
| 音频编码 | 默认值：AAC。具体细节请参考[支持转换的音频编码格式](/faq/dora/av-processing/1432-avthumb-parameter-acodec-format-and-explanation)。                |

# 视频编辑 [#视频编辑]

| 类别     | 说明                                                 |
| ------ | -------------------------------------------------- |
| 视频水印   | 支持在输出的视频上最多覆盖20个图片和文字水印。注：支持png、jpg、gif、apng 图片格式。 |
| 音视频拼接  | 用于将指定的数个音频片段拼接成一段音频，或者将数个视频片段拼接成一段视频。              |
| 添加字幕   | 支持 srt格式字幕、带有字幕的mkv文件、embed（将原视频的字幕流嵌入目标视频）。       |
| 添加混音   | 在原视频中加入期望的音视频文件。                                   |
| 替换音频文件 | 用于替换原视频中音频的目标音频文件。                                 |
| 添加马赛克  | 支持对视频特定位置进行马赛克处理。                                  |
| 去除音频   | 支持从视频文件中去除音频流。                                     |
| 去除视频   | 支持从视频文件中去除视频流。                                     |
| 去除字幕   | 支持从视频文件中去除字幕。                                      |
| 去除媒体流  | 从输入源中选择要保留的或者要去除的媒体流，流的编号可以通过 avinfo 来查看。          |

# 视频截图 [#视频截图]

| 类别      | 说明                                                                             |
| ------- | ------------------------------------------------------------------------------ |
| 视频帧缩略图  | 用于从视频流中截取指定时刻的单帧画面并按指定大小缩放成图片。<br /><br />对存储于 kodo 上的视频文件截取指定时间的JPG、PNG 格式图像。 |
| 视频采样缩略图 | 用于从视频文件中截取多帧画面并按指定大小缩放成图片。<br /><br />输出的目标截图格式，支持 JPG、PNG 等。                  |

# 锐智转码 [#锐智转码]

| 功能   | 说明                                                                                                                                                                                                                                                                                                                                          |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 锐智转码 | \*\*1.节省带宽：\*\*融合感知编码、深度学习、图像处理、画质增强等技术，在保证画质的前提下，节省 20% 以上码率，为用户降低成本。<br /><br />\*\*2.视频编码技术：\*\*根据视频内容自适应码率以及自适应分辨率，不同场景可以适配最优的算法提升压缩和画质效果，追求最佳的收益效果。<br /><br />\*\*3.提升画质：\*\*AI 视频前处理包括：去编码脏效应、去燥、去毛刺、锐化、饱和度增强、去模糊等，并引入 Vmaf 和 Mos 质量评价体系，提升视频主观画质。<br /><br /> \*\*4.精细处理：\*\*ROI 感兴趣区域识别，包括人脸、人眼聚焦、前景重点区域、及各个块的主观敏感度，对用户关注区域进行动态编码。 |

# 倍速转码 [#倍速转码]

| 功能   | 说明                                                        |
| ---- | --------------------------------------------------------- |
| 倍速转码 | 加速对视频资源进行编码。适用于25分钟以上的长视频，通过对视频分片并行转码，大幅提升转码速度，转码速度可提升3倍。 |

# 其他音视频功能 [#其他音视频功能]

| 类别       | 说明                                                                                                                                                                       |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 音视频分段    | 用于按时长或时间点对原视频分段，不改变原音/视频的编码格式、分辨率、码率等，将原音/视频切成多个较小的文件。<br /><br />注:如果原音视频文件的编码格式无法封装到目标封装格式，那么会返回错误。                                                                    |
| 音视频切片    | 用于支持 HTTP Live Streaming播放。<br /><br />HTTP Live Streaming 是由 Apple 提出的基于 HTTP 的流媒体传输协议。它将一整个音频、视频流切割成可由 HTTP 下载的一个个小的音视频流，并生成一个 M3U8 播放列表，客户端只需要获取资源的 M3U8 播放列表即可播放音视频。 |
| 音视频元信息   | 用于获取指定音频、视频资源的元信息。<br /><br />视频信息包括：编码标准、分辨率（宽/高）、码率、帧率等；音频信息包括：编码标准、声道、采样率、码率等。                                                                                        |
| 实时音视频转码  | 用于对已经上传到七牛云的音频、视频，在终端播放时按照指定参数进行实时转码。注意：该功能目前支持华东和华北的 bucket。                                                                                                            |
| 多码率自适应转码 | 用于对已经上传到七牛云的视频转码成包含多种码率的HLS视频流。以便能随着终端网络带宽的变化动态选择适应的码率播放。                                                                                                                |
| 私有M3U8   | 只能用于私有空间中的 m3u8 文件，作用是对 m3u8文件中的 ts 资源进行批量下载授权。<br /><br />通过将 ts 资源的 url 改写成私有 url，以临时获取访问权限。                                                                           |

# 图片处理 [#图片处理]

| 功能       | 说明                                                                                               |
| -------- | ------------------------------------------------------------------------------------------------ |
| 图片基本处理   | 可对图片进行缩略操作，生成各种缩略图。<br /><br />imageView2 接口可支持处理的原图片格式有 psd、jpeg、png、gif、webp、tiff、bmp。         |
| 图片高级处理   | 提供了一系列高级图片处理功能，包括缩放、裁剪、旋转等。<br /><br />imageMogr2 接口可支持处理的原图片格式有 psd、jpeg、png、gif、webp、tiff、bmp。 |
| 图片瘦身     | 将存储在七牛的JPEG、PNG格式的图片实时压缩而尽可能不影响画质。<br /><br />降低CDN分发成本<br /><br />加快客户端图片的加载速度，提升用户体验。          |
| 图片基本信息   | 可以获取图片格式、大小、色彩模型信息。<br /><br />在图片下载 URL 后附加 imageInfo 指示符（区分大小写），即可获取 JSON 格式的图片基本信息。           |
| 图片水印处理   | 提供四种水印接口：图片水印、文字水印，文字平铺水印、混合水印。                                                                  |
| 盲水印处理    | 为原图添加不可见水印，不影响原图质量。<br /><br />支持图片盲水印和文字盲水印。                                                    |
| 图片EXIF信息 | 专门为数码相机的照片设定的可交换图像文件格式，通过在图片下载URL后附加exif指示符（区分大小写）获取。                                            |
| 图片圆角处理   | 将图片生成圆角图片，并且可以指定图片的圆角大小。<br /><br />这个接口支持的原图片格式有png、jpg，处理后的图片格式为png。                           |
| 图片平均色调   | 用于计算一幅图片的平均色调，并以0xRRGGBB形式返回。                                                                    |
| 动图合成     | 用于将多张图片合成 GIF 动图。<br /><br />支持处理的原图片格式有 jpeg 和 png。                                             |

# 文件处理 [#文件处理]

| 功能      | 说明                                                                              |
| ------- | ------------------------------------------------------------------------------- |
| 文件HASH值 | 用于实时得到存储在七牛的文件的HASH值。<br /><br /> 目前支持华东、华南、华北三个区域的存储 bucket。                   |
| 文本文件合并  | 用于将数个七牛云上的源文件的二进制内容按指定顺序合并到新文件。<br /><br />不能用于音视频拼接和图片拼接。                      |
| 多文件压缩   | 为用户提供了批量文件的压缩存储功能。                                                              |
| MD转HTML | 支持直接将七牛云存储上的 Markdown 类型的资源转为 HTML 文件并返回。                                       |
| 资源下载二维码 | 用于为存放在七牛云存储上的资源的下载URL或资源内容生成二维码图片，方便用户在各种客户端之间传播资源。<br /><br />所生成的二维码图片格式为png。 |

# 内容安全 [#内容安全]

| 类别     | 说明                                                                                                                           |
| ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| 图片内容审核 | 主要用于检测或识别图片中的不良信息，并给出审核结果管控建议。支持的审核类型包括：<br /><br />1. 图片鉴黄<br /><br />2. 图片鉴暴恐<br /><br />3. 图片敏感人物识别<br /><br />4. 图片广告识别。 |
| 视频内容审核 | 主要用于检测或识别视频中的不良信息，并给出审核结果管控建议支持的审核类型包括：<br /><br />1. 视频鉴黄<br /><br />2. 视频鉴暴恐<br /><br />3. 视频敏感人物识别。                       |

# 内容识别\# [#内容识别]

| 类别       | 说明                                                                                                                                 |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| OCR身份证识别 | 对存储在七牛云 bucket（支持华东、华北和华南 bucket）或 非七牛云 bucket 的身份证正反面图片进行智能识别，可得到身份证中姓名、性别、民族、住址和身份证号码等关键信息。<br /><br />目前支持的图片格式有 png、jpg 和 bmp。 |
| 人脸识别     | 业界领先的人脸检测、五官关键点定位、人脸属性分析和快速的人脸聚类功能，包括以下能力：<br /><br />1. 人脸检测<br /><br />2. 1:1人脸比对<br /><br />3. 1:N人脸比对。                         |

# 第三方服务 [#第三方服务]

| 类别      | 服务提供商 | 说明                                                                                                                                                               |
| ------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 图片鉴黄    | 图普科技  | 能够帮您有效判断保存在七牛云存储的空间中的图片是属于色情、性感还是正常。<br /><br />关于接口的详细信息请参阅[图普科技图片鉴黄服务](/products/dora/1-features_introduction)。                                                |
| 图片鉴暴恐   | 图普科技  | 帮您识别保存在七牛云空间中的图片是属于暴恐还是非暴恐，并给出判断分数。 <br /><br />关于接口的详细信息请参阅[图普科技图片鉴暴恐服务](/products/dora/1-features_introduction)。                                               |
| 短视频鉴黄   | 图普科技  | 能够帮您有效判断保存在七牛云的视频是属于色情，性感还是正常。<br /><br />关于接口的详细信息请参阅[图普科技视频鉴黄服务](/products/dora/1-features_introduction)。                                                      |
| 图片广告过滤  | 图普科技  | 帮您判断保存在七牛云的图片是否属于广告。<br /><br />关于接口的详细信息请参阅[图普科技广告过滤服务](/products/dora/1-features_introduction)。                                                                |
| 广告过滤增强版 | 图普科技  | 能够帮您有效判断保存在七牛云的带文字图片是否属于广告，如果图片被识别为带有文字，会将对应的文字内容识别出来反馈给您，可以方便的根据文本信息去判断是否是广告内容。<br /><br />关于接口的详细信息请参阅[图普科技广告过滤服务增强版](/products/dora/1-features_introduction)。 |
| 垃圾评论过滤  | 达观数据  | 能够帮您有效判断保存在七牛云的文本是否属于广告以及文本质量如何。<br /><br />关于接口的详细信息请参阅[达观垃圾评论过滤服务](/products/dora/1-features_introduction)。                                                    |
| 文本鉴黄鉴政  | 达观数据  | 能够帮您有效判断保存在七牛云的文本是属于色情、政治违规还是正常。<br /><br />关于接口的详细信息请参阅[达观数据文本鉴黄鉴政服务](/products/dora/1-features_introduction)。                                                  |
| 文本反垃圾   | 阿里    | 能够有效帮助您检测出您的文本中是否存在违规的风险内容，高效过滤色情、广告、涉政、暴恐等多类垃圾文字及敏感词。<br /><br />关于接口的详细信息请参阅[阿里文本反垃圾服务](/products/dora/1-features_introduction)。                               |
| 图片广告审核  | 阿里    | 能够有效帮助您检测出您的图片中是否存在违规的风险内容，识别图片中的广告以及文字违规信息。<br /><br />关于接口的详细信息请参阅[阿里图片广告审核服务](/products/dora/1-features_introduction)。                                        |
| 语音审核    | 阿里    | 能够有效帮助您检测出您的音视频中的语音是否存在违规的风险内容。<br /><br />关于接口的详细信息请参阅[阿里音频审核服务](/products/dora/1-features_introduction)。                                                       |
| 风格迁移    | versa | 能够有效的将图片与风格转换成目标图片风格。<br /><br />关于接口的详细信息请参阅versa 风格迁移服务。                                                                                                       |
| 人像分割    | versa | 能够帮您有效的把图片中人物与背景单独分离开。<br /><br />关于接口的详细信息请参阅[versa 人像分割](/products/dora/1-features_introduction)  。                                                            |
| 实例分割    | versa | 有效的将图片中不同实例分别与背景分离。<br /><br />关于接口的详细信息请参阅[versa 人像分割](/products/dora/1-features_introduction)  。                                                               |
| 智能填充    | versa | 有效的将图像中的指定区域进行修复重建或者去除图像中的多余物体。<br /><br />关于接口的详细信息请参阅[versa 智能填充](/products/dora/1-features_introduction)  。                                                   |


# 产品优势 (/products/dora/2-product-advantage1)



最近更新时间: 2021-07-22 15:42:48

**稳定可靠**

* 近千台高性能物理机组成的处理集群，可支撑大规模高并发处理需求
* 每日处理请求数百亿次，服务可用性达到 99.99%

**高性价比**

* 无需前期投资，只按实际用量付费
* 锐智转码和和H.265技术，同等视频质量，文件更小，节省大量宽带和存储成本。

**灵活接入**

* 成熟完善 SDK 和 API ，调用方式简单，缩短产品开发运维时间
* 专业服务团队 7X24 小时服务

**功能丰富**

* 视频转码、截图、水印、拼接等丰富的媒体处理功能满足各种应用场景
* 高可扩展的媒体处理模板，支持自定义处理，满足多样化的媒体数据处理需求

**识别准确**

* 内容审核、场景识别、物体检测功能处于业界领先水平
* 平均复审率低于 10%，大幅降低运营成本


# 查看账单&用量 (/products/dora/0-look-at-the-bill)



最近更新时间: 2021-10-26 16:06:41

# 查看消费明细 [#查看消费明细]

您可以通过控制台查看多媒体处理服务详细的计量计费信息。

1. 登录 [七牛云管理控制台首页](https://portal.qiniu.com/home)。

2. 单击顶部导航栏中的 **费用**，进入【财务中心】。

3. 单击左侧菜单 **账单**

   ![img](/docs-assets/products/dora/%282-buying-guide%29/0-look-at-the-bill/WX20201216-163030-a3b5a41c2add.webp)

4. 从账单列表中，点击【账单编号】，进入账单详情，查看多媒体处理的消费情况。

   ![img](/docs-assets/products/dora/%282-buying-guide%29/0-look-at-the-bill/WX20201216-163322-abbbc3539c96.webp)

# 查看订单明细 [#查看订单明细]

您可以通过控制台，查看多媒体资源包购买记录。

1. 登录 [七牛云管理控制台首页](http://home.console.aliyun.com/new?spm=a2c4g.11186623.2.4.yRY9cZ#)。

2. 单击顶部导航栏中的 **费用**，进入【财务中心】。

3. 单击左侧菜单 **订单列表**

   ![img](/docs-assets/products/dora/%282-buying-guide%29/0-look-at-the-bill/WX20201216-163742-f0199c4d708e.webp)

4. 从订单列表中，点击【详情】按钮，查看订单详情。

   ![img](/docs-assets/products/dora/%282-buying-guide%29/0-look-at-the-bill/WX20201216-163923-e234fd46aa1d.webp)

# 资源用量 [#资源用量]

您可以查看每个服务的资源用量数据。

1. 登录[七牛云控制台](https://portal.qiniu.com/create)。
2. 单击导航栏中的“智能多媒体”，进入智能多媒体服务页。
3. 如：单击左侧“官方API -> 基础音视频处理 -> 视频截图”，设置查询条件，筛选出需要查看的使用量数据。
   ![](/docs-assets/products/dora/%282-buying-guide%29/0-look-at-the-bill/ziyuanyongliang-a972ef0c6d7e.webp)


# 防黑产图片盗刷 (/products/dora/0-anti-blackmail-image-theft)



最近更新时间: 2024-05-27 15:24:25

# **背景** [#背景]

用户通过使用七牛对象存储、CDN等服务来搭建自身业务（比如个人网站、短视频业务、内容创作社区等），享受稳定高效可靠的数据存储分发服务的同时，也面临着一些黑产用户来盗刷流量的问题。虽然对象存储提供了[多种防盗刷手段](/products/kodo/data-security-best-practices/3-reduce-the-risk-of-be-malicious-access-stolen) 来帮助开发者降低存储空间被恶意访问、流量盗刷的风险。但是从问题根源入手，就是对常见的图片内容进行分析检测。

本文介绍的是 [图片异常检测](/products/dora/image-processing-api/13-abnormal-image-detection) 的能力，通过检测图片中是否包含除图片以外的可疑文件，例如 MPEG-TS 文件，精准检测出异常图片文件，可以对该类图片文件进行删除禁用，防止存储空间被非法盗用，精准打击黑产盗刷行为。

* **图片内容伪装**，隐蔽性最强也是最常见的黑产手段，黑产用户通过App开发者的接口将伪装的图片（比如违规的视频TS文件），上传到云存储。图片文件上传后，黑产用户在黑产业务里将伪装后的图片通过CDN URL 下载后还原播放。此类问题场景经常发生在UGC业务场景，由于黑产是通过正常的接口上传伪装过的文件，App开发者很难察觉到自己被黑产入侵，当发生大量的盗刷流量，产生大量的费用消耗时App开发者才会进行问题排查，且排查、止损过程繁琐复杂。

![](/docs-assets/products/dora/%285-best-practices%29/0-anti-blackmail-image-theft/image2024-5-23_10-27-29-004bff67b254.webp)

# **功能介绍** [#功能介绍]

针对存储在对象存储kodo上的图片，智能多媒体服务提供了图片异常检测功能，可以检测图片中是否存在可以文件，有以下三种使用方式。

| 使用方式             | 配置类型      | 说明                                                                                                            |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
| 上传到kodo后自动触发检测   | 通过控制台配置使用 | 通过配置 [增量审核任务](https://portal.qiniu.com/kodo/censor)，图片上传时自动触发异常图片检测功能，可对存在异常的图片进行封禁处理。                        |
| 对kodo中存量文件进行批量检测 | 通过控制台配置使用 | 通过配置  [存量审核任务](https://portal.qiniu.com/kodo/censor)，对历史存量图片进行检测，将存在异常的图片进行封禁、删除等处理。                          |
| 使用接口检测kodo中的单个图片 | 通过API接口使用 | 调用接口检测对象存储中的某个图片是否隐含其他类型的可疑文件，详情请查看 [异常图片检测](/products/dora/image-processing-api/13-abnormal-image-detection) |

### **限制说明** [#限制说明]

* 支持格式：JPG、JPEG、PNG、BMP、GIF、WEBP，及纯TS视频流（仅更改后缀）

### **使用方式一：上传到kodo后自动触发检测** [#使用方式一上传到kodo后自动触发检测]

如果您的业务存在上传图片的场景，建议您创建 [增量审核任务](https://portal.qiniu.com/kodo/censor)，即图片上传时自动触发异常图片检测功能。参考以下步骤进行配置：

1. 进入对象存储控制台页面，在左边导航栏中，选择【存储安全→ 内容审核】，选择增量审核，点击【新建任务】。

   ![](/docs-assets/products/dora/%285-best-practices%29/0-anti-blackmail-image-theft/image2024-5-23_11-20-13-8c1cd77f31d4.webp)

2. 新建增量任务页面，配置如下内容，并创建保存。

* 存储空间：必填

* 前缀：选填项

* 文件名过滤：选填项

* 文件类型：必填，此处选择图片

* 审核类型：必填，此处选择异常检测

* 自动禁用：选填，`此处最好勾选`，如果检测到有异常图片就自动禁用，禁用后该文件将无法被公开访问，达到防盗刷的效果。

* 回调地址：选填，如果勾选了自动禁用，可以不填；如果不勾选自动禁用，建议配置回调地址，后续手动处理异常图片（比如禁用、删除）。

* 队列：必填

  ![](/docs-assets/products/dora/%285-best-practices%29/0-anti-blackmail-image-theft/image2024-5-23_11-23-46-f70e18bd5856.webp)

3. 保存后，该增量审核任务创建成功，且立即被开启生效，后续上传的文件都将自动进行异常图片检测处理。

   ![](/docs-assets/products/dora/%285-best-practices%29/0-anti-blackmail-image-theft/image2024-5-23_14-12-33-6e6604426c38.webp)

4. 点击【结果复核】，查看异常图片检测详情。

   ![](/docs-assets/products/dora/%285-best-practices%29/0-anti-blackmail-image-theft/image2024-5-23_14-18-13-3f0612ce7f87.webp)

### **使用方式二：对kodo中存量文件进行批量检测** [#使用方式二对kodo中存量文件进行批量检测]

如果您的业务在对象存储上有历史图片数据存在被黑产盗刷的风险，建议您创建 [存量审核任务](https://portal.qiniu.com/kodo/censor)，对历史存量图片进行检测，将存在异常的图片进行封禁、删除等处理。参考以下步骤进行配置：

1. 进入对象存储控制台页面，在左边导航栏中，选择【存储安全→ 内容审核】，选择增量审核，点击【新建任务】。

   ![](/docs-assets/products/dora/%285-best-practices%29/0-anti-blackmail-image-theft/image2024-5-23_14-38-9-c2f5a1cd96a1.webp)

2. 新建存量任务页面，配置如下内容，并创建保存。

* 存储空间：必填

* 文件名过滤：选填项，支持按文件名前缀去筛选文件

* 选择文件时间：选填项，支持按照时间维度去筛选文件

* 文件类型：必填，此处选择图片

* 审核类型：必填，此处选择异常检测

* 队列：必填

  ![](/docs-assets/products/dora/%285-best-practices%29/0-anti-blackmail-image-theft/image2024-5-23_14-24-57-ec430b4373b4.webp)

3. 保存后，该存量审核任务创建成功，且立即开始审核处理，会都符合过滤规则的文件全部进行异常图片检测处理。

   ![](/docs-assets/products/dora/%285-best-practices%29/0-anti-blackmail-image-theft/image2024-5-23_14-42-18-f2c25a0b4237.webp)

4. 等到存量审核任务执行完成后，请先通过【结果复核】， 确认审核结果是否正确、符合预期。便于后续对存量结果进行封禁/删除等处理，避免误封/误删资源。

   ![](/docs-assets/products/dora/%285-best-practices%29/0-anti-blackmail-image-theft/image2024-5-23_14-58-36-114f9bc13c22.webp)

5. 如果需要对存量的结果进行处理，点击【更多→ 存量结果】进行操作。目前支持封禁、删除、导出三种处理方式。

* 审核结果，选择【违规】；审核类型，选择【异常检测】

* 确认选择异常检测的结果文件，可以对结果文件进行封禁、删除、导出处理

  ![](/docs-assets/products/dora/%285-best-practices%29/0-anti-blackmail-image-theft/image2024-5-23_15-0-7-f8745b45e5dc.webp)

### **使用方式三：使用接口检测kodo中的单个图片** [#使用方式三使用接口检测kodo中的单个图片]

如果您希望在自己的业务代码中使用异常图片检测功能，可以调用接口检测对象存储中的某个图片是否隐含其他类型的可疑文件。

* 可以通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing) 或 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 的方式来调用
* 接口详情，请查看 [异常图片检测](/products/dora/image-processing-api/13-abnormal-image-detection)

# **服务价格** [#服务价格]

| 类型     | 价格       |
| :----- | :------- |
| 异常图片检测 | 0.1 元/千次 |


# 服务等级协议(SLA) (/products/dora/12736-service-level-agreements-slas-2024)



最近更新时间: 2024-07-22 16:01:00

生效日期：2024年7月22日

**为使用七牛云智能多媒体服务（以下简称“本服务”），您应当阅读并遵守《七牛云对象存储服务等级协议》（以下简称“本协议”或“SLA”），以及[《七牛云服务用户协议》](https://www.qiniu.com/user-agreement)和[《七牛云隐私权政策》](https://www.qiniu.com/privacy-right)。本协议包含本服务的术语和定义、服务可用性/服务成功率等级指标、赔偿方案、免责条款等相关内容。请您务必审慎阅读、充分理解各条款内容，特别是限制、免责条款或者其他涉及您重大权益的条款，这类条款可能会以加粗等形式提示您重点注意。**

**除非您已充分阅读、完全理解并接受本协议所有条款，否则，请您不要购买本服务。您单击“同意”、“下一步”或您的购买、使用等行为或者您以其他任何明示或者默示方式表示接受本协议的，即视为您已阅读并同意本协议的约束。本协议即在您与七牛云之间产生法律效力，成为对双方均具有约束力的法律文件。**

# **1.定义和术语** [#1定义和术语]

**七牛云智能多媒服务**：本协议向用户提供七牛云智能多媒体数据处理的付费服务，但不包括以下服务类型：

（1）用户自定义的数据处理服务

**服务周期**：是指购买本服务的服务期限所包含的自然月。如用户是3月11日开通服务，则服务周期计算到3月31日。

**月度服务费**：指客户的某一个七牛云账号在一个自然月中使用七牛云智能多媒体服务按区域和服务类型分别统计的服务费用。如果客户一次性支付了多个月份的服务费用（即购买资源包），则将按照使用量比例分摊计算月度服务费用。

**有效请求**：七牛云智能多媒体服务端收到的请求视为有效请求，**但不包括以下类型**：

（1）未通过身份验证和鉴权失败的请求或欠费停服状态下的请求

（2）账号欠费状态下的请求（即HTTP状态码403的请求）

**错误请求**：使用七牛云智能多媒体服务，由七牛云服务返回的内部错误（错误状态码 5XX），**但不包括以下类型的请求**：

（1）由智能多媒体服务发起的合理升级、变更、停机而导致的错误请求或服务不可用情况；

（2）由于客户业务受到攻击而导致被智能多媒体服务限制的请求；

（3）内容违规或其他原因导致域名被封禁而产生的错误；

**每5分钟错误请求**：根据区域统计的失败请求，以每 5 分钟为单位按照如下方式计算：

```
每5分钟错误率=每5分钟失败请求数/每5分钟有效总请求数 ×100%
```

# **2.服务可用性** [#2服务可用性]

## **2.1服务可用性计算方式** [#21服务可用性计算方式]

七牛智能多媒体服务根据不同区域统计对应的服务可用性，根据服务周期内每5分钟错误率之和➗服务周期内5分钟的总个数，计算出每5分钟错误率的平均值，从而计算出服务可用性，即：

```
服务可用性=（1-服务周期内的每5分钟错误率之和/服务周期内的5分钟总个数) ×100%
```

\*\*注意：\*\*服务周期内的5分钟总个数=12 x 24 x 该服务周期的天数

## **2.2服务可用性承诺** [#22服务可用性承诺]

**智能多媒体服务承诺，服务可用性不低于 99.9%** 。如七牛云智能多媒体服务未达到上述服务可用性承诺，客户可依据本协议第3条约定获得赔偿。

# **3.赔偿方案** [#3赔偿方案]

客户账号按区域统计服务周期内的服务可用性，如服务可用性低于标准，您可按照以下条款约定获得赔偿。

## **3.1赔偿标准** [#31赔偿标准]

（1）赔偿只针对已经使用七牛云智能多媒体数据处理服务并且支付费用的用户；赔偿方式仅限于用于支付七牛云多媒体数据处理服务的抵用券，抵用券的使用遵循七牛云发布的相关规则。

（2）赔偿额按照服务可用性未达标的服务月度及区域单独计算，以具体区域未达标服务所对应的月度服务费为基数计算，且赔偿总额不超过该区域未达标服务所对应的月度服务费。赔偿额具体计算方式如下（下表中的“月度服务费”指具体区域未达标服务所对应的月度服务费）：

| 服务可用性              | 赔偿抵用券金额   |
| ------------------ | --------- |
| 低于99.9%但等于或高于99.0% | 月度服务费的10% |
| 低于99.0%但等于或高于95.0% | 月度服务费的25% |
| 低于95%              | 月度服务费的50% |

## **3.2赔偿申请时限** [#32赔偿申请时限]

（1）客户可以每月 **第五个工作日** 后，对上个服务周期没有达到可用性的服务，通过账户的工单系统提出赔偿申请。赔偿申请提出后七牛云会进行相应审核，对于服务周期的服务可用性计算，若双方出现争议，**双方均同意最终以七牛云的后台记录为准**。

（2）赔偿申请必须在服务可用性未达标的服务周期结束后两（2）个月内提出。若在两（2）个月内未提出赔偿申请，或是在服务可用性未达标的服务周期结束后的两（2）个月以后才提出赔偿申请，均视为客户主动放弃要求赔偿及向七牛云主张其他权利的权利，七牛云有权不受理客户的赔偿申请，不对客户进行任何赔偿或补偿。

# **4.免责条款** [#4免责条款]

详见[《七牛云服务用户协议》](https://www.qiniu.com/user-agreement?ref=developer.qiniu.com) 中"免责条款"部分的相关内容。由于以下原因造成的服务不可用，相应服务不可用时间不属于服务不可用的计算范畴和七牛云的赔偿范围，七牛云无需向客户承担责任：

* **用户自定义数据处理的服务可用性，由开发者自己负责保障，不适用本 SLA；**

* **七牛云预先通知客户后进行系统维护所引起的，包括割接、维修、升级和模拟故障演练；**

* **任何七牛云所属设备以外的网络、设备或配置调整引起的故障;**

* **客户的应用程序或数据信息受到黑客攻击而引起的；**

* **客户维护不当或保密不当致使数据、口令、密码等丢失或泄漏所引起的；**

* **客户自行升级操作系统所引起的；**

* **客户的应用程序或安装活动所引起的；**

* **客户的疏忽或由用户授权的操作所引起的；**

* **不可抗力以及意外事件引起的；**

* **其他非七牛云原因所造成的不可用或服务不达标；**

* **属于相关法律法规、相关协议、相关规则或七牛云单独发布的相关规则、说明等中所述的七牛云可以免责、免除赔偿责任等的情况**

# **5.其他** [#5其他]

* 本协议一经公布立即生效，七牛云有权随时对协议内容进行修改。如用户不同意七牛云对本协议相关内容所做的修改，用户有权停止使用七牛云数据处理服务。若用户继续使用七牛云数据处理服务，则视为用户接受七牛云对本协议相关内容所做的修改。
* 本协议项下七牛云智能多媒体数据处理服务对于用户所有的通知均可通过网页公告、站内信、电子邮件、手机短信或其他方式进行；该通知于发送之日视为已送达收件人。
* 本协议的订立、执行和解释及争议的解决均应适用中国法律并受中国法院管辖。如双方就本协议内容或其执行发生任何争议，双方应尽量友好协商解决；协商不成时，任何一方均可向上海市浦东新区人民法院提起诉讼。
* 本协议构成双方对本协议之约定事项及其他有关事宜的完整协议，除本协议规定的之外，未赋予本协议各方其他权利。
* 如本协议中的任何协议无论因何种原因完全或部分无效或不具有执行力，本协议的其余部分仍应有效并且有约束力。
* 七牛云智能多媒体服务SLA历史版本：《服务等级协议(SLA)》(2021年07月23日版)。


# 产品更新动态 (/products/kodo/0-product-news)



最近更新时间: 2026-05-08 12:07:49

| 时间                    | 功能                                        | 描述                                                                                                 | 备注                                                                                                                                 |
| --------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <div>2026.03.20</div> | <div>**HTML2Markdown 自适应**</div>          | 支持空间自适应，在指定域名访问 HTML 对象时可响应 Markdown 内容。                                                           | [使用手册](/products/kodo/development-guidelines/dev-the-data-processing/6-auto-html2md)\<br>[最佳实践](/products/kodo/4-html2markdown-ai) |
| <div>2025.09.30</div> | <div>**使用大模型视觉理解对象存储**</div>              | 支持使用大模型直接视觉理解对象存储中的文件，通过内网服务就近处理，减少响应时间、避免产生外网流量。模型支持直接理解携带数据处理命令的文件 URL。                          | 存量运营                                                                                                                               |
| <div>2025.04.08</div> | <div>**上线半托管 Agent 数据迁移模式**</div>         | 数据迁移功能新增半托管 Agent 模式，用户需要在自有服务器部署 Agent 以启动已创建的迁移任务，支持独享计算和网络带宽资源。新增定时迁移，支持按固定或自定义间隔迁移时间、指定定时执行次数。 | [最佳实践](/products/kodo/data-migration)<br />[使用手册](/products/kodo/data-migration)                                                   |
| <div>2025.02.19</div> | <div>**上线空间清单功能**</div>                   | 上线空间清单功能，支持自定义规则，以列举空间中的文件、获取文件大小、存储类型、文件类型等信息，帮助用户列举和管理空间中海量文件。                                   | 公开测试阶段<br />[空间清单](/products/kodo/development-guidelines/management-of-storage-space/15-bucket-inventory)                          |
| <div>2024.08.12</div> | <div>**上线智能分层存储类型**</div>                 | 上线智能分层存储，适用于访问模式不固定或者无法预估访问模式的数据。                                                                  | [智能分层简介](/products/kodo/kodo-category/0-storage-class-intelligent-tiering)                                                         |
| <div>2024.07.31</div> | <div>**上线 西北-陕西1 区域**</div>               | 上线 西北-陕西1 区域，满足公有云客户日益增长的业务需求。                                                                     | [区域说明](/products/kodo/2-region-endpoint-fq)                                                                                        |
| <div>2024.05.16</div> | <div>**上线 亚太-胡志明 区域**</div>               | 上线 亚太-胡志明 区域，满足公有云客户日益增长的业务出海需求。                                                                   | [区域说明](/products/kodo/2-region-endpoint-fq)                                                                                        |
| <div>2024.05.07</div> | <div>**上线数据迁移功能**</div>                   | 上线数据迁移功能，支持全托管式的在线数据迁移、提供可视化界面，帮助用户轻松管理数据迁移任务。                                                     | [最佳实践](/products/kodo/data-migration)<br />[使用手册](/products/kodo/data-migration)                                                   |
| <div>2024.03.27</div> | <div>**上线实时转码**</div>                     | 上线实时转码，可以即播即转、秒级开播，为用户提供全新的转码体验。                                                                   | 公开测试阶段 <br />[使用手册](/products/kodo/development-guidelines/dev-the-data-processing/2-video-process)                                 |
| <div>2024.03.20</div> | <div>**上线传输加速**</div>                     | 上线传输加速，为云存储互联网的上传、下载提供端到端的加速方案。                                                                    | [使用手册](/products/kodo/development-guidelines/1-transfer-acceleration)                                                              |
| <div>2023.12.25</div> | <div>**上线归档直读存储类型**</div>                 | 上线归档直读存储类型，适用于长期保存需要极低频次实时读取的数据。                                                                   | 全部区域上线<br />[类型说明](/products/kodo/kodo-category#archive_ir)                                                                        |
| <div>2023.11.09</div> | <div>**上线 亚太-河内 区域**</div>                | 上线 亚太-河内 区域，满足公有云客户日益增长的业务出海需求。                                                                    | [区域说明](/products/kodo/2-region-endpoint-fq)                                                                                        |
| <div>2022.07.08</div> | <div>**Kodo Browser 1.0.18**</div>        | 多方面优化工具的上传体验，提升小文件批量上传性能。客户端上传任务调度速度在小文件批量上传场景提升 3\~4 倍                                            | [使用手册](/products/kodo/1-kodo-browser)                                                                                              |
| <div>2022.04.15</div> | <div>**Rust 官方 SDK 上线**</div>             | 专注于强大的编译时正确性保证语言  Rust 官方 SDK 上线。                                                                  | [使用手册](/products/kodo/6-rust)                                                                                                      |
| <div>2022.03.17</div> | <div>**上线深度归档存储类型**</div>                 | 上线深度归档存储类型，存储单价最低、解冻时间比归档存储更长，适合存放需要保留超长时间、但访问非常少的极冷数据。                                            | 全部区域上线<br />[类型说明](/products/kodo/kodo-category#deep_archive)                                                                      |
| <div>2022.01.20</div> | <div>**目录式文件管理**</div>                    | 七牛云对象存储 Portal 界面新增目录式文件管理功能，支持用户通过目录来管理空间内的文件。                                                    | 全部区域上线                                                                                                                             |
| <div>2021.08.23</div> | <div>**Kodo Browser 1.0.14**</div>        | 新增了修改文件存储类型的操作，支持批量解冻归档存储文件、批量修改存储类型。                                                              | 全部区域上线<br />[使用手册](/products/kodo/1-kodo-browser)                                                                                  |
| <div>2021.08.03</div> | <div>**图片样式管理支持 IAM Policy**</div>        | 支持IAM用户授权后，管理图片样式和样式分隔符。                                                                           | 全部区域上线                                                                                                                             |
| <div>2021.07.12</div> | <div>**修改文件状态支持 IAM Policy**</div>        | 支持IAM用户授权后，禁用或启用文件。                                                                                | 全部区域上线                                                                                                                             |
| <div>2021.05.11</div> | <div>**新区域上线**</div>                      | 华东-浙江2 区域上线                                                                                        | [区域详情](/products/kodo/2-region-endpoint-fq)                                                                                        |
| <div>2021.03.18</div> | <div>**Kodo Browser 1.0.13**</div>        | 支持公有云的授权空间管理、支持自定义文件列举条目数。                                                                         | 全部区域上线<br />[使用手册](/products/kodo/1-kodo-browser)                                                                                  |
| <div>2020.11.23</div> | <div>**存储计量查询支持 IAM Policy**</div>        | 支持IAM用户授权后，查询存储计量数据、做同步/异步文件抓取上传。                                                                  | 全部区域上线                                                                                                                             |
| <div>2020.10.21</div> | <div>**Kodo Browser 1.0.11**</div>        | 支持使用空间绑定的 cdn 域名预览、下载文件。                                                                           | 全部区域上线<br />[使用手册](/products/kodo/1-kodo-browser)                                                                                  |
| <div>2020.08.27</div> | <div>**Kodo Browser 1.0.10**</div>        | 支持 IAM 用户通过客户端管理存储资源。                                                                              | 全部区域上线<br />[使用手册](/products/kodo/1-kodo-browser)                                                                                  |
| <div>2020.08.27</div> | <div>**S3 支持 IAM Policy**</div>           | S3API 支持 IAM 用户的对接使用和权限控制。                                                                         | 全部区域上线                                                                                                                             |
| <div>2020.03.18</div> | <div>**Kodo Browser 1.0.8**</div>         | 支持多账号切换、批量导出文件URL等。                                                                                | 全部区域上线<br />[使用手册](/products/kodo/1-kodo-browser)                                                                                  |
| <div>2020.02.28</div> | <div>**S3 CORS**</div>                    | 兼容 AWS 的 S3 CORS。                                                                                  | 全部区域上线<br />[了解详情](/products/kodo/development-guidelines/aws-s3-compatible/compatible-s3-api)                                      |
| <div>2020.02.07</div> | <div>**Qiniu Jenkins Plugin 1.0.1**</div> | 纳入Jenkins官方插件列表，可以从Jenkins系统的插件列表中直接安装。                                                            | [使用手册](/products/kodo/5-qiniu-jenkins-plugin)                                                                                      |
| 2020.01.06            | **kodoimport**                            | 数据迁移工具，可以轻松将本地或其它云存储的数据迁移到七牛云存储。<br />同时适用于公/私有云的应用场景。                                             | [使用手册](/products/kodo/6435-kodoimport)                                                                                             |
| 2020.01.03            | **Qiniu Jenkins Plugin**                  | 支持将 Jenkins 构建产生的文件保存到七牛云存储，以及从七牛云下载已保存的构建文件到本地，无需占用本地的存储资源。<br />同时适用于公/私有云的应用场景。                 | [使用手册](/products/kodo/5-qiniu-jenkins-plugin)                                                                                      |
| 2020.01.01            | **归档存储**                                  | 存储安全、持久且成本极低，最大程度满足冷数据存储的低成本需求，适合需要长期保存、但在存储周期内极少需要被访问的归档数据存储场景，比如档案数据、医疗影像、科学资料、长期备份数据等。          | <div>全部区域上线</div>[了解详情](/products/kodo/kodo-category#archive)                                                                      |
| 2019.12.31            | **S3 ACL**                                | 兼容 AWS 的 S3 ACL。                                                                                   | 全部区域上线<br />[了解详情](/products/kodo/development-guidelines/aws-s3-compatible/compatible-s3-api)                                      |
| 2019.11.28            | **Kodo Browser 1.0.6**                    | 新增外部路径功能：经由S3API Bucket Policy 授予权限的空间或目录，添加为「外部路径」，即可在客户端中使用和管理。                                  | [使用手册](/products/kodo/1-kodo-browser)                                                                                              |
| 2019.11.15            | **存储空间标签**                                | 使用存储空间标签对 Bucket 进行分类管理。                                                                           | 全部区域上线<br />[操作手册](/products/kodo/development-guidelines/management-of-storage-space/5-dev-space-label)                            |
| 2019.11.15            | **S3 Bucket Policy**                      | 兼容 AWS 的 S3 Bucket Policy。细粒度的Bucket和Objects权限控制，支持设置IP黑、白名单。                                      | 全部区域上线<br />[了解详情](/products/kodo/development-guidelines/aws-s3-compatible/compatible-s3-api/0-bucketpolicy)                       |
| 2019.11.05            | **IPv6**                                  | 对象存储正式支持IPv6协议，支撑用户业务的平滑升级。                                                                        | [了解详情](https://blog.qiniu.com/archives/8885?ref=www.qiniu.com)                                                                     |
| 2019.10.22            | **事件通知**                                  | 设定空间事件通知规则，以及时获取存储资源重要操作的消息通知。                                                                     | [操作手册](/products/kodo/development-guidelines/management-of-storage-space/8-dev-event-notification)                                 |
| 2019.10.22            | **Referer 防盗链**                           | 支持空间 Referer 防盗链设置，防止数据被盗用，支持 Referer 的黑、白名单设置。                                                    | [操作手册](/products/kodo/development-guidelines/dev-data-security/0-dev-preventing-hotlinking)                                        |
| 2019.10.22            | **跨域资源共享（CORS）**                          | 跨域资源共享（CORS），是HTML5提供的标准跨域解决方案。七牛云对象存储支持 CORS 标准以实现跨域访问。                                           | [操作手册](/products/kodo/development-guidelines/management-of-storage-space/6-dev-cross-domain-resource-sharing)                      |
| 2019.10.16            | **Kodo Browser 1.0.4**                    | 新增复制文件外链功能、私有云系统的区域配置界面、上传/下载的限速控制与配置、版本更新检测与下载功能；同时发布了Linux x64客户端。                               | [使用手册](/products/kodo/1-kodo-browser)                                                                                              |
| 2019.09.20            | **Terraform**                             | 通过 Terraform 管理七牛云对象存储的空间和对象资源。                                                                    | [使用手册](/products/kodo/the-third-party-software-extension-support/0-kodo-terraform)                                                 |
| 2019.07.24            | **Kodo Browser**                          | 图形化管理工具，支持用户通过可视化界面进行上传、下载、移动、复制和重命名等操作。<br />同时适用于公/私有云的应用场景。                                     | [使用手册](/products/kodo/1-kodo-browser)                                                                                              |
| 2019.07.03            | **S3APIV2**                               | 新版的AWS S3兼容接口，兼容性更好、功能更全面。                                                                         | 全部区域上线<br />[了解详情](/products/kodo/development-guidelines/aws-s3-compatible)                                                        |


# 2021 年 08 月 1 日起低频存储数据取回降价通知 (/products/kodo/1-price-off-notice)



最近更新时间: 2026-03-26 17:20:37

尊敬的七牛云用户，您好！
感谢您对七牛云对象存储（KODO）产品的支持，为了更加灵活的调整同一计费项不同区域计费价格，平台将于 2021 年 8 月 1 日将账单中部分费用描述拆分到各个区域级别费用描述。具体拆分费用描述包含：PUT/DELETE 请求、GET 请求、低频存储 PUT/DELETE 请求、低频存储 GET 请求、存储类型转换类请求、低频存储数据取回。同时，我们非常高兴地宣布 2021 年 8 月 1 日起，`国内区域（华东-浙江2、华南、华东、华北）的 低频存储数据取回 降价为 0.03 元/GB，降幅达 50%` 。我们长期坚持不断优化成本结构，释放积累的技术红利，反哺消费者。
具体计费说明：

<table align="center">
  <tbody><tr><td>费用描述</td><td>区域级别费用描述</td><td>计量</td><td>价格</td></tr><tr><td rowspan="12">PUT/DELETE 请求</td><td rowspan="2">PUT/DELETE 请求-华东-浙江2</td><td>0 - 10 万次</td><td>免费</td></tr><tr><td>10 万次以上</td><td>0.01 元/万次</td></tr><tr><td rowspan="2">PUT/DELETE 请求-华南</td><td>0 - 10 万次</td><td>免费</td></tr><tr><td>10 万次以上</td><td>0.01 元/万次</td></tr><tr><td rowspan="2">PUT/DELETE 请求-华东</td><td>0 - 10 万次</td><td>免费</td></tr><tr><td>10 万次以上</td><td>0.01 元/万次</td></tr><tr><td rowspan="2">PUT/DELETE 请求-华北</td><td>0 - 10 万次</td><td>免费</td></tr><tr><td>10 万次以上</td><td>0.01 元/万次</td></tr><tr><td rowspan="2">PUT/DELETE 请求-北美</td><td>0 - 10 万次</td><td>免费</td></tr><tr><td>10 万次以上</td><td>0.01 元/万次</td></tr><tr><td rowspan="2">PUT/DELETE 请求-东南亚</td><td>0 - 10 万次</td><td>免费</td></tr><tr><td>10 万次以上</td><td>0.01 元/万次</td></tr><tr><td rowspan="12">GET 请求</td><td rowspan="2">GET 请求-华东-浙江2</td><td>0 - 10 万次</td><td>免费</td></tr><tr><td>10 万次以上</td><td>0.01 元/万次</td></tr><tr><td rowspan="2">GET 请求-华南</td><td>0 - 10 万次</td><td>免费</td></tr><tr><td>10 万次以上</td><td>0.01 元/万次</td></tr><tr><td rowspan="2">GET 请求-华东</td><td>0 - 10 万次</td><td>免费</td></tr><tr><td>10 万次以上</td><td>0.01 元/万次</td></tr><tr><td rowspan="2">GET 请求-华北</td><td>0 - 10 万次</td><td>免费</td></tr><tr><td>10 万次以上</td><td>0.01 元/万次</td></tr><tr><td rowspan="2">GET 请求-北美</td><td>0 - 10 万次</td><td>免费</td></tr><tr><td>10 万次以上</td><td>0.01 元/万次</td></tr><tr><td rowspan="2">GET 请求-东南亚</td><td>0 - 10 万次</td><td>免费</td></tr><tr><td>10 万次以上</td><td>0.01 元/万次</td></tr><tr><td rowspan="6">低频存储 PUT/DELETE 请求</td><td>低频存储 PUT/DELETE 请求-华东-浙江2</td><td colspan="2">0.1 元/万次</td></tr><tr><td>低频存储 PUT/DELETE 请求-华南</td><td colspan="2">0.1 元/万次</td></tr><tr><td>低频存储 PUT/DELETE 请求-华东</td><td colspan="2">0.1 元/万次</td></tr><tr><td>低频存储 PUT/DELETE 请求-华北</td><td colspan="2">0.1 元/万次</td></tr><tr><td>低频存储 PUT/DELETE 请求-北美</td><td colspan="2">0.1 元/万次</td></tr><tr><td>低频存储 PUT/DELETE 请求-东南亚</td><td colspan="2">0.1 元/万次</td></tr><tr><td rowspan="6">低频存储 Get 请求</td><td>低频存储 Get 请求-华东-浙江2</td><td colspan="2">0.1 元/万次</td></tr><tr><td>低频存储 GET 请求-华南</td><td colspan="2">0.1 元/万次</td></tr><tr><td>低频存储 GET 请求-华东</td><td colspan="2">0.1 元/万次</td></tr><tr><td>低频存储 GET 请求-华北</td><td colspan="2">0.1 元/万次</td></tr><tr><td>低频存储 GET 请求-北美</td><td colspan="2">0.1 元/万次</td></tr><tr><td>低频存储 GET 请求-东南亚</td><td colspan="2">0.1 元/万次</td></tr><tr><td rowspan="6">存储类型转换类请求</td><td>存储类型转换类请求-华东-浙江2</td><td colspan="2">0.1 元/万次</td></tr><tr><td>存储类型转换类请求-华南</td><td colspan="2">0.1 元/万次</td></tr><tr><td>存储类型转换类请求-华东</td><td colspan="2">0.1 元/万次</td></tr><tr><td>存储类型转换类请求-华北</td><td colspan="2">0.1 元/万次</td></tr><tr><td>存储类型转换类请求-北美</td><td colspan="2">0.1 元/万次</td></tr><tr><td>存储类型转换类请求-东南亚</td><td colspan="2">0.1 元/万次</td></tr><tr><td rowspan="6">低频存储数据取回</td><td>低频存储数据取回-华东-浙江2</td><td colspan="2">0.03 元/GB</td></tr><tr><td>低频存储数据取回-华南</td><td colspan="2">0.03 元/GB</td></tr><tr><td>低频存储数据取回-华东</td><td colspan="2">0.03 元/GB</td></tr><tr><td>低频存储数据取回-华北</td><td colspan="2">0.03 元/GB</td></tr><tr><td>低频存储数据取回-北美</td><td colspan="2">0.06 元/GB</td></tr><tr><td>低频存储数据取回-东南亚</td><td colspan="2">0.06 元/GB</td></tr></tbody>
</table>

温馨提示：若在使用过程中遇到任何问题，您可以 [ 提交工单 ](https://support.qiniu.com/tickets/new/form?category=%E5%85%B6%E4%BB%96%E7%B1%BB%E5%92%A8%E8%AF%A2\&space=%E5%AF%B9%E8%B1%A1%E5%AD%98%E5%82%A8) 进行反馈，我们将竭诚为您服务！

此致

七牛云KODO团队


# 存储类型转换次数计费项变更 (/products/kodo/2-chtype-billing-item-changes)



最近更新时间: 2022-06-07 16:57:56

自 2022 年 7 月 1 日起，七牛云对象存储将把各区域的「存储类型转换次数」合并记入对应区域和存储类型的「PUT/DELETE 请求次数」中，不再单独做「存储类型转换次数」的计量和计费。

调整前，中国大陆用户「存储类型转换次数」计费说明如下：\
![img](/docs-assets/products/kodo/%280-product-dynamic%29/2-chtype-billing-item-changes/FiRUv2hu8cuQt4-kERfC9USndkUR-cc8cd3a0b103.webp)

调整后，中国大陆用户「存储类型转换次数」可以复用标准存储类型的「PUT/DELETE 请求次数」免费额度，并按各存储类型的「PUT/DELETE 请求次数」单价结算费用。

![img](/docs-assets/products/kodo/%280-product-dynamic%29/2-chtype-billing-item-changes/FmGrHMS62rtftb_OdlGXy6YbImPh-803d93093a1e.webp)

调整前，海外用户「存储类型转换次数」计费说明如下：\
![img](/docs-assets/products/kodo/%280-product-dynamic%29/2-chtype-billing-item-changes/FvvGfYxU2RZhNggIhv_9bU5qmgvi-ccd2e0c733ad.webp)

调整后，海外用户「存储类型转换次数」可以复用标准存储类型的「PUT/DELETE 请求次数」免费额度，并按各存储类型的「PUT/DELETE 请求次数」单价结算费用。\
![img](/docs-assets/products/kodo/%280-product-dynamic%29/2-chtype-billing-item-changes/FjpA9JjETljlxdOpL9tkWj62l7FX-7e180e4464f1.webp)


# 对象存储空间访问域名安全策略升级 (/products/kodo/3-safety-visit)



最近更新时间: 2026-04-07 10:18:47

**影响时间**
2026-04-08 10:00:00 (UTC+08) 起

<br />

**升级内容**
为提升七牛云对象存储服务（Kodo）的安全性和合规性管理，我们将于北京时间 2026 年 04 月 08 日 10:00:00 起，针对该日期之后全区域新创建的空间进行使用安全的升级：
使用 Kodo 提供的 **CDN 测试域名**或 **S3 协议的空间外网访问域名**

* 通过浏览器访问文件时，不会显示文件内容，而是以附件形式进行下载，并在返回头部中增加两个 Header：
  ```
  X-Kodo-Force-Download：true
  Content-Disposition: attachment
  ```
* 不支持静态页面、重定向功能

使用 Kodo 提供的 **S3 协议的空间外网访问域名**

* 访问 apk、ipa、exe 等类型文件时，禁止下载

<br />

**应对方案**
使用自定义域名访问 Kodo 的请求，Response Header 中不会加上此信息，也不会执行附件形式下载。如需使用自定义域名访问 Kodo，请参考[绑定源站域名](/products/kodo/development-guidelines/management-of-storage-space/12-dev-the-binding-source-domain-name)。

我们理解这些变动可能对您的业务流程产生影响，如有任何疑问或帮助，请随时[提交工单](https://support.qiniu.com/tickets/category)联系我们。感谢您的理解与配合。


# 编程模型 (/products/kodo/0-programming-model)



最近更新时间: 2022-03-02 11:56:24

以保护数据安全和考虑架构合理性为出发点，我们对基于<span id="Productname">七牛云存储</span>服务如何进行开发提供了一些设计和编码建议。希望开发者在使用<span id="Productname">七牛云存储</span>服务之前详细阅读这些建议，并尽可能的符合这些原则，以免造成不必要的时间浪费和带来数据安全风险。

<a id="basic-structure" />

# 基本结构 [#基本结构]

基于<span id="Productname">七牛云存储</span>服务构建的应用，建议使用如下基本架构：

![基本模型](/docs-assets/products/kodo/%281-product-introduction%29/0-programming-model/FuAHhZgiYaHTDqLritFe1K85AVrI-13b6734821ba.webp)

从该结构图，我们可以看到以下几个关键组件：

* <span id="Productname">
    七牛云存储服务
  </span>

  <span id="Productname">七牛云存储</span>服务是以<span id="Keyvalue">[键值对](/products/kodo/1-product-introduction#2)</span>方式提供非结构化资源存储服务。向业务服务器提供资源管理服务，向客户端提供资源上传和下载服务。

* 业务服务器

  业务服务器需要开发者自行管理和维护，并且至少提供如下几个基本功能：

  * 生成各种安全凭证（参考[安全机制](/products/kodo/development-guidelines/security)），安全凭证的创建不能在客户端进行，否则会产生极大的安全风险。
  * 上传域名等跟随安全凭证一起下发给客户端，提高域名等变更灵活性。各区域域名情况参考 [域名列表](/products/kodo/2-region-endpoint-fq)
  * 使用关系型数据库（例如MySQL）管理用户帐号信息。最终用户信息的管理并非<span id="Productname">云存储</span>服务的功能范畴。云存储服务只管理企业账号。
  * 使用数据库管理资源元数据和资源之间的关联关系。
  * 响应客户端的业务请求，执行业务流程并返回执行结果。

* 客户端

  客户端通常同时是资源的生产方和消费方。客户端在展示内容时，通常需要先从业务服务器获取资源的元信息，并得到必要的[下载凭证](/products/kodo/development-guidelines/security/0-download-token)，然后使用下载凭证从<span id="Productname">七牛云存储</span>服务获取待展示的资源内容，从而实现一个完整的内容展示过程。

<a id="workflow" />

# 业务流程 [#业务流程]

关键的几个交互过程：

* 上传

  客户端在上传资源到<span id="Productname">七牛云存储</span>之前要先从业务服务器获取一个有效的[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)，因此需要先后和两个服务端打交道。

  ![基本上传流程](/docs-assets/products/kodo/%281-product-introduction%29/0-programming-model/Fmy1Y_s9I4oCPYuMGDrvYxCRv2FM-92269d5e3fbc.webp)

  如果有设置回调，则上传完成时<span id="Productname">七牛云存储</span>会自动发起回调到指定的业务服务器。

  ![带回调的上传流程](/docs-assets/products/kodo/%281-product-introduction%29/0-programming-model/FkPZ31ECmtGnEisOahMKc5kQkuRr-5c74deed5544.webp)

* 下载

  公开资源不需要对应的下载凭证，客户端可以直接从<span id="Productname">七牛云存储</span>下载对应资源。私有资源需要对应的下载凭证，因此必须先和业务服务器打交道。

  按照实际的使用场景，客户端对于内容的展示非常类似一个动态网页的生成过程，因此无论该页面内容是公开还是私有，均需要从业务服务器获取展示该页面的动态布局信息。所以通常显示过程也是需要先后和业务服务器及<span id="Productname">七牛云存储</span>服务打交道。

* 资源管理

  为了防止安全漏洞，资源管理操作应该只在业务服务器端进行。如果允许客户端进行资源管理，即使将[管理凭证](/products/kodo/development-guidelines/security/access-token)的生成动作放到业务服务器端进行，仍然很容易被第三方截获请求全文，从而导致重放攻击的风险。

<a id="principle" />

# 关键原则 [#关键原则]

这个模型的关键点如下：

* 整个架构中需要一个业务服务器组件。
* 无论如何，<span id="AKSK">[访问密钥（AK/SK）](/faq/kodo/1334-the-access-key-secret-key-encryption-key-safe-use-instructions)</span>均不得包含在客户端的分发包中（如二进制代码、配置文件或网页中）。
* SecretKey不得在任何场景中的公网上传输，更不得传输到客户端。
* 业务服务器端应维持一个用于管理资源元数据的数据库和一个用于管理最终用户账号信息的数据库。
* 原则上客户端和<span id="Productname">七牛云存储</span>之间的交互只有上传和下载，不应使用任何其他的API。


# 产品概述 (/products/kodo/1-product-introduction)



最近更新时间: 2021-01-12 10:41:33

七牛云对象存储 Kodo 是七牛云提供的高可靠、强安全、低成本、可扩展的存储服务。您可通过控制台、API、SDK 等方式简单快速地接入七牛存储服务，实现海量数据的存储和管理。通过 Kodo 可以进行文件的上传、下载和管理。

此外，Kodo 的姊妹产品[融合 CDN](https://www.qiniu.com/products/fusion)可以对文件下载进行加速，[智能多媒体 API](https://www.qiniu.com/products/dora)更是提供了丰富的基于海量数据深度学习算法的计算机视觉服务，如人脸技术、场景物体识别、OCR 文字识别和内容审核等。

<br />

Kodo 主要应用于以下一些场景：

### **在线存储和分发** [#在线存储和分发]

七牛云对象存储提供高可用和高可靠的对象存储服务，您可以放心的将各种内容存储在云端。利用七牛云对象存储的扩展性和按需付费的优势，可以满足您持续快速增长的存储需求。您也可以搭配使用七牛云的对象存储和[融合 CDN](https://www.qiniu.com/products/fusion)服务，实现全球覆盖、快速高效的内容分发。

### **镜像存储** [#镜像存储]

七牛云对象存储支持镜像存储，这是一种快速的数据迁移和加速服务。可以帮助您实现无缝数据迁移，迁移过程中并不影响原有业务系统的访问。镜像存储适用于迁移原有业务系统的已有数据。

### **备份和归档** [#备份和归档]

七牛云对象存储提供高可用和高可靠的存储解决方案来备份和归档您的关键数据。通过七牛云的身份验证机制可以设置不同的访问权限和级别，保障您数据的访问安全。相比传统自建的备份和归档存储系统，您无需在业务初期采购高昂硬件，无需担心数据增长带来的扩容问题，从而节省更多的存储成本、维护成本和人力资源成本。

### **富媒体数据处理** [#富媒体数据处理]

针对海量的用户生成内容，七牛云对象存储能够提供跨地域、高并发的内容上传和访问服务。同时结合七牛云提供的数据处理服务，可以在云端实现图片裁剪、格式转化和水印，以及视频转码、切片和拼接等富媒体处理功能，满足移动网络场景下多终端设备的访问需求。

### **静态资源托管** [#静态资源托管]

七牛云对象存储无缝集合各类第三方扩展插件，如 WordPress、Discuz、Emlog 等，并支持一键将各类插件里的静态资源托管到七牛云对象存储。


# 存储区域 (/products/kodo/2-region-endpoint-fq)



最近更新时间: 2025-12-02 18:30:25

## 区域信息 [#区域信息]

* 对象存储 **亚太-河内、亚太-胡志明** 区域，现已转存量运营。

## 区域和访问域名 [#区域和访问域名]

| 存储区域 Region  | 区域 Region ID   | 域名                                                                                                                                                                                                                                                                                                             |
| ------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 华东-浙江        | z0             | 空间管理：`http(s)://uc.qiniuapi.com`<br /> 源站上传：`http(s)://up-z0.qiniup.com`<br />源站下载：`http(s)://iovip-z0.qiniuio.com`<br /> 对象管理：`http(s)://rs-z0.qiniuapi.com`<br /> 对象列举：`http(s)://rsf-z0.qiniuapi.com`<br />  计量查询：`http(s)://api.qiniuapi.com`                                                              |
| 华东-浙江2       | cn-east-2      | 空间管理：`http(s)://uc.qiniuapi.com`<br /> 源站上传：`http(s)://up-cn-east-2.qiniup.com`<br />源站下载：`http(s)://iovip-cn-east-2.qiniuio.com`<br /> 对象管理：`http(s)://rs-cn-east-2.qiniuapi.com`<br /> 对象列举：`http(s)://rsf-cn-east-2.qiniuapi.com`<br />计量查询：`http(s)://api.qiniuapi.com`                                    |
| 华北-河北        | z1             | 空间管理：`http(s)://uc.qiniuapi.com`<br />源站上传：`http(s)://up-z1.qiniup.com` <br />源站下载：`http(s)://iovip-z1.qiniuio.com` <br /> 对象管理：`http(s)://rs-z1.qiniuapi.com`<br /> 对象列举：`http(s)://rsf-z1.qiniuapi.com`<br />  计量查询：`http(s)://api.qiniuapi.com`                                                             |
| 华南-广东        | z2             | 空间管理：`http(s)://uc.qiniuapi.com`<br /> 源站上传：`http(s)://up-z2.qiniup.com`<br />源站下载：`http(s)://iovip-z2.qiniuio.com`<br /> 对象管理：`http(s)://rs-z2.qiniuapi.com`<br /> 对象列举：`http(s)://rsf-z2.qiniuapi.com`<br />计量查询：`http(s)://api.qiniuapi.com`                                                                |
| 北美-洛杉矶       | na0            | 空间管理：`http(s)://uc.qiniuapi.com`<br />源站上传：`http(s)://up-na0.qiniup.com`<br />源站下载：`http(s)://iovip-na0.qiniuio.com` <br /> 对象管理：`http(s)://rs-na0.qiniuapi.com`<br /> 对象列举：`http(s)://rsf-na0.qiniuapi.com`<br /> 计量查询：`http(s)://api.qiniuapi.com`                                                           |
| 亚太-新加坡（原东南亚） | as0            | 空间管理：`http(s)://uc.qiniuapi.com`<br /> 源站上传：`http(s)://up-as0.qiniup.com`<br />源站下载：`http(s)://iovip-as0.qiniuio.com`<br /> 对象管理：`http(s)://rs-as0.qiniuapi.com`<br /> 对象列举：`http(s)://rsf-as0.qiniuapi.com`<br />计量查询：`http(s)://api.qiniuapi.com`                                                            |
| 亚太-河内        | ap-southeast-2 | 空间管理：`http(s)://uc.qiniuapi.com`<br /> 源站上传：`http(s)://up-ap-southeast-2.qiniup.com`<br />源站下载：`http(s)://iovip-ap-southeast-2.qiniuio.com`<br /> 对象管理：`http(s)://rs-ap-southeast-2.qiniuapi.com`<br /> 对象列举：`http(s)://rsf-ap-southeast-2.qiniuapi.com`<br />计量查询：`http(s)://api-ap-southeast-2.qiniuapi.com` |
| 亚太-胡志明       | ap-southeast-3 | 空间管理：`http(s)://uc.qiniuapi.com`<br /> 源站上传：`http(s)://up-ap-southeast-3.qiniup.com`<br />源站下载：`http(s)://iovip-ap-southeast-3.qiniuio.com`<br /> 对象管理：`http(s)://rs-ap-southeast-3.qiniuapi.com`<br /> 对象列举：`http(s)://rsf-ap-southeast-3.qiniuapi.com`<br />计量查询：`http(s)://api-ap-southeast-3.qiniuapi.com` |


# 基本概念 (/products/kodo/3-the-basic-concept)



最近更新时间: 2026-05-08 17:38:19

<a id="kodo-bucket" />

## **空间** [#空间]

空间是资源的组织管理单位，一个资源必然位于某个空间中。可以为每个空间设置一系列的属性，以对资源提供合理的管理动作。

空间提供两种访问控制：公开空间和私有空间。公开和私有仅对空间的读文件生效，修改、删除、写入等对空间的操作均需要拥有者的授权才能进行操作。空间访问控制可通过对象存储控制台[空间设置](/products/kodo/kodo-console-guide/bucket-management/space-settings)的**访问控制**修改。<br />
**公开空间**：可通过文件对象的 URL 直接访问。<br />
**私有空间**：文件对象的访问则必须获得拥有者的授权才能访问。

<br />

<a id="kodo-object" />

## **资源** [#资源]

资源是七牛云存储服务中的逻辑存储单元。对于每一个账号，该账号里存放的每个资源都有唯一的空间与[键(Key)](/products/kodo/1-j#key)标识。资源名称是一个字符串，例如`level1/level2/example1.jpg`，它可以是任意字符包括 UTF-8 编码形式的 Unicode 字符。

您可以在上传资源时为其指定一个方便管理的资源名，通过前缀来达到类似于文件目录的分类和层次效果。以下是合法的资源名称示例：

```
index.html
features/index.html
imgs/features/feature1.png
about.html
```

假设资源名为`features/index.html`的资源位于某个绑定了域名`example.com`的公开空间中，则您可以在浏览器里输入以下 URL 访问资源：

```
http://www.example.com/features/index.html

或开启空间静态页面默认首页配置后省略掉 index.html：
http://www.example.com/features/
```

<br />

<a id="kodo-region" />

## **存储区域** [#存储区域]

存储区域是在创建空间时指定的，一旦指定后就无法修改。存储区域表示七牛云对象存储服务的数据中心所在区域。您可以根据费用、请求来源等因素选择合适的存储区域。一般选择离您近的存储区域访问速度更快。有关存储区域的详细介绍请查阅[存储区域](/products/kodo/2-region-endpoint-fq)选择说明。

<br />

<a id="ak-sk" />

## **访问密钥** [#访问密钥]

AccessKey . SecretKey 合称为七牛云的密钥，用于对操作请求进行签名验证。一个账号最多拥有两对密钥，用于不同的访问。<br />&#x2A;*AccessKey:** 用于标识用户，用户将 AccessKey 放入访问请求，以便七牛云存储识别访问者的身份。<br />&#x2A;*SecretKey:** 是用于加密签名字符串和服务器端验证签名字符串的密钥。

可通过对象存储控制台中的[密钥管理](https://portal.qiniu.com/user/key)查询访问密钥。


# H (/products/kodo/0-h)



最近更新时间: 2017-01-19 19:05:51

**HTTP Referer**

HTTP Referer是header的一部分，当浏览器向web服务器发送请求的时候，一般会带上Referer，告诉服务器我是从哪个页面链接过来的，服务器藉此可以获得一些信息用于处理。

<span id="hmac-sha1" />

**HMAC-SHA1**

HMAC是哈希运算消息认证码 (Hash-based Message Authentication Code)，HMAC运算利用哈希算法，以一个密钥和一个消息为输入，生成一个消息摘要作为输出。您可以使用它同时验证数据的完整性和消息的真实性。HMAC-SHA1签名算法是一种常用的签名算法，用于对一段信息进行生成签名摘要。


# J (/products/kodo/1-j)



最近更新时间: 2021-05-14 18:40:49

<span id="key" />

**键 (key)**

空间中资源的唯一标识符。空间中的每个资源都有一个对应的键。因为空间和键一起唯一标识每一个资源，您可以认为七牛云存储是基于 `空间＋键` 和资源本身之间的基本数据映射。

例如： `http://78re52.com1.z0.glb.clouddn.com/resource/AllEast.jpg`

* `78re52.com1.z0.glb.clouddn.com` 是空间的绑定域名
* `resource/AllEast.jpg` 是键

<span id="json" />

**JSON**

JSON（JavaScript Object Notation）一种轻量级的数据交换格式，具有良好的可读和便于快速编写的特性。可在不同平台之间进行数据交换。JSON采用兼容性很高的、完全独立于语言文本格式，同时也具备类似于C语言的习惯（包括C, C++, C#, Java, JavaScript, Perl, Python等）体系的行为。这些特性使JSON成为理想的数据交换语言。


# L (/products/kodo/2-l)



最近更新时间: 2021-05-13 21:24:50

<span id="token" />

**令牌 (Token)**

令牌是用户访问七牛云存储时，进行身份验证的凭证。当用户将一个Bucket设置为私有后，在访问七牛云存储时，必须通过身份验证。用户将访问请求中的一些要素整合起来，用 [签名密钥](/products/kodo/4-q) 对其加密，得到令牌。然后将令牌随同请求一起发送至七牛云存储。用户可以在令牌中指定请求的时效（七牛云存储统一使用UTC时间计算令牌有效期），防止请求被非法使用。


# U (/products/kodo/3-u)



最近更新时间: 2017-01-20 15:16:13

<span id="unixtime" />

**Unix 时间戳**

Unix时间戳，是一种时间表示方式，定义为从1970年01月01日00时00分00秒起至现在的总秒数。


# Q (/products/kodo/4-q)



最近更新时间: 2021-05-13 21:23:52

<a id="secret-key" />

**签名密钥**

签名密钥 (Secret Key) 简称 SK ，是<span id="Productname">七牛云存储</span>颁发给用户，用于对访问请求签名的字串。用户使用签名密钥对访问请求的核心要素进行签名，获得请求认证[令牌](/products/kodo/2-l#token)。用户将令牌随同访问请求一起发送至<span id="Productname">七牛云存储服务</span>，<span id="Productname">七牛云存储</span>将对令牌进行校验，以确认用户请求的合法性。


# 快速入门文档 (/products/kodo/0-console-quickstart)



最近更新时间: 2026-04-30 11:34:30

阅读本文后，即可轻松创建和删除空间，上传、下载和删除文件。

七牛对象存储将数据文件以资源的形式上传到空间中。您可以创建一个或者多个空间，然后向每个空间中上传一个或多个文件。通过获取已上传文件的地址进行文件的分享和下载。您还可以通过修改存储空间或文件的属性或元信息来设置相应的访问权限。快速入门接下来将假设您至少已经熟悉七牛云对象存储的[基本概念](/products/kodo/3-the-basic-concept)。

为了顺利完成快速入门，您需要一个七牛云账号 ([点击注册](https://portal.qiniu.com/signup))。另外推荐使用谷歌浏览器（Chrome）。

本快速入门指南涵盖以下内容：

* [Step 1：创建空间](#step1)
* [Step 2：上传文件](#step2)
* [Step 3：下载文件](#step3)
* [Step 4：删除文件](#step4)
* [Step 5：删除空间](#step5)

关于七牛云对象存储，请参阅 [对象存储文档](/faq/kodo)。

<br />

<a id="step1" />

# 步骤1：创建空间 [#步骤1创建空间]

首先，您需要创建一个 [空间（Bucket）](/products/kodo/3-the-basic-concept#kodo-bucket)。

1. 登录 [七牛开发者平台](https://portal.qiniu.com/signin)。

2. 进入 [空间管理](https://portal.qiniu.com/bucket) 界面

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/FqqwVgBvR1Q3nXhKoknyD2l4S3zm-1dfd7c8bd52f.webp" width="800" />

3. 点击[新建空间](https://portal.qiniu.com/kodo/bucket?shouldCreateBucket=true)
   &#x2A;*注： 如果您是体验用户，新建空间时，会因账号信息未完善而创建失败。**

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/FuNH0gkub3nE4xjbIduouWUr1Jc1-975e792e0ae7.webp" width="800" />

4. 空间创建成功之后，点击**空间名称**，即可进入空间概览

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/FnP5PNIcbkNAsF_Oek70KRlYqoGP-d90c5c326615.webp" width="800" />

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/FqG2TvxDF5RSeq5o8Y2Qr8wHfkfY-9dfc4098bf8b.webp" width="800" />

5. 点击**文件管理**，即可在此界面进行上传、下载、访问、修改文件等操作。

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/Fmod6r6TqlKB7tg_uJmwmmXicecR-ce76abed5d84.webp" width="800" />

<br />

<a id="step2" />

# 步骤2：上传文件 [#步骤2上传文件]

空间创建成功后，您可以向空间里上传资源。资源可以是任意的文件：文档，照片，视频，音乐文件，或其它文件类型。

1. 在 [空间列表](https://portal.qiniu.com/kodo/bucket) 中选择一个空间，然后进入**文件管理**

2. 点击**上传文件**，选择指定文件，点击**开始上传**。

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/FoAhlA-FnjzxGJUYpLNQxAfZBmzc-bfda7c27854e.webp" width="800" />

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/Fpz4SOfw9C4jn7BeRG9O0L0XzkYK-ddb9e127d425.webp" width="800" />

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/FntQr6a09ZMt0s1H9JLrlMGzPAzu-4e14a5e3ce07.webp" width="800" />

3. 您可以在任务中心查看文件上传状态

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/FmJE6dYX67Z2XdjxUbj64JnAwAVR-a6b191fa67c9.webp" width="800" />

<br />

<a id="step3" />

# 步骤3：下载文件 [#步骤3下载文件]

您可以通过浏览器打开和查看已经添加至空间的文件。您也可以下载该文件到您的本地计算机。

1. 在 [空间列表](https://portal.qiniu.com/kodo/bucket) 中选择一个空间，然后进入**文件管理**

2. 在指定文件栏，点击右侧**更多**，点击**下载**

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/FlioA8fpsCSmGYZNFxsi05ZE2Iuu-37836a305e26.webp" width="800" />

或选择多个文件，点击**批量操作**进行**批量下载**

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/Fk1qxfgqLCgzfkYCvqA2Mrr4w54A-b64062a06f94.webp" width="800" />

<br />

<a id="step4" />

# 步骤4：删除文件 [#步骤4删除文件]

如果您不再需要把已上传的文件保存在七牛空间中，您可以删除它。
&#x2A;*注：删除空间中的文件后，不可恢复，慎重操作。**

1. 在 [空间列表](https://portal.qiniu.com/kodo/bucket) 中选择一个空间，然后进入**文件管理**

2. 在指定文件栏，点击右侧**更多**，点击**删除**

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/FpCsFq90G9u-ueLS53E2lOrrdbOU-25cab0f89eef.webp" width="800" />

或选择多个文件，点击**批量操作**进行**批量删除**

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/FtA0mC2sfsWgjSZ3ncdYO8m_-R_g-d488b1f70248.webp" width="800" />

<br />

<a id="step5" />

# 步骤5：删除空间 [#步骤5删除空间]

如果您不再需要已创建的空间时，您可以删除它。
&#x2A;*注：空间不为空时，禁止删除，需先删除空间内的文件。**

1. 在 [空间列表](https://portal.qiniu.com/kodo/bucket) 中选择一个空间，然后进入**空间设置**

2. 找到空间设置最下方的删除空间卡片，点击**删除空间**后，需要**输入账号密码**才可成功删除。

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/Fh81Bano-uTJ5JRBMRd50gaw7uDT-c6c9fc6e4e75.webp" width="800" />

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/Fo6yVUafEbH2QXRhLh1ROtTdfxfS-424052d8fcc2.webp" width="800" />

<img src="/docs-assets/products/kodo/%283-quick-start%29/0-console-quickstart/FgpAyVHni1vCSULOds0Vqx7sf2lG-e751a0042da8.webp" width="800" />


# 账号欠费保护期功能限制 (/products/kodo/0-accounts-owe-protection)



最近更新时间: 2026-04-17 15:33:15

依据七牛云 [新版欠费流程](/faq/account-finance/account-problem/5996-new-owe-the-process-description) 规定，针对处于欠费保护期的账号，七牛云对象存储的开发者平台会限制部分功能的使用，详见下表说明。

<a id="type" />

## 欠费保护期限制功能列表 [#欠费保护期限制功能列表]

| 功能    | 限制说明                                     |
| ----- | ---------------------------------------- |
| 新建空间  | 禁用                                       |
| 绑定域名  | 禁用                                       |
| 样式分隔符 | 可以查看已有的设置信息<br />禁止修改设置                  |
| 图片样式  | 可以查看、删除已有图片样式<br />禁止新增、修改图片样式           |
| 转码样式  | 可以查看、删除已有转码样式<br />禁止新增、修改转码样式           |
| 空间设置  | 可以查看已有的空间设置信息<br />禁止修改空间设置信息            |
| 跨区域同步 | 可以查看、已有的跨区域同步任务信息<br />禁止创建、启动/暂停跨区域同步任务 |

如果需要关闭此功能，请进入[https://portal.qiniu.com/financial/overview](https://portal.qiniu.com/financial/overview)
![截屏2026-04-16 11.13.54.png](/docs-assets/products/kodo/%282-buying-guide%29/0-accounts-owe-protection/FrqW5E13TNJ6XMBIQDTg4g8o_2sd-6060804f1cf6.webp)
点击“点击取消”，确认即可。


# 计量项与计费项 (/products/kodo/1-metering-and-billing)



最近更新时间: 2025-02-19 14:02:09

# **费用组成** [#费用组成]

对象存储服务的计费项类型有：存储费用，流量费用，请求费用，数据处理费用和管理功能费用。
使用对象存储服务时默认采用按量付费模式，[查询产品价格](https://www.qiniu.com/prices/kodo)。同时也支持购买资源包（包年包月）的方式提前购买资源的使用额度和时长，获取更多的优惠，[购买资源包](https://qmall.qiniu.com/template/MTEy?spec_combo=MzA0OQ)。

<table>
  <tbody><tr><td>类型</td><td>计费项</td><td>说明</td></tr><tr><td rowspan="3">存储费用</td><td>存储空间费用</td><td>占用的存储空间容量</td></tr><tr><td>提前删除费用</td><td>低频、归档直读、归档、深度归档存储类型未存满最短存储时间、就删除或转换为其他存储类型时产生的存储容量费用</td></tr><tr><td>智能分层对象监控和自动化费用</td><td>智能分层对象监控和自动分层变更费用，系统将实时监测。若您上传了智能分层存储类型的数据至该存储桶，则会产生该费用。</td></tr><tr><td rowspan="4">流量费用</td><td>外网流出流量</td><td>通过互联网浏览数据或下载对象存储数据到本地所产生的下行流量</td></tr><tr><td>CDN回源流量</td><td>通过七牛云的 CDN 服务浏览或下载对象存储的数据所产生的回源流量</td></tr><tr><td>跨区域同步流量</td><td>通过跨区域同步功能将源 Bucket 的数据同步复制到目标 Bucket 时所产生的流出流量</td></tr><tr><td>传输加速流量</td><td>开启了传输加速，且使用加速域名访问对象存储空间产生的流量费用。例如通过加速域名向开启加速功能的存储空间中上传了 1 GB 的数据，则会产生 1 GB 传输加速费用</td></tr><tr><td rowspan="3">请求费用</td><td>PUT/DELETE 请求次数</td><td>调用写请求的次数（包括 list 请求在内）</td></tr><tr><td>GET 请求次数</td><td>调用读请求的次数</td></tr><tr><td>数据取回请求次数</td><td>调用深度归档存储解冻接口的次数</td></tr><tr><td>数据处理费用</td><td>数据取回</td><td>标准存储：不涉及<br />低频存储：访问低频存储数据时，会产生额外的数据取回费。按服务端读取的数据量计算<br />归档直读存储：访问归档直读存储数据时，会产生额外的数据取回费。按服务端读取的数据量计算<br />归档存储：访问归档存储数据前，需要先解冻数据。按解冻数据量计算<br />深度归档存储：访问深度归档存储数据前，需要先解冻数据。按解冻数据量计算</td></tr><tr><td>管理功能费用</td><td>清单功能</td><td>当用户使用了空间清单功能后，列出空间中对象列表时产生的费用</td></tr></tbody>
</table>

**注意**：自 2022 年 7 月 1 日起，七牛云对象存储将把各区域的「存储类型转换次数」合并记入对应区域和存储类型的「PUT/DELETE 请求次数」中，不再单独做「存储类型转换次数」的计量和计费。[点击查看详情](/products/kodo/2-chtype-billing-item-changes)

<a id="storage" />

# **存储费用** [#存储费用]

| 存储类型           | 计量                                                                                                                                                    | 计费说明                                             |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| 标准存储           | 存储量：按实际存储量计算<br />存储时间：按实际存储天数计算<br />月平均存储量=每天存储量加和/月计费天数                                                                                            | 按量付费 <br /> 每 GB 每月单价 \* 每月平均存储量 (GB)            |
| 低频存储           | 存储量：单个 Object 小于 64KB，按 64KB 计算存储量；大于 64KB，按实际大小计算存储量<br />存储时间：按低频存储类型保存的实际天数计算<br />月平均存储量=每天存储量加和/月计费天数                                            | 按量付费 <br /> 每 GB 每月单价 \* 每月平均存储量 (GB)            |
| 低频存储提前删除       | 存储量：单个 Object 小于 64KB，按 64KB 计算存储量；大于 64KB，按实际大小计算存储量<br />存储时间：存储时间不足 30 天删除或转换为其他存储类型的 Object，才产生提前删除量<br /> 月平均提前删除量 = 存储量 \* (30 - 已存储时间）/月计费天数   | 按量付费 <br /> 提前删除费用 = 每 GB 每月单价 \* 每月平均提前删除量 (GB) |
| 智能分层存储频繁访问层    | 存储量：按实际存储量计算<br />存储时间：按实际存储天数计算<br />月平均存储量=每天存储量加和/月计费天数                                                                                            | 每 GB 每月单价 \* 每月平均存储量 (GB)                        |
| 智能分层存储不频繁访问层   | 存储量：按实际存储量计算<br />存储时间：按实际存储天数计算<br />月平均存储量=每天存储量加和/月计费天数                                                                                            | 每 GB 每月单价 \* 每月平均存储量 (GB)                        |
| 智能分层存储归档直读访问层  | 存储量：按实际存储量计算<br />存储时间：按实际存储天数计算<br />月平均存储量=每天存储量加和/月计费天数                                                                                            | 每 GB 每月单价 \* 每月平均存储量 (GB)                        |
| 智能分层对象监控和自动化费用 | 对象数量：该费用按照大于或等于 64KB 的对象个数进行计算<br />存储时间：按实际存储天数计算<br />月平均数量=每天对象数量加和/月计费天数                                                                          | 每万个单价 \* 每月平均对象数量 /10000 (个)                     |
| 归档直读存储         | 存储量：单个 Object 小于 64KB，按 64KB 计算存储量；大于 64KB，按实际大小计算存储量<br />存储时间：按归档直读存储类型保存的实际天数计算<br />月平均存储量=每天存储量加和/月计费天数                                          | 按量付费 <br /> 每 GB 每月单价 \* 每月平均存储量 (GB)            |
| 归档直读存储提前删除     | 存储量：单个 Object 小于 64KB，按 64KB 计算存储量；大于 64KB，按实际大小计算存储量<br />存储时间：存储时间不足 60 天删除或转换为其他存储类型的 Object，才产生提前删除量<br /> 月平均提前删除量 = 存储量 \* (60 - 已存储时间）/月计费天数   | 按量付费 <br /> 提前删除费用 = 每 GB 每月单价 \* 每月平均提前删除量 (GB) |
| 归档存储           | 存储量：单个 Object 小于 64KB，按 64KB 计算存储量；大于 64KB，按实际大小计算存储量<br />存储时间：按归档存储类型保存的实际天数计算 <br />月平均存储量 = 每天存储量加和/月计费天数                                         | 按量付费 <br /> 每 GB 每月单价 \* 每月平均存储量 (GB)            |
| 归档存储提前删除       | 存储量：单个 Object 小于 64KB，按 64KB 计算存储量；大于 64KB，按实际大小计算存储量<br />存储时间：存储时间不足 60 天删除或转换为其他存储类型的 Object，才产生提前删除量<br /> 月平均提前删除量 = 存储量 \* (60 - 已存储时间）/月计费天数   | 按量付费 <br /> 提前删除费用 = 每 GB 每月单价 \* 每月平均提前删除量 (GB) |
| 深度归档存储         | 存储量：单个 Object 小于 64KB，按 64KB 计算存储量；大于 64KB，按实际大小计算存储量<br />存储时间：按深度归档存储类型保存的实际天数计算<br />月平均存储量 = 每天存储量加和/月计费天数                                        | 按量付费 <br /> 每 GB 每月单价 \* 每月平均存储量 (GB)            |
| 深度归档存储提前删除     | 存储量：单个 Object 小于 64KB，按 64KB 计算存储量；大于 64KB，按实际大小计算存储量<br />存储时间：存储时间不足 180 天删除或转换为其他存储类型的 Object，才产生提前删除量<br /> 月平均提前删除量 = 存储量 \* (180 - 已存储时间）/月计费天数 | 按量付费 <br /> 提前删除费用 = 每 GB 每月单价 \* 每月平均提前删除量 (GB) |

<a id="flow" />

# **流量费用** [#流量费用]

| 计费项     | 计量                                                                                | 计费说明                           |
| ------- | --------------------------------------------------------------------------------- | ------------------------------ |
| 外网流出流量  | 通过互联网浏览数据或下载对象存储数据到本地所产生的下行流量                                                     | 按量付费<br />每GB单价 \* 每月累计的流量(GB) |
| CDN回源流量 | 通过七牛云的 CDN 服务浏览或下载对象存储的数据所产生的回源流量                                                 | 按量付费<br />每GB单价 \* 每月累计的流量(GB) |
| 跨区域同步流量 | 通过跨区域同步功能将源 Bucket 的数据同步复制到目标 Bucket 时所产生的流出流量                                    | 按量付费<br />每GB单价 \* 每月累计的流量(GB) |
| 传输加速流量  | 开启了传输加速，且使用加速域名访问对象存储空间产生的流量费用。例如通过加速域名向开启加速功能的存储空间中上传了 1 GB 的数据，则会产生 1 GB 传输加速流量 | <br />每GB单价 \* 每月累计的流量(GB)     |

<a id="hits" />

# **请求费用** [#请求费用]

| 计费项             | 计量               | 计费说明                                          |
| --------------- | ---------------- | --------------------------------------------- |
| PUT/DELETE 请求次数 | 调用写请求和list请求的次数和 | 按量付费<br />每万次请求单价 \* (每月累计的请求次数-免费次数) / 10000 |
| GET 请求次数        | 调用读请求的次数         | 按量付费<br />每万次请求单价 \* (每月累计的请求次数-免费次数) / 10000 |
| 数据取回请求次数        | 调用深度归档存储解冻接口的次数  | 按量付费<br />每万次请求单价 \* 每月累计的请求次数 / 10000        |

**注意**：自 2022 年 7 月 1 日起，七牛云对象存储将把各区域的「存储类型转换次数」合并记入对应区域和存储类型的「PUT/DELETE 请求次数」中，不再单独做「存储类型转换次数」的计量和计费。[点击查看详情](/products/kodo/2-chtype-billing-item-changes)

<a id="restore" />

# **数据处理费用** [#数据处理费用]

目前对象存储的数据处理费用只有数据取回一项

| 存储类型   | 计量                                       | 计费说明                              |
| ------ | ---------------------------------------- | --------------------------------- |
| 标准存储   | 免费                                       | -                                 |
| 低频存储   | 从服务端读取的数据量<br />每次低频存储数据访问从服务端读取的数据量加和   | 按量付费<br />每GB单价 \* 每月累计的取回数据量(GB) |
| 归档直读存储 | 从服务端读取的数据量<br />每次归档直读存储数据访问从服务端读取的数据量加和 | 按量付费<br />每GB单价 \* 每月累计的取回数据量(GB) |
| 归档存储   | 解冻数据量<br />每次解冻归档存储文件的数据量加和              | 按量付费<br />每GB单价 \* 每月累计的解冻数据量(GB) |
| 深度归档存储 | 解冻数据量<br />每次解冻深度归档存储文件的数据量加和            | 按量付费<br />每GB单价 \* 每月累计的解冻数据量(GB) |

<a id="restore" />

# **管理功能费用** [#管理功能费用]

| 计费项  | 计量                                   | 计费说明                                         |
| ---- | ------------------------------------ | -------------------------------------------- |
| 清单功能 | 不区分存储类型<br />按列出的（空间中所有或指定前缀的）对象数量计量 | 按量付费<br />每列出百万个对象的单价 \* 每月累计的列出数量 / 1000000 |

<br />

<a id="examples" />

# **计费案例** [#计费案例]

以下案例单价来自 2022 年 3 月 15 日七牛云官网公布的详细价格信息。单价的变动请以[七牛云官网](https://www.qiniu.com/prices?source=kodo)发布的数据为准。

## **标准存储** [#标准存储]

赵先生在七牛云(华南区域)存储了 500GB 标准存储类型文件，每天的PUT/DELETE请求数均值为 10000 次，GET 请求次数为 50000 次，每天通过七牛 CDN 回源流出的流量约为 3 GB，则赵先生当月需支付费用约 61.21 元。

* 存储费用=(500GB-10GB) \* 0.099元/GB/月=48.51 元
  标准存储有10GB的免费空间额度
* PUT/DELETE请求费用=(10000次/天 \* 30天-100000次) \* 0.01元/10000次=0.2 元
  标准存储有10万次的 PUT/DELETE 请求免费额度
* GET 请求费用=(50000次/天 \* 30天-1000000次) \* 0.01元/10000次=0.5 元
  标准存储有100万次的 GET 请求免费额度
* CDN 回源流量费用=(3GB/天 \* 30天-10GB) \* 0.15元/GB=12元
* 标准存储有10GB的CDN回源流量免费额度
* 总费用，约 61.21 元

## **低频存储** [#低频存储]

刘小姐在七牛云存储了 100GB 的低频存储类型文件。其中，有 10000 个大小为 20KB 的文件。20 号的时候，刘小姐下载了一个大小为 1GB 的文件到本地，并将文件内容更新之后重新上传至 七牛云存储，更新后的文件大小仍为 1GB，新文件后续被其他人下载过2次，则刘小姐当月约需支付 7.10 元。

* 存储费用=(100GB+10000 \* 44KB) \* 0.06元/GB/月=100.42GB \* 0.06元/GB/月= 6.03 元
  低频存储类型的文件最小计量为64KB，10000个20KB的文件实际大小约为0.19GB，而低频存储计量为0.61GB
* 提前删除费用=1GB \* 0.06元/GB/月 / 30 天 \* 10 天=0.02 元
  上传新的同名文件会导致原有文件被删除，并保存新的文件；原有文件存储不足30天，会产生提前删除费用。
* 外网流出费用=1GB \* 3 \* 0.29元/GB=0.87 元
* 数据取回费用=1GB \* 3 \* 0.06元/GB=0.18 元
  文件被访问3次，每次都会计算数据取回量
* 请求次数较少，可忽略不计
* 总费用，约 7.10 元

## **智能分层存储** [#智能分层存储]

假设企业拥有 1TB 文件，每个文件均大于 64KB，总共 10 万个文件，数据以智能分层存储类型存储在华东-浙江地域，假设每 30 天都会有 20% 的文件（即 2 万个文件）沉降，文件在年初被一次性全量写入，并保存 12 个月满 1 年；那么 前 4 个月每 30 天的对象监控费用和存储费用，如下表所示：

| 存储天数                                                     | 每30天对象监控费用（元）                 | 每30天智能分层存储费用（元）                                                                        | 每30天标准存储费用（元）                  |
| -------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------- | ------------------------------ |
| 30\*1                                                    | 0.175元/每万个对象/月 \* 10 万 = 1.75 | 1024 \* 0.148 元/GB/月 = 151.552                                                         | 1024 \* 0.148 元/GB/月 = 151.552 |
| 30\*2                                                    | 0.175元/每万个对象/月 \* 10 万 = 1.75 | 819.2 \* 0.148 元/GB/月 + 204.8 \* 0.06 元/GB/月 = 133.5296                                | 1024 \* 0.148 元/GB/月 = 151.552 |
| 30\*3                                                    | 0.175元/每万个对象/月 \* 10 万 = 1.75 | 655.36 \* 0.148 元/GB/月 + 368.64 \* 0.06 元/GB/月 = 119.11168                             | 1024 \* 0.148 元/GB/月 = 151.552 |
| 30\*4                                                    | 0.175元/每万个对象/月 \* 10 万 = 1.75 | 524.288 \* 0.148 元/GB/月 + 425.984 \* 0.06 元/GB/月 + 73.728 \* 0.034 元/GB/月 = 105.660416 | 1024 \* 0.148 元/GB/月 = 151.552 |
| `为简化计算，体现智能分层存储类型和其他类型成本优化对比，这里没有考虑免费额度，实际使用账单会有免费额度的说明` |                               |                                                                                        |                                |

## **归档直读存储** [#归档直读存储]

赵小姐在七牛云华东-浙江2区域存储了 500GB 的归档直读存储类型文件。其中，有 10000 个大小为 20KB 的文件。10 号的时候，刘小姐下载了一个大小为 1GB 的文件到本地，并将文件内容更新之后重新上传至七牛云存储，更新后的文件大小仍为 1GB，新文件后续被其他人下载过2次，则刘小姐当月约需支付 16.94 元。

* 存储费用=(500GB+10000 \* 44KB) \* 0.031元/GB/月=500.42GB \* 0.031元/GB/月= 15.51 元
  归档直读存储类型的文件最小计量为64KB，10000个20KB的文件实际大小约为0.19GB，而归档直读存储计量为0.61GB
* 提前删除费用=1GB \* 0.031元/GB/月 / 30 天 \* 50 天=0.05 元
  上传新的同名文件会导致原有文件被删除，并保存新的文件；原有文件存储不足60天，会产生提前删除费用。
* 外网流出费用=1GB \* 3 \* 0.26元/GB=0.78 元
* 数据取回费用=1GB \* 3 \* 0.2元/GB=0.6 元
  文件被访问3次，每次都会计算数据取回量
* 请求次数较少，可忽略不计
* 总费用，约 16.94 元

## **归档存储** [#归档存储]

李先生在七牛云(华东区域)存储了 1TB 的归档存储类型文件。25 号～ 30 号的期间，有一批 100GB 的档案数据需要提供在线访问。25 号上午李先生解冻了这批归档数据（2000个文件），25 号～ 30 号期间，通过七牛CDN下载数据总量约为100GB，则李先生当月约需支付 57.27 元。

* 归档文件存储费用=1024GB \* 0.032元/GB/月=32.77 元
* 归档文件解冻后临时副本的存储费用（标准存储类型）=(100GB \* 6天 / 30天 - 10GB)\*0.148元/GB/月=1.48 元
  标准存储有10GB的免费空间额度
* 数据取回费用=100GB \* 0.08元/GB=8 元
  归档文件的数据取回按实际解冻数据量计算；数据解冻后的访问，不会产生数据取回费用
* 解冻归档文件请求次数费用=2000次 \* 0.1元/10000次=0.02 元
* CDN 回源流量费用=100GB \* 0.15元/GB=15 元
* 总费用，约 57.27 元

## **深度归档存储** [#深度归档存储]

王先生在七牛云(华东区域)存储了 1TB 的深度归档存储类型文件。25 号～ 30 号的期间，有一批 100GB 的档案数据需要提供在线访问。25 号上午王先生解冻了这批深度归档数据（2000个文件），25 号～ 30 号期间，通过七牛CDN下载数据总量约为100GB，则王先生当月约需支付 41.97 元。

* 深度归档文件存储费用=1024GB \* 0.012元/GB/月= 12.29 元
* 深度归档文件解冻后临时副本的存储费用（标准存储类型）=(100GB \* 6天 / 30天 - 10GB)\*0.148元/GB/月=1.48 元
  标准存储有 10GB 的免费空间额度
* 数据取回费用=100GB \* 0.12元/GB= 12 元
* 深度归档文件的数据取回按实际解冻数据量计算；数据解冻后的访问，不会产生数据取回费用
* 数据取回请求次数费用=2000次 \* 6元/10000次=1.2 元
* CDN 回源流量费用=100GB \* 0.15元/GB=15 元
* 总费用，约 41.97 元

## **传输加速** [#传输加速]

张先生在七牛云(华南区域)开通了传输加速服务，1月（共 31 天）25 号，在美国洛杉矶通过加速域名上传了 100 GB 的数据，100 个文件的标准存储。则张先生当月约需支付 127.012 元。

* 标准存储文件存储费用 = ( 100 GB - 10 GB ) \* 7 / 31 \* 0.099元/GB/月= 2.012 元
* 请求次数较少，可忽略不计
* 全球加速上行（非中国内地 - 中国内地地域）= 100 GB \* 1.25 元/GB = 125 元
* 总费用，约 127.012 元


# 数据格式 (/products/kodo/0-data-format)



最近更新时间: 2021-07-27 18:42:57

本节描述七牛云存储 API 中使用到的数据格式。

## EncodedEntryURI 格式 [#encodedentryuri-格式]

本格式用于在 URI中指定目标资源空间与目标资源名，格式如下：

```
entry = '<Bucket>:<Key>'
encodedEntryURI = urlsafe_base64_encode(entry)
```

假设 **entry** 为 `qiniuphotos:gogopher.jpg` ，则对应的 **encodedEntryURI** 为 `cWluaXVwaG90b3M6Z29nb3BoZXIuanBn` 。

## URL安全的Base64编码 [#url安全的base64编码]

URL安全的Base64编码适用于以URL方式传递Base64编码结果的场景。该编码方式的基本过程是先将内容以Base64格式编码为字符串，然后检查该结果字符串，将字符串中的加号 `+` 换成中划线 `-` ，并且将斜杠 `/` 换成下划线 `_` 。

详细编码规范请参考 [RFC4648](https://tools.ietf.org/html/rfc4648#section-4) 标准中的相关描述。


# 数据统计接口 (/products/kodo/1-statistic-interface)



最近更新时间: 2024-08-12 15:23:48

数据统计相关的接口：

| 接口                                                                                                       | 说明                                       |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| [space](/products/kodo/statistic-interface/3908-statistic-space)                                         | 获取标准存储的存储量统计                             |
| [count](/products/kodo/statistic-interface/3914-count)                                                   | 获取标准存储的文件数量统计                            |
| [space\_line](/products/kodo/the-bucket-interface/2-get-the-bucket-space-domain)                         | 获取低频存储的存储量统计                             |
| [count\_line](/products/kodo/development-guidelines/aws-s3-compatible/compatible-s3-api)                 | 获取低频存储的文件数量统计                            |
| [space\_intelligent\_tiering](/products/kodo/kodo-category/0-storage-class-intelligent-tiering)          | 获取智能分层存储的存储量统计                           |
| [count\_intelligent\_tiering](/products/kodo/kodo-category/0-storage-class-intelligent-tiering)          | 获取智能分层存储的文件数量统计                          |
| [count\_intelligent\_tiering\_monitor](/products/kodo/kodo-category/0-storage-class-intelligent-tiering) | 获取智能分层存储的监控文件数                           |
| [space\_archive\_ir](/products/kodo/rs/12-restore-archive)                                               | 获取归档直读存储的存储量统计                           |
| [count\_archive\_ir](/products/kodo/rs/12-restore-archive)                                               | 获取归档直读存储的文件数量统计                          |
| [space\_archive](/products/kodo/rs/12-restore-archive)                                                   | 获取归档存储的存储量统计                             |
| [count\_archive](/products/kodo/rs/12-restore-archive)                                                   | 获取归档存储的文件数量统计                            |
| [space\_deep\_archive](/products/kodo/rs/12-restore-archive)                                             | 获取深度归档存储的存储量统计                           |
| [count\_deep\_archive](/products/kodo/rs/12-restore-archive)                                             | 获取深度归档存储的文件数量统计                          |
| [blob\_transfer](/products/kodo/development-guidelines/1-transfer-acceleration)                          | 获取跨区域同步流量统计                              |
| [rs\_chtype](/products/kodo/rs)                                                                          | 获取存储类型请求次数统计                             |
| [blob\_io](/products/kodo/development-guidelines/aws-s3-compatible/compatible-s3-api)                    | 获取外网流出流量统计，CDN回源流出流量统计，数据读取统计， GET请求次数统计 |
| [rs\_put](/products/kodo/rs)                                                                             | 获取 PUT 请求次数统计                            |

注：接口提供 2018-01-01 号及之后的数据查询，历史数据默认不提供，如有需要请工单联系我们。


# HTTP Headers (/products/kodo/3924-common-request-headers)



最近更新时间: 2022-11-29 17:52:08

| HTTP header    | 描述                                                                                                                                                                                                                                                                                                  | 类型      |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| Authorization  | 用于验证请求合法性的认证信息。该头部应严格按照[管理凭证](/products/kodo/development-guidelines/security/access-token)或[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)格式进行填充，否则会返回 401 错误码。例如`Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1 ...`或`Authorization: UpToken QNJi_bYJlmO5LeY08FfoNj9w_r...`。 | 请求头     |
| Content-Length | 请求或响应内容长度，单位`字节`。例如`Content-Length: 299`。                                                                                                                                                                                                                                                           | 请求头、响应头 |
| Content-Type   | 请求或响应内容的 MIME 类型。例如`Content-Type: application/json`。                                                                                                                                                                                                                                                | 请求头、响应头 |
| Host           | 上传服务器域名。例如`Host: rsf-z0.qiniuapi.com`。                                                                                                                                                                                                                                                              | 请求头     |
| Connection     | 标明客户端与服务器之间的通信状态。例如`Connection: keep-alive`。                                                                                                                                                                                                                                                        | 请求头、响应头 |
| Date           | 服务器端响应时间。例如`Date: Wed, 22 Nov 2017 01:52:39 GMT`。                                                                                                                                                                                                                                                   | 响应头     |
| X-Qiniu-Date   | 生成请求的时间，ISO 8601 格式 UTC  时间，形如 `yyyyMMddTHHmmssZ`，例如 `20060102T150405Z`。如果请求中的 X-Qiniu-Date 时间和七牛服务器的当前时间差 15 分钟以上，服务器将拒绝该请求，并返回 HTTP 403 错误。该 header 需要包含在 Authorization 中，详情见 [管理凭证](/products/kodo/development-guidelines/security/access-token)                                                 | 请求头     |
| Etag           | Etag 是 Object 被创建时用于标识 Object 内容的。ETag 值反映 Object 内容是否发生变化，ETag 返回值根据不同请求的情况选择。例如`ETag: "lrMxbjcfPyC7F1siA6tF78B1IMAq"`。                                                                                                                                                                            | 响应头     |
| Server         | 生成响应的服务器名称。例如`Server: nginx`。                                                                                                                                                                                                                                                                       | 响应头     |
| X-Reqid        | 上传请求的唯一 ID。通过该 ID 可快速定位用户请求的相关日志。在联系技术支持时提供该 ID 可快速解决问题。例如`X-Reqid: BlcAAAFP_Hx-RfkU`。                                                                                                                                                                                                              | 响应头     |
| X-Log          | 用于快速定位问题的参考信息。例如`X-Log: RSF:102;RSF:103;ZONEPROXY:105`。                                                                                                                                                                                                                                             | 响应头     |


# 错误响应 (/products/kodo/3928-error-responses)



最近更新时间: 2024-12-10 14:12:29

本节为您提供请求出现错误时，返回的错误码和对应的错误信息。

<br />

<a id="error-responses-format" />

# **错误响应格式** [#错误响应格式]

当您请求出现错误时，响应头部信息包括：

* Content-Type: application/json
* 一个合适的 3xx，4xx，或者 5xx 的 HTTP 状态码

各个接口在遇到执行错误时，将返回一个 JSON 格式组织的信息对象，描述出错原因。具体格式如下：

```
{
	"code": <httpCode int>,
    "error": "<errMsg string>"
}
```

| 字段名称  | 说明               |
| ----- | ---------------- |
| code  | 返回的错误码，用来定位错误场景。 |
| error | 包含详细的错误信息        |

<br />

<a id="error-codes-list" />

# **错误码列表** [#错误码列表]

以下表格列出了所有错误码：

| HTTP状态码 | 说明                                                                                                                                                                                                                                                                                                                                  |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 298     | 部分操作执行成功                                                                                                                                                                                                                                                                                                                            |
| 400     | 请求报文格式错误<br />包括上传时，上传表单格式错误。例如`incorrect region`表示上传域名与上传空间的区域不符，此时需要升级 SDK 版本。                                                                                                                                                                                                                                                    |
| 401     | 认证授权失败<br />错误信息包括密钥信息不正确；数字签名错误；授权已超时，例如`token not specified`表示上传请求中没有带 token ，可以抓包验证后排查代码逻辑; `token out of date`表示 token 过期，推荐 token 过期时间设置为 3600 秒（1 小时），如果是客户端上传，建议每次上传从服务端获取新的 token；`bad token`表示 token 错误，说明生成 token 的算法有问题，建议直接使用七牛服务端 SDK 生成 token。                                                                        |
| 403     | 权限不足，拒绝访问。<br />例如`key doesn't match scope`表示上传文件指定的 key 和上传 token 中，putPolicy 的 scope 字段不符。上传指定的 key 必须跟 scope 里的 key 完全匹配或者前缀匹配；`request time too skewed` 表示请求中的时间和服务端相差 `15`分钟以上，请校验时间；`ExpUser can only upload image/audio/video/plaintext`表示账号是体验用户，体验用户只能上传文本、图片、音频、视频类型的文件，完成实名认证即可解决；`not allowed`表示您是体验用户，若想继续操作，请先前往实名认证。 |
| 404     | 资源不存在<br />包括空间资源不存在；镜像源资源不存在。                                                                                                                                                                                                                                                                                                      |
| 405     | 请求方式错误<br />主要指非预期的请求方式。                                                                                                                                                                                                                                                                                                            |
| 406     | 上传的数据 CRC32 校验错误                                                                                                                                                                                                                                                                                                                    |
| 413     | 请求资源大小大于指定的最大值                                                                                                                                                                                                                                                                                                                      |
| 419     | 用户账号被冻结                                                                                                                                                                                                                                                                                                                             |
| 478     | 镜像回源失败<br />主要指镜像源服务器出现异常。                                                                                                                                                                                                                                                                                                          |
| 502     | 错误网关                                                                                                                                                                                                                                                                                                                                |
| 503     | 服务端不可用                                                                                                                                                                                                                                                                                                                              |
| 504     | 服务端操作超时                                                                                                                                                                                                                                                                                                                             |
| 573     | 单个资源访问频率过高                                                                                                                                                                                                                                                                                                                          |
| 579     | 上传成功但是回调失败<br />包括业务服务器异常；七牛服务器异常；服务器间网络异常。需要确认回调服务器接受 POST 请求，并可以给出 200 的响应。                                                                                                                                                                                                                                                       |
| 599     | 服务端操作失败                                                                                                                                                                                                                                                                                                                             |
| 608     | 资源内容被修改                                                                                                                                                                                                                                                                                                                             |
| 612     | 指定资源不存在或已被删除                                                                                                                                                                                                                                                                                                                        |
| 614     | 目标资源已存在                                                                                                                                                                                                                                                                                                                             |
| 630     | 已创建的空间数量达到上限，无法创建新空间。                                                                                                                                                                                                                                                                                                               |
| 631     | 指定空间不存在                                                                                                                                                                                                                                                                                                                             |
| 640     | 调用[列举资源(list)](/products/kodo/rs/4-list)接口时，指定非法的`marker`参数。                                                                                                                                                                                                                                                                        |
| 701     | 在断点续上传过程中，后续上传接收地址不正确或`ctx`信息已过期。                                                                                                                                                                                                                                                                                                   |

<span id="Null">
  如遇 5xx 系列错误，请将完整的错误信息（包括所有的 HTTP 响应头部）

  [提交工单](https://support.qiniu.com/tickets/category)

   给我们。
</span>


# API 概览 (/products/kodo/3939-overview-of-the-api)



最近更新时间: 2025-06-10 11:11:03

<a id="service-operation" />

# **Service API** [#service-api]

| 接口                                                               | 说明                |
| ---------------------------------------------------------------- | ----------------- |
| [buckets](/products/kodo/the-service-interface/3926-get-service) | 列举请求者拥有的所有 Bucket |

<br />

<a id="bucket-operation" />

# **Bucket API** [#bucket-api]

| 接口                                                                                 | 说明              |
| ---------------------------------------------------------------------------------- | --------------- |
| [mkbucketv3](/products/kodo/the-bucket-interface/0-mkbucketv3)                     | 创建新的存储空间        |
| [drop](/products/kodo/the-bucket-interface/1-drop-bucket)                          | 删除指定存储空间        |
| [domains](/products/kodo/the-bucket-interface/2-get-the-bucket-space-domain)       | 获取一个空间绑定的所有域名列表 |
| [private](/products/kodo/the-bucket-interface/3946-set-bucket-private)             | 设置空间访问权限        |
| [putBucketTagging](/products/kodo/the-bucket-interface/3-put-bucket-tagging)       | 设置空间标签          |
| [getBucketTagging](/products/kodo/the-bucket-interface/6315-get-bucket-tagging)    | 查询空间标签          |
| [deleteBucketTagging](/products/kodo/the-bucket-interface/4-delete-bucket-tagging) | 删除空间标签          |

<br />

<a id="object-operation" />

# **Object API** [#object-api]

| 接口                                                                                                  | 说明                                                      |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| [upload](/products/kodo/rs/8-upload)                                                                | 用于在一次 HTTP 会话中上传单一的一个对象                                 |
| [mkblk](/products/kodo/rs/shard-to-upload/1-mkblk)                                                  | 为后续分片上传创建一个新的块，同时上传第一片数据                                |
| [bput](/products/kodo/rs/shard-to-upload/0-bput)                                                    | 上传指定块的一片数据，具体数据量可根据现场环境调整，同一块的每片数据必须串行上传                |
| [mkfile](/products/kodo/rs/shard-to-upload/2-mkfile)                                                | 将上传好的所有数据块按指定顺序合并成一个对象资源                                |
| [initiateMultipartUpload](/products/kodo/rs/multipartupload-interface/0-initialize-multipartupload) | 通知服务端开启分块上传任务,得到全局唯一任务UploadId                          |
| [uploadPart](/products/kodo/rs/multipartupload-interface/1-upload-part)                             | 分块上传数据，需指定的任务UploadId                                   |
| [completeMultipartUpload](/products/kodo/rs/multipartupload-interface/3-complete-multipart-upload)  | 完成整个对象的分块上传，需指定的任务UploadId                              |
| [abortMultipartUpload](/products/kodo/rs/multipartupload-interface/2-abort-multipart-upload)        | 中止分块上传任务，并且删除已经上传的块，需指定的任务UploadId                      |
| [listParts](/products/kodo/rs/multipartupload-interface/4-listparts)                                | 列举指定 UploadId 所属的所有已经上传成功Part                           |
| [list](/products/kodo/rs/4-list)                                                                    | 用于列举指定空间里的所有对象条目                                        |
| [stat](/products/kodo/rs/7-stat)                                                                    | 仅获取对象的 Metadata 信息，不返回对象内容                              |
| [chgm](/products/kodo/rs/1-chgm)                                                                    | 修改对象的 MIME 类型信息                                         |
| [move](/products/kodo/rs/5-move)                                                                    | 将源空间的指定对象移动到目标空间，或在同一空间内对对象重命名                          |
| [copy](/products/kodo/rs/2-copy)                                                                    | 将指定对象复制为新命名对象                                           |
| [delete](/products/kodo/rs/3-delete)                                                                | 删除指定对象                                                  |
| [batch](/products/kodo/rs/0-batch)                                                                  | 指在单一请求中执行多次获取元信息、移动、复制、删除操作，极大提高对象管理效率                  |
| [chstatus](/products/kodo/rs/11-modify-the-file-status)                                             | 修改对象的存储状态，即切换启用、禁用状态                                    |
| [chtype](/products/kodo/rs/9-modify-the-file-storage-type)                                          | 修改对象的存储类型信息，即标准存储、低频存储、归档直读存储等不同存储类型之间的互相转换             |
| [restoreAr](/products/kodo/rs/12-restore-archive)                                                   | 解冻归档存储类型的对象                                             |
| [deleteAfterDays](/products/kodo/rs/9-update-file-lifecycle)                                        | 设置一个对象多少天后过期删除                                          |
| [lifecycle](/products/kodo/rs/8062-modify-object-life-cycle)                                        | 修改已上传对象的生命周期，即修改对象转低频时间、转归档直读事件、转归档时间、转深度归档时间和过期删除时间    |
| [prefetch](/products/kodo/rs/6-prefetch)                                                            | 对于设置了镜像存储的空间，从镜像源站抓取指定名称的对象并存储到该空间中                     |
| [sisyphus/fetch](/products/kodo/rs/10-asynch-fetch)                                                 | 从指定 URL 抓取对象，并将该对象存储到指定空间中。每次只抓取一个对象，抓取时可以指定保存空间名和最终对象名 |

<br />


# 命令行工具 Qshell (/products/kodo/0-qshell)



最近更新时间: 2026-04-10 10:38:05

# 简介 [#简介]

Qshell 是利用七牛文档上公开的API实现的一个方便开发者测试和使用七牛API服务的命令行工具。该工具设计和开发的主要目的就是帮助开发者快速解决问题。目前该工具融合了七牛存储，CDN，以及其他的一些七牛服务中经常使用到的方法对应的便捷命令，比如b64decode，就是用来解码七牛的URL安全的Base64编码用的，所以这是一个面向开发者的工具，任何新的被认为适合加到该工具中的命令需求，都可以在[ISSUE列表](https://github.com/qiniu/qshell/issues)里面提出来，我们会尽快评估实现，以帮助大家更好地使用七牛服务。

Github [代码地址](https://github.com/qiniu/qshell)

# 下载 [#下载]

该工具使用 Go 语言编写而成，当然为了方便不熟悉 Go 或者急于使用工具来解决问题的开发者，我们提供了预先编译好的各主流操作系统平台的二进制文件供大家下载使用，由于平台的多样性，我们把这些二进制打包放到一个文件里面，请大家根据下面的说明各自需要选择支持合适平台来使用。

> 更新日志 [查看](https://github.com/qiniu/qshell/blob/master/CHANGELOG.md)，`强烈建议使用 v2.8.0 及以上版本`.

| 支持平台          | 链接                                                                          |
| ------------- | --------------------------------------------------------------------------- |
| Windows X86   | [下载](https://kodo-toolbox-new.qiniu.com/qshell-v2.19.2-windows-386.zip)     |
| Windows amd64 | [下载](https://kodo-toolbox-new.qiniu.com/qshell-v2.19.2-windows-amd64.zip)   |
| Windows arm   | [下载](https://kodo-toolbox-new.qiniu.com/qshell-v2.19.2-windows-arm.zip)     |
| Linux X86     | [下载](https://kodo-toolbox-new.qiniu.com/qshell-v2.19.2-linux-386.tar.gz)    |
| Linux amd64   | [下载](https://kodo-toolbox-new.qiniu.com/qshell-v2.19.2-linux-amd64.tar.gz)  |
| Linux arm     | [下载](https://kodo-toolbox-new.qiniu.com/qshell-v2.19.2-linux-arm.tar.gz)    |
| Linux arm64   | [下载](https://kodo-toolbox-new.qiniu.com/qshell-v2.19.2-linux-arm64.tar.gz)  |
| Mac OS amd64  | [下载](https://kodo-toolbox-new.qiniu.com/qshell-v2.19.2-darwin-amd64.tar.gz) |
| Mac OS arm64  | [下载](https://kodo-toolbox-new.qiniu.com/qshell-v2.19.2-darwin-arm64.tar.gz) |

# 安装 [#安装]

该工具由于是命令行工具，所以只需要从上面的下载链接下载后即可执行使用。

**Linux和Mac平台**

（1）权限
如果在Linux或者Mac系统上遇到`Permission Denied`的错误，请使用命令`chmod +x qshell`来为文件添加可执行权限。这里的`qshell`是上面文件重命名之后的简写。

（2）任何位置运行
对于Linux或者Mac，如果希望能够在任何位置都可以执行，那么可以把`qshell`所在的目录加入到环境变量`$PATH`中去。假设`qshell`命令被解压到路径`/home/jemy/tools`目录下面，那么我们可以把如下的命令写入到你所使用的bash所对应的配置文件中，如果是`/bin/bash`，那么就是`~/.bashrc`文件，如果是`/bin/zsh`，那么就是`~/.zshrc`文件中。写入的内容为：

```
export PATH=$PATH:/home/jemy/tools
```

保存完毕之后，可以通过两种方式立即生效，其一为输入`source ~/.zshrc`或者`source ~/.bashrc`来使配置立即生效，或者完全关闭命令行，然后重新打开一个即可，接下来就可以在任何位置使用`qshell`命令了。

**Windows平台**

（1）闪退问题
本工具是一个命令行工具，在Windows下面请先打开命令行终端，然后输入工具名称执行，不要双击打开，否则会出现闪退现象。

（2）任何位置运行
如果你希望可以在任意目录下使用`qshell`，请将`qshell`工具可执行文件所在目录添加到系统的环境变量中。由于Windows系统是图形界面，所以方便一点。假设`qshell.exe`命令被解压到路径`E:\jemy\tools`目录下面，那么我们把这个目录放到系统的环境变量`PATH`里面。

![](/docs-assets/products/kodo/%287-tools%29/0-qshell/FrJbSsVTFtZyFcEPKhVMYLfsSd9e-9f7526a26c50.webp)

（3）文本编码问题

当使用 qupload 等需要配置文件的命令时，不要使用 Notepad++ 等编辑器来编写配置文件，在本地右键默认新建一个文本文档来进行编写。

（4） Windows 平台文件路径和字符

Windows 平台下的文件路径需要写为`\\`的写法，如`C:\\Users\\li\\Downloads`。

在使用命令和配置文件时，需要使用 `“”` 双引号,不能使用单引号。

# 密钥设置 [#密钥设置]

该工具有两类命令，一类需要鉴权，另一类不需要。

需要鉴权的命令都需要依赖七牛账号下的 `AccessKey` 和 `SecretKey`。所以这类命令运行之前，需要使用 `account` 命令来设置下 `AccessKey` ，`SecretKey` 。

```
$ qshell account ak sk name
```

其中name表示该账号的名称, 如果ak, sk, name首字母是"-", 需要使用如下的方式添加账号, 这样避免把该项识别成命令行选项:

```
$ qshell account -- ak sk name
```

可以连续使用qshell account 添加账号ak, sk, name信息，qshell会保存这些账号的信息， 可以使用qshell user命令列举账号信息，在各个账号之间切换, 删除账号等

# 账户管理 [#账户管理]

使用qshell user 子命令可以用来管理记录的多账户信息。

1. qshell user ls可以列举账户下所有的账户信息
2. qshell user cu \<userName>可以用来切换账户
3. qshell user cu 不携带\<userName>的话会切换到最近的上个账户；比如我在A账户做完操作后，使用qshell user cu B到了B 账户，那么使用qshell user cu可以切回到A账户.

# 开启命令的自动补全 [#开启命令的自动补全]

**linux上，使用bash**

在centos上，需要安装bash-completion包，默认该包没有安装

```
$ yum install bash-completion -y

```

给当前的bash加入自动补全， 运行命令

```
$ source <(qshell completion bash)

```

也可以把这个配置加入bash的启动文件中，这样到bash启动的时候，会自动加载qshell的补全配置：

```
$ echo "source <(qshell completion bash)" >> ~/.bashrc
```

**Mac上，使用zsh**
把如下代码加入zsh的启动文件中\~/.zshrc

```
if [ $commands[qshell] ]; then
  source <(qshell completion zsh)
fi
```

# 命令选项 [#命令选项]

该工具还有一些有用的选项参数如下：

| 参数    | 描述                                               |
| ----- | ------------------------------------------------ |
| --doc | 查看命令使用手册                                         |
| -d    | 设置是否输出 DEBUG 日志，如果指定这个选项，则输出 DEBUG 级别的日志         |
| -D    | 设置是否输出更加详细的 DEBUG 日志，如果指定这个选项，则输出详细的 DEBUG 级别的日志 |
| -h    | 打印命令列表帮助信息，遇到参数忘记的情况下，可以使用该命令                    |
| -v    | 打印工具版本，反馈问题的时候，请提前告知工具对应版本号                      |
| -C    | qshell配置文件, 其配置格式请看下一节                           |
| -L    | 使用当前工作路径作为qshell的配置目录                            |

# 配置文件 [#配置文件]

1. 配置文件格式支持 json，用户可按需进行配置，配置文件分两层：

* 全局配置：需要在家目录下创建文件名为 .qshell.json 的 json 文件，此配置对 qshell 中的所有账号生效（qshell 当前账号可以通过 qshell user cu 命令进行切换）。
* 账号配置：在 qshell 用户目录下（ $\{家目录}/.qshell/users/$\{qshell 账号名}/ ）创建文件名为 .qshell.json 的 json 文件，此配置仅对当前目录所属的 qshell 账号生效；账号配置优先级大于全局配置。

2. 配置文件可以配置 use\_https 和 host 相关信息：

* use\_https：qshell 请求是否使用 https。
* host 配置：如 io host, up host, uc host, api host, rs host, rsf host；除 uc host 外，其他 host 要么不配置，要么全配置。
  * 公有云可以不配置 host；
  * 私有云：如果私有云支持 uc 查询 bucket 所在区域信息（/query api），那么仅配置 uc host 即可；如果不支持则必须配置所有 host。

注：
qshell 某些命令的配置和文件的配置会有重合，此时优先级如下：

```
qshell 命令配置 > 账号配置 > 全局配置
```

通过 -C/-L 选项指定配置文件，实际是指定账号配置。

配置例子：

默认官方的列举空间的文件使用的是rs.qiniu.com域名，如果因为某种原因，比如私有存储，需要替换使用rs-test.qiniu.com这个域名的话，那么只需要
在家目录下创建文件名字为.qshell.json的配置文件，文件内容为

```json
{
    "hosts": {
        "rs": "rs-test.qiniu.com"
    }
}
```

如果想要更改io host为io-test.qiniu.com的话，只需要继续在上面的hosts中添加，如下：

```json
{
    "hosts": {
        "rs": "rs-test.qiniu.com",
        "io": "io-test.qiniu.com"
    }
}
```

同理如果全部修改的话

```json
{
    "hosts": {
        "rs": "rs-test.qiniu.com",
        "io": "io-test.qiniu.com",
        "api": "",
        "rsf": ""
    }
}
```

# 命令列表 [#命令列表]

* `v2.7.0 及以上版本，命令列表及命令使用文档说明，可直接使用 qshell 自助查看。`
  * `qshell -h，显示支持命令列表`
  * `qshell <子命令> --doc 查看详细命令使用说明`
* 以下列表内使用文档链接适用于 v2.3.0 —— v2.6.3 版本
* 查看工具版本号请使用命令 qshell -v

## 账号设置命令 [#账号设置命令]

| 命令      | 类别 | 描述                                | 详细                                                               |
| ------- | -- | --------------------------------- | ---------------------------------------------------------------- |
| account | 账号 | 设置或显示当前用户的`AccessKey`和`SecretKey` | [文档](http://github.com/qiniu/qshell/blob/master/docs/account.md) |
| user    | 账号 | 列举账号信息，在各个账号之间切换, 删除账号            | [文档](http://github.com/qiniu/qshell/blob/master/docs/user.md)    |

## 存储相关命令 [#存储相关命令]

| 命令               | 类别    | 描述                                             | 详细                                                                        |
| ---------------- | ----- | ---------------------------------------------- | ------------------------------------------------------------------------- |
| mkbucket         | 创建    | 创建存储空间                                         | [文档](http://github.com/qiniu/qshell/blob/master/docs/mkbucket.md)         |
| bucket           | 查看    | 查看存储空间信息                                       | [文档](http://github.com/qiniu/qshell/blob/master/docs/bucket.md)           |
| batchdelete      | 删除    | 批量删除七牛空间中的文件，可以直接根据`listbucket`的结果来删除          | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchdelete.md)      |
| delete           | 删除    | 删除七牛空间中的一个文件                                   | [文档](http://github.com/qiniu/qshell/blob/master/docs/delete.md)           |
| batchchgm        | 修改    | 批量修改七牛空间中文件的MimeType                           | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchchgm.md)        |
| chgm             | 修改    | 修改七牛空间中的一个文件的MimeType                          | [文档](http://github.com/qiniu/qshell/blob/master/docs/chgm.md)             |
| batchchtype      | 修改    | 批量修改七牛空间中的文件的存储类型                              | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchchtype.md)      |
| chtype           | 修改    | 修改七牛空间中的一个文件的存储类型                              | [文档](http://github.com/qiniu/qshell/blob/master/docs/chtype.md)           |
| batchexpire      | 修改    | 批量修改七牛空间中的文件的生存时间,注意:`取消`生存时间设置`只有2.10及以上版本`支持 | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchexpire.md)      |
| expire           | 修改    | 修改七牛空间中的一个文件的生存时间                              | [文档](http://github.com/qiniu/qshell/blob/master/docs/expire.md)           |
| batchcopy        | 拷贝    | 批量复制七牛空间中的文件到另一个空间                             | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchcopy.md)        |
| copy             | 拷贝    | 复制七牛空间中的一个文件                                   | [文档](http://github.com/qiniu/qshell/blob/master/docs/copy.md)             |
| batchmove        | 移动    | 批量移动七牛空间中的文件到另一个空间                             | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchmove.md)        |
| move             | 移动    | 移动或重命名七牛空间中的一个文件                               | [文档](http://github.com/qiniu/qshell/blob/master/docs/move.md)             |
| batchrename      | 重命名   | 批量重命名七牛空间中的文件                                  | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchrename.md)      |
| rename           | 重命名   | 重命名七牛空间中的文件                                    | [文档](http://github.com/qiniu/qshell/blob/master/docs/rename.md)           |
| batchrestorear   | 解冻    | 批量解冻七牛空间中的归档/深度归档存储类型文件                        | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchrestorear.md)   |
| restorear        | 解冻    | 解冻七牛空间中的归档/深度归档存储类型文件                          | [文档](http://github.com/qiniu/qshell/blob/master/docs/restorear.md)        |
| batchstat        | 查询    | 批量查询七牛空间中文件的基本信息                               | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchstat.md)        |
| stat             | 查询    | 查询七牛空间中一个文件的基本信息                               | [文档](http://github.com/qiniu/qshell/blob/master/docs/stat.md)             |
| batchchlifecycle | 修改    | 批量修改七牛空间中文件的生命周期                               | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchchlifecycle.md) |
| chlifecycle      | 修改    | 修改七牛空间中一个文件的生命周期                               | [文档](http://github.com/qiniu/qshell/blob/master/docs/chlifecycle.md)      |
| buckets          | 查询    | 获取当前账号下所有的空间名称                                 | [文档](http://github.com/qiniu/qshell/blob/master/docs/buckets.md)          |
| domains          | 查询    | 获取指定空间的所有关联域名                                  | [文档](http://github.com/qiniu/qshell/blob/master/docs/domains.md)          |
| listbucket       | 列举    | 列举七牛空间里面的所有文件                                  | [文档](http://github.com/qiniu/qshell/blob/master/docs/listbucket.md)       |
| listbucket2      | 列举    | 列举七牛空间里面的所有文件                                  | [文档](http://github.com/qiniu/qshell/blob/master/docs/listbucket2.md)      |
| batchforbidden   | 禁用    | 批量修改文件可访问状态                                    | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchforbidden.md)   |
| forbidden        | 禁用    | 修改文件可访问状态                                      | [文档](http://github.com/qiniu/qshell/blob/master/docs/forbidden.md)        |
| fput             | 上传    | 以文件表单的方式上传一个文件                                 | [文档](http://github.com/qiniu/qshell/blob/master/docs/fput.md)             |
| rput             | 上传    | 以分片上传的方式上传一个文件                                 | [文档](http://github.com/qiniu/qshell/blob/master/docs/rput.md)             |
| qupload          | 上传    | 同步数据到七牛空间， 带同步进度信息，和数据上传完整性检查（配置式）             | [文档](http://github.com/qiniu/qshell/blob/master/docs/qupload.md)          |
| qupload2         | 上传    | 同步数据到七牛空间， 带同步进度信息，和数据上传完整性检查（命令式）             | [文档](http://github.com/qiniu/qshell/blob/master/docs/qupload2.md)         |
| qdownload        | 下载    | 从七牛空间同步数据到本地，支持只同步某些前缀的文件，支持增量同步               | [文档](http://github.com/qiniu/qshell/blob/master/docs/qdownload.md)        |
| qdownload2       | 下载    | 从七牛空间同步数据到本地，支持只同步某些前缀的文件，支持增量同步（命令式）          | [文档](http://github.com/qiniu/qshell/blob/master/docs/qdownload2.md)       |
| get              | 下载    | 下载存储空间中的文件                                     | [文档](http://github.com/qiniu/qshell/blob/master/docs/get.md)              |
| fetch            | 抓取    | 从Internet上抓取一个资源并存储到七牛空间中                      | [文档](http://github.com/qiniu/qshell/blob/master/docs/fetch.md)            |
| batchfetch       | 抓取    | 从Internet批量抓取资源到七牛空间中                          | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchfetch.md)       |
| sync             | 抓取    | 从Internet上抓取一个资源并存储到七牛空间中，适合大文件的场合             | [文档](http://github.com/qiniu/qshell/blob/master/docs/sync.md)             |
| abfetch          | 抓取    | 异步抓取网络资源到七牛存储空间                                | [文档](http://github.com/qiniu/qshell/blob/master/docs/abfetch.md)          |
| m3u8delete       | m3u8  | 根据流媒体播放列表文件删除七牛空间中的流媒体切片                       | [文档](http://github.com/qiniu/qshell/blob/master/docs/m3u8delete.md)       |
| m3u8replace      | m3u8  | 修改流媒体播放列表文件中的切片引用域名                            | [文档](http://github.com/qiniu/qshell/blob/master/docs/m3u8replace.md)      |
| create-share     | 共享文件夹 | 需要分享的目录或前缀创建授权链接                               | [文档](http://github.com/qiniu/qshell/blob/master/docs/create-share.md)     |
| share-cp         | 共享文件夹 | 从目录分享链接内下载单个文件或按目录批量下载文件                       | [文档](http://github.com/qiniu/qshell/blob/master/docs/share-cp.md)         |
| share-ls         | 共享文件夹 | 列举分享的目录和文件                                     | [文档](http://github.com/qiniu/qshell/blob/master/docs/share-ls.md)         |
| batchsign        | 其他    | 批量根据资源的公开外链生成资源的私有外链                           | [文档](http://github.com/qiniu/qshell/blob/master/docs/batchsign.md)        |
| dircache         | 其他    | 输出本地指定路径下所有的文件列表                               | [文档](http://github.com/qiniu/qshell/blob/master/docs/dircache.md)         |
| privateurl       | 其他    | 生成私有空间资源的访问外链                                  | [文档](http://github.com/qiniu/qshell/blob/master/docs/privateurl.md)       |

<br />

<br />

## CDN 相关的命令 [#cdn-相关的命令]

|命令|描述|详细|
\|------|------------|----------|--------|
|cdnrefresh|批量刷新cdn的访问外链或目录|[文档](http://github.com/qiniu/qshell/blob/master/docs/cdnrefresh.md)|
|cdnprefetch|批量预取cdn的访问外链|[文档](http://github.com/qiniu/qshell/blob/master/docs/cdnprefetch.md)|

<br />

<br />

## 工具类命令 [#工具类命令]

| 命令        | 描述                                                  | 详细                                                                 |
| --------- | --------------------------------------------------- | ------------------------------------------------------------------ |
| b64encode | base64编码工具，可选是否使用UrlSafe方式，默认UrlSafe                | [文档](http://github.com/qiniu/qshell/blob/master/docs/b64encode.md) |
| b64decode | base64解码工具，可选是否使用UrlSafe方式，默认UrlSafe                | [文档](http://github.com/qiniu/qshell/blob/master/docs/b64decode.md) |
| urlencode | url编码工具                                             | [文档](http://github.com/qiniu/qshell/blob/master/docs/urlencode.md) |
| urldecode | url解码工具                                             | [文档](http://github.com/qiniu/qshell/blob/master/docs/urldecode.md) |
| ts2d      | 将timestamp(单位秒)转为UTC+8:00中国日期，主要用来检查上传策略的deadline参数 | [文档](http://github.com/qiniu/qshell/blob/master/docs/ts2d.md)      |
| tms2d     | 将timestamp(单位毫秒)转为UTC+8:00中国日期                      | [文档](http://github.com/qiniu/qshell/blob/master/docs/tms2d.md)     |
| tns2d     | 将timestamp(单位100纳秒)转为UTC+8:00中国日期                   | [文档](http://github.com/qiniu/qshell/blob/master/docs/tns2d.md)     |
| d2ts      | 将日期转为timestamp(单位秒)                                 | [文档](http://github.com/qiniu/qshell/blob/master/docs/d2ts.md)      |
| ip        | 根据淘宝的公开API查询ip地址的地理位置                               | [文档](http://github.com/qiniu/qshell/blob/master/docs/ip.md)        |
| unzip     | 解压zip文件，支持UTF-8编码和GBK编码                             | [文档](http://github.com/qiniu/qshell/blob/master/docs/unzip.md)     |
| reqid     | 七牛自定义头部X-Reqid解码工具                                  | [文档](http://github.com/qiniu/qshell/blob/master/docs/reqid.md)     |
| qetag     | 根据七牛的qetag算法来计算文件的hash                              | [文档](http://github.com/qiniu/qshell/blob/master/docs/qetag.md)     |
| saveas    | 实时处理的saveas链接快捷生成工具                                 | [文档](http://github.com/qiniu/qshell/blob/master/docs/saveas.md)    |

<br />

<br />

## 音视频处理相关命令 [#音视频处理相关命令]

| 命令     | 类别 | 描述          | 详细                                                              |
| ------ | -- | ----------- | --------------------------------------------------------------- |
| pfop   | 提交 | 提交异步音视频处理请求 | [文档](http://github.com/qiniu/qshell/blob/master/docs/pfop.md)   |
| prefop | 查询 | 查询七牛数据处理的结果 | [文档](http://github.com/qiniu/qshell/blob/master/docs/prefop.md) |

<br />

<br />

## 签名类命令 [#签名类命令]

| 命令    | 类别 | 描述                                 | 详细                                                             |
| ----- | -- | ---------------------------------- | -------------------------------------------------------------- |
| token | 其他 | 计算upToken, Qbox token, Qiniu Token | [文档](http://github.com/qiniu/qshell/blob/master/docs/token.md) |

<br />

<br />

## 第三方存储类工具 [#第三方存储类工具]

| 命令            | 类别 | 描述               | 详细                                                                     |
| ------------- | -- | ---------------- | ---------------------------------------------------------------------- |
| alilistbucket | 列举 | 列举阿里OSS空间里面的所有文件 | [文档](http://github.com/qiniu/qshell/blob/master/docs/alilistbucket.md) |
| awslist       | 列举 | 列举亚马逊的存储空间       | [文档](http://github.com/qiniu/qshell/blob/master/docs/awslist.md)       |
| awsfetch      | 抓取 | 从亚马逊存储迁移数据到七牛存储  | [文档](http://github.com/qiniu/qshell/blob/master/docs/awsfetch.md)      |

<br />

<br />

# 问题反馈 [#问题反馈]

如果您有任何问题，请写在[ISSUE列表](https://github.com/qiniu/qshell/issues)里面，我们会尽快回复您。


# 图形化工具 Kodo Browser (/products/kodo/1-kodo-browser)



最近更新时间: 2025-09-15 11:53:06

Kodo Browser 是七牛对象存储提供的图形化管理工具，支持用户通过可视化页面进行上传、下载等操作。

Github [代码地址](https://github.com/qiniu/kodo-browser)

# 下载 [#下载]

| 支持平台        | 链接                                                                                              |
| ----------- | ----------------------------------------------------------------------------------------------- |
| Windows x86 | [下载](https://kodo-toolbox-new.qiniu.com/kodobrowser/client/kodo-browser-Windows-x86-v2.3.2.zip) |
| Windows x64 | [下载](https://kodo-toolbox-new.qiniu.com/kodobrowser/client/kodo-browser-Windows-x64-v2.3.2.zip) |
| Mac OS      | [下载](https://kodo-toolbox-new.qiniu.com/kodobrowser/client/kodo-browser-Mac%20OS-v2.3.2.zip)    |
| Linux x64   | [下载](https://kodo-toolbox-new.qiniu.com/kodobrowser/client/kodo-browser-Linux-x64-v2.3.2.zip)   |

[查看更新日志/下载历史版本](https://github.com/qiniu/kodo-browser/releases)

# 登录 [#登录]

安装后，点击 Kodo Browser 图标进入登录页面；默认是登录、管理公有云存储资源，Endpoint也可以选择「自定义（私有云）」，登录、管理私有云存储资源。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FhMfb50vakSlRA_0kxKPL-Myg4v-def0ea0172f8.webp)

* AccessKeyId/AccessKeySecret：通过[七牛控制台个人中心](https://portal.qiniu.com/user/key)获取 AK/SK

登录私有云环境时，需要先在登录页面配置区域信息；Endpoint选择「自定义（私有云）」后，点击右侧设置图标即可打开配置页面

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fsjf5_jmieWUXIz3OHS5mPirewQn-ce381fafa263.webp)

* 自定义 Endpoint 未配置时，禁止登录私有云环境。支持开启区域设置，配置区域 Endpoint。
* 自 1.0.10 版本开始，支持 IAM 用户登录使用 Kodo Browser。

## **记住密钥** [#记住密钥]

可以勾选「记住密钥」，记录登录成功的 AccessKeyId/AccessKeySecret 信息，以便于下一次的快速登录。

<font color="red">
  **注意：请不要在临时使用的电脑上勾选记住密钥！**

   
</font>

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FvmaU1N-2bJ84XSV55523nieFRj3-6f7cafc516a4.webp)

点击「AK 历史」，可以选择之前已验证通过的 AccessKeyId/AccessKeySecret 对来做登录。已添加的 AK 历史记录可以被删除。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FvE4UXQrwbPTqfa49DgqYHrJ6QnE-0254e5ef5544.webp)

* 登录私有云环境时，需保证当前的私有云环境区域配置信息与 AccessKeyId/AccessKeySecret 相匹配。

## **切换账号** [#切换账号]

客户端允许在不退出登录的情况下，直接切换账号。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fg8uE0rPsHZWcOfeNRS5WJafg3Z-6eadc88acfdf.webp)

* 点击客户端右上角的账户小图标
* 点击切换账号，在 AK 历史弹窗中选择要切换的 AK 点击「使用」
* 客户端就会尝试以所选择的账号重新登录，并定位到首页展示

## **使用分享链接登录** [#使用分享链接登录]

点击「使用分享链接登录」，支持使用 Kodo Browser 或 Kodo 控制台生成的目录分享链接和链接提取码登录、进而访问已授权文件列表。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fizj8fXVkzBWsys39GU_kN8na4SX-afe109ff13cf.webp)

* 输入分享链接，支持由 Kodo Browser 或 Kodo 控制台获取目录分享链接
* 输入提取码，为6位由数字或字母组成
* 点击「登录」，即可查看被授权访问的文件列表

# 功能说明 [#功能说明]

## **Bucket 操作** [#bucket-操作]

自1.0.13 版本开始，客户端支持公有云的授权空间管理。

### **创建 Bucket** [#创建-bucket]

* 在 Kodo browser 首页点击【新建 Bucket】
* 输入 Bucket 信息
  * 名称：由 3 \~ 63 个字符组成 ，可包含小写字母、数字和短划线，且必须以小写字母或者数字开头和结尾
  * 区域：选择 Bucket 所在区域
  * ACL 权限：暂不支持设置，默认创建公开 Bucket
* 点击【确定】

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FlK4Q0UVmrbTiGoxnd54JXGkzAH4-5162815fe3df.webp)

### **删除 Bucket** [#删除-bucket]

在 Bucket 列表中选中指定的 Bucket，点击【更多】-【删除】即可。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fn7sNC15SiE28mFX6lpO35SUvxi0-02e31da5c8a8.webp)

### **编辑 Bucket 备注** [#编辑-bucket-备注]

在 Bucket 列表中选中指定的 Bucket，点击【更多】-【编辑备注】即可。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FmgN9GL9brGlRokLoqepXvQmgK83-2e414f9709d9.webp)

## **Object 操作** [#object-操作]

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fi42ertE5m2H9z04-WxZX3BcoMzR-31fa8765bb11.webp)

### **创建目录** [#创建目录]

* 在 Bucket 列表中点击对应的 Bucket，进入 Bucket 内对象列表
* 点击【创建目录】
* 输入目录名称，点击【确定】

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FuY3dw-GnR2DDmesbK2WGkAXl-eP-17a6a088954b.webp)

### **上传文件/目录** [#上传文件目录]

* 在指定的 Bucket 或目录内，点击【上传】
* 选择需要上传的文件或目录即可

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FnS3qywIgswXJI4n2XGx6rqR7P2C-436f121ebcd0.webp)

* 上传文件/目录，支持拖拽操作。&#x2A;*注意，Windows 系统下做目录上传时，需要采用拖拽操作。**
* 上传文件时，可以指定要保存的存储类型。客户端默认禁止上传同名文件，但是可以在上传确认界面中开启「覆盖上传」，在本次上传中执行覆盖上传、变更同名文件。
* 如本空间已开启传输加速功能，则支持在上传文件时选择开启加速上传，使用传输加速域名上传文件、加快上传速度。&#x2A;*注意，使用传输加速域名上传时，将产生传输加速费用。**

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fk2mkDV69S0HABJssiU1SsEzzeo1-7a0a3ed8ad6e.webp)

* 客户端默认允许上传空目录，但是可以在上传任务管理器中设置「是否允许空目录上传」；图标为蓝色时表示「允许空目录上传」。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FidbqAYYJ0TODkA9XoGpzERjMw5x-2bce26ab8fc0.webp)

### **下载文件/目录** [#下载文件目录]

* 在指定的 Bucket 或目录内，选中需要下载的文件或目录
* 点击【下载】，并选择下载目录即可
* 如本地下载目录中包含同名文件，将会在原文件名后添加后缀保存

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FiuZX8R5RTAVVwZc6ndjPrJO_Azz-38bb573d9bf4.webp)

* 客户端下载同名文件时，默认会在文件名最后添加数字编号；但是可以在上传任务管理器中设置「是否开启覆盖下载」模式，在下载同名文件时覆盖所选路径下已存在的文件；图标为蓝色时表示「开启覆盖下载」。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FlgsKPvqJVL81SG8i2gSr-aaG0JW-34af098136e9.webp)

* 客户端默认使用空间源站域名做文件预览和下载，也支持选用空间已绑定的cdn域名来预览和下载文件。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fosphyzk-Al9hilJsdE12XX2kdNi-ccc2356488a0.webp)

<font color="red">
  **注意**
</font>

默认不使用自有域名下载公有云存储的文件时，**会产生一定的外网流出流量**，**可能会产生流量计费**。
使用空间已绑定的cdn域名下载公有云存储的文件时，**则会产生CDN回源流量**。

### **复制文件/目录** [#复制文件目录]

* 在指定的 Bucket 或目录内，选中需要复制的文件或目录
* 点击【复制】
* 进入需要粘贴文件的 Bucket 或目录，点击【粘贴】

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FqAiC38d0lqFGUBiYAfNAOzarPUr-613435e0b25f.webp)

* 当原 Bucket 与目标 Bucket 一致，需要重命名文件，否则会提示【已有同名文件，是否覆盖？】，此时可根据您的需求选择【确定】或【取消】
* 当原 Bucket 与目标 Bucket 不一致，会覆盖目标 Bucket 中的同名原文件
  * **`注意：被覆盖的同名目标文件如为未存满最短时间的低频、归档直读、归档和深度归档存储类型，该操作将产生提前删除费用，请谨慎操作！`**

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FlGxuZkMLgD0Sl6vyCC2m5DpKIUt-b9584d2c6853.webp)

* 不支持跨区域复制

### **移动文件/目录** [#移动文件目录]

* 在指定的 Bucket 或目录内，选中需要移动的文件或目录
* 点击【更多】-【移动】
* 进入需要粘贴文件的 Bucket 或目录，点击【粘贴】

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FpDyj6K9cpRmtVZ3YmeV9jOzGHS7-526b19625432.webp)

* 当原 Bucket 与目标 Bucket 一致，需要重命名文件，否则会提示【已有同名文件，是否覆盖？】，此时可根据您的需求选择【确定】或【取消】
* 当原 Bucket 与目标 Bucket 不一致，会覆盖目标 Bucket 中的同名原文件

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FhZQS-QxgxAMICEgmXlL1ThqQKWG-604aafcfa029.webp)

* 不支持跨区域移动
  &#x2A;*`注意：`**
  * **`对未存满最短时间的低频、归档直读、归档和深度归档存储类型的文件移动，该操作将产生提前删除费用，请谨慎操作！`**
  * **`移动目录将移动该目录下所有文件。如存在未存满最短时间的低频、归档直读、归档和深度归档存储类型的文件，该操作将产生提前删除费用，请谨慎操作！`**

### **重命名文件/目录** [#重命名文件目录]

* 在指定的 Bucket 或目录内，选中需要重命名的文件或目录
* 点击【重命名】
* 输入文件名称：禁止以 `/` 开头或结尾，禁止输入连续的 `/`。当文件名在 Bucket 中已存在，会提示【已有同名文件，是否覆盖？】，此时可根据您的需求选择【确定】或【取消】
* 点击【确定】
  &#x2A;*`注意：`**
  * **`对未存满最短时间的低频、归档直读、归档和深度归档存储类型的文件重命名，该操作将产生提前删除费用，请谨慎操作！`**
  * **`修改目录名将修改该目录下所有文件的路径。如存在未存满最短时间的低频、归档直读、归档和深度归档存储类型的文件，该操作将产生提前删除费用，请谨慎操作！`**

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FswyquUt1qKETBinXwKiSzJ3qAHr-49b93e1957ea.webp)

### **删除文件/目录** [#删除文件目录]

* 在指定的 Bucket 或目录内，选中需要删除的文件或目录
* 点击【删除】并【确定】

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fl543QnOJFL83gta8D7iutNbC27x-9aa522d7de45.webp)

* 支持单个文件、目录的删除，也支持批量删除
* **`删除未存满最短时间的低频、归档直读、归档和深度归档存储类型的文件，将产生提前删除费用，请谨慎操作！`**

### **解冻归档存储和深度归档存储文件** [#解冻归档存储和深度归档存储文件]

归档存储和深度归档存储类型的文件，鼠标悬停在文件「名称」上时，可以查看解冻状态。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FlZNBdPaVoKudzhowyd3P0tXGii-a13152f68b52.webp)

在文件列表视图的「操作」列中点击解冻图标，可以解冻归档存储和深度归档存储类型的文件。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fsp5fhceYja5G7C86-1G-oRA1UCZ-5ac1909177e9.webp)

* 设置解冻天数：1\~7。
* 点击【确定】
* 成功提交解冻请求后，文件会切换为「解冻中」的状态。
* 归档存储 1~~5 分钟解冻完成，深度归档存储 5~~12 小时解冻完成。当文件变为「已解冻」状态时，文件的内容才可以被正常访问。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fkj0AAE1Ldpp56tzLFPsksKThMeg-d0986eb340a1.webp)

### **修改文件存储类型** [#修改文件存储类型]

文件列表中会展示文件的存储类型信息。[不同存储类型的差别](/products/kodo/kodo-category)

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fjj4na28TXJMKy3eslQN0E2Kwu-t-800d48da2c29.webp)

在列表视图的「操作」列中点击修改存储类型的图标，可以修改文件的存储类型。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FnijVLRF47Hstw8NH9mdG8oApKe5-830b327773df.webp)

* 归档存储和深度归档存储类型的文件需要先解冻为可读取状态，才能进行类型转换。
* 低频存储、归档直读存储、归档存储和深度归档存储类型，Object 最小计量 64KB。
* 从低频存储类型转换为其他类型时，如果该 Object 保存时间少于 30 天，将按照 30 天来计费。
* 从归档直读存储类型转换为其他类型时，如果该 Object 保存时间少于 60 天，将按照 60 天来计费。
* 从归档存储类型转换为其他类型时，如果该 Object 保存时间少于 60 天，将按照 60 天来计费。
* 从深度归档存储类型转换为其他类型时，如果该 Object 保存时间少于 180 天，将按照 180 天来计费。

### **预览文件** [#预览文件]

在列表视图中双击文件名，或在矩阵视图中双击文件即可预览。目前支持 txt 和大部分图片文件的预览。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fl-4g0wvB3SxkRE3XEEcar4bPfBK-c4d4d13a071b.webp)

**注意：归档存储和深度归档存储文件，必须先解冻才能预览。**

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FpeZpo78cyd7HfBr_fXwhz1md2IK-7366140d5c19.webp)

### **获取外链** [#获取外链]

在文件列表视图的「操作」列中点击外链图标，或在文件的预览界面点击「获取外链」，都能方便地生成并复制文件外链。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FpPrpFmopeuwIuj6HLCXIgI3rme5-9ce0061f3c8a.webp)

默认不使用自有域名时，文件外链必须设置有效期，有效期范围1-604800s，默认600。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FrzKrPi5G5d8g3RSVuTpe7ZbVjOF-d4a1e9a82a53.webp)

* 设置外链有效期
* 外链生成，【点击复制】文件外链即拷贝到剪切板

客户端支持选用空间已绑定的自定义 cdn 域名或自定义源站域名来生成外链。使用自定义域名时，

* 空间是公开的，生成永久有效外链，无需设置有效期
* 空间是私有的，必须设置外链有效期，有效期最长 1 年，默认 600s

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fvdiulw6WIAcK06jsXk2t3c53B2h-d3d5dfaa5251.webp)

<font color="red">
  **注意**
</font>

不使用自有域名（使用空间的源站域名）或使用自定义源站域名生成外链，经由外链访问公有云存储的文件时，**会产生一定的外网流出流量**，**可能会产生流量计费**。
使用空间的cdn域名生成外链，经由外链访问公有云存储的文件时，**产生的是 CDN 回源流量**。
归档存储和深度归档存储文件，可以直接获取外链，但是文件访问前需要先解冻。

### **批量导出外链** [#批量导出外链]

在文件列表视图中勾选多个文件，点击批量操作区域的「导出外链」，可以一次性将多个文件的外链以 csv 文件保存到本地。
勾选目录时，会把目录下所有文件的外链导出，而目录本身则不会导出外链。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FqTgbq-thOVtedu3G0I7gdwhwLC-5079a03bac21.webp)

客户端支持选用空间已绑定的自定义 cdn 域名或自定义源站域名来生成外链：

* 不使用自有域名时，文件外链必须设置有效期，有效期范围1-604800s，默认600s
* 使用自定义域名时，空间是公开的，无需设置外链有效期；空间是私有的，则必须设置有效期，有效期最长 1 年，默认 600s

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FofGSxEYgsjdmJCGVYrwgIuKkdrw-0ad56fed84d2.webp)

* 设置外链有效期
* 点击【生成并导出】
* 客户端会弹出本地目录选择框，选择外链文件要保存的路径
* 确认后，客户端将把所有文件外链以 csv 格式保存至所选路径下。csv 文件命名举例：kodo-browser-download-links-20200317110450.csv
  * 使用时建议以文本编辑工具打开csv文件
  * 文件名有中文字符时，使用 Excel 打开csv文件需要选择编码方式：打开新的空白sheet ——> 数据 ——> 从文本 ——> 选择已下载的 csv 文件，点击获取数据 ——> 选择文件原始格式或编码为：Unicode(UTF-8) ——> 设置数据分隔，点击完成，导入的中文字符即可正常显示

### **分享目录** [#分享目录]

在文件列表目录栏的「操作」列中点击分享图标

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FvuFOrqLr0Yp9p0uaH116EDhjfBB-c32dd9397f26.webp)

* 设置分享链接有效期，支持自定义范围 900 - 7200 秒或快速选择15分钟、30分钟、1小时、2小时
* 定义提取码，必须为 6 位，只能由字母数字组成；支持自定义或点击「随机生成」自动生成
* 点击「提交」获取分享链接，点击「复制链接与提取码」按钮进行复制
* 将链接和提取码分发给他人，即可通过链接访问该目录下的文件。支持通过浏览器或 Kodo Browser 打开分享链接。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fpzr0NHn2EseauYYu6n87XgKHF_z-03870b3f68a6.webp)

## **管理外部路径** [#管理外部路径]

经由 Bucket Policy 授予权限的空间或目录，需要添加为「外部路径」，才能在客户端中使用和管理。

### **开启外部路径功能** [#开启外部路径功能]

点击【设置】进入设置页面

* 外部路径：勾选时，表示启用外部路径功能；不勾选时，客户端不显示「外部路径」菜单。外部路径功能，默认不启用。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FvPw6iOF9NxjhhSn2F7EH8JwPFNY-17dd91ae86c4.webp)

### **管理外部路径** [#管理外部路径-1]

外部路径功能启用后，界面会出现「外部路径」的菜单

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FuMKfZ7TGXw_8dkwPxd4gXr1cgmS-52d6e3a5cbfa.webp)

点击「添加外部路径」打开弹窗

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FnkPWy6XlogFcw-S0HqF8FBOlKk6-4dc4fb1c1708.webp)

* 输入外部路径名：可以是被授权的空间或目录，需要由授权者提供。
* 选择外部路径的区域
* 点击确定，添加完成

添加好的外部路径，只要有相应的权限，支持的操作与自己创建的空间一致。

选中某个已添加的外部路径，点击「更多」的「删除」，可以把这个外部路径移除。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fvmj7x8SAiL7qevRrPJ6ApCefEIo-3c4de1544ee7.webp)

* 此操作为客户端的配置移除，并没有真正删除对应的空间或目录。客户端不支持删除通过 Bucket Policy 授予权限的空间或目录。

## **其他操作** [#其他操作]

### **断点上传设置** [#断点上传设置]

点击【设置】进入设置页面

* 断点上传：勾选时表示开启断点上传功能；不勾选时，「断点上传」相关设置不生效
* 断点上传文件阈值：当开启断点上传且文件大小大于此阈值时，自动使用可恢复的分片上传，范围：10MB\~1000MB
* 断点上传文件大小：分片大小，范围 1MB\~100MB
* 断点上传分片并发数：同时进行上传的分配文件数，范围 1\~5
* 最大上传任务数：同时上传的任务数，不仅限于断点上传模式；超过任务数量会进入队列，等待前面的任务完成，范围 1\~10
  ![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FjdKf1OKX4nSoHSHUu-RZ2QCVRGF-dbe2846763f3.webp)

### **上传限速** [#上传限速]

客户端支持设置单个文件的上传限速(单个上传任务的限速)，结合「最大上传任务数」的设置，实现客户端上传的整体限速控制。

* 上传限速：勾选时表示开启限速控制；不勾选时，「单个文件上传限速」的设置不生效
* 单个文件上传限速：单个文件上传的带宽限制值，范围 1KB/s - 100MB/s

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Ft3bRc103yjxLSHi_9s_dXVnqBUV-ab0303897955.webp)

### **断点下载设置** [#断点下载设置]

* 断点下载：勾选时表示开启断点下载功能；不勾选时，「断点下载」相关设置不生效
* 断点下载文件阈值：当开启断点下载且文件大小大于此阈值时，自动使用可恢复的分片下载，范围 10M\~1000MB
* 断点下载文件大小：分片大小，范围 8M\~100MB
* 最大下载任务数：同时下载的任务数，不仅限于断点下载模式；超过任务数量会进入队列，等待前面的任务完成，范围 1\~10

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FiIgmHsmbenbf8rSCzyMtWyP65QA-4a31ac31e0a5.webp)

### **下载限速** [#下载限速]

客户端支持设置单个文件的下载限速(单个下载任务的限速)，结合「最大下载任务数」的设置，实现客户端下载的整体限速控制。

* 下载限速：勾选时表示开启限速控制；不勾选时，「单个文件下载限速」的设置不生效
* 单个文件下载限速：单个文件下载的带宽限制值，范围 1KB/s - 100MB/s

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/Fl-qp4BNBPUtVFTEtuGaovta9PR6-9d8e58b74e0d.webp)

### **文件列表分步加载** [#文件列表分步加载]

客户端默认会把当前路径下的所有文件/目录全部列举出来，文件数量特别多的时候，等待时间会比较久，可以设置开启文件列表的分页加载模式。

* 文件列表分页加载：勾选时表示分页加载文件列表，而不是一次性列举出来所有的文件列表。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FqbQpZrw9NcY2RQTHQZz1xSwtECy-b6d4d4052173.webp)

开启分页加载后，文件列表滑动到底部会触发列举下一页的文件列表。

* 自定义列举条目数：客户端支持自定义每次列举文件时的加载条目数，默认是 100。只有当「分页加载」模式开启时，此设置才生效。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FjBDjdVN5Q1xVQY0aQFQYUabkllJ-b27d985ad4c1.webp)

### **书签** [#书签]

客户端支持书签功能。

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FrYwh1KAhjQmj2iQd_E8gqwIIRec-f6c0e9a5b0c4.webp)

* 在对应的界面访问路由下，点击五角星图标，可以将页面保存为书签
* 点击「书签管理」，可以查看、使用和删除已保存的书签

![image.png](/docs-assets/products/kodo/%287-tools%29/1-kodo-browser/FvH8t9IHdGSA9gHrJX9AQBXmpwwb-54ccdbce8239.webp)

* 点击已保存的书签URL，客户端会跳转到对应的页面
* 不再需要使用的书签，可以点击删除


# Qiniu Jenkins Plugin (/products/kodo/5-qiniu-jenkins-plugin)



最近更新时间: 2023-11-01 17:19:04

七牛云存储 Jenkins 插件，支持将构建产生的文件保存到七牛，以及从七牛云下载已保存的构建文件到本地，不再占用本地的存储资源。

Github [代码地址](https://github.com/jenkinsci/qiniu-plugin)

# 安装 [#安装]

## 从官方插件列表安装（推荐） [#从官方插件列表安装推荐]

* 点击 Manage Jenkins 进入管理界面。
* 点击 Manage Plugins进入插件管理界面。
* 选择 Available Tab，搜索查找到 **Qiniu** 插件（This plugin upload is to archive build artifacts to Qiniu）。
* 点击 Install without restart 或 Download now and install after restart，安装插件。

![](/docs-assets/products/kodo/%287-tools%29/5-qiniu-jenkins-plugin/Fu-E2lYEBCEj7qp-iFdYC4AfLuQ-6f9ee6c719f0.webp)

注意：如果之前手动安装过 Qiniu 插件，想从官方插件列表中安装最新版本的插件，需要先将手动安装的插件卸载。

* 进入 Manage Plugins 插件管理界面后，选择 Installed Tab，搜索查找到已安装的 **Qiniu** 插件。
* 点击 Uninstall 卸载插件，再按上述步骤安装即可。

![](/docs-assets/products/kodo/%287-tools%29/5-qiniu-jenkins-plugin/Fr-xbe2zdlIOUV01TCYxFABvNVC0-b1bb12a98ecb.webp)

## 手动安装 [#手动安装]

点击下载 [Qiniu Jenkins Plugin](https://kodo-toolbox-new.qiniu.com/qiniu-jenkins-v1.0.1.hpi) 。

* 点击 Manage Jenkins 进入管理界面。
* 点击 Manage Plugins进入插件管理界面。
* 选择 Advanced Tab，在Upload Plugin 设置页选择下载好的七牛云存储插件。
* 点击 Upload 上传。

![](/docs-assets/products/kodo/%287-tools%29/5-qiniu-jenkins-plugin/FhoH9tc39LW-4e44V8pTv5XylP4z-e4ec2f351cd6.webp)

# 全局配置 [#全局配置]

插件安装好以后，需要先做 Jenkins 的全局配置。

* 点击 Manage Jenkins 进入管理界面。
* 点击 Configure System 进入配置界面。
* 点击 Artifact Management for Builds 按钮，选择 Qiniu Artifact Manager。
* 在出现的 Qiniu Artifact Manager 配置栏中，依次填写 Access Key，Secret Key 和 Bucket Name，注意 Bucket Name 必须是七牛账户中已有的存储空间名称。

![](/docs-assets/products/kodo/%287-tools%29/5-qiniu-jenkins-plugin/FmyBL69l3RVy739aMhq0XTW2mmWK-fd4f1e8b8ef6.webp)

* 可以点击旁边的 Advanced 按钮，将出现更多配置项，这里的配置项都是可选的。
  * Archive as infrequent storage object：是否以低频存储的方式存储文件，推荐使用低频存储类型。不勾选时，以标准存储类型存储。
  * Delete Artifacts ：build 删除时是否删除已保存的文件，默认删除。可以取消勾选，删除 build 的时候保留已保存的云端文件。
  * Object Name Prefix：在存储空间中的对象名称前缀。如果有多套 Jenkins 系统，可以不同前缀路径来区分。
  * Bucket Download Domain：存储空间绑定的下载域名。如果不填，则从存储空间中选择一个下载域名。但如果在存储空间中没有绑定任何下载域名，则该项必填。
  * Use HTTPs Protocol：是否使用 HTTPS 传输协议，默认使用 HTTP 传输协议。
  * 如果是需要保存到私有云存储中，则必须配置Qiniu UP Domain，Qiniu Uc Domain，Qiniu Rs/Rsf Domain，Qiniu API Domain ；保存到公有云存储时，忽略这些Domain配置。
* 点击 Save 按钮保存。

![企业微信截图\_e9afdc24-cad8-4db1-8d85-d1955850372c.png](/docs-assets/products/kodo/%287-tools%29/5-qiniu-jenkins-plugin/FkO-cZGEC2ANK5jwD08ROpdltsXU-2970aadaac06.webp)

# 部署 [#部署]

全局配置，设置好了统一的存储空间及七牛云存储账号的AK/SK，然后就可以针对不同的项目来部署、配置构建结果保存的具体规则。

## **普通部署** [#普通部署]

在 Job 配置界面中，添加 Archive the artifacts to Qiniu 的设置。

* 点击 Post-build Actions 下拉框里的 Archive the artifacts to Qiniu 选项，添加一个配置框。
* 在 Files to archive 里输入要保存的构建结果路径，可以使用通配符;只需要输入当前 workspace 下的相对路径即可。
* 可以点击旁边的 Advanced 按钮，将出现更多配置项，这里的配置项都是可选的。
  * Excludes：排除的文件路径匹配规则。表示要从构建结果中排除一部分文件，依然可以使用通配符。
  * Do not fail build if archiving returns nothing：即使没有匹配到任何文件，也不导致保存失败；表示允许保存空的文件。
  * Archive artifacts only if build is successful：表示仅当构建成功才会保存。
  * Use default excludes：使用默认的排除规则。表示自动将 SCM 软件用的配置文件或数据文件排除，不予保存。
  * Treat include and exclude patterns as case sensitive：文件路径匹配规则是否对大小写敏感。勾选，表示要保存的结果路径为大小写敏感。
* 点击 Save 按钮保存。

![9afdc24-cad8-4db1-8d85-d1955850372c.png](/docs-assets/products/kodo/%287-tools%29/5-qiniu-jenkins-plugin/FkO-cZGEC2ANK5jwD08ROpdltsXU-2970aadaac06.webp)

**注意：**
为保证文件名称唯一性，保存文件的命名规则为：`<Object Name Prefix>/<Project Full Name>/<Build Number>/<File Path>`

## **Pipeline部署** [#pipeline部署]

在 Pipeline 配置界面中，可以使用 archiveArtifactsToQiniu 指令将构建产生的文件保存到七牛云存储。

脚本示例如下：

```
node {
   stage('Build') {
      sh '''
rm -rf **
mkdir -p {aa,bb,cc}/{dd,ee,ff}
for file in {aa,bb,cc}/{dd,ee,ff}/{gg,hh,ii}
do
  dd if=/dev/urandom of="$file" count=1024 bs=1
done
      '''
   }
   stage('Results') {
      archiveArtifactsToQiniu allowEmptyArchive: false, caseSensitive: false, excludeFilesGlob: '', includeFilesGlob: '**', onlyIfSuccessful: false, useDefaultExcludes: false
   }
}

```

参数说明如下：

| 参数名称               | 参数类型 | 描述                                     | 备注                       |
| ------------------ | ---- | -------------------------------------- | ------------------------ |
| includeFilesGlob   | 字符串  | 要保存的构建结果路径，支持使用通配符                     | 必填，保存所有文件，填写 `**`        |
| excludeFilesGlob   | 字符串  | 要从构建结果中排除、不做保存的文件，支持使用通配符              | 必填，不排除任何文件，填写 `''`       |
| allowEmptyArchive  | 布尔值  | 允许保存空的文件                               | 必填                       |
| onlyIfSuccessful   | 布尔值  | 仅当构建成功才将产生的文件保存                        | 必填，且需设置为true；设置为false不生效 |
| useDefaultExcludes | 布尔值  | 使用默认的排除规则，自动将 SCM 软件用的配置文件或数据文件排除，不予保存 | 可选                       |
| caseSensitive      | 布尔值  | 要保存的结果路径大小写敏感                          | 可选                       |

# 下载 [#下载]

保存到七牛云存储的构建结果文件，可以在每次构建页面中看到，点击即可从七牛云存储下载构建输出的文件到本地。

![](/docs-assets/products/kodo/%287-tools%29/5-qiniu-jenkins-plugin/FpAFPLt-psFIpWbXgnwq7ssLfJLT-30a88176ac7f.webp)


# 数据迁移工具 Kodoimport (/products/kodo/6435-kodoimport)



最近更新时间: 2025-08-20 17:14:37

\<!-- TOC -->

* [1. 简介](#1-简介)
  * [1.1 下载](#11-下载)
  * [1.2 文档](#12-文档)
  * [1.3 kodoimport-cli](#13-kodoimport-cli)
  * [1.4 角色](#14-角色)
    * [1.4.1 Job](#141-job)
    * [1.4.2 Scheduler](#142-scheduler)
    * [1.4.3 Worker](#143-worker)
    * [1.4.4 Executor](#144-executor)
  * [注意事项](#注意事项)
* [2. 安装](#2-安装)
  * [2.1 二进制程序](#21-二进制程序)
  * [2.2 Docker](#22-docker)
  * [2.3 Kubernetes](#23-kubernetes)
* [3. 启动](#3-启动)
  * [3.1 二进制程序启动](#31-二进制程序启动)
    * [3.1.1 单机模式](#311-单机模式)
    * [3.1.2 多机模式](#312-多机模式)
  * [3.2 Docker 启动](#32-docker-启动)
    * [3.2.1 单机模式](#321-单机模式)
    * [3.2.2 多机模式](#322-多机模式)
  * [3.3 kodoimport 启动参数](#33-kodoimport-启动参数)
* [4. 创建数据迁移 Job](#4-创建数据迁移-job)
  \<!-- TOC -->

<a id="1-简介" />

# 1. 简介 [#1-简介]

kodoimport 为七牛云的数据迁移工具，和 kodoimport-cli 搭配使用，支持以下源的迁移：

* 本地源
* HTTP 源
* 七牛源
* S3 源
* OSS 源

迁移工具支持以下功能：

* 支持单机模式和分布式模式。单机模式部署简单使用方便，但是单机模式迁移能力有限，如果有大规模数据迁移需求分布式模式更为合适
* 支持流量控制
* 支持迁移特定前缀的文件
* 支持为迁移目标设置特定前缀
* 支持并行数据下载和上传
* 支持数据校验
* 支持增量迁移
* 支持同时配置多个迁移 Job

kodoimport 启动后会创建迁移服务、文档服务等，等待创建迁移的 Job 进行相关的迁移工作；

<a id="11-下载" />

## 1.1 下载 [#11-下载]

| 支持平台        | 下载链接                                                                                         |
| ----------- | -------------------------------------------------------------------------------------------- |
| Windows x64 | [下载](https://kodo-toolbox-new.qiniu.com/kodoimport-v2.6.2-202609201455-windows-amd64.tar.gz) |
| Macos amd64 | [下载](https://kodo-toolbox-new.qiniu.com/kodoimport-v2.6.2-202609201455-darwin-amd64.tar.gz)  |
| Macos arm64 | [下载](https://kodo-toolbox-new.qiniu.com/kodoimport-v2.6.2-202609201455-darwin-arm64.tar.gz)  |
| Linux amd64 | [下载](https://kodo-toolbox-new.qiniu.com/kodoimport-v2.6.2-202609201455-linux-amd64.tar.gz)   |
| Linux arm64 | [下载](https://kodo-toolbox-new.qiniu.com/kodoimport-v2.6.2-202609201455-linux-arm64.tar.gz)   |

<a id="12-文档" />

## 1.2 文档 [#12-文档]

kodoimport 内置了文档，你可以直接在本机上启动 kodoimport 并根据面板 Docs URL 中提示的链接在浏览器中使用文档，也可以在迁移设备上启动
kodoimport 然后通过本机浏览器进行访问（本机网络必须能访问到设备，如果本机和迁移设备不在一个网络，可通过 vpn、docker 端口映射、k8s
外网访问等方式解决）；

默认情况下：文档仅允许本机访问，你可以通过修改 kodoimport 的启动选项 --web-address 以允许其他电脑访问。
eg:

```
kodoimport --web-address "0.0.0.0:7900"
```

```text
kodoimport 启动后面板如下：

=========================================================
              Welcome to kodoimport !
  If you are using kodoimport running docker or kubernetes,
adjust the IP below to the host IP.

	Version        : Unknown
	Scheduler  Addr: 127.0.0.1:8001
	Docs        URL: http://127.0.0.1:7900/docs
	Stat        URL: http://127.0.0.1:7900/stat
	Kodoimport Path: /Users/test/.kodoimport/kodoimport
	Workspace      : /Users/test/.kodoimport

	Basic Auth:
           UserName:
           Password:
=========================================================
```

<a id="13-kodoimport-cli" />

## 1.3 kodoimport-cli [#13-kodoimport-cli]

kodoimport-cli 为 kodoimport 迁移服务的交互工具，包含获取服务状态信息以及 Job 的创建、暂停、删除、重试等功能，具体可参考文档服务中相关文档。

<a id="14-角色" />

## 1.4 角色 [#14-角色]

<a id="141-job" />

### 1.4.1 Job [#141-job]

Job 为一组相同源到相同七牛存储的任务集合。比如：七牛 BucketA 到七牛 BucketB 的迁移，每个文件的迁移为一个迁移任务。

<a id="142-scheduler" />

### 1.4.2 Scheduler [#142-scheduler]

Scheduler 为迁移的调度器，负责将 Job 中的任务下发给 Worker 进行执行。所有的 Job 信息均存储在 Scheduler
端，并会被持久化到本地工作目录中。

`工作目录` 可在 kodoimport 启动时配置，目录中存放着日志、Job 相关信息等，默认为：`${当前用户家目录}/.kodoimport`。

`工作目录` 结构如下：

```text
├── log    // 日志
│   ├── access  // kodoimport-cli 请求日志
│   │   ├── log2024031214.txt
│   │   └── 2024031410.txt
│   └── system  // kodoimport Scheduler 和 Worker 运行日志
│       ├── 2024031214.txt
│       └── 2024031410.log
└── server
    ├── qiniu-bash      // JobID 为 qiniu-bash 的 Job 的工作目录
    │   ├── 00000-round  // 第 0 轮迁移的状态信息保存目录
    │   │   ├── 700-result.txt  // 执行结果，700 为状态码具体错误信息见内部 Task 信息；
    │   │   └── cache           // 状态信息
    │   │       └── info_cache.db
    │   │           ├── 000001.log
    │   │           ├── CURRENT
    │   │           ├── LOCK
    │   │           ├── LOG
    │   │           └── MANIFEST-000000
    │   └── cache
    └── qiniu-bash.conf // JobID 为 qiniu-bash 的 Job 的配置文件
```

<a id="143-worker" />

### 1.4.3 Worker [#143-worker]

任务执行体，会从 Scheduler 获取任务并执行，同一台设备上进配置一个 Worker 即可。如果此台设备上也需要配置 Scheduler，可使用将
Mode 设置为 0，同时构建 Scheduler 和 Worker，其他设备的 Worker 也可接入此 Scheduler 中。

`工作目录` 可在 kodoimport 启动时配置，目录中存放着日志等信息，默认为：`${当前用户家目录}/.kodoimport`。

<a id="144-executor" />

### 1.4.4 Executor [#144-executor]

任务执行的最小单元，Worker 上有多少个并发就会有多少个 Executor，一般不用关心此概念。

<a id="注意事项" />

## 注意事项 [#注意事项]

**空间要求：**

| 项目 | 大小                                                                | 备注                                                        |
| -- | ----------------------------------------------------------------- | --------------------------------------------------------- |
| 内存 | Schdueler: 2G <br /> Worker: Executor 数（默认：20） \* 分片上传的块大小（默认：4M） | 查看分片上传的块大小：kodoimport-cli job.config dst.uploadPartSizeMB |
| 硬盘 | 1千万文件：4Gi \~ 10Gi。                                                | 迁移后的结果信息会被存储，成功被迁移的文件存储信息较少，失败的存储信息较多；可以按待文件数量进行评估        |

<a id="2-安装" />

# 2. 安装 [#2-安装]

<a id="21-二进制程序" />

## 2.1 二进制程序 [#21-二进制程序]

在下面网站中下载相应版本：[kodoimport](/products/kodo/6435-kodoimport)

<a id="22-docker" />

## 2.2 Docker [#22-docker]

```bash
# 获取 Docker 镜像
docker pull kodoproduct/kodoimport:latest
```

<a id="23-kubernetes" />

## 2.3 Kubernetes [#23-kubernetes]

参考 kodoimport 内置文档中，安装部分的 Kubernetes 配置文件：kodoimport.yaml，并根据注释结合自己根据实际情况进行调整。

```bash
# 部署
kubectl apply -f kodoimport.yaml
```

<a id="3-启动" />

# 3. 启动 [#3-启动]

<a id="31-二进制程序启动" />

## 3.1 二进制程序启动 [#31-二进制程序启动]

<a id="311-单机模式" />

### 3.1.1 单机模式 [#311-单机模式]

```bash
# 解压后找到 kodoimport 二进制执行程序，执行以下命令：

./kodoimport
```

<a id="312-多机模式" />

### 3.1.2 多机模式 [#312-多机模式]

```bash
# 解压后找到 kodoimport 二进制执行程序
# Scheduler 的主机 IP 为：192.168.1.5
# Worker    的主机 IP 为：192.168.1.6
# 启动 Scheduler
kodoimport --mode 1  --scheduler-address "0.0.0.0:8001"

# 启动 Worker
kodoimport --mode 2  --scheduler-address "192.168.1.5:8001"
```

<a id="32-docker-启动" />

## 3.2 Docker 启动 [#32-docker-启动]

<a id="321-单机模式" />

### 3.2.1 单机模式 [#321-单机模式]

```bash
# 单机模式
# /Users/test/.kodoimport 为挂载的 kodoimport 工作目录，kodoimport 运行的状态信息会保存此处
docker run -it -p 7900:7900 \
               --mount type=bind,source=/Users/test/.kodoimport,target=/root/.kodoimport \
               kodoproduct/kodoimport:latest
```

<a id="322-多机模式" />

### 3.2.2 多机模式 [#322-多机模式]

```bash
# Scheduler 的宿主机 IP 为：192.168.1.5
# Worker    的宿主机 IP 为：192.168.1.6
# 启动 Scheduler
# /Users/test/.kodoimport 为挂载的 kodoimport 工作目录，kodoimport 运行的状态信息会保存此处
docker run -it -p 7902:7902 -p 8001:8001 \
                            --mount type=bind,source=/Users/test/.kodoimport,target=/root/.kodoimport \
                            kodoproduct/kodoimport:latest \
                            --mode 1  \
                            --scheduler-address "0.0.0.0:8001" \
                            --web-address "0.0.0.0:7902"

# 启动 Worker
docker run -it -p 7902:7902 kodoproduct/kodoimport:latest \
                            --mode 2  \
                            --scheduler-address "192.168.1.5:8001" \
                            --web-address "0.0.0.0:7902:192.168.1.6"
```

<a id="33-kodoimport-启动参数" />

## 3.3 kodoimport 启动参数 [#33-kodoimport-启动参数]

|          参数         |   类型   | 作用                                                                                                                                                                                                                                   |            默认值           |
| :-----------------: | :----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------: |
|        --mode       |   int  | 运行模式 <br /> 0：同时部署启动 Scheduler 和 Worker <br /> 1：仅启动 Scheduler <br /> 其他：仅启动 Worker。                                                                                                                                                 |             0            |
|     --workspace     | string | kodoimport 的工作目录，存储 kodoimport 的日志等信息；<br /> 当 kodoimport 中启动了 Scheduer 还会包含 Job 的信息。                                                                                                                                                | `${当前用户家目录}/.kodoimport` |
|    --web-address    | string | Web 监听的地址，样式: 监听Host:监听端口:路由Host。<br /> kodoimport 运行状态和文档，以及 kodoimport-cli 和 kodoimport 的交互也依赖此端口。<br /> 一般只设置监听地址即可（监听Host:监听端口），在 docker 的多机模式中，由于 Scheduler 需要转发请求到 Worker，此时需要配置 Worker 的路由Host（Docker 宿主机地址）。<br /> 仅支持 IPv4。 |       0.0.0.0:7900       |
| --scheduler-address | string | Scheduler 和 Worker 远程调用的地址。<br /> 当启动了 Scheduler 时，为 Scheduler 监听地址；<br /> 当进启动 Worker 时，为 Schdulder 访问地址。<br /> 仅支持 IPv4。                                                                                                           |      127.0.0.1:8001      |
|    --worker-name    | string | Worker 的别名。                                                                                                                                                                                                                          |             无            |
|     --log-level     | string | 日志等级；可配值有：debug、info、warning 和 error；<br /> 当 Worker 启动时未指定此参数，Worker 会使用 Scheduler 配置的值。                                                                                                                                            |           info           |
|   --executor-count  |   int  | Worker 的并发执行数量；<br /> 当 Worker 启动时未指定此参数，Worker 会使用 Scheduler 配置的值。                                                                                                                                                                  |            20            |
|      --username     | string | Web 请求中使用的 Basic Auth 验证的用户名 <br /> 只有 Username 和 Password 同时指定才会生效。                                                                                                                                                                 |             无            |
|      --password     | string | Web 请求中使用的 Basic Auth 验证的密码 <br /> 只有 Username 和 Password 同时指定才会生效。                                                                                                                                                                  |             无            |

**注：**
&#x2A;*特殊状态码说明：**

* 230：文件迁移成功，但由于无法获取文件 Hash 而无法确保文件一致性的文件。

<a id="4-创建数据迁移-job" />

# 4. 创建数据迁移 Job [#4-创建数据迁移-job]

使用 kodoimport-cli 创建迁移 Job，详细使用说明请参考 kodoimport 内置文档中的示例

```shell
kodoimport-cli job create -h
```


# Java SDK (/products/kodo/0-java)



最近更新时间: 2025-06-20 13:41:38

## 简介 [#简介]

此 SDK 适用于 Java 8 及以上版本。使用此 SDK 构建您的网络应用程序，能让您以非常便捷地方式将数据安全地存储到七牛云上。无论您的网络应用是一个网站程序，还是包括从云端（服务端程序）到终端（手持设备应用）的架构服务或应用，通过七牛云及其 SDK，都能让您应用程序的终端用户高速上传和下载，同时也让您的服务端更加轻盈。

Java SDK 属于七牛服务端 SDK 之一，主要有如下功能：

1. 提供生成客户端上传所需的上传凭证的功能
2. 提供文件从服务端直接上传七牛的功能
3. 提供对七牛空间中文件进行管理的功能
4. 提供对七牛空间中文件进行处理的功能
5. 提供七牛融合 CDN 相关的刷新，预取，日志功能
6. 提供七牛视频监控 QVS 设备管理、流管理等功能

## 开源 [#开源]

* [Java SDK 项目地址](https://github.com/qiniu/java-sdk)
* [Java SDK 发布地址](https://github.com/qiniu/java-sdk/releases)
* [Java SDK 历史文档](/products/kodo/android/android-sdk-6)

<span id="install-by-yourself" />

## 安装 [#安装]

* [使用 Gradle](/products/kodo/0-java#install-by-gradle)
* [使用 Maven](/products/kodo/0-java#install-by-maven)
* [手动安装](/products/kodo/0-java#install-by-yourself)

## 注意 [#注意]

* 从 7.2.24 开始，okhttp3 升级到 3.14.2，其要求 java 1.8 及以上。
* 若为 java 1.7 ，请手动指定 okhttp3 依赖 3.12，要求 3.12.3 及以上， `com.squareup.okhttp3:okhttp:3.12.3`

```
compile ('com.qiniu:qiniu-java-sdk:7.19.0') {
        exclude group: 'com.squareup.okhttp3', module: 'okhttp'
    }
    compile 'com.squareup.okhttp3:okhttp:3.12.6'
```

<span id="install-by-gradle" />

### Gradle [#gradle]

```
compile 'com.qiniu:qiniu-java-sdk:7.19.+'
```

<span id="install-by-maven" />

### Maven [#maven]

```
<dependency>
  <groupId>com.qiniu</groupId>
  <artifactId>qiniu-java-sdk</artifactId>
  <version>[7.19.0, 7.19.99]</version>
</dependency>
```

这里的 `version` 指定了一个版本范围，每次更新 `pom.xml` 的时候会尝试去下载 `7.19.x` 版本中的最新版本，你可以手动指定一个固定的版本。

### 手动下载 [#手动下载]

请尽量使用包管理工具自动解决依赖问题。如果条件实在不满足，只能通过手动下载 jar 包的方式来解决。本项目自身 jar 及依赖的第三方库如下：

Java SDK 依赖的第三方库及其版本如下：

```
<dependencies>
    <dependency>
      <groupId>com.squareup.okhttp3</groupId>
      <artifactId>okhttp</artifactId>
      <version>3.14.2</version>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.8.5</version>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>com.qiniu</groupId>
      <artifactId>happy-dns-java</artifactId>
      <version>0.1.6</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.12</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
```

| 库名称            | 库项目地址                                            | 库下载地址                                                                              |
| -------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------- |
| qiniu-java-sdk | [链接 🔗](https://github.com/qiniu/java-sdk)       | [链接 🔗](http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22qiniu-java-sdk%22)       |
| happy-dns-java | [链接 🔗](https://github.com/qiniu/happy-dns-java) | [链接 🔗](http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22happy-dns-java%22)       |
| okhttp3        | [链接 🔗](https://github.com/square/okhttp)        | [链接 🔗](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.squareup.okhttp3%22) |
| okio           | [链接 🔗](https://github.com/square/okio)          | [链接 🔗](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.squareup.okio%22)    |
| gson           | [链接 🔗](https://github.com/google/gson)          | [链接 🔗](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.google.code.gson%22) |
| junit          | [链接 🔗](http://junit.org/junit4/)                | [链接 🔗](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22junit%22)                |

可以点击每个库的下载链接，然后选择对应的 jar 进行下载，然后引入到项目中。

## 鉴权 [#鉴权]

Java SDK 的所有的功能，都需要合法的授权。授权凭证的签算需要七牛账号下的一对有效的 `Access Key` 和 `Secret Key` ，这对密钥可以通过如下步骤获得：

1. 点击 [注册 🔗](https://portal.qiniu.com/signup) 开通七牛开发者帐号
2. 如果已有账号，直接登录七牛开发者后台，点击 [这里 🔗](https://portal.qiniu.com/user/key) 查看 Access Key 和 Secret Key

<span id="upload-file" />

<span id="form-upload-file" />

## 文件上传 [#文件上传]

* [上传流程](/products/kodo/0-java#%E4%B8%8A%E4%BC%A0%E6%B5%81%E7%A8%8B)
* [客户端上传凭证](/products/kodo/0-java#%E5%AE%A2%E6%88%B7%E7%AB%AF%E4%B8%8A%E4%BC%A0%E5%87%AD%E8%AF%81)
  * [简单上传凭证](/products/kodo/0-java#simple-uptoken)
    * [覆盖上传凭证](/products/kodo/0-java#overwrite-uptoken)
    * [自定义上传回复凭证](/products/kodo/0-java#returnbody-uptoken)
    * [带回调业务服务器的凭证](/products/kodo/0-java#%E5%B8%A6%E5%9B%9E%E8%B0%83%E4%B8%9A%E5%8A%A1%E6%9C%8D%E5%8A%A1%E5%99%A8%E7%9A%84%E5%87%AD%E8%AF%81)
    * [带数据处理的凭证](/products/kodo/0-java#%E5%B8%A6%E6%95%B0%E6%8D%AE%E5%A4%84%E7%90%86%E7%9A%84%E5%87%AD%E8%AF%81)
    * [带自定义参数的凭证](/products/kodo/0-java#%E5%B8%A6%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%82%E6%95%B0%E7%9A%84%E5%87%AD%E8%AF%81)
    * [综合上传凭证](/products/kodo/0-java#%E7%BB%BC%E5%90%88%E4%B8%8A%E4%BC%A0%E5%87%AD%E8%AF%81)
* [服务器直传](/products/kodo/0-java#server-upload)
  * [构建配置类](/products/kodo/0-java#%E6%9E%84%E5%BB%BA%E9%85%8D%E7%BD%AE%E7%B1%BB)
    * [自定义上传域名](/products/kodo/0-java#upload-selfdomain)
    * [设置请求协议为 http](/products/kodo/0-java#%E8%AE%BE%E7%BD%AE%E8%AF%B7%E6%B1%82%E5%8D%8F%E8%AE%AE%E4%B8%BA-http)
    * [文件上传](/products/kodo/0-java#upload-file)
    * [字节数组上传](/products/kodo/0-java#%E5%AD%97%E8%8A%82%E6%95%B0%E7%BB%84%E4%B8%8A%E4%BC%A0)
    * [数据流上传](/products/kodo/0-java#%E6%95%B0%E6%8D%AE%E6%B5%81%E4%B8%8A%E4%BC%A0)
    * [断点续传](/products/kodo/0-java#upload-resumable)
    * [自定义参数上传](/products/kodo/0-java#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%82%E6%95%B0%E4%B8%8A%E4%BC%A0)
    * [解析自定义回复内容](/products/kodo/0-java#%E8%A7%A3%E6%9E%90%E8%87%AA%E5%AE%9A%E4%B9%89%E5%9B%9E%E5%A4%8D%E5%86%85%E5%AE%B9)
    * [业务服务器验证存储服务回调](/products/kodo/0-java#%E4%B8%9A%E5%8A%A1%E6%9C%8D%E5%8A%A1%E5%99%A8%E9%AA%8C%E8%AF%81%E5%AD%98%E5%82%A8%E6%9C%8D%E5%8A%A1%E5%9B%9E%E8%B0%83)

## 上传流程 [#上传流程]

文件上传分为客户端上传（主要是指网页端和移动端等面向终端用户的场景）和服务端上传两种场景，具体可以参考文档 [业务流程](/products/kodo/0-programming-model) 。

* 客户端上传：Java 编写的服务端仅提供上传需要的凭证，网页端和移动端等客户端从服务端获取此凭证后使用客户端相应的 SDK 进行上传操作
* 服务端上传：文件在服务端或者服务端作为文件的中转站，使用此 Java SDK 上传文件至七牛云端

服务端 SDK 在上传方面主要提供两种功能

* 生成客户端上传所需要的上传凭证
* 服务端上传文件到七牛云端

## 客户端上传凭证 [#客户端上传凭证]

客户端（移动端或者 Web 端）上传文件的时候，需要从客户自己的业务服务器获取上传凭证，而这些上传凭证是通过服务端的 SDK 来生成的，然后通过客户自己的业务 API 分发给客户端使用。根据上传的业务需求不同，七牛云Java SDK 支持丰富的上传凭证生成方式。

<span id="simple-uptoken" />

### 简单上传的凭证 [#简单上传的凭证]

最简单的上传凭证只需要 `AccessKey` ， `SecretKey` 和 `Bucket` 就可以。

```
import com.qiniu.util.Auth;

String accessKey = "access key";
String secretKey = "secret key";
String bucket = "bucket name";

Auth auth = Auth.create(accessKey, secretKey);
String upToken = auth.uploadToken(bucket);
System.out.println(upToken);
```

<span id="overwrite-uptoken" />

### 覆盖上传的凭证 [#覆盖上传的凭证]

覆盖上传除了需要 `简单上传` 所需要的信息之外，还需要想进行覆盖的文件名称，这个文件名称同时是客户端上传代码中指定的文件名，两者必须一致。

```
import com.qiniu.util.Auth;

String accessKey = "access key";
String secretKey = "secret key";
String bucket = "bucket name";
String key = "file key";

Auth auth = Auth.create(accessKey, secretKey);
String upToken = auth.uploadToken(bucket, key);
System.out.println(upToken);
```

<span id="returnbody-uptoken" />

### 自定义上传回复的凭证 [#自定义上传回复的凭证]

默认情况下，文件上传到七牛之后，在没有设置 `returnBody` 或者 `回调` 相关的参数情况下，七牛返回给上传端的回复格式为 `hash` 和 `key` ，例如：

```
{"hash":"Ftgm-CkWePC9fzMBTRNmPMhGBcSV","key":"qiniu.jpg"}
```

有时候我们希望能自定义这个返回的 JSON 格式的内容，可以通过设置 `returnBody` 参数来实现，在 `returnBody` 中，我们可以使用七牛支持的 [魔法变量](/products/kodo/development-guidelines/upload-types/0-vars#%E9%AD%94%E6%B3%95%E5%8F%98%E9%87%8F) 和 [自定义变量](/products/kodo/development-guidelines/upload-types/0-vars#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%98%E9%87%8F) 。

```
import com.qiniu.util.Auth;
import com.qiniu.util.StringMap;

String accessKey = "access key";
String secretKey = "secret key";
String bucket = "bucket name";

Auth auth = Auth.create(accessKey, secretKey);
StringMap putPolicy = new StringMap();
putPolicy.put("returnBody", "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"bucket\":\"$(bucket)\",\"fsize\":$(fsize)}");
long expireSeconds = 3600;
String upToken = auth.uploadToken(bucket, null, expireSeconds, putPolicy);
System.out.println(upToken);
```

则文件上传到七牛之后，收到的回复内容如下：

```
{"key":"qiniu.jpg","hash":"Ftgm-CkWePC9fzMBTRNmPMhGBcSV","bucket":"if-bc","fsize":39335}
```

### 带回调业务服务器的凭证 [#带回调业务服务器的凭证]

上面生成的 `自定义上传回复` 的上传凭证适用于上传端（无论是客户端还是服务端）和七牛服务器之间进行直接交互的情况下。在客户端上传的场景之下，有时候客户端需要在文件上传到七牛之后，从业务服务器获取相关的信息，这个时候就要用到七牛的上传回调及相关回调参数的设置。

```
import com.qiniu.util.Auth;
import com.qiniu.util.StringMap;

String accessKey = "access key";
String secretKey = "secret key";
String bucket = "bucket name";

Auth auth = Auth.create(accessKey, secretKey);
StringMap putPolicy = new StringMap();
putPolicy.put("callbackUrl", "http://api.example.com/qiniu/upload/callback");
putPolicy.put("callbackBody", "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"bucket\":\"$(bucket)\",\"fsize\":$(fsize)}");
putPolicy.put("callbackBodyType", "application/json");
long expireSeconds = 3600;
String upToken = auth.uploadToken(bucket, null, expireSeconds, putPolicy);
System.out.println(upToken);
```

在使用了上传回调的情况下，客户端收到的回复就是业务服务器响应七牛的 JSON 格式内容。\
通常情况下，我们建议使用 `application/json` 格式来设置 `callbackBody` ，保持数据格式的统一性。实际情况下， `callbackBody` 也支持 `application/x-www-form-urlencoded` 格式来组织内容，这个主要看业务服务器在接收到 `callbackBody` 的内容时如何解析。例如：

```
import com.qiniu.util.Auth;
import com.qiniu.util.StringMap;

String accessKey = "access key";
String secretKey = "secret key";
String bucket = "bucket name";

Auth auth = Auth.create(accessKey, secretKey);
StringMap putPolicy = new StringMap();
putPolicy.put("callbackUrl", "http://api.example.com/qiniu/upload/callback");
putPolicy.put("callbackBody", "key=$(key)&hash=$(etag)&bucket=$(bucket)&fsize=$(fsize)");
long expireSeconds = 3600;
String upToken = auth.uploadToken(bucket, null, expireSeconds, putPolicy);
System.out.println(upToken);
```

### 带数据处理的凭证 [#带数据处理的凭证]

存储服务支持在文件上传到七牛之后，立即对其进行多种指令的数据处理，这个只需要在生成的上传凭证中指定相关的处理参数即可。

```
import com.qiniu.util.Auth;
import com.qiniu.util.StringMap;
import com.qiniu.util.StringUtils;
import com.qiniu.util.UrlSafeBase64;

String accessKey = "access key";
String secretKey = "secret key";
String bucket = "bucket name";

Auth auth = Auth.create(accessKey, secretKey);
StringMap putPolicy = new StringMap();

//数据处理指令，支持多个指令
String saveMp4Entry = String.format("%s:avthumb_test_target.mp4", bucket);
String saveJpgEntry = String.format("%s:vframe_test_target.jpg", bucket);
String avthumbMp4Fop = String.format("avthumb/mp4|saveas/%s", UrlSafeBase64.encodeToString(saveMp4Entry));
String vframeJpgFop = String.format("vframe/jpg/offset/1|saveas/%s", UrlSafeBase64.encodeToString(saveJpgEntry));

//将多个数据处理指令拼接起来
String persistentOpfs = StringUtils.join(new String[]{
        avthumbMp4Fop, vframeJpgFop
}, ";");
putPolicy.put("persistentOps", persistentOpfs);

//数据处理队列名称
putPolicy.put("persistentPipeline", "mps-pipe1");
//任务类型：0: 普通任务 1: 闲时任务，配置闲时任务时 persistentPipeline 不可配置
putPolicy.put("persistentType", 1);

//数据处理完成结果通知地址
putPolicy.put("persistentNotifyUrl", "http://api.example.com/qiniu/pfop/notify");

long expireSeconds = 3600;
String upToken = auth.uploadToken(bucket, null, expireSeconds, putPolicy);
System.out.println(upToken);
```

* 队列 pipeline 请参阅 [创建私有队列](https://portal.qiniu.com/dora/media-gate/pipeline) ；转码操作具体参数请参阅 [音视频转码](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) ；saveas 请参阅 [处理结果另存](/products/dora/processing-mechanism/0-processing-results-save-saveas) 。
* 闲时任务的功能介绍、使用场景、定价，详见 [闲时任务策略说明](/products/dora/processing-mechanism/persist/2-idle-time-task-strategy) 。

也可以支持使用工作流模版替代数据处理指令。工作流模板是预先编排好的一系列媒体处理流程（如转码、截图、视频拼接等各类处理），登录 [对象存储控制台](https://portal.qiniu.com/kodo/bucket) 进行创建，详情参考 [工作流模板操作指南](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template) ， `persistentWorkflowTemplateID` 对应工作流模板列表的 `名称` 字段

```
import com.qiniu.util.Auth;
import com.qiniu.util.StringMap;

String accessKey = "access key";
String secretKey = "secret key";
String bucket = "bucket name";

Auth auth = Auth.create(accessKey, secretKey);
StringMap putPolicy = new StringMap();

//工作流模版
putPolicy.put("persistentWorkflowTemplateID", "tempname");

//数据处理队列名称
putPolicy.put("persistentPipeline", "mps-pipe1");
//任务类型：0: 普通任务 1: 闲时任务，配置闲时任务时 persistentPipeline 不可配置
putPolicy.put("persistentType", 1);

//数据处理完成结果通知地址
putPolicy.put("persistentNotifyUrl", "http://api.example.com/qiniu/pfop/notify");

long expireSeconds = 3600;
String upToken = auth.uploadToken(bucket, null, expireSeconds, putPolicy);
System.out.println(upToken);
```

* 需要注意的是， `persistentWorkflowTemplateID` 和 `persistentOps` 两个参数只能二选一。

### 带自定义参数的凭证 [#带自定义参数的凭证]

存储服务支持客户端上传文件的时候定义一些自定义参数，这些参数可以在 `returnBody` 和 `callbackBody` 里面和七牛内置支持的魔法变量（即系统变量）通过相同的方式来引用。这些自定义的参数名称必须以 `x:`开头。例如客户端上传的时候指定了自定义的参数 `x:user` 和 `x:age` 分别是 `String` 和 `int` 类型。那么可以通过下面的方式引用：

```
putPolicy.put("returnBody", "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"bucket\":\"$(bucket)\",\"fsize\":$(fsize),\"user\":\"$(x:user)\",\"age\",$(x:age)}");
```

或者

```
putPolicy.put("callbackBody", "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"bucket\":\"$(bucket)\",\"fsize\":$(fsize),\"user\":\"$(x:user)\",\"age\",$(x:age)}");
```

### 综合上传凭证 [#综合上传凭证]

上面生成上传凭证的方法，都是通过设置 [上传策略 🔗](/products/kodo/development-guidelines/security/1-put-policy) 相关的参数来支持的，这些参数可以通过不同的组合方式来满足不同的业务需求，可以灵活地组织你所需要的上传凭证。

### 上传凭证额外参数 [#上传凭证额外参数]

默认会拒绝不在预定义之中的参数。即：

```
String upToken = auth.uploadToken(bucket, key, expireSeconds, putPolicy, true);
```

若允许添加额外参数，可以将参数设置为 `false` 。

```
String upToken = auth.uploadToken(bucket, key, expireSeconds, putPolicy, false);
```

<span id="server-upload" />

## 服务端直传 [#服务端直传]

服务端直传是指客户利用七牛服务端 SDK 从服务端直接上传文件到七牛云，交互的双方一般都在机房里面，所以服务端可以自己生成上传凭证，然后利用此 SDK 中的上传逻辑进行上传，最后从七牛云获取上传的结果，这个过程中由于双方都是业务服务器，所以很少利用到上传回调的功能，而是直接自定义 `returnBody` 来获取自定义的回复内容。

### 构建配置类 [#构建配置类]

存储支持空间创建在不同的机房，在使用 Java SDK 中的 `UploadManager` 上传文件之前，必须要构建一个上传用的 `Configuration` 对象，在该对象中，可以指定空间对应的 `Region` 以及其他的一些影响上传的参数。

```
import com.qiniu.storage.Configuration;
import com.qiniu.storage.Region;
import com.qiniu.storage.UploadManager;

//构造一个带指定Region对象的配置类
Configuration cfg = Configuration.create(Region.region0());
cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;// 指定分片上传版本
//...其他参数参考类注释

UploadManager uploadManager = new UploadManager(cfg);
//...生成上传凭证，然后准备上传
```

跨区域双活指定 `RegionGroup` (内测功能，需要工单申请开通跨区域双活功能之后使用)

```
import com.qiniu.storage.Configuration;
import com.qiniu.storage.Region;
import com.qiniu.storage.RegionGroup;

Region region0 = Region.region0();
Region region1 = Region.region1();
RegionGroup regionGroup = new RegionGroup();
regionGroup.addRegion(region0);
regionGroup.addRegion(region1);
Configuration config = Configuration.create(regionGroup);
config.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;// 指定分片上传版本
```

其中关于 `Region` 对象和机房的关系如下：

| 机房  | Region                                    |
| --- | ----------------------------------------- |
| 华东  | `Region.region0()`, `Region.huadong()`    |
| 华北  | `Region.region1()`, `Region.huabei()`     |
| 华南  | `Region.region2()`, `Region.huanan()`     |
| 北美  | `Region.regionNa0()`, `Region.beimei()`   |
| 东南亚 | `Region.regionAs0()`, `Region.xinjiapo()` |

### 注意 [#注意-1]

* 若不指定 `Region` 或 `Region.autoRegion()` ，则会使用 自动判断 区域，使用相应域名处理。
* 如果可以明确 区域 的话，最好指定固定区域，这样可以少一步网络请求，少一步出错的可能。

<span id="upload-selfdomain" />

### 自定义区域域名 [#自定义区域域名]

```
import com.qiniu.storage.Configuration;
import com.qiniu.storage.Region;

Region region = new Region.Builder()
                .region("z0")
                .accUpHost("up.qiniup.com")
                .srcUpHost("upload.qiniup.com")
                .iovipHost("iovip.qiniuio.com")
                .rsHost("rs.qiniu.com")
                .rsfHost("rsf.qiniu.com")
                .apiHost("api.qiniu.com")
                .build();
Configuration cfg = Configuration.create(region);
cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;// 指定分片上传版本
```

### 设置请求协议为 http [#设置请求协议为-http]

```
import com.qiniu.storage.Region;
import com.qiniu.storage.RegionGroup;
import com.qiniu.storage.Configuration;
import com.qiniu.storage.UploadManager;

Configuration cfg = Configuration.create(region);
cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;// 指定分片上传版本
cfg.useHttpsDomains = false;
UploadManager uploadManager = new UploadManager(cfg);
```

### 文件上传 [#文件上传-1]

最简单的就是上传本地文件，直接指定文件的完整路径即可上传。

```
import com.google.gson.Gson;
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.Configuration;
import com.qiniu.storage.Region;
import com.qiniu.storage.UploadManager;
import com.qiniu.storage.model.DefaultPutRet;
import com.qiniu.util.Auth;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;// 指定分片上传版本
//...其他参数参考类注释

UploadManager uploadManager = new UploadManager(cfg);
//...生成上传凭证，然后准备上传
String accessKey = "your access key";
String secretKey = "your secret key";
String bucket = "your bucket name";
//如果是Windows情况下，格式是 D:\\qiniu\\test.png
String localFilePath = "/home/qiniu/test.png";
//默认不指定key的情况下，以文件内容的hash值作为文件名
String key = null;

Auth auth = Auth.create(accessKey, secretKey);
String upToken = auth.uploadToken(bucket);

try {
    Response response = uploadManager.put(localFilePath, key, upToken);
    //解析上传成功的结果
    DefaultPutRet putRet = new Gson().fromJson(response.bodyString(), DefaultPutRet.class);
    System.out.println(putRet.key);
    System.out.println(putRet.hash);
} catch (QiniuException ex) {
    ex.printStackTrace();
    if (ex.response != null) {
        System.err.println(ex.response);

        try {
            String body = ex.response.toString();
            System.err.println(body);
        } catch (Exception ignored) {
        }
    }
}
```

<span id="form-upload-bytes" />

### 字节数组上传 [#字节数组上传]

可以支持将内存中的字节数组上传到空间中。

```
import com.google.gson.Gson;
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.Configuration;
import com.qiniu.storage.Region;
import com.qiniu.storage.UploadManager;
import com.qiniu.storage.model.DefaultPutRet;
import com.qiniu.util.Auth;
import java.io.UnsupportedEncodingException;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;// 指定分片上传版本
//...其他参数参考类注释

UploadManager uploadManager = new UploadManager(cfg);
//...生成上传凭证，然后准备上传
String accessKey = "your access key";
String secretKey = "your secret key";
String bucket = "your bucket name";

//默认不指定key的情况下，以文件内容的hash值作为文件名
String key = null;

try {
    byte[] uploadBytes = "hello qiniu cloud".getBytes("utf-8");
    Auth auth = Auth.create(accessKey, secretKey);
    String upToken = auth.uploadToken(bucket);

    try {
        Response response = uploadManager.put(uploadBytes, key, upToken);
        //解析上传成功的结果
        DefaultPutRet putRet = new Gson().fromJson(response.bodyString(), DefaultPutRet.class);
        System.out.println(putRet.key);
        System.out.println(putRet.hash);
    } catch (QiniuException ex) {
        ex.printStackTrace();
        if (ex.response != null) {
            System.err.println(ex.response);

            try {
                String body = ex.response.toString();
                System.err.println(body);
            } catch (Exception ignored) {
            }
        }
    }
} catch (UnsupportedEncodingException ex) {
    //ignore
}
```

<span id="form-upload-stream" />

### 数据流上传 [#数据流上传]

这里演示的是 `InputStream` 对象的上传，适用于所有的 `InputStream` 子类。这里的 `ByteInputStream` 只用于演示目的，实际用法根据情况而定。

```
import com.google.gson.Gson;
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.Configuration;
import com.qiniu.storage.Region;
import com.qiniu.storage.UploadManager;
import com.qiniu.storage.model.DefaultPutRet;
import com.qiniu.util.Auth;
import java.io.ByteArrayInputStream;
import java.io.UnsupportedEncodingException;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;// 指定分片上传版本
//...其他参数参考类注释

UploadManager uploadManager = new UploadManager(cfg);
//...生成上传凭证，然后准备上传
String accessKey = "your access key";
String secretKey = "your secret key";
String bucket = "your bucket name";

//默认不指定key的情况下，以文件内容的hash值作为文件名
String key = null;

try {
    byte[] uploadBytes = "hello qiniu cloud".getBytes("utf-8");
    ByteArrayInputStream byteInputStream=new ByteArrayInputStream(uploadBytes);
    Auth auth = Auth.create(accessKey, secretKey);
    String upToken = auth.uploadToken(bucket);

    try {
        Response response = uploadManager.put(byteInputStream,key,upToken,null, null);
        //解析上传成功的结果
        DefaultPutRet putRet = new Gson().fromJson(response.bodyString(), DefaultPutRet.class);
        System.out.println(putRet.key);
        System.out.println(putRet.hash);
    } catch (QiniuException ex) {
        ex.printStackTrace();
        if (ex.response != null) {
            System.err.println(ex.response);

            try {
                String body = ex.response.toString();
                System.err.println(body);
            } catch (Exception ignored) {
            }
        }
    }
} catch (UnsupportedEncodingException ex) {
    //ignore
}
```

<span id="upload-resumable" />

<span id="resume-upload-file" />

### 断点续上传 [#断点续上传]

断点续传是在分片上传的基础上实现。SDK 内置两种上传方式：表单上传和分片上传。表单上传使用一个 HTTP POST 请求完成文件的上传，因此比较适合较小的文件。相比而言，分片上传比较适合上传比较大的文件（例如数百 MB 或更大）。\
若需深入了解上传方式之间的区别，请参阅上传类型中 [表单上传](/products/kodo/development-guidelines/upload-types/1-form-upload) 、 [分片上传 v1 版](/products/kodo/development-guidelines/upload-types/2-chunked-upload) 和 [分片上传 v2 版](/products/kodo/rs/multipartupload-interface) 接口说明。\
可以选择分片上传版本，推荐 Configuration.ResumableUploadAPIVersion.V2，表示 分片上传 v2 版，默认 Configuration.ResumableUploadAPIVersion.V1，表示 分片上传 v1 版。

```
import com.google.gson.Gson;
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.Configuration;
import com.qiniu.storage.Region;
import com.qiniu.storage.UploadManager;
import com.qiniu.storage.model.DefaultPutRet;
import com.qiniu.storage.persistent.FileRecorder;
import com.qiniu.util.Auth;
import java.io.IOException;
import java.nio.file.Paths;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;// 指定分片上传版本
cfg.resumableUploadMaxConcurrentTaskCount = 2;  // 设置分片上传并发，1：采用同步上传；大于1：采用并发上传
//...其他参数参考类注释

//...生成上传凭证，然后准备上传
String accessKey = "your access key";
String secretKey = "your secret key";
String bucket = "your bucket name";
//如果是Windows情况下，格式是 D:\\qiniu\\test.png
String localFilePath = "/home/qiniu/test.mp4";
//默认不指定key的情况下，以文件内容的hash值作为文件名
String key = null;

Auth auth = Auth.create(accessKey, secretKey);
String upToken = auth.uploadToken(bucket);

String localTempDir = Paths.get(System.getenv("java.io.tmpdir"), bucket).toString();
try {
    //设置断点续传文件进度保存目录
    FileRecorder fileRecorder = new FileRecorder(localTempDir);
    UploadManager uploadManager = new UploadManager(cfg, fileRecorder);
    try {
        Response response = uploadManager.put(localFilePath, key, upToken);
        //解析上传成功的结果
        DefaultPutRet putRet = new Gson().fromJson(response.bodyString(), DefaultPutRet.class);
        System.out.println(putRet.key);
        System.out.println(putRet.hash);
    } catch (QiniuException ex) {
        ex.printStackTrace();
        if (ex.response != null) {
            System.err.println(ex.response);

            try {
                String body = ex.response.toString();
                System.err.println(body);
            } catch (Exception ignored) {
            }
        }
    }
} catch (IOException ex) {
    ex.printStackTrace();
}
```

### 自定义参数上传 [#自定义参数上传]

```
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.Configuration;
import com.qiniu.storage.Region;
import com.qiniu.storage.UploadManager;
import com.qiniu.util.Auth;
import com.qiniu.util.StringMap;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;// 指定分片上传版本
//...其他参数参考类注释

//...生成上传凭证，然后准备上传
String accessKey = "your access key";
String secretKey = "your secret key";
String bucket = "your bucket name";
//如果是Windows情况下，格式是 D:\\qiniu\\test.png
String localFilePath = "/home/qiniu/test.mp4";
//默认不指定key的情况下，以文件内容的hash值作为文件名
//设置上传后的文件名称
String key = "qiniu_test.jpg";

Auth auth = Auth.create(accessKey, secretKey);

//上传自定义参数，自定义参数名称需要以 x:开头
StringMap params = new StringMap();
params.put("x:fname","123.jpg");
params.put("x:age",20);

//上传策略
StringMap policy = new StringMap();
//自定义上传后返回内容，返回自定义参数，需要设置 x:参数名称，注意下面
policy.put("returnBody", "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"fname\":\"$(x:fname)\",\"age\",$(x:age)}");
//生成上传token
String upToken = auth.uploadToken(bucket, key, 3600, policy);
try {
    Response response = uploadManager.put(localFilePath, key, upToken,params,null,false);
    System.out.println(response.bodyString());
} catch (QiniuException ex) {
    ex.printStackTrace();
    if (ex.response != null) {
        System.err.println(ex.response);

        try {
            String body = ex.response.toString();
            System.err.println(body);
        } catch (Exception ignored) {
        }
    }
}
```

## 解析自定义回复内容 [#解析自定义回复内容]

有些情况下，七牛返回给上传端的内容不是默认的 `hash` 和 `key` 形式，这种情况下，可能出现在自定义 `returnBody` 或者自定义了 `callbackBody` 的情况下，前者一般是服务端直传的场景，而后者则是接受上传回调的场景，这两种场景之下，都涉及到需要将自定义的回复内容解析为 `Java` 的类对象，一般建议在交互过程中，都采用 `JSON` 的方式，这样处理起来方法比较一致，而且 `JSON` 的方法最通用。

遇到诸如自定义 `returnBody` 的情况：

```
putPolicy.put("returnBody", "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"bucket\":\"$(bucket)\",\"fsize\":$(fsize)}");
```

或者是自定义了 `callbackBody` 的情况：

```
putPolicy.put("callbackBody", "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"bucket\":\"$(bucket)\",\"fsize\":$(fsize)}");
```

我们只需要自己定义了对应的类，例如：

```
class MyPutRet {
    public String key; // 文件保存的 key
    public String hash; // 文件保存的 Etag
    public String bucket; // 文件保存的 bucket
    public long fsize; // 文件的大小，单位：B
}
```

然后在获取到上传回复的 `Response` 对象时，使用如下的方法就可以转为自定义回复的类对象了：

```
MyPutRet myPutRet=response.jsonToObject(MyPutRet.class);
```

## 业务服务器验证存储服务回调 [#业务服务器验证存储服务回调]

在上传策略里面设置了上传回调相关参数的时候，七牛在文件上传到服务器之后，会主动地向 `callbackUrl` 发送 POST 请求的回调，回调的内容为 `callbackBody` 模版所定义的内容，如果这个模版里面引用了 [魔法变量](/products/kodo/development-guidelines/upload-types/0-vars#%E9%AD%94%E6%B3%95%E5%8F%98%E9%87%8F) 或者 [自定义变量](/products/kodo/development-guidelines/upload-types/0-vars#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%98%E9%87%8F) ，那么这些变量会被自动填充对应的值，然后在发送给业务服务器。

业务服务器在收到来自七牛的回调请求的时候，可以根据请求头部的 `Authorization` 字段来进行验证，查看该请求是否是来自七牛的未经篡改的请求。具体可以参考七牛的 [回调鉴权](/faq/kodo/image-storage-common-problems/1376-seven-cattle-image-storage-instruction-manuals) 。

注意：业务端服务器回调鉴权的 Content-Type 类型应该与上传策略中指定的 callbackBodyType 相同，默认为 application/x-www-form-urlencoded，当 Content-Type 为 application/x-www-form-urlencoded 时，签名内容必须包括请求内容。当 Content-Type 为 application/json 时，签名内容不包括请求内容。

```
import com.qiniu.util.Auth;

String accessKey = "your access key";
String secretKey = "your secret key";

/*
* 这两个参数就是在定义PutPolicy参数时指定的内容
*/

//回调地址
String callbackUrl = "http://api.example.com/qiniu/callback";
//定义回调内容的组织格式，与上传策略中的callbackBodyType要保持一致
//String callbackBodyType = "application/x-www-form-urlencoded"; //回调鉴权的签名包括请求内容callbackBody
String callbackBodyType = "application/json";//回调鉴权的签名不包括请求内容

/**
 * 这两个参数根据实际所使用的HTTP框架进行获取
 */
//通过获取请求的HTTP头部Authorization字段获得
String callbackAuthHeader = "xxx";
//通过读取回调POST请求体获得，不要设置为null
byte[] callbackBody = null;

Auth auth = Auth.create(accessKey, secretKey);
//检查是否为合法的回调请求
boolean validCallback = auth.isValidCallback(callbackAuthHeader, callbackUrl, callbackBody, callbackBodyType);
if (validCallback) {
    //继续处理其他业务逻辑
} else {
    //这是哪里的请求，被劫持，篡改了吧？
}
```

## 下载文件 [#下载文件]

* [公开空间](/products/kodo/0-java#%E5%85%AC%E5%BC%80%E7%A9%BA%E9%97%B4)
* [私有空间](/products/kodo/0-java#%E7%A7%81%E6%9C%89%E7%A9%BA%E9%97%B4)

文件下载分为公开空间的文件下载和私有空间的文件下载。

## 公开空间 [#公开空间]

### 手动拼接方式 [#手动拼接方式]

对于公开空间，其访问的链接主要是将空间绑定的域名拼接上空间里面的文件名即可访问，标准情况下需要在拼接链接之前，将文件名进行 `urlencode` 以兼容不同的字符。如果有其他访问处理需求，在文件名之后继续拼接即可。

```
import java.net.URLEncoder;

String fileName = "a/b/qiniu.jpg";
// domainOfBucket 中的域名为用户 bucket 绑定的下载域名，下面域名仅为示例，不可使用
String domainOfBucket = "http://mock.qiniu.com";
String encodedFileName = URLEncoder.encode(fileName, "utf-8").replace("+", "%20");
String finalUrl = String.format("%s/%s", domainOfBucket, encodedFileName);
System.out.println(finalUrl);
```

### sdk 自动生成方式 [#sdk-自动生成方式]

sdk 封装了下载 URL 的生成，只需要输入下载所需参数即可。已支持多媒体处理命令等。

```
import com.qiniu.storage.DownloadUrl;

// domain   用户 bucket 绑定的下载域名 eg: mock.qiniu.com【必须】
// useHttps 是否使用 https【必须】
// key      下载资源在七牛云存储的 key【必须】
DownloadUrl url = new DownloadUrl(domain, useHttps, key);
url.setAttname(attname) // 配置 attname
   .setFop(fop) // 配置 fop
   .setStyle(style, styleSeparator, styleParam) // 配置 style
String urlString = url.buildURL();
System.out.println(urlString);
```

<span id="private-get" />

<span id="download-private" />

## 私有空间 [#私有空间]

### 手动拼接方式 [#手动拼接方式-1]

对于私有空间，首先需要按照公开空间的文件访问方式构建对应的公开空间访问链接，然后再对这个链接进行私有授权签名。

```
import com.qiniu.util.Auth;
import java.net.URLEncoder;

String fileName = "公司/存储/qiniu.jpg";
String domainOfBucket = "http://devtools.qiniu.com";
String encodedFileName = URLEncoder.encode(fileName, "utf-8").replace("+", "%20");
String publicUrl = String.format("%s/%s", domainOfBucket, encodedFileName);

String accessKey = "your access key";
String secretKey = "your secret key";
Auth auth = Auth.create(accessKey, secretKey);
long expireInSeconds = 3600;//1小时，可以自定义链接过期时间
String finalUrl = auth.privateDownloadUrl(publicUrl, expireInSeconds);
System.out.println(finalUrl);
```

#### sdk 自动生成方式 [#sdk-自动生成方式-1]

sdk 封装了下载 URL 的生成，只需要输入下载所需参数即可。已支持多媒体处理命令，过期时间 e 和 签名 token 等。

```
import com.qiniu.storage.DownloadUrl;
import com.qiniu.util.Auth;

// domain   下载 domain, eg: qiniu.com【必须】
// useHttps 是否使用 https【必须】
// key      下载资源在七牛云存储的 key【必须】
DownloadUrl url = new DownloadUrl(domain, useHttps, key);
url.setAttname(attname) // 配置 attname
   .setFop(fop) // 配置 fop
   .setStyle(style, styleSeparator, styleParam) // 配置 style

// 带有效期
long expireInSeconds = 3600;//1小时，可以自定义链接过期时间
long deadline = System.currentTimeMillis()/1000 + expireInSeconds;
Auth auth = Auth.create("your access key", "your secret key");
String urlString = url.buildURL(auth, deadline);
System.out.println(urlString);
```

## 资源管理 [#资源管理]

资源管理包括的主要功能有：

* [获取文件信息](/products/kodo/0-java#%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E4%BF%A1%E6%81%AF)
* [修改文件类型](/products/kodo/0-java#%E4%BF%AE%E6%94%B9%E6%96%87%E4%BB%B6%E7%B1%BB%E5%9E%8B)
* [移动或重命名文件](/products/kodo/0-java#%E7%A7%BB%E5%8A%A8%E6%88%96%E9%87%8D%E5%91%BD%E5%90%8D%E6%96%87%E4%BB%B6)
* [复制文件副本](/products/kodo/0-java#%E5%A4%8D%E5%88%B6%E6%96%87%E4%BB%B6%E5%89%AF%E6%9C%AC)
* [删除空间中的文件](/products/kodo/0-java#%E5%88%A0%E9%99%A4%E7%A9%BA%E9%97%B4%E4%B8%AD%E7%9A%84%E6%96%87%E4%BB%B6)
* [设置或更新文件生存时间](/products/kodo/0-java#rs-delete-after-days)
* [获取空间文件列表](/products/kodo/0-java#%E8%8E%B7%E5%8F%96%E7%A9%BA%E9%97%B4%E6%96%87%E4%BB%B6%E5%88%97%E8%A1%A8)
* [抓取网络资源到空间](/products/kodo/0-java#%E6%8A%93%E5%8F%96%E7%BD%91%E7%BB%9C%E8%B5%84%E6%BA%90%E5%88%B0%E7%A9%BA%E9%97%B4)
* [资源管理批量操作](/products/kodo/0-java#%E8%B5%84%E6%BA%90%E7%AE%A1%E7%90%86%E6%89%B9%E9%87%8F%E6%93%8D%E4%BD%9C)
  * [批量获取文件信息](/products/kodo/0-java#%E6%89%B9%E9%87%8F%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E4%BF%A1%E6%81%AF)
    * [批量修改文件类型](/products/kodo/0-java#%E6%89%B9%E9%87%8F%E4%BF%AE%E6%94%B9%E6%96%87%E4%BB%B6%E7%B1%BB%E5%9E%8B)
    * [批量删除文件](/products/kodo/0-java#%E6%89%B9%E9%87%8F%E5%88%A0%E9%99%A4%E6%96%87%E4%BB%B6)
    * [批量移动或重命名文件](/products/kodo/0-java#%E6%89%B9%E9%87%8F%E7%A7%BB%E5%8A%A8%E6%88%96%E9%87%8D%E5%91%BD%E5%90%8D%E6%96%87%E4%BB%B6)
    * [批量复制文件](/products/kodo/0-java#%E6%89%B9%E9%87%8F%E5%A4%8D%E5%88%B6%E6%96%87%E4%BB%B6)
    * [批量解冻归档存储类型文件](/products/kodo/0-java#%E6%89%B9%E9%87%8F%E8%A7%A3%E5%86%BB%E5%BD%92%E6%A1%A3%E5%AD%98%E5%82%A8%E7%B1%BB%E5%9E%8B%E6%96%87%E4%BB%B6)
    * [批量混合指令操作](/products/kodo/0-java#%E6%89%B9%E9%87%8F%E6%B7%B7%E5%90%88%E6%8C%87%E4%BB%A4%E6%93%8D%E4%BD%9C)
* [更新镜像存储空间中的文件内容](/products/kodo/0-java#rs-prefetch)
* [更新镜像存储空间中文件内容](/products/kodo/0-java#%E6%9B%B4%E6%96%B0%E9%95%9C%E5%83%8F%E5%AD%98%E5%82%A8%E7%A9%BA%E9%97%B4%E4%B8%AD%E6%96%87%E4%BB%B6%E5%86%85%E5%AE%B9)

<span id="rs-batch-stat" />

## 获取文件信息 [#获取文件信息]

```
import com.qiniu.common.QiniuException;
import com.qiniu.storage.*;
import com.qiniu.storage.model.FileInfo;
import com.qiniu.util.Auth;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";
String bucket = "your bucket name";
String key = "your file key";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);
try {
    FileInfo fileInfo = bucketManager.stat(bucket, key);
    System.out.println(fileInfo.hash);
    System.out.println(fileInfo.fsize);
    System.out.println(fileInfo.mimeType);
    System.out.println(fileInfo.putTime);
} catch (QiniuException ex) {
    System.err.println(ex.response.toString());
}
```

<span id="rs-chgm" />

## 修改文件类型 [#修改文件类型]

```
import com.qiniu.common.QiniuException;
import com.qiniu.storage.*;
import com.qiniu.util.Auth;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String bucket = "your bucket name";
String key = "your file key";
String newMimeType = "new mime type";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);

//修改文件类型
try {
    bucketManager.changeMime(bucket, key, newMimeType);
} catch (QiniuException ex) {
    System.out.println(ex.response.toString());
}
```

<span id="rs-move" />

## 移动或重命名文件 [#移动或重命名文件]

移动操作本身支持移动文件到相同，不同空间中，在移动的同时也可以支持文件重命名。唯一的限制条件是，移动的源空间和目标空间必须在同一个机房。

| 源空间     | 目标空间    | 源文件名 | 目标文件名 | 描述                       |
| ------- | ------- | ---- | ----- | ------------------------ |
| BucketA | BucketA | KeyA | KeyB  | 相当于同空间文件重命名              |
| BucketA | BucketB | KeyA | KeyA  | 移动文件到 BucketB，文件名一致      |
| BucketA | BucketB | KeyA | KeyB  | 移动文件到 BucketB，文件名变成 KeyB |

`move` 操作支持强制覆盖选项，即如果目标文件已存在，可以设置强制覆盖参数 `force` 来覆盖那个文件的内容。

```
import com.qiniu.common.QiniuException;
import com.qiniu.storage.*;
import com.qiniu.util.Auth;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String fromBucket = "from bucket name";
String fromKey = "from key";
String toBucket = "to bucket name";
String toKey = "to key";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);
try {
    bucketManager.move(fromBucket, fromKey, toBucket, toKey);
} catch (QiniuException ex) {
    //如果遇到异常，说明移动失败
    System.err.println(ex.code());
    System.err.println(ex.response.toString());
}
```

<span id="rs-copy" />

## 复制文件副本 [#复制文件副本]

文件的复制和文件移动其实操作一样，主要的区别是移动后源文件不存在了，而复制的结果是源文件还存在，只是多了一个新的文件副本。

```
import com.qiniu.common.QiniuException;
import com.qiniu.storage.*;
import com.qiniu.util.Auth;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String fromBucket = "from bucket name";
String fromKey = "from key";
String toBucket = "to bucket name";
String toKey = "to key";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);
try {
    bucketManager.copy(fromBucket, fromKey, toBucket, toKey);
} catch (QiniuException ex) {
    //如果遇到异常，说明复制失败
    System.err.println(ex.code());
    System.err.println(ex.response.toString());
}
```

<span id="rs-delete" />

## 删除空间中的文件 [#删除空间中的文件]

```
import com.qiniu.common.QiniuException;
import com.qiniu.storage.*;
import com.qiniu.util.Auth;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String bucket = "your bucket name";
String key = "your file key";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);
try {
    bucketManager.delete(bucket, key);
} catch (QiniuException ex) {
    //如果遇到异常，说明删除失败
    System.err.println(ex.code());
    System.err.println(ex.response.toString());
}
```

<span id="rs-delete-after-days" />

## 设置或更新文件的生存时间 [#设置或更新文件的生存时间]

可以给已经存在于空间中的文件设置文件生存时间，或者更新已设置了生存时间但尚未被删除的文件的新的生存时间。

```
import com.qiniu.common.QiniuException;
import com.qiniu.storage.*;
import com.qiniu.util.Auth;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "access key";
String secretKey = "secret key";
String bucket = "bucket name";
String key = "file key";
//过期天数，该文件10天后删除
int days = 10;

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);
try {
    bucketManager.deleteAfterDays(bucket, key, days);
} catch (QiniuException ex) {
    System.err.println(ex.response.toString());
}
```

<span id="rsf-api" />

## 获取空间文件列表 [#获取空间文件列表]

```
import com.qiniu.storage.*;
import com.qiniu.util.Auth;
import com.qiniu.storage.model.FileInfo;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String bucket = "your bucket name";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);

//文件名前缀
String prefix = "";
//每次迭代的长度限制，最大1000，推荐值 1000
int limit = 1000;
//指定目录分隔符，列出所有公共前缀（模拟列出目录效果）。缺省值为空字符串
String delimiter = "";

//列举空间文件列表
BucketManager.FileListIterator fileListIterator = bucketManager.createFileListIterator(bucket, prefix, limit, delimiter);
while (fileListIterator.hasNext()) {
    //处理获取的file list结果
    FileInfo[] items = fileListIterator.next();
    for (FileInfo item : items) {
        System.out.println(item.key);
        System.out.println(item.hash);
        System.out.println(item.fsize);
        System.out.println(item.mimeType);
        System.out.println(item.putTime);
        System.out.println(item.endUser);
    }
}
```

## 抓取网络资源到空间 [#抓取网络资源到空间]

```
import com.qiniu.storage.*;
import com.qiniu.storage.model.FetchRet;
import com.qiniu.util.Auth;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String bucket = "your bucket name";
String key = "your file key";
String remoteSrcUrl = "http://devtools.qiniu.com/qiniu.png";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);

//抓取网络资源到空间
try {
    FetchRet fetchRet = bucketManager.fetch(remoteSrcUrl, bucket, key);
    System.out.println(fetchRet.hash);
    System.out.println(fetchRet.key);
    System.out.println(fetchRet.mimeType);
    System.out.println(fetchRet.fsize);
} catch (QiniuException ex) {
    System.err.println(ex.response.toString());
}
```

<span id="rs-batch" />

## 资源管理批量操作 [#资源管理批量操作]

### 批量获取文件信息 [#批量获取文件信息]

```
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.*;
import com.qiniu.storage.model.BatchStatus;
import com.qiniu.util.Auth;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String bucket = "your bucket name";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);

try {
    //单次批量请求的文件数量不得超过1000
    String[] keyList = new String[]{
            "qiniu.jpg",
            "qiniu.mp4",
            "qiniu.png",
    };
    BucketManager.BatchOperations batchOperations = new BucketManager.BatchOperations();
    batchOperations.addStatOps(bucket, keyList);
    Response response = bucketManager.batch(batchOperations);
    BatchStatus[] batchStatusList = response.jsonToObject(BatchStatus[].class);

    for (int i = 0; i < keyList.length; i++) {
        BatchStatus status = batchStatusList[i];
        String key = keyList[i];
        System.out.print(key+"\t");
        if (status.code == 200) {
            //文件存在
            System.out.println(status.data.hash);
            System.out.println(status.data.mimeType);
            System.out.println(status.data.fsize);
            System.out.println(status.data.putTime);
        } else {
            System.out.println(status.data.error);
        }
    }
} catch (QiniuException ex) {
    System.err.println(ex.response.toString());
}
```

### 批量修改文件类型 [#批量修改文件类型]

```
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.*;
import com.qiniu.storage.model.BatchStatus;
import com.qiniu.util.Auth;
import java.util.HashMap;
import java.util.Map;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String bucket = "your bucket name";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);

try {
    //单次批量请求的文件数量不得超过1000
    HashMap<String, String> keyMimeMap = new HashMap<>();
    keyMimeMap.put("qiniu.jpg", "image/jpg");
    keyMimeMap.put("qiniu.png", "image/png");
    keyMimeMap.put("qiniu.mp4", "video/mp4");
    BucketManager.BatchOperations batchOperations = new BucketManager.BatchOperations();

    //添加指令
    for (Map.Entry<String, String> entry : keyMimeMap.entrySet()) {
        String key = entry.getKey();
        String newMimeType = entry.getValue();
        batchOperations.addChgmOp(bucket, key, newMimeType);
    }

    Response response = bucketManager.batch(batchOperations);
    BatchStatus[] batchStatusList = response.jsonToObject(BatchStatus[].class);

    int index = 0;
    for (Map.Entry<String, String> entry : keyMimeMap.entrySet()) {
        String key = entry.getKey();
        System.out.print(key + "\t");
        BatchStatus status = batchStatusList[index];
        if (status.code == 200) {
            System.out.println("change mime success");
        } else {
            System.out.println(status.data.error);
        }
        index += 1;
    }
} catch (QiniuException ex) {
    System.err.println(ex.response.toString());
}
```

### 批量删除文件 [#批量删除文件]

```
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.*;
import com.qiniu.storage.model.BatchStatus;
import com.qiniu.util.Auth;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String bucket = "your bucket name";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);

try {
    //单次批量请求的文件数量不得超过1000
    String[] keyList = new String[]{
            "qiniu.jpg",
            "qiniu.mp4",
            "qiniu.png",
    };
    BucketManager.BatchOperations batchOperations = new BucketManager.BatchOperations();
    batchOperations.addDeleteOp(bucket, keyList);
    Response response = bucketManager.batch(batchOperations);
    BatchStatus[] batchStatusList = response.jsonToObject(BatchStatus[].class);

    for (int i = 0; i < keyList.length; i++) {
        BatchStatus status = batchStatusList[i];
        String key = keyList[i];
        System.out.print(key + "\t");
        if (status.code == 200) {
            System.out.println("delete success");
        } else {
            System.out.println(status.data.error);
        }
    }
} catch (QiniuException ex) {
    System.err.println(ex.response.toString());
}
```

<span id="rs-batch-move" />

### 批量移动或重命名文件 [#批量移动或重命名文件]

```
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.*;
import com.qiniu.storage.model.BatchStatus;
import com.qiniu.util.Auth;

Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String bucket = "your bucket name";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);

try {
    //单次批量请求的文件数量不得超过1000
    String[] keyList = new String[]{
            "qiniu.jpg",
            "qiniu.mp4",
            "qiniu.png",
    };
    BucketManager.BatchOperations batchOperations = new BucketManager.BatchOperations();
    for (String key : keyList) {
        batchOperations.addMoveOp(bucket, key, bucket, key + "_move");
    }

    Response response = bucketManager.batch(batchOperations);
    BatchStatus[] batchStatusList = response.jsonToObject(BatchStatus[].class);

    for (int i = 0; i < keyList.length; i++) {
        BatchStatus status = batchStatusList[i];
        String key = keyList[i];
        System.out.print(key + "\t");
        if (status.code == 200) {
            System.out.println("move success");
        } else {
            System.out.println(status.data.error);
        }
    }
} catch (QiniuException ex) {
    System.err.println(ex.response.toString());
}
```

### 批量复制文件 [#批量复制文件]

```
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.*;
import com.qiniu.storage.model.BatchStatus;
import com.qiniu.util.Auth;

Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String bucket = "your bucket name";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);

try {
    //单次批量请求的文件数量不得超过1000
    String[] keyList = new String[]{
            "qiniu.jpg",
            "qiniu.mp4",
            "qiniu.png",
    };
    BucketManager.BatchOperations batchOperations = new BucketManager.BatchOperations();
    for (String key : keyList) {
        batchOperations.addCopyOp(bucket, key, bucket, key + "_copy");
    }

    Response response = bucketManager.batch(batchOperations);
    BatchStatus[] batchStatusList = response.jsonToObject(BatchStatus[].class);

    for (int i = 0; i < keyList.length; i++) {
        BatchStatus status = batchStatusList[i];
        String key = keyList[i];
        System.out.print(key + "\t");
        if (status.code == 200) {
            System.out.println("copy success");
        } else {
            System.out.println(status.data.error);
        }
    }
} catch (QiniuException ex) {
    System.err.println(ex.response.toString());
}
```

### 批量解冻归档存储类型文件 [#批量解冻归档存储类型文件]

```
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.*;
import com.qiniu.storage.model.BatchStatus;
import com.qiniu.util.Auth;

Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String bucket = "your bucket name";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);

try {
    //单次批量请求的文件数量不得超过1000
    String[] keyList = new String[]{
            "qiniu.jpg",
            "qiniu.mp4",
            "qiniu.png",
    };
    int freezeAfterDays = 7 ;
    BucketManager.BatchOperations batchOperations = new BucketManager.BatchOperations();
    for (String key : keyList) {
        batchOperations.addRestoreArchiveOps(bucket, freezeAfterDays, key);
    }

    Response response = bucketManager.batch(batchOperations);
    BatchStatus[] batchStatusList = response.jsonToObject(BatchStatus[].class);

    for (int i = 0; i < keyList.length; i++) {
        BatchStatus status = batchStatusList[i];
        String key = keyList[i];
        System.out.print(key + "\t");
        if (status.code == 200) {
            System.out.println("restoreAr success");
        } else {
            System.out.println(status.data.error);
        }
    }
} catch (QiniuException ex) {
    System.err.println(ex.response.toString());
}
```

### 批量混合指令操作 [#批量混合指令操作]

其实 `batch` 接口支持混合指令的处理，不过为了方便解析请求的回复，一般不推荐这样做。

```
import com.qiniu.common.QiniuException;
import com.qiniu.http.Response;
import com.qiniu.storage.*;
import com.qiniu.storage.model.BatchStatus;
import com.qiniu.util.Auth;

Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String bucket = "your bucket name";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);

try {
    //单次批量请求的文件数量不得超过1000
    BucketManager.BatchOperations batchOperations = new BucketManager.BatchOperations();

    //添加混合指令
    batchOperations.addStatOps(bucket, "qiniu.png", "qiniu.jpg");
    batchOperations.addCopyOp(bucket, "qiniu.png", bucket, "qiniu_copy1.png");
    batchOperations.addMoveOp(bucket, "qiniu2.png", bucket, "qiniu3.png");
    batchOperations.addDeleteOp(bucket, "qiniu4.png");
    batchOperations.addRestoreArchiveOps(bucket, 1, "qiniu.png");

    Response response = bucketManager.batch(batchOperations);
    BatchStatus[] batchStatusList = response.jsonToObject(BatchStatus[].class);

    for (BatchStatus status : batchStatusList) {
        if (status.code == 200) {
            System.out.println("operation success");
        } else {
            System.out.println(status.data.error);
        }
    }
} catch (QiniuException ex) {
    System.err.println(ex.response.toString());
}
```

<span id="rs-prefetch" />

## 更新镜像存储空间中文件内容 [#更新镜像存储空间中文件内容]

对于配置了镜像存储的空间，如果镜像源站更新了文件内容，则默认情况下，七牛不会再主动从客户镜像源站同步新的副本，这个时候就需要利用这个 `prefetch` 接口来主动地将空间中的文件和更新后的源站副本进行同步。调用方式很简单，指定空间和文件名即可。

```
import com.qiniu.common.QiniuException;
import com.qiniu.storage.*;
import com.qiniu.util.Auth;

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

String accessKey = "your access key";
String secretKey = "your secret key";

String bucket = "your bucket name";
String key = "your file key";

Auth auth = Auth.create(accessKey, secretKey);
BucketManager bucketManager = new BucketManager(auth, cfg);
try {
    bucketManager.prefetch(bucket, key);
} catch (QiniuException ex) {
    //如果遇到异常，说明更新失败
    System.err.println(ex.code());
    System.err.println(ex.response.toString());
}
```

## 持久化数据处理 [#持久化数据处理]

## 发送数据处理请求（数据处理指令） [#发送数据处理请求数据处理指令]

对于已经保存到七牛空间的文件，可以通过发送持久化的数据处理指令来进行处理，这些指令支持七牛官方提供的指令，也包括客户自己开发的自定义数据处理的指令。数据处理的结果还可以通过七牛主动通知的方式告知业务服务器。

闲时任务的功能介绍、使用场景、定价，详见 [闲时任务策略说明](/products/dora/processing-mechanism/persist/2-idle-time-task-strategy) 。

```
import com.qiniu.common.QiniuException;
import com.qiniu.processing.OperationManager;
import com.qiniu.processing.OperationStatus;
import com.qiniu.storage.*;
import com.qiniu.util.Auth;
import com.qiniu.util.StringUtils;
import com.qiniu.util.UrlSafeBase64;

String accessKey = "access key";
String secretKey = "secret key";

//待处理文件所在空间
String bucket = "bucket name";
//待处理文件名
String key = "file key";

Auth auth = Auth.create(accessKey, secretKey);

//数据处理指令，支持多个指令
String saveMp4Entry = String.format("%s:avthumb_test_target.mp4", bucket);
String saveJpgEntry = String.format("%s:vframe_test_target.jpg", bucket);
String avthumbMp4Fop = String.format("avthumb/mp4|saveas/%s", UrlSafeBase64.encodeToString(saveMp4Entry));
String vframeJpgFop = String.format("vframe/jpg/offset/1|saveas/%s", UrlSafeBase64.encodeToString(saveJpgEntry));
//将多个数据处理指令拼接起来
String persistentOpfs = StringUtils.join(new String[]{
        avthumbMp4Fop, vframeJpgFop
}, ";");

//数据处理队列名称，必须
String persistentPipeline = "mps-pipe1";
//任务类型：0: 普通任务 1: 闲时任务，配置闲时任务时 persistentPipeline 不可配置（指定为 null）
Integer persistentType = 1;
//数据处理完成结果通知地址
String persistentNotifyUrl = "http://api.example.com/qiniu/pfop/notify";

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

//构建持久化数据处理对象
OperationManager operationManager = new OperationManager(auth, cfg);
try {

    String persistentId = operationManager.pfop(bucket, key, persistentOpfs, persistentPipeline, persistentNotifyUrl, persistentType, true);
    //可以根据该 persistentId 查询任务处理进度
    System.out.println(persistentId);

    OperationStatus operationStatus = operationManager.prefop(persistentId);
    //解析 operationStatus 的结果
} catch (QiniuException e) {
    System.err.println(e.response.toString());
}
```

## 发送数据处理请求（工作流模版） [#发送数据处理请求工作流模版]

也可以支持使用工作流模版替代数据处理指令。工作流模板是预先编排好的一系列媒体处理流程（如转码、截图、视频拼接等各类处理），登录 [对象存储控制台](https://portal.qiniu.com/kodo/bucket) 进行创建，详情参考 [工作流模板操作指南](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template) ， `persistentWorkflowTemplateID` 对应工作流模板列表的 `名称` 字段

```
import com.qiniu.common.QiniuException;
import com.qiniu.processing.OperationManager;
import com.qiniu.processing.OperationStatus;
import com.qiniu.storage.*;
import com.qiniu.util.Auth;
import com.qiniu.util.StringMap;

String accessKey = "access key";
String secretKey = "secret key";

//待处理文件所在空间
String bucket = "bucket name";
//待处理文件名
String key = "file key";

Auth auth = Auth.create(accessKey, secretKey);

//工作流模版，必须
String persistentWorkflowTemplateID = "tempname";
//数据处理队列名称，必须
String persistentPipeline = "mps-pipe1";
//任务类型：0: 普通任务 1: 闲时任务，配置闲时任务时 persistentPipeline 不可配置（指定为 null）
Integer persistentType = 1;
//数据处理完成结果通知地址
String persistentNotifyUrl = "http://api.example.com/qiniu/pfop/notify";

//构造一个带指定 Region 对象的配置类
Configuration cfg = Configuration.create(Region.region0());
//...其他参数参考类注释

//构建持久化数据处理对象
OperationManager operationManager = new OperationManager(auth, cfg);
try {
    StringMap params = new StringMap().
        putNotEmpty("persistentWorkflowTemplateID", persistentWorkflowTemplateID).
        putNotEmpty("pipeline", persistentPipeline).
        putNotEmpty("notifyURL", persistentNotifyUrl).
        putNotNull("type", persistentType);
    String persistentId = operationManager.pfop(bucket, key, params);
    //可以根据该 persistentId 查询任务处理进度
    System.out.println(persistentId);

    OperationStatus operationStatus = operationManager.prefop(persistentId);
    //解析 operationStatus 的结果
} catch (QiniuException e) {
    System.err.println(e.response.toString());
}
```

## 查询数据处理请求状态 [#查询数据处理请求状态]

由于数据处理是异步处理，可以根据发送处理请求时返回的 `persistentId` 去查询任务的处理进度，如果在设置了 `persistentNotifyUrl` 的情况下，直接业务服务器等待处理结果通知即可，如果需要主动查询，可以采用如上代码中的：

```
OperationStatus operationStatus = operationManager.prefop(persistentId);
//解析 operationStatus 的结果
```

## CDN 相关功能 [#cdn-相关功能]

* [文件刷新](/products/kodo/0-java#%E6%96%87%E4%BB%B6%E5%88%B7%E6%96%B0)
* [目录刷新](/products/kodo/0-java#%E7%9B%AE%E5%BD%95%E5%88%B7%E6%96%B0)
* [刷新查询](/products/kodo/0-java#%E5%88%B7%E6%96%B0%E6%9F%A5%E8%AF%A2)
* [文件预取操作](/products/kodo/0-java#fusion-prefetch)
* [获取域名流量](/products/kodo/0-java#%E8%8E%B7%E5%8F%96%E5%9F%9F%E5%90%8D%E6%B5%81%E9%87%8F)
* [获取域名带宽](/products/kodo/0-java#%E8%8E%B7%E5%8F%96%E5%9F%9F%E5%90%8D%E5%B8%A6%E5%AE%BD)
* [获取日志下载链接](/products/kodo/0-java#%E8%8E%B7%E5%8F%96%E6%97%A5%E5%BF%97%E4%B8%8B%E8%BD%BD%E9%93%BE%E6%8E%A5)
* [构建时间戳防盗链访问链接](/products/kodo/0-java#%E6%9E%84%E5%BB%BA%E6%97%B6%E9%97%B4%E6%88%B3%E9%98%B2%E7%9B%97%E9%93%BE%E8%AE%BF%E9%97%AE%E9%93%BE%E6%8E%A5)

<span id="fusion-refresh-urls" />

## 文件刷新 [#文件刷新]

```
import com.qiniu.cdn.CdnManager;
import com.qiniu.cdn.CdnResult;
import com.qiniu.common.QiniuException;
import com.qiniu.util.Auth;

String accessKey = "your access key";
String secretKey = "your secret key";
Auth auth = Auth.create(accessKey, secretKey);
CdnManager c = new CdnManager(auth);

//待刷新的链接列表
String[] urls = new String[]{
        "http://javasdk.qiniudn.com/gopher1.jpg",
        "http://javasdk.qiniudn.com/gopher2.jpg",
        //....
};
try {
    //单次方法调用刷新的链接不可以超过100个
    CdnResult.RefreshResult result = c.refreshUrls(urls);
    System.out.println(result.code);
    //获取其他的回复内容
} catch (QiniuException e) {
    System.err.println(e.response.toString());
}
```

<span id="fusion-refresh-dirs" />

## 目录刷新 [#目录刷新]

```
import com.qiniu.cdn.CdnManager;
import com.qiniu.cdn.CdnResult;
import com.qiniu.common.QiniuException;
import com.qiniu.util.Auth;

String accessKey = "your access key";
String secretKey = "your secret key";
Auth auth = Auth.create(accessKey, secretKey);
CdnManager c = new CdnManager(auth);

//待刷新的目录列表，目录必须以 / 结尾
String[] dirs = new String[]{
        "http://javasdk.qiniudn.com/gopher1/",
        "http://javasdk.qiniudn.com/gopher2/",
        //....
};
try {
    //单次方法调用刷新的目录不可以超过10个，另外刷新目录权限需要联系技术支持开通
    CdnResult.RefreshResult result = c.refreshDirs(dirs);
    System.out.println(result.code);
    //获取其他的回复内容
} catch (QiniuException e) {
    System.err.println(e.response.toString());
}
```

## 刷新查询 [#刷新查询]

```
import com.qiniu.common.QiniuException;
import com.qiniu.http.Client;
import com.qiniu.http.Response;
import com.qiniu.util.Auth;
import com.qiniu.util.StringMap;

public static void getRefreshResult() {
    String accessKey = "";
    String secretKey = "";
    String url ="http://fusion.qiniuapi.com/v2/tune/refresh/list";
    String body = "{\"urls\":[\"http://p9w3dsbag.bkt.clouddn.com/demo.html\"]}";
    Auth auth = Auth.create(accessKey, secretKey);
    StringMap str = auth.authorization(url, body.getBytes(), Client.JsonMime);
    Client client = new Client();
    try {
        Response r = client.post(url, body.getBytes(), str);
        System.out.println(r.reqId);
        System.out.println(r.bodyString());
    } catch (QiniuException e) {
        // TODO Auto-generated catch block
        e.printStackTrace();
    }
}
```

<span id="fusion-prefetch" />

## 文件预取 [#文件预取]

```
import com.qiniu.cdn.CdnManager;
import com.qiniu.cdn.CdnResult;
import com.qiniu.common.QiniuException;
import com.qiniu.util.Auth;

String accessKey = "your access key";
String secretKey = "your secret key";
Auth auth = Auth.create(accessKey, secretKey);
CdnManager c = new CdnManager(auth);

//待预取的文件链接
String[] urls = new String[]{
        "http://javasdk.qiniudn.com/gopher1.jpg",
        "http://javasdk.qiniudn.com/gopher2.jpg",
        //...
};
try {
    //单次调用方法预取的链接数量不得超过100个
    CdnResult.PrefetchResult result = c.prefetchUrls(urls);
    System.out.println(result.code);
    //获取其他的回复内容
} catch (QiniuException e) {
    System.err.println(e.response.toString());
}
```

<span id="fusion-cdn_flux" />

## 获取域名流量 [#获取域名流量]

```
import com.qiniu.cdn.CdnManager;
import com.qiniu.cdn.CdnResult;
import com.qiniu.common.QiniuException;
import com.qiniu.util.Auth;

String accessKey = "your access key";
String secretKey = "your secret key";
Auth auth = Auth.create(accessKey, secretKey);
CdnManager c = new CdnManager(auth);

//域名列表
String[] domains = new String[]{
        "img1.example.com",
        "img2.example.com",
};

//开始和结束日期
String fromDate = "2017-01-02";
String toDate = "2017-01-10";
//数据粒度，支持的取值为 5min ／ hour ／day
String granularity = "day";

try {
    CdnResult.FluxResult fluxResult = c.getFluxData(domains, fromDate, toDate, granularity);
    //处理得到的结果数据
    //...
} catch (QiniuException e) {
    System.err.println(e.response.toString());
}
```

<span id="fusion-cdn_bandwidth" />

## 获取域名带宽 [#获取域名带宽]

```
import com.qiniu.cdn.CdnManager;
import com.qiniu.cdn.CdnResult;
import com.qiniu.common.QiniuException;
import com.qiniu.util.Auth;

String accessKey = "your access key";
String secretKey = "your secret key";
Auth auth = Auth.create(accessKey, secretKey);
CdnManager c = new CdnManager(auth);

//域名列表
String[] domains = new String[]{
        "img1.example.com",
        "img2.example.com",
};

//开始和结束日期
String fromDate = "2017-01-02";
String toDate = "2017-01-10";
//数据粒度，支持的取值为 5min ／ hour ／day
String granularity = "day";

try {
    CdnResult.BandwidthResult bandwidthResult = c.getBandwidthData(domains, fromDate, toDate, granularity);
    //处理得到的结果数据
    //...
} catch (QiniuException e) {
    System.err.println(e.response.toString());
}
```

<span id="fusion-cdn_logs" />

<span id="qiniu-cdn-loglist" />

## 获取日志下载链接 [#获取日志下载链接]

```
import com.qiniu.cdn.CdnManager;
import com.qiniu.cdn.CdnResult;
import com.qiniu.common.QiniuException;
import com.qiniu.util.Auth;

String accessKey = "your access key";
String secretKey = "your secret key";
Auth auth = Auth.create(accessKey, secretKey);
CdnManager c = new CdnManager(auth);

//域名列表
String[] domains = new String[]{
        "img1.example.com",
        "img2.example.com",
};

//具体日期
String logDate = "2017-01-02";

try {
    CdnResult.LogListResult logListResult = c.getCdnLogList(domains, logDate);
    //处理得到的结果数据
    //...
} catch (QiniuException e) {
    System.err.println(e.response.toString());
}
```

## 构建时间戳防盗链访问链接 [#构建时间戳防盗链访问链接]

具体算法可以参考： [时间戳防盗链](/products/cdn/configuration-management-fusion/access-control-configuration/1-timestamp-hotlinking-prevention-fusion)

```
import com.qiniu.cdn.CdnManager;
import com.qiniu.util.StringMap;

String host = "http://video.example.com";
String fileName = "基本概括.mp4";

//查询参数
StringMap queryStringMap = new StringMap();
queryStringMap.put("name", "七牛");
queryStringMap.put("year", 2017);
queryStringMap.put("年龄", 28);

//链接过期时间
long deadline = System.currentTimeMillis() / 1000 + 3600;

//签名密钥，从后台域名属性中获取
String encryptKey = "xxx";
String signedUrl;
try {
    signedUrl = CdnManager.createTimestampAntiLeechUrl(host, fileName,
            queryStringMap, encryptKey, deadline);
    System.out.println(signedUrl);
} catch (Exception ex) {
    ex.printStackTrace();
}
```

## API 参考 [#api-参考]

* [存储 API 参考](/products/kodo/kodo-console-guide/0-an-overview-of-the-console)
* [融合 CDN API 参考](/products/cdn/0-fusion-api-overview)
* [官方数据处理 API 参考](/faq/dora)
* [视频监控 QVS API 参考](/faq/qvs)

## 常见问题 [#常见问题]

* QiniuExeption 保留了请求响应的信息，失败情况下会抛出此异常，可以提交给我们排查问题。
* API 的使用，demo 可以参考 [单元测试](https://github.com/qiniu/java-sdk/blob/master/src/test) 。

## 相关资源 [#相关资源]

如果您有任何关于我们文档或产品的建议和想法，欢迎您通过以下方式与我们互动讨论：

* [技术论坛](http://segmentfault.com/qiniu) - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
* [提交工单](https://support.qiniu.com/tickets/new) - 如果您的问题不适合在论坛讨论或希望及时解决，您也可以提交一个工单，我们的技术支持人员会第一时间回复您
* [博客](http://blog.qiniu.com/) - 这里会持续更新发布市场活动和技术分享文章
* [微博](http://weibo.com/qiniutek)
* [常见问题](https://support.qiniu.com/question)

## 贡献代码 [#贡献代码]

1. Fork
2. 创建您的特性分支 git checkout -b my-new-feature
3. 提交您的改动 git commit -am ‘Added some feature’
4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature
5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

## 许可证 [#许可证]

Copyright © 2014 qiniu.com

基于 MIT 协议发布:

* [www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)


# Objective-C SDK (/products/kodo/1-objc)



最近更新时间: 2025-06-16 16:16:26

Objective-C SDK 为客户端 SDK，没有包含 token 生成实现，为了安全，token 都建议通过网络从服务端获取 具体生成代码可以参考七牛服务端官方 SDK 。支持 Mac 和 iOS，会根据文件大小自动选择表单上传还是断点续上传。

* [Objective-C SDK 下载地址](https://github.com/qiniu/objc-sdk/releases)
* [Objective-C SDK 源码地址](https://github.com/qiniu/objc-sdk)
* [Objective-C SDK 单元测试](https://github.com/qiniu/objc-sdk/tree/master/QiniuSDKTests)

| Qiniu SDK 版本                                                                              | 最低 iOS 版本 | 最低 OS X 版本 | Notes          |
| ----------------------------------------------------------------------------------------- | --------- | ---------- | -------------- |
| [8.9.x](https://github.com/qiniu/objc-sdk/tree/v8.5.0)                                    | iOS 9     | OS X 10.15 | Xcode 最低版本 11. |
| [8.8.x](https://github.com/qiniu/objc-sdk/tree/v8.5.0)                                    | iOS 9     | OS X 10.15 | Xcode 最低版本 11. |
| [8.7.x](https://github.com/qiniu/objc-sdk/tree/v8.5.0)                                    | iOS 9     | OS X 10.15 | Xcode 最低版本 11. |
| [8.6.x](https://github.com/qiniu/objc-sdk/tree/v8.5.0)                                    | iOS 9     | OS X 10.15 | Xcode 最低版本 11. |
| [8.5.x](https://github.com/qiniu/objc-sdk/tree/v8.5.0)                                    | iOS 7     | OS X 10.15 | Xcode 最低版本 11. |
| [8.4.x](https://github.com/qiniu/objc-sdk/tree/v8.4.0)                                    | iOS 7     | OS X 10.15 | Xcode 最低版本 11. |
| [8.3.x](https://github.com/qiniu/objc-sdk/tree/v8.3.0)                                    | iOS 7     | OS X 10.15 | Xcode 最低版本 11. |
| [8.2.x](https://github.com/qiniu/objc-sdk/tree/v8.2.0)                                    | iOS 7     | OS X 10.15 | Xcode 最低版本 11. |
| [8.1.x](https://github.com/qiniu/objc-sdk/tree/v8.1.0)                                    | iOS 7     | OS X 10.15 | Xcode 最低版本 11. |
| [8.0.x](https://github.com/qiniu/objc-sdk/tree/v8.0.0)                                    | iOS 7     | OS X 10.15 | Xcode 最低版本 11. |
| [7.4.x](https://github.com/qiniu/objc-sdk/tree/v7.4.0)                                    | iOS 7     | OS X 10.9  | Xcode 最低版本 6.  |
| [7.3.x](https://github.com/qiniu/objc-sdk/tree/v7.3.0)                                    | iOS 7     | OS X 10.9  | Xcode 最低版本 6.  |
| [7.2.x](https://github.com/qiniu/objc-sdk/tree/v7.2.0)                                    | iOS 7     | OS X 10.9  | Xcode 最低版本 6.  |
| [7.1.x / AFNetworking-3.x](https://github.com/qiniu/objc-sdk/tree/AFNetworking-3.x)       | iOS 7     | OS X 10.9  | Xcode 最低版本 6.  |
| [7.0.x / AFNetworking-2.x](https://github.com/qiniu/objc-sdk/tree/7.0.x/AFNetworking-2.x) | iOS 6     | OS X 10.8  | Xcode 最低版本 5.  |
| [7.x / AFNetworking-1.x](https://github.com/qiniu/objc-sdk/tree/AFNetworking-1.x)         | iOS 5     | OS X 10.7  | Xcode 最低版本 5.  |
| [6.x](https://github.com/qiniu/ios-sdk)                                                   | iOS 6     | None       | Xcode 最低版本 5.  |

## 1 安装 [#1-安装]

## 1.1 使用 Cocoapods 进行安装 [#11-使用-cocoapods-进行安装]

```
pod "Qiniu", "~> 8.9.0"
```

## 1.2 通过 Swift Package Manager [#12-通过-swift-package-manager]

```
App 对接:
File -> Swift Packages -> Add Package Dependency，输入库链接，选择相应版本即可。
库链接: https://github.com/qiniu/objc-sdk

库对接:
let package = Package(
    dependencies: [
        .package(url: "https://github.com/qiniu/objc-sdk", from: "8.9.0")
    ],
    // ...
)

库引入方式：
import QiniuSDK
```

## 2 推荐的使用姿势 [#2-推荐的使用姿势]

iOS SDK 作为移动端的 SDK，在使用时会被嵌入到移动端的应用中，为了保证信息的安全以及业务的灵活性，我们给出以下几点建议：

**注** ：\
文档中的示例基于 SDK 的版本为 v8.9.0

### 2.1 AccessKey 和 SecretKey 下发 [#21-accesskey-和-secretkey-下发]

账户以及 iam 子账户的密钥对 AccessKey 和 SecretKey 不要固化在客户端中，其涉及相关参数通过用户自己的业务服务端来生成并下发（比如上传的 Token）。业务服务端集中管理 AccessKey 和 SecretKey ，避免泄漏；其次 AccessKey 、SecretKey 和客户端应用需解耦，其因泄露更换时不会产生不必要麻烦。

### 2.2 上传域名下发，并可以下发多个域名 [#22-上传域名下发并可以下发多个域名]

SDK 上传过程：

1. 获取七牛 Bucket 的上传域名；
   * 指定域名。通过指定区域 id 或直接给上传域名列表方式指定域名，详情见 [域名配置](/products/kodo/1-objc#3-%E5%9F%9F%E5%90%8D%E9%85%8D%E7%BD%AE) QNFixedZone；
     * SDK 自动查询域名。SDK 内部自动调用七牛服务端接口，查询 Bucket 的上传域名，详情见 [域名配置](/products/kodo/1-objc#3-%E5%9F%9F%E5%90%8D%E9%85%8D%E7%BD%AE) QNAutoZone；
2. 使用上传域名进行上传，上传过程会伴随主备重试，既多个域名时，一个域名上传失败，会尝试使用其他域名进行上传。

**建议的上传域名下发方式**

用户服务在下发上传 Token 时同时下发上传域名（可以在 App 需要进行上传时，先请求获取获取上传 Token 及上传域名），可下发多个域名，App 在拿到 Token 和上传域名后，配置上传 Config 以及 QNUploadManager，进而进行上传操作。

具体代码示例如下：

```
// Upload_Domain1, Upload_Domain2 为服务下发的上传域名
QNFixedZone *fixedZone = [[QNFixedZone alloc] initWithUpDomainList:@[@"Upload_Domain1", @"Upload_Domain2"]];
QNConfiguration *config = [QNConfiguration buildV2:^(QNConfigurationBuilder *builder) {
    builder.zone = fixedZone;
}];
QNUploadManager *manager = [[QNUploadManager alloc] initWithConfiguration:config];
```

**域名下发的优点：**

1. 跳过域名查询过程，上传更高效。
2. 避免在 App 硬编码上传域名，导致使用不灵活，比如：
   * 在客户更换/增加区域时，由于 App 硬编码了区域，已发布的 App 无法处理此问题。
     * 某些客户生产环境使用的 Bucket 和 测试环境使用的 Bucket 不在同一个区域，在实际上线时错用了测试 Bucket 的区域，导致 Bucket 和区域不匹配，App 相关功能不可用。
     * 自定义域名，由于硬编码，老版本 App 也无法灵活应对。

除了上面的问题，还有很多情景不再列举，上面问题的根本原因是由于 App 硬编码了区域的上传域名导致 App 不能灵活应对上传域名需要修改的场景，所以建议客户通过服务下发上传的方式来配置 SDK 的上传域名, 而不是直接硬编码上传域名。

## 3 域名配置 [#3-域名配置]

域名配置分为 QNFixZone 和 QNAutoZone 两种方式。

## 3.1 QNFixZone [#31-qnfixzone]

在 QNFixZone 中，上传域名被固定，且不可更改。有两种配置方式：

### 3.1.1 通过指定上传区域 ID 方式 [#311-通过指定上传区域-id-方式]

区域 ID 和区域域名对应关系参考 [这里](/products/kodo/2-region-endpoint-fq)

```
// 指定上传区域为 华东-浙江
QNFixedZone *zone = [QNFixedZone createWithRegionId:@"z0"];
```

这种方式硬编码了上传域名的区域，且不可更改，所以不建议在生产环境中使用，仅供测试使用。

### 3.1.2 直接配置上传域名 [#312-直接配置上传域名]

直接配置上传域名的方式可以灵活配置域名，我们不建议上传域名配置为固定域名，而是通过服务下发的方式进行配置。具体上传域名下发请参考 **上传域名下发** 介绍。

```
// Upload_Domain1, Upload_Domain2 为服务下发的上传域名
QNFixedZone *fixedZone = [[QNFixedZone alloc] initWithUpDomainList:@[@"Upload_Domain1", @"Upload_Domain2"]];
```

## 3.2 QNAutoZone [#32-qnautozone]

如果用户不想关心上传域名相关的逻辑，而且没有任何自定义的需求，完全依赖七牛的上传域名，则可以使用 AutoZone。AutoZone 相对于 FixZone 来说，在第一次上传时查询上传域名，后续会使用缓存的上传域名进行上传。在缓存有效期内不会更换上传域名，当前域名缓存有效期为 24 小时。\
示例代码：

```
// 不指定 uc 域名，使用七牛公有云默认域名
QNAutoZone *zone = [[QNAutoZone alloc] init];

// 指定 uc 域名，公有云无需指定
QNAutoZone *zone = [QNAutoZone zoneWithUcHosts:@[@"UCHost0", @"UCHost1"]];
```

不过我们推荐用户使用 **上传域名下发** 的方式来配置上传域名，防止后续业务变更需要。

## 4 上传 [#4-上传]

## 4.1 上传示例 [#41-上传示例]

SDK 内置两种上传方式：表单上传和分片上传，并根据具体情况，内部做了自动切换。表单上传使用一个 HTTP POST 请求完成文件的上传，因此比较适合较小的文件和较好的网络环境。相比而言，分片上传更能适应不稳定的网络环境，也比较适合上传比较大的文件（例如数百 MB 或更大）。

若需深入了解上传方式之间的区别，请参阅上传类型中 [表单上传](/products/kodo/development-guidelines/upload-types/1-form-upload) 、 [分片上传 v1 版](/products/kodo/development-guidelines/upload-types/2-chunked-upload) 和 [分片上传 v2 版](/products/kodo/rs/multipartupload-interface) 接口说明。

QNUploadManager 上传接口参数说明：

| 参数                | 类型                                                  | 说明                                                                              |
| ----------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
| data              | NSData \*/NSString \*/PHAsset \*/PHAssetResource \* | 数据，可以是 NSData、文件路径、资源、数据流                                                       |
| key               | NSString \*                                         | 保存在服务器上的资源唯一标识，请参阅 [键值对](/products/kodo/3-the-basic-concept#%E8%B5%84%E6%BA%90) |
| token             | NSString \*                                         | 服务器分配的 token                                                                    |
| completionHandler | QNUpCompletionHandler                               | 上传回调函数，必填                                                                       |
| option            | QNUploadOption                                      | 如果需要进度通知、中途取消、指定 mimeType，则需要填写相应字段，详见下面的 QNUploadOption 参数说明                   |

QNUploadOption 参数说明：

| 参数              | 类型                                         | 说明                              |
| --------------- | ------------------------------------------ | ------------------------------- |
| params          | NSDictionary\<NSString \*, NSString \*> \* | 自定义变量，key 必须以 x: 开始             |
| metaDataParam   | NSDictionary\<NSString \*, NSString \*> \* | 自定义meta数据，key 必须以 x-qn-meta- 开始 |
| mimeType        | NSString                                   | 指定文件的 mimeType                  |
| progressHandler | QNUpProgressHandler                        | 上传进度回调                          |

```
#import <QiniuSDK.h>

QNConfiguration *configuration = [QNConfiguration buildV2:^(QNConfigurationBuilder *builder) {
    // 配置上传区域，Host0、Host1 建议通过服务方式下发
    builder.zone = [[QNFixedZone alloc] initWithUpDomainList:@[@"Host0", @"Host2"]];
    // 分片上传阈值：4MB，大于 4MB 采用分片上传，小于 4MB 采用表单上传
    builder.putThreshold = 4*1024*1024;
    // 开启并发分片上传
    builder.useConcurrentResumeUpload = true;
    // 使用分片 V2
    builder.resumeUploadVersion = QNResumeUploadVersionV2;
    // 文件分片上传时断点续传信息保存，表单上传此配置无效
    NSString *recorderPath = [NSHomeDirectory() stringByAppendingPathComponent:@"Documents"];
    builder.recorder = [QNFileRecorder fileRecorderWithFolder:recorderPath error:nil];
}];
QNUploadManager *upManager = [[QNUploadManager alloc] initWithConfiguration:configuration];

__weak typeof(self) weakSelf = self;
QNUploadOption *uploadOption = [[QNUploadOption alloc] initWithMime:nil progressHandler:^(NSString *key, float percent) {
    NSLog(@"percent == %.2f", percent);
}
                                                             params:nil
                                                           checkCrc:NO
                                                 cancellationSignal:^BOOL{
    // 当需要取消时，此处返回 true，SDK 内部会多次检查返回值，当返回值为 true 时会取消上传操作
    return false;
}];

NSString *filePath = @"";    // 文件路径
NSString *key = @"";         // 文件 key
NSString *uploadToken = @""; // 上传的 Token
[upManager putFile:filePath key:key token:uploadToken complete:^(QNResponseInfo *info, NSString *key, NSDictionary *resp) {
    if (info.isOK) {
        // 上传成功
    } else {
        // 上传失败
    }
} option:uploadOption];
```

## 4.2 上传配置介绍 [#42-上传配置介绍]

### 4.2.1 开启传输加速 [#421-开启传输加速]

默认情况下，SDK 未开启使用加速域名上传的功能，如需开启需按下面方式进行配置：

```
// 1. 在七牛云存储控制台修改 Bucket 配置，域名管理 -> 开启传输加速（SDK 开启使用加速域名上传的功能仅仅是 SDK 支持
//    使用加速域名，所以要想使用传输加速，七牛云服务端需开启此功能）
// 
// 2. SDK 配置 
// 方式一：使用 QNFixZone 配置
QNConfiguration *config = [QNConfiguration buildV2:^(QNConfigurationBuilder *builder) {
    // Upload_Domain1 和 Upload_Domain2 为加速域名，可以参考七牛云存储控制台域名管理页面，建议通过用户服务下发，不要硬编码
    builder.zone =  [[QNFixedZone alloc] initWithUpDomainList:@[@"Upload_Domain1", @"Upload_Domain2"]];
}];

// 方式二：使用 AutoZone
QNConfiguration *config = [QNConfiguration buildV2:^(QNConfigurationBuilder *builder) {
    builder.accelerateUploading = YES;        // 开启传输加速，此参数仅对使用 QNAutoZone 时有效 （v8.8.0 开始支持）
    builder.zone = [[QNAutoZone alloc] init]; // 默认是 AutoZone，所以 zone 也可以不配置
}];
```

### 4.2.2 其他配置 [#422-其他配置]

```
QNConfiguration *configuration = [QNConfiguration buildV2:^(QNConfigurationBuilder *builder) {
    builder.zone = [[QNAutoZone alloc] init]; // 配置上传区域，使用 QNAutoZone
    builder.recorderKeyGen = ^NSString *(NSString *uploadKey, NSString *filePath) {
        // 自定义 文件分片上传时断点续传信息保存的 key，默认使用 uploadKey
        return [NSString stringWithFormat:@"%@-%@", uploadKey, filePath];
    };
    // 文件分片上传时断点续传信息保存，表单上传此配置无效
    NSString *recorderPath = [NSHomeDirectory() stringByAppendingPathComponent:@"Documents"];
    builder.recorder = [QNFileRecorder fileRecorderWithFolder:recorderPath error:nil];
    // 文件采用分片上传时，分片大小为 2MB
    builder.chunkSize = 2*1024*1024;
    
    // 分片上传阈值：4MB，大于 4MB 采用分片上传，小于 4MB 采用表单上传
    builder.putThreshold = 4*1024*1024;
    
    // 单个域名/IP请求失败后最大重试次数为 1 次
    builder.retryMax = 1;
    
    // 重试时间间隔：0.5s
    builder.retryInterval = 0.5;
    
    // 请求超时时间：60s
    builder.timeoutInterval = 60;
    
    // 使用 HTTPS
    builder.useHttps = true;
    
    // 使用备用域名进行重试
    builder.allowBackupHost = true;
    
    // 开启加速上传
    builder.accelerateUploading = true;
   
    // 开启并发分片上传
    builder.useConcurrentResumeUpload = true;
    
    // 使用并发分片上传时，一个文件并发上传的分片个数
    builder.concurrentTaskCount = 2;
    
    // 使用分片 V2
    builder.resumeUploadVersion = QNResumeUploadVersionV2;
}];

// 指定文件 mime type
NSString *mimeType = @"";
// 用于服务器上传回调通知的自定义参数，参数的key必须以x: 开头  eg: x:foo
NSDictionary <NSString *, NSString *> * params = @{};
// 用于设置meta数据，参数的key必须以x-qn-meta- 开头  eg: x-qn-meta-key
NSDictionary <NSString *, NSString *> * metaDataParams = @{};
BOOL checkCrc = true;
QNUploadOption *option = [[QNUploadOption alloc] initWithMime:mimeType
                                          byteProgressHandler:^(NSString *key, long long uploadBytes, long long totalBytes) {
    // 处理上传进度
} params:params metaDataParams:metaDataParams checkCrc:checkCrc cancellationSignal:^BOOL{
    // 当需要取消时，此处返回 false，SDK 内部会不间断检测此返回值
    return false;
}];

// 关闭 DNS 预解析
//从 7.4.0 开始增加了 DNS 预解析和缓存策略（每 2 分钟（进程非挂起状态）会自动刷新缓存策略）来减少 DNS 解析错误。默认预解析开启，需获取 IP 信息。
kQNGlobalConfiguration.isDnsOpen = NO;

// 关闭网络状态检测，当因网络异常而失败时，会检测网络状态，进而根据情况调整重试逻辑。默认开启网络状态检测。
kQNGlobalConfiguration.connectCheckEnable = NO;
```

## 5 下载文件 [#5-下载文件]

该 SDK 并未提供下载文件相关的功能接口，因为文件下载是一个标准的 HTTP GET 过程。开发者只需理解资源 URI 的组成格式即可非常方便的构建资源 URI，并在必要的时候加上 [下载凭证](/products/kodo/development-guidelines/security/0-download-token) ，即可使用 HTTP GET 请求获取相应资源。

从安全性和代码可维护性的角度考虑，我们建议下载 URL 的拼接过程也在业务服务器进行，让客户端从业务服务器请求。

## API 参考 [#api-参考]

* [存储 API 参考](/products/kodo/kodo-console-guide/0-an-overview-of-the-console)
* [官方数据处理 API 参考](/faq/dora)

## 常见问题 [#常见问题]

* 如果碰到 crc 链接错误，请把 libz.dylib 加入到项目中去。
* 如果碰到 res\_9\_ninit 链接错误，请把 libresolv.dylib 加入到项目中去。
* 如果需要支持 iOS 5 或者支持 RestKit，请用 AFNetworking 1.x 分支的版本。
* 如果碰到其他编译错误，请参考 Cocoapods 的 [troubleshooting](http://guides.cocoapods.org/using/troubleshooting.html) 。
* iOS 9+ 强制使用 https ，需要在 project build info 添加 NSAppTransportSecurity 类型 Dictionary。在 NSAppTransportSecurity下添加 NSAllowsArbitraryLoads 类型 Boolean ，值设为 YES。具体操作请查阅 [这里](http://blog.csdn.net/guoer9973/article/details/48622823) 。

## 相关资源 [#相关资源]

如果您有任何关于我们文档或产品的建议和想法，欢迎您通过以下方式与我们互动讨论：

* [技术论坛](http://segmentfault.com/qiniu) - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
* [提交工单](http://support.qiniu.com/) - 如果您的问题不适合在论坛讨论或希望及时解决，您也可以提交一个工单，我们的技术支持人员会第一时间回复您
* [博客](http://blog.qiniu.com/) - 这里会持续更新发布市场活动和技术分享文章
* [微博](http://weibo.com/qiniutek)
* [常见问题](https://support.qiniu.com/)

## 贡献代码 [#贡献代码]

1. Fork
2. 创建您的特性分支 git checkout -b my-new-feature
3. 提交您的改动 git commit -am ‘Added some feature’
4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature
5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

## 许可证 [#许可证]

Copyright © 2020 qiniu.com

基于 MIT 协议发布:

* [www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)


# Python SDK (/products/kodo/2-python)



最近更新时间: 2025-07-14 11:34:08

从 v5.0.0 版本开始，我们对 SDK 的内容进行了精简。所有管理操作，比如：创建/删除 bucket、为 bucket 绑定域名、设置数据处理的样式分隔符、新增数据处理样式等都去除了，统一建议到 [七牛开发者平台](https://portal.qiniu.com/) 来完成。另外，此前服务端还有自己独有的上传 API，现在也推荐统一成基于客户端上传的工作方式。

此 Python SDK 适用于 2.7 和 3.3 及以上版本

* [Python SDK 下载地址](https://github.com/qiniu/python-sdk/releases)
* [Python SDK 源码地址](https://github.com/qiniu/python-sdk)

**注** ：\
此文档示例基于最新版本 SDK，如出现不存在的方法请尝试升级 SDK 至最新版本。

## 安装 [#安装]

* 直接安装:

```
pip install qiniu
或
easy_install qiniu
```

* 源码安装：

```
#从Python SDK 下载地址下载源码
tar xvzf python-sdk-$VERSION.tar.gz
cd python-sdk-$VERSION
python setup.py install
```

## 初始化 [#初始化]

在使用 SDK 前，您需要一对有效的 AccessKey 和 SecretKey 签名授权。\
可以通过如下步骤获得：

1. 点击 [注册](https://portal.qiniu.com/signup) 开通七牛开发者帐号
2. 如果已有账号，直接登录七牛开发者后台，点击 [这里](https://portal.qiniu.com/user/key) 查看 Access Key 和 Secret Key

获取 Access Key 和 Secret Key 后，调用如下两行代码进行初始化对接：

```
from qiniu import Auth

q = Auth(access_key, secret_key)
```

## 上传相关 [#上传相关]

* [上传流程](/products/kodo/2-python#%E4%B8%8A%E4%BC%A0%E6%B5%81%E7%A8%8B)
* [上传带回调](/products/kodo/2-python#upload-callback)
* [上传并预持久化数据处理](/products/kodo/2-python#upload-prefop)
* [生成上传 token](/products/kodo/2-python#%E7%94%9F%E6%88%90%E4%B8%8A%E4%BC%A0-token)
* [上传加速](/products/kodo/2-python#%E4%B8%8A%E4%BC%A0%E5%8A%A0%E9%80%9F)

## 上传流程 [#上传流程]

为了尽可能地改善终端用户的上传体验，七牛云存储首创了客户端直传功能。更多信息请参阅 [业务流程](/products/kodo/0-programming-model) 。

SDK 内置两种上传方式：表单上传和分片上传，并根据具体情况，内部做了自动切换。表单上传使用一个 HTTP POST 请求完成文件的上传，因此比较适合较小的文件和较好的网络环境。相比而言，分片上传更能适应不稳定的网络环境，也比较适合上传比较大的文件（例如数百 MB 或更大）。

若需深入了解上传方式之间的区别，请参阅上传类型中 [表单上传](/products/kodo/development-guidelines/upload-types/1-form-upload) 、 [分片上传 v1 版](/products/kodo/development-guidelines/upload-types/2-chunked-upload) 和 [分片上传 v2 版](/products/kodo/rs/multipartupload-interface) 接口说明。 可以选择分片上传版本，推荐 `version = 'v2'` ，表示 [分片上传 v2 版](/products/kodo/development-guidelines/upload-types/8-multipartupload) ， `version = 'v1'` ，表示 [分片上传 v1 版](/products/kodo/development-guidelines/upload-types/2-chunked-upload) ，兼容历史情况，详见 put\_file\_v2 或 put\_stream\_v2 方法的 [API 文档](https://github.com/qiniu/python-sdk/blob/master/qiniu/services/storage/uploader.py) 。

上传代码：

```
# -*- coding: utf-8 -*-
# flake8: noqa

from qiniu import Auth, put_file_v2, etag
import qiniu.config

#需要填写你的 Access Key 和 Secret Key
access_key = 'Access_Key'
secret_key = 'Secret_Key'

#构建鉴权对象
q = Auth(access_key, secret_key)

#要上传的空间
bucket_name = 'Bucket_Name'

#上传后保存的文件名
key = 'my-python-logo.png'

#生成上传 Token，可以指定过期时间等
token = q.upload_token(bucket_name, key, 3600)

#要上传文件的本地路径
localfile = './sync/bbb.jpg'

ret, info = put_file_v2(token, key, localfile, version='v2')
print(info)
assert ret['key'] == key
assert ret['hash'] == etag(localfile)
```

<span id="upload-callback" />

## 上传&回调 [#上传回调]

```
# -*- coding: utf-8 -*-
# flake8: noqa

from qiniu import Auth, put_file_v2, etag
import qiniu.config

access_key = 'Access_Key'
secret_key = 'Secret_Key'

q = Auth(access_key, secret_key)

bucket_name = 'Bucket_Name'

key = 'my-python-logo.png'

#上传文件到存储后， 存储服务将文件名和文件大小回调给业务服务器。
policy={
 'callbackUrl':'http://your.domain.com/callback.php',
 'callbackBody':'filename=$(fname)&filesize=$(fsize)'
 }

token = q.upload_token(bucket_name, key, 3600, policy)

localfile = './sync/bbb.jpg'

ret, info = put_file_v2(token, key, localfile, version='v2')
print(info)
assert ret['key'] == key
assert ret['hash'] == etag(localfile)
```

## 上传&预转持续化 [#上传预转持续化]

开发者希望在上传文件过程中自动触发数据处理过程（即预转持久化）。

以视频转码为例：

```
# -*- coding: utf-8 -*-
# flake8: noqa

from qiniu import Auth, put_file_v2, etag, urlsafe_base64_encode
import qiniu.config

access_key = 'Access_Key'
secret_key = 'Secret_Key'

q = Auth(access_key, secret_key)

bucket_name = 'Bucket_Name'

key = 'my-python-logo.png'

#设置转码参数
fops = 'avthumb/mp4/s/640x360/vb/1.25m'

#转码是使用的队列名称
pipeline = 'abc'

#可以对转码后的文件进行使用saveas参数自定义命名，当然也可以不指定文件会默认命名并保存在当前空间
saveas_key = urlsafe_base64_encode('目标Bucket_Name:自定义文件key')
fops = fops+'|saveas/'+saveas_key
#任务类型：0: 普通任务 1: 闲时任务（一旦指定闲时任务，就不能指定 persistentPipeline）
persistent_type = 0
#任务模版 ID，使用预设好的任务；与 fops 冲突，只能二选一
#persistent_workflow_template_id = 'your-workflow-id'

#在上传策略中指定
policy={
  'persistentOps': fops,
  'persistentPipeline': pipeline,
  'persistentType': persistent_type
  #'persistentWorkflowTemplateID': persistent_workflow_template_id
 }

token = q.upload_token(bucket_name, key, 3600, policy)

localfile = './sync/bbb.jpg'

ret, info = put_file_v2(token, key, localfile, version='v2')
print(info)
assert ret['key'] == key
assert ret['hash'] == etag(localfile)
```

* 队列 pipeline 请参阅 [创建私有队列](https://portal.qiniu.com/dora/media-gate/pipeline) ；转码操作 具体参数请参阅 [音视频转码](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) ；saveas 请参阅 [处理结果另存](/products/dora/processing-mechanism/0-processing-results-save-saveas) 。
* 闲时任务的功能介绍、使用场景、定价，详见 [闲时任务策略说明](/products/dora/processing-mechanism/persist/2-idle-time-task-strategy) 。
* 工作流模板是预先编排好的一系列媒体处理流程（如转码、截图、视频拼接等各类处理），登录 [对象存储控制台](https://portal.qiniu.com/kodo/bucket) 进行创建，详情参考 [工作流模板操作指南](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template) ， `persistentWorkflowTemplateID` 对应工作流模板列表的 `名称` 字段

**Tips** ：上面的 Demo 只是针对视频转码功能，如果您需要使用比如音视频切片、视频截图、视频拼接等功能只需要修改上面 fops 后面的参数即可，如： `fops = vframe/jpg/offset/1/w/480/h/360/rotate/90` 就表示视频截图了。

可以看到上传成功后的行为主要是由 [上传凭证](/products/kodo/development-guidelines/security/2-upload-token) 中的 上传策略 来指定。其中 上传策略 可以指定的行为不止这些，具体请参阅 [上传策略](/products/kodo/development-guidelines/security/1-put-policy) 。

## 生成上传 token [#生成上传-token]

```
# -*- coding: utf-8 -*-
# flake8: noqa

from qiniu import Auth

#需要填写你的 Access Key 和 Secret Key
access_key = ''
secret_key = ''

#构建鉴权对象
q = Auth(access_key, secret_key)

#要上传的空间
bucket_name = ''

#上传后保存的文件名
key = ''

#生成上传 Token，可以指定过期时间等

# 上传策略示例
# /products/kodo/development-guidelines/security/1-put-policy
policy = {
 # 'callbackUrl':'https://requestb.in/1c7q2d31',
 # 'callbackBody':'filename=$(fname)&filesize=$(fsize)'
 # 'persistentOps':'imageView2/1/w/200/h/200'
 }

#3600为token过期时间，秒为单位。3600等于一小时
token = q.upload_token(bucket_name, key, 3600, policy)

print(token)
```

## 上传加速 [#上传加速]

```
# -*- coding: utf-8 -*-
# flake8: noqa

from qiniu import Auth, Region
from qiniu.services.storage.uploaders import FormUploader, ResumeUploaderV2

#需要填写你的 Access Key 和 Secret Key
access_key = 'Access_Key'
secret_key = 'Secret_Key'

#构建鉴权对象
q = Auth(access_key, secret_key)

#要上传的空间
bucket_name = 'Bucket_Name'

#上传后保存的文件名
key = 'my-python-logo.png'

#生成上传 Token，可以指定过期时间等
token = q.upload_token(bucket_name, key, 3600)

#要上传文件的本地路径
localfile = './sync/bbb.jpg'

form_uploader = FormUploader(bucket_name, regions=[Region(up_host='https://<BucketId>.kodo-accelerate.<RegionId>.qiniucs.com')]) # 这里填写空间级别传输加速域名
ret, info = form_uploader.upload(key, localfile, up_token=token)
print(info, ret)

resumeUploader = ResumeUploaderV2(bucket_name, regions=[Region(up_host='https://<BucketId>.kodo-accelerate.<RegionId>.qiniucs.com')]) # 这里填写空间级别传输加速域名
ret, info = resumeUploader.upload(key, localfile, up_token=token)
print(info, ret)
```

<span id="upload-prefop" />

## 持久化数据处理 [#持久化数据处理]

* [触发持久化操作](/products/kodo/2-python#%E8%A7%A6%E5%8F%91%E6%8C%81%E4%B9%85%E5%8C%96%E6%93%8D%E4%BD%9C)

## 触发持久化操作 [#触发持久化操作]

如果需要对已存在于空间中的资源进行持久化数据处理（即触发持久化）。

以视频转码为例：

```
# -*- coding: utf-8 -*-
# flake8: noqa
from qiniu import Auth, PersistentFop, build_op, op_save, urlsafe_base64_encode

#对已经上传到存储的视频发起异步转码操作
access_key = 'Access_Key'
secret_key = 'Secret_Key'
q = Auth(access_key, secret_key)

#要转码的文件所在的空间和文件名。
bucket = 'Bucket_Name'
key = '1.mp4'

#转码是使用的队列名称。
pipeline = 'mpsdemo'

#要进行转码的转码操作。
fops = 'avthumb/mp4/s/640x360/vb/1.25m'

#可以对转码后的文件进行使用saveas参数自定义命名，当然也可以不指定文件会默认命名并保存在当前空间
saveas_key = urlsafe_base64_encode('目标Bucket_Name:自定义文件key')
fops = fops+'|saveas/'+saveas_key
force = 1
#任务类型：0: 普通任务 1: 闲时任务（一旦指定闲时任务，就不能指定 pipeline）
persistent_type = 0
#任务模版 ID，使用预设好的任务；与 fops 冲突，只能二选一
#workflow_template_id = 'your-workflow-id'

pfop = PersistentFop(q, bucket, pipeline)
ops = []
ops.append(fops)
ret, info = pfop.execute(
  key,
  ops=ops,
  #workflow_template_id=workflow_template_id
  force=force,
  persistent_type=persistent_type
)
print(info)
assert ret['persistentId'] is not None
```

**注意** ：

* 上面的 Demo 只是针对视频转码功能，如果您需要使用比如音视频切片、视频截图、视频拼接等功能只需要修改上面 `fops` 后面的参数即可，如： `fops = 'vframe/jpg/offset/1/w/480/h/360/rotate/90'` 就表示视频截图了。
* 闲时任务的功能介绍、使用场景、定价，详见 [闲时任务策略说明](/products/dora/processing-mechanism/persist/2-idle-time-task-strategy) 。
* 工作流模板是预先编排好的一系列媒体处理流程（如转码、截图、视频拼接等各类处理），登录 [对象存储控制台](https://portal.qiniu.com/kodo/bucket) 进行创建，详情参考 [工作流模板操作指南](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template) ， `workflow_template_id` 对应工作流模板列表的 `名称` 字段。

但这个只是将转码这个耗时的操作提交到队列中，要想知道转码操作现在的状态， 需要根据返回的 `persistentId` 进行查询， [查询接口](/products/dora/processing-mechanism/persist/1-persistent-processing-status-query-prefop) 。如果您不方便持续轮询每个异步处理的进度和状态，七牛可以异步处理完成后通知您们的业务服务器。这样就需要您在视频转码的例子中，初始化 `PersistentFo` p 时添加上 `notifyUrl` ， 来通知您们的业务服务器。

## 下载相关 [#下载相关]

* [生成时间戳防盗链](/products/kodo/2-python#%E7%94%9F%E6%88%90%E6%97%B6%E9%97%B4%E6%88%B3%E9%98%B2%E7%9B%97%E9%93%BE)
* [私有空间下载文件](/products/kodo/2-python#download-private)

## 生成时间戳防盗链 [#生成时间戳防盗链]

```
# -*- coding: utf-8 -*-

"""
获取一个配置时间戳防盗链的url
"""

from qiniu.services.cdn.manager import create_timestamp_anti_leech_url
import time

host = 'http://a.example.com'

# 配置时间戳时指定的key
encrypt_key = ''

# 资源路径
file_name = 'a/b/c/example.jpeg'

# 查询字符串,不需要加?
query_string = ''

# 截止日期的时间戳,秒为单位，3600为当前时间一小时之后过期
deadline = int(time.time())+3600

timestamp_url = create_timestamp_anti_leech_url(host, file_name, query_string, encrypt_key, deadline)

print(timestamp_url)
```

<span id="private-get" />

<span id="download-private" />

## 私有空间下载 [#私有空间下载]

```
# -*- coding: utf-8 -*-
# flake8: noqa
import requests

from qiniu import Auth

access_key = 'AK'
secret_key = 'SK'

q = Auth(access_key, secret_key)

#有两种方式构造base_url的形式
base_url = 'http://%s/%s' % (bucket_domain, key)

#或者直接输入url的方式下载
base_url = 'http://domain/key'

#可以设置token过期时间
private_url = q.private_download_url(base_url, expires=3600)

print(private_url)
r = requests.get(private_url)
assert r.status_code == 200
```

## 资源管理 [#资源管理]

资源管理包括的主要功能有：

* [获取文件信息](/products/kodo/2-python#%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E4%BF%A1%E6%81%AF)
* [修改文件 MimeType](/products/kodo/2-python#rs-chgm)
* [修改文件存储类型](/products/kodo/2-python#%E4%BF%AE%E6%94%B9%E6%96%87%E4%BB%B6%E5%AD%98%E5%82%A8%E7%B1%BB%E5%9E%8B)
* [移动或重命名文件](/products/kodo/2-python#rs-move)
* [复制文件副本](/products/kodo/2-python#rs-copy)
* [删除空间中的文件](/products/kodo/2-python#rs-delete)
* [设置或更新文件生存时间](/products/kodo/2-python#%E8%AE%BE%E7%BD%AE%E6%88%96%E6%9B%B4%E6%96%B0%E6%96%87%E4%BB%B6%E7%94%9F%E5%AD%98%E6%97%B6%E9%97%B4)
* [获取指定前缀文件列表](/products/kodo/2-python#%E8%8E%B7%E5%8F%96%E6%8C%87%E5%AE%9A%E5%89%8D%E7%BC%80%E6%96%87%E4%BB%B6%E5%88%97%E8%A1%A8)
* [抓取网络资源到空间](/products/kodo/2-python#%E6%8A%93%E5%8F%96%E7%BD%91%E7%BB%9C%E8%B5%84%E6%BA%90%E5%88%B0%E7%A9%BA%E9%97%B4)
* [更新镜像存储空间中文件内容](/products/kodo/2-python#rs-prefetch)
* [资源管理批量操作](/products/kodo/2-python#rs-batch)
  * [批量获取文件信息](/products/kodo/2-python#rs-batch-stat)
    * [批量删除文件](/products/kodo/2-python#%E6%89%B9%E9%87%8F%E5%88%A0%E9%99%A4%E6%96%87%E4%BB%B6)
    * [批量复制文件](/products/kodo/2-python#%E6%89%B9%E9%87%8F%E5%A4%8D%E5%88%B6%E6%96%87%E4%BB%B6)
    * [批量移动](/products/kodo/2-python#rs-batch-move)
    * [批量重命名](/products/kodo/2-python#rs-batch-rename)

<span id="rs-batch-stat" />

## 获取文件信息 [#获取文件信息]

```
# -*- coding: utf-8 -*-
# flake8: noqa
from qiniu import Auth
from qiniu import BucketManager

access_key = 'Access_Key'
secret_key = 'Secret_Key'

#初始化Auth状态
q = Auth(access_key, secret_key)

#初始化BucketManager
bucket = BucketManager(q)

#你要测试的空间， 并且这个key在你空间中存在
bucket_name = 'Bucket_Name'
key = 'python-logo.png'

#获取文件的状态信息
ret, info = bucket.stat(bucket_name, key)
print(info)
assert 'hash' in ret
```

<span id="rs-list" />

## 获取指定前缀文件列表 [#获取指定前缀文件列表]

```
# -*- coding: utf-8 -*-
# flake8: noqa
from qiniu import Auth
from qiniu import BucketManager

access_key = '...'
secret_key = '...'

q = Auth(access_key, secret_key)
bucket = BucketManager(q)

bucket_name = 'Bucket_Name'
# 前缀
prefix = None
# 列举条目
limit = 10
# 列举出除'/'的所有文件以及以'/'为分隔的所有前缀
delimiter = None
# 标记
marker = None

ret, eof, info = bucket.list(bucket_name, prefix, marker, limit, delimiter)

print(info)

assert len(ret.get('items')) is not None
```

## 抓取网络资源到空间 [#抓取网络资源到空间]

```
# -*- coding: utf-8 -*-
# flake8: noqa

from qiniu import Auth
from qiniu import BucketManager

access_key = '...'
secret_key = '...'

bucket_name = 'Bucket_Name'

q = Auth(access_key, secret_key)

bucket = BucketManager(q)

url = 'http://7xr875.com1.z0.glb.clouddn.com/xxx.jpg'

key = 'xxx.jpg'

ret, info = bucket.fetch(url, bucket_name, key)
print(info)
assert ret['key'] == key
```

<span id="rs-prefetch" />

## 抓取镜像源文件到空间 [#抓取镜像源文件到空间]

```
# -*- coding: utf-8 -*-
# flake8: noqa

from qiniu import Auth
from qiniu import BucketManager

access_key = '...'
secret_key = '...'

bucket_name = 'Bucket_Name'

q = Auth(access_key, secret_key)

bucket = BucketManager(q)

# 要拉取的文件名
key = 'test.jpg'

ret, info = bucket.prefetch(bucket_name, key)
print(info)
assert ret['key'] == key
```

<span id="rs-move" />

## 移动单个文件 [#移动单个文件]

```
# -*- coding: utf-8 -*-
# flake8: noqa
from qiniu import Auth
from qiniu import BucketManager

access_key = 'Access_Key'
secret_key = 'Secret_Key'

#初始化Auth状态
q = Auth(access_key, secret_key)

#初始化BucketManager
bucket = BucketManager(q)

#你要测试的空间， 并且这个key在你空间中存在
bucket_name = 'Bucket_Name'
key = 'python-logo.png'

#将文件从文件key 移动到文件key2，可以实现文件的重命名 可以在不同bucket移动
key2 = 'python-logo2.png'

ret, info = bucket.move(bucket_name, key, bucket_name, key2)
print(info)
assert ret == {}
```

<span id="rs-copy" />

## 复制单个文件 [#复制单个文件]

```
# -*- coding: utf-8 -*-
# flake8: noqa
from qiniu import Auth
from qiniu import BucketManager

access_key = 'Access_Key'
secret_key = 'Secret_Key'

#初始化Auth状态
q = Auth(access_key, secret_key)

#初始化BucketManager
bucket = BucketManager(q)

#你要测试的空间， 并且这个key在你空间中存在
bucket_name = 'Bucket_Name'
key = 'python-logo.png'

#将文件从文件key 复制到文件key2。 可以在不同bucket复制
key2 = 'python-logo2.png'

ret, info = bucket.copy(bucket_name, key, bucket_name, key2)
print(info)
assert ret == {}
```

<span id="rs-delete" />

## 删除单个文件 [#删除单个文件]

```
# -*- coding: utf-8 -*-
# flake8: noqa
from qiniu import Auth
from qiniu import BucketManager

access_key = 'Access_Key'
secret_key = 'Secret_Key'

#初始化Auth状态
q = Auth(access_key, secret_key)

#初始化BucketManager
bucket = BucketManager(q)

#你要测试的空间， 并且这个key在你空间中存在
bucket_name = 'Bucket_Name'
key = 'python-logo.png'

#删除bucket_name 中的文件 key
ret, info = bucket.delete(bucket_name, key)
print(info)
assert ret == {}
```

<span id="rs-delete-after-days" />

## 设置或更新文件生存时间 [#设置或更新文件生存时间]

```
# -*- coding: utf-8 -*-
# flake8: noqa

from qiniu import Auth
from qiniu import BucketManager

access_key = '...'
secret_key = '...'

#初始化Auth状态
q = Auth(access_key, secret_key)

#初始化BucketManager
bucket = BucketManager(q)

#你要测试的空间， 并且这个key在你空间中存在
bucket_name = 'Bucket_Name'
key = 'python-test.png'

#您要更新的生命周期
days = '5'

ret, info = bucket.delete_after_days(bucket_name, key, days)
print(info)
```

<span id="rs-chgm" />

## 修改文件存储类型 [#修改文件存储类型]

```
# -*- coding: utf-8 -*-
# flake8: noqa

from qiniu import Auth
from qiniu import BucketManager

access_key = '...'
secret_key = '...'

q = Auth(access_key, secret_key)

bucket = BucketManager(q)

bucket_name = 'Bucket_Name'

key = '...'

ret, info = bucket.change_type(bucket_name, key, 1) # 0 是标准存储，1 表示低频存储，2 表示归档存储，3 表示深度归档存储，4 表示归档直读存储

print(info)
```

## 修改资源元信息 [#修改资源元信息]

```
# -*- coding: utf-8 -*-
# flake8: noqa

from qiniu import Auth
from qiniu import BucketManager

access_key = '...'
secret_key = '...'

q = Auth(access_key, secret_key)

bucket = BucketManager(q)

bucket_name = 'Bucket_Name'

key = '...'

# 将一个文件的元信息修改为jpg
ret, info = bucket.change_mime(bucket_name, key, 'image/jpg')
print(info)
```

<span id="rs-batch" />

## 批量操作 [#批量操作]

```
# -*- coding: utf-8 -*-
# flake8: noqa

from qiniu import Auth
from qiniu import BucketManager,build_batch_rename
from qiniu import build_batch_copy
from qiniu import build_batch_move

access_key = '...'
secret_key = '...'

# 初始化Auth状态
q = Auth(access_key, secret_key)

# 初始化BucketManager
bucket = BucketManager(q)
keys = {'123.jpg':'123.jpg'}

# ops = build_batch_copy(bucket_name, keys, 'teest',force='true')
# ops = build_batch_move(bucket_name, keys, 'teest', force='true')
ops = build_batch_rename(bucket_name, keys,force='true')

ret, info = bucket.batch(ops)
print(ret)
print(info)
assert ret == {}
```

## 批量查询文件信息 [#批量查询文件信息]

```
# -*- coding: utf-8 -*-
"""
批量查询文件信息

/products/kodo/rs/0-batch
"""

from qiniu import build_batch_stat, Auth, BucketManager

access_key = ''

secret_key = ''

q = Auth(access_key, secret_key)

bucket = BucketManager(q)

bucket_name = ''

# 需要查询的文件名
keys = ['1.gif', '2.txt', '3.png', '4.html']

ops = build_batch_stat(bucket_name, keys)
ret, info = bucket.batch(ops)
print(info)
```

<span id="rs-batch-rename" />

## 批量重命名文件 [#批量重命名文件]

```
# -*- coding: utf-8 -*-
"""
批量重命名文件

/products/kodo/rs/0-batch
"""

from qiniu import build_batch_rename, Auth, BucketManager

access_key = ''

secret_key = ''

q = Auth(access_key, secret_key)

bucket = BucketManager(q)

bucket_name = ''

# force为true时强制同名覆盖, 字典的键为原文件，值为目标文件
ops = build_batch_rename(bucket_name, {'src_key1': 'target_key1', 'src_key2': 'target_key2'}, force='true')
ret, info = bucket.batch(ops)
print(info)
```

<span id="rs-batch-move" />

## 批量移动文件 [#批量移动文件]

```
# -*- coding: utf-8 -*-
"""
批量移动文件

/products/kodo/rs/0-batch
"""

from qiniu import build_batch_move, Auth, BucketManager

access_key = ''

secret_key = ''

q = Auth(access_key, secret_key)

bucket = BucketManager(q)

src_bucket_name = ''

target_bucket_name = ''

# force为true时强制同名覆盖, 字典的键为原文件，值为目标文件
ops = build_batch_move(src_bucket_name, {'src_key1': 'target_key1', 'src_key2': 'target_key2'}, target_bucket_name, force='true')
ret, info = bucket.batch(ops)
print(info)
```

## 批量删除文件 [#批量删除文件]

```
# -*- coding: utf-8 -*-
"""
批量删除文件

/products/kodo/rs/0-batch
"""

from qiniu import build_batch_delete, Auth, BucketManager

access_key = ''

secret_key = ''

q = Auth(access_key, secret_key)

bucket = BucketManager(q)

bucket_name = ''

keys = ['1.gif', '2.txt', '3.png', '4.html']

ops = build_batch_delete(bucket_name, keys)
ret, info = bucket.batch(ops)
print(info)
```

## 批量复制文件 [#批量复制文件]

```
# -*- coding: utf-8 -*-
"""
批量拷贝文件

/products/kodo/rs/0-batch
"""

from qiniu import build_batch_copy, Auth, BucketManager

access_key = ''

secret_key = ''

q = Auth(access_key, secret_key)

bucket = BucketManager(q)

src_bucket_name = ''

target_bucket_name = ''

# force为true时强制同名覆盖, 字典的键为原文件，值为目标文件
ops = build_batch_copy(src_bucket_name, {'src_key1': 'target_key1', 'src_key2': 'target_key2'}, target_bucket_name, force='true')
ret, info = bucket.batch(ops)
print(info)
```

## CDN 相关 [#cdn-相关]

* [文件刷新](/products/kodo/2-python#fusion-refresh-urls)
* [目录刷新](/products/kodo/2-python#fusion-refresh-dirs)
* [文件预取操作](/products/kodo/2-python#fusion-prefetch)
* [获取日志文件链接](/products/kodo/2-python#fusion-cdn_logs)
* [获取指定时间段域名流量](/products/kodo/2-python#fusion-cdn_flux)
* [获取指定时间段域名带宽](/products/kodo/2-python#fusion-cdn_bandwidth)

<span id="fusion-refresh-urls" />

### 刷新节点资源 [#刷新节点资源]

```
# -*- coding: utf-8 -*-
import qiniu
from qiniu import CdnManager

# 账户ak，sk
access_key = '...'
secret_key = '...'

auth = qiniu.Auth(access_key=access_key, secret_key=secret_key)
cdn_manager = CdnManager(auth)

# 需要刷新的文件链接
urls = [
    'http://aaa.example.com/a.gif',
    'http://bbb.example.com/b.jpg'
]

# 刷新链接
refresh_url_result = cdn_manager.refresh_urls(urls)
print(refresh_url_result)
```

<span id="fusion-refresh-dirs" />

### 刷新整个目录下的节点资源 [#刷新整个目录下的节点资源]

```
# -*- coding: utf-8 -*-
import qiniu
from qiniu import CdnManager

# 账户ak，sk
access_key = '...'
secret_key = '...'

auth = qiniu.Auth(access_key=access_key, secret_key=secret_key)
cdn_manager = CdnManager(auth)

# 需要刷新的目录链接
dirs = [
    'http://aaa.example.com/doc/img/',
    'http://bbb.example.com/doc/video/'
]

# 刷新链接
refresh_dir_result = cdn_manager.refresh_dirs(dirs)
```

<span id="fusion-prefetch" />

### 预取资源到 cdn 结点 [#预取资源到-cdn-结点]

```
# -*- coding: utf-8 -*-
"""
预取资源到cdn节点

/faq/products/cdn/6-the-significance-of-file-prefetching-and-operating-methods
"""

import qiniu
from qiniu import CdnManager

# 账户ak，sk
access_key = '...'
secret_key = '...'

auth = qiniu.Auth(access_key=access_key, secret_key=secret_key)
cdn_manager = CdnManager(auth)

# 需要刷新的文件链接
urls = [
    'http://aaa.example.com/doc/img/',
    'http://bbb.example.com/doc/video/'
]

# 刷新链接
refresh_dir_result = cdn_manager.prefetch_urls(urls)
```

<span id="fusion-cdn_logs" />

### 获取指定域名指定时间内的日志链接 [#获取指定域名指定时间内的日志链接]

```
# -*- coding: utf-8 -*-
"""
获取指定域名指定时间内的日志链接
"""
import qiniu
from qiniu import CdnManager

# 账户ak，sk
access_key = ''
secret_key = ''

auth = qiniu.Auth(access_key=access_key, secret_key=secret_key)
cdn_manager = CdnManager(auth)

log_date = '2017-07-20'

urls = [
    'a.example.com',
    'b.example.com'
]
ret, info = cdn_manager.get_log_list_data(urls, log_date)

print(ret)
print(info)
```

<span id="fusion-cdn_flux" />

## 获取指定域名指定时间段内的流量 [#获取指定域名指定时间段内的流量]

```
# -*- coding: utf-8 -*-

import qiniu
from qiniu import CdnManager

# 账户ak，sk
access_key = ''
secret_key = ''

auth = qiniu.Auth(access_key=access_key, secret_key=secret_key)
cdn_manager = CdnManager(auth)

startDate = '2017-07-20'

endDate = '2017-08-20'

granularity = 'day'

urls = [
    'a.example.com',
    'b.example.com'
]

# 获得指定域名流量
ret, info = cdn_manager.get_flux_data(urls, startDate, endDate, granularity)

print(ret)
print(info)
```

<span id="fusion-cdn_bandwidth" />

## 获取指定域名指定时间段内的带宽 [#获取指定域名指定时间段内的带宽]

```
# -*- coding: utf-8 -*-

import qiniu
from qiniu import CdnManager

# 账户ak，sk
access_key = ''
secret_key = ''

auth = qiniu.Auth(access_key=access_key, secret_key=secret_key)
cdn_manager = CdnManager(auth)

startDate = '2017-07-20'

endDate = '2017-08-20'

granularity = 'day'

urls = [
    'a.example.com',
    'b.example.com'
]

ret, info = cdn_manager.get_bandwidth_data(urls, startDate, endDate, granularity)

print(ret)
print(info)
```

## API 参考手册 [#api-参考手册]

* [对象存储 API 参考手册](/products/kodo/kodo-console-guide/0-an-overview-of-the-console)
* [数据处理 API 参考手册](/faq/dora)

## 常见问题 [#常见问题]

* 第二个参数 info 保留了请求响应的信息，失败情况下 ret 为 none ，将 info 打印出来，提交给我们。
* API 的使用 demo 可以参考 [单元测试](https://github.com/qiniu/python-sdk/blob/master/test_qiniu.py) 。
* 如果碰到 `ImportError: No module named requests.auth` 请安装 `requests` 。

## 相关资源 [#相关资源]

如果您有任何关于我们文档或产品的建议和想法，欢迎到我们的技术论坛参与讨论。

* [技术论坛](http://segmentfault.com/qiniu) - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
* [提交工单](https://support.qiniu.com/tickets/new) - 如果您的问题不适合在论坛讨论或得不到回答，您也可以提交一个工单，技术支持人员会尽快回复您
* [博客](http://blog.qiniu.com/) - 这里会持续发布市场活动和技术分享文章
* [微博](http://weibo.com/qiniutek)
* [常见问题](https://support.qiniu.com/question)

## 贡献代码 [#贡献代码]

1. Fork
2. 创建您的特性分支 git checkout -b my-new-feature
3. 提交您的改动 git commit -am ‘Added some feature’
4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature
5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

## 许可证 [#许可证]

Copyright © 2014 qiniu.com

基于 MIT 协议发布:

* [www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)


# C/C++ SDK (/products/kodo/3-cpp)



最近更新时间: 2024-11-21 17:23:10

本 SDK 使用符合 C89 标准的 C 语言实现。由于 C 语言的普适性，原则上此 SDK 可以跨所有主流平台，不仅可以直接在 C 和 C++ 的工程中使用，也可以用于与 C 语言交互性较好的语言中，例如 C#（使用 P/Invoke 交互）、Java（使用 JNI 交互）、Lua 等。

本开发指南假设开发者使用的开发语言是 C/C++，C-SDK 以开源方式提供。开发者可以从本文档提供的下载地址查看和下载 SDK 的源代码，并按自己的工程现状进行合理使用，例如编译为静态库或者动态库后进行链接，或者直接将 SDK 的源代码加入到自己的工程中一起编译，以保持工程设置的简单性。

* [C/C++ SDK 源码地址](https://github.com/qiniu/c-sdk)
* [C/C++ SDK Demo](https://github.com/qiniu/c-sdk/tree/master/examples)

从 v5.0.0 版本开始，我们对 SDK 的内容进行了精简。所有管理操作，\
例如创建/删除 bucket，为 bucket 绑定域名 (publish)，设置数据处理的样式分隔符，新增数据处理样式等都去除了，建议统一到七牛 [开发者平台](https://portal.qiniu.com/) 完成。另外，此前服务端还有自己独有的上传 API，现在也推荐统一成基于客户端上传的工作方式。

从内容上来说，C-SDK 主要包含如下几方面的内容：

* 公共部分，所有情况下都用到：qiniu/base.c、qiniu/conf.c、qiniu/http.c
* 客户端上传文件：qiniu/base\_io.c、qiniu/io.c
* 客户端断点续上传：qiniu/base\_io.c、qiniu/io.c、qiniu/multipart\_upload.c
* 数据处理：qiniu/fop.c
* 服务端操作：qiniu/auth\_mac.c（授权），qiniu/rs.c（资源管理，上传凭证 uptoken/下载凭证 dntoken 生成）
* cdn 相关功能：qiniu/cdn.c

## 安装 [#安装]

C-SDK 使用 [cURL](http://curl.haxx.se/) 进行网络相关操作。无论是作为客户端还是服务端，都需要依赖 cURL。如果作为服务端，C-SDK 因为需要用 HMAC 进行数字签名做授权（简称签名授权），所以依赖了 [OpenSSL](http://www.openssl.org/) 库。C-SDK 并没有带上这 2 个外部库，因此在使用 C-SDK 之前，首先确认您的当前开发环境中是否已经安装了这 2 个外部库，然后检查这 2 个外部库的头文件目录和库文件目录是否都已经加入到了项目工程的设置。

在主流的 \*nix 环境下，通常 [cURL](http://curl.haxx.se/) 和 [OpenSSL](http://www.openssl.org/) 都已经随系统默认安装到了 /usr/include 和 /usr/lib 目录下。如果您的系统还没有这些库，请自行安装。

如果你使用 gcc 进行编译，服务端典型的链接选项是：-lcurl -lssl -lcrypto -lm，客户端则是：-lcurl -lm。

如果在项目构建过程中出现环境相关的编译错误和链接错误，请确认这些选项是否都已经正确配置，以及所依赖的库是否都已经正确安装。

**ACCESS\_KEY 和 SECRET\_KEY**

如果你的服务端采用 C-SDK，那么使用 C-SDK 前，您需要拥有一对有效的 AccessKey 和 SecretKey 用来进行签名授权。可以通过如下步骤获得：

1. 点击 [注册 🔗](https://portal.qiniu.com/signup) 开通七牛开发者帐号
2. 登录七牛开发者平台，点击 [个人中心](https://portal.qiniu.com/user/key) 查看 Access Key 和 Secret Key

C-SDK 的 conf.h 文件中声明了对应的两个变量：QINIU\_ACCESS\_KEY 和 QINIU\_SECRET\_KEY。您需要在启动程序之初初始化这两个变量为七牛颁发的 AccessKey 和 SecretKey。

**初始化**

对于服务端而言，常规程序流程是：

```
Qiniu_Client client;

QINIU_ACCESS_KEY = "<Please apply your access key>";
QINIU_SECRET_KEY = "<Dont send your secret key to anyone>";

Qiniu_Servend_Init(-1);                            /* 全局初始化函数，整个进程只需要调用一次 */
Qiniu_Client_InitMacAuth(&client, 1024, NULL);     /* HTTP客户端初始化。HTTP客户端是线程不安全的，不要在多个线程间共用 */
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True); /* 启用区域自动查询，无需手动设置区域 */

...

Qiniu_Client_Cleanup(&client);                 /* 每个HTTP客户端使用完后释放 */
Qiniu_Servend_Cleanup();                       /* 全局清理函数，只需要在进程退出时调用一次 */
```

对于客户端而言，常规程序流程是：

```
Qiniu_Client client;

Qiniu_Global_Init(-1);                             /* 全局初始化函数，整个进程只需要调用一次 */
Qiniu_Client_InitNoAuth(&client, 1024);            /* HTTP客户端初始化。HTTP客户端是线程不安全的，不要在多个线程间共用 */
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True); /* 启用区域自动查询，无需手动设置区域 */

...

Qiniu_Client_Cleanup(&client);          /* 每个HTTP客户端使用完后释放 */
Qiniu_Global_Cleanup();                 /* 全局清理函数，只需要在进程退出时调用一次 */
```

两者主要的区别在于：

* 客户端没有 QINIU\_ACCESS\_KEY、QINIU\_SECRET\_KEY 变量（不需要初始化）。
* 客户端没有签名授权，所以初始化 Qiniu\_Client 对象应该用 Qiniu\_Client\_InitNoAuth 而不是 Qiniu\_Client\_InitMacAuth。
* 客户端初始化／清理用 Qiniu\_Global\_Init/Cleanup，而服务端用 Qiniu\_Servend\_Init/Cleanup 这对函数。

## 内存管理 [#内存管理]

在 C-SDK 中，有一些函数会涉及到内存的动态分配。这些函数的一惯处理方式是在函数内部申请内存，并以指针的形式直接返回。这就要求函数调用者在得到指针后，需要在恰当的时机去释放这些内存。对于特殊的结构体，C-SDK 都会提供特定的函数来释放内存，例如 Qiniu\_Buffer 提供了 Qiniu\_Buffer\_Cleanup 函数。而对于其他基本数据类型的指针，则由 Qiniu\_Free 函数来负责释放不再使用的内存。

## HTTP 客户端 [#http-客户端]

在 C-SDK 中，HTTP 客户端叫 Qiniu\_Client。在某些语言环境中，这个类是线程安全的，多个线程可以共享同一份实例，但在 C-SDK 中它被设计为线程不安全的。一个重要的原因是我们试图简化内存管理的负担。HTTP 请求结果的生命周期被设计成由 Qiniu\_Client 负责，在下一次请求时会自动释放上一次 HTTP 请求的结果。如果某个 HTTP 请求结果的数据需要长期使用，建议您复制一份，如：

```
void stat(Qiniu_Client* client, const char* bucket, const char* key) {
    Qiniu_RS_StatRet ret;
    Qiniu_Error err = Qiniu_RS_Stat(client, &ret, bucket, key);
    if (err.code != 200) {
        debug(client, err);
        return;
    }
    printf("hash: %s, fsize: %lld, mimeType: %s\n", ret.hash, ret.fsize, ret.mimeType);
}
```

这个例子中，Qiniu\_RS\_Stat 请求返回了 Qiniu\_Error 和 Qiniu\_RS\_StatRet 两个结构体。其中的 Qiniu\_Error 类型如下：

```
typedef struct _Qiniu_Error {
    int code;
    const char* message;
} Qiniu_Error;
```

Qiniu\_RS\_StatRet 类型如下：

```
typedef struct _Qiniu_RS_StatRet {
    const char* hash;
    const char* mimeType;
    Qiniu_Int64 fsize;
    Qiniu_Int64 putTime;
    Qiniu_Int64 type;
} Qiniu_RS_StatRet;
```

\*\*注意：\*\*Qiniu\_Error.message、Qiniu\_RS\_StatRet.hash、Qiniu\_RS\_StatRet.mimeType 都声明为 const char\* 类型，是个只读字符串，并不管理字符串内容的生命周期。\
这些字符串什么时候失效？下次 Qiniu\_Client 发生网络 API 请求时失效。如果您需要长久使用，建议您复制一份，如：

```
hash = strdup(ret.hash);
```

## 错误处理与调试 [#错误处理与调试]

在 HTTP 请求出错的时候，C-SDK 统一返回了一个 Qiniu\_Error 结构体：

```
typedef struct _Qiniu_Error {
    int code;
    const char* message;
} Qiniu_Error;
```

即一个错误码和对应的描述消息。这个错误码有可能是 cURL 的错误码，表示请求发送环节发生了意外，或者是一个 HTTP 错误码，表示请求发送正常，服务器端处理请求后返回了 HTTP 错误码。

如果一切正常，code 应该是 200，即 HTTP 的 OK 状态码。如果不是 200，则需要对 code 值进行相应分析。对于低于 200 的值，可以查看 [cURL 错误码](http://curl.haxx.se/libcurl/c/libcurl-errors.html) ，否则应查看七牛 [HTTP 状态码](/products/kodo/3-cpp) 。

如果 message 指示的信息还不够友好，也可以尝试把整个 HTTP 返回包打印出来看看：

```
void debug(Qiniu_Client* client, Qiniu_Error err)
{
    printf("\nerror code: %d, message: %s\n", err.code, err.message);
    printf("respose header:\n%s", Qiniu_Buffer_CStr(&client->respHeader));
    printf("respose body:\n%s", Qiniu_Buffer_CStr(&client->b));
}
```

<span id="upload-file" />

<span id="form-upload-file" />

## 文件上传 [#文件上传]

* [上传流程](/products/kodo/3-cpp#%E4%B8%8A%E4%BC%A0%E6%B5%81%E7%A8%8B)
* [上传凭证](/products/kodo/3-cpp#%E4%B8%8A%E4%BC%A0%E5%87%AD%E8%AF%81)
  * [简单上传凭证](/products/kodo/3-cpp#simple-uptoken)
    * [覆盖上传凭证](/products/kodo/3-cpp#overwrite-uptoken)
    * [自定义上传回复凭证](/products/kodo/3-cpp#returnbody-uptoken)
    * [带回调业务服务器的凭证](/products/kodo/3-cpp#%E5%B8%A6%E5%9B%9E%E8%B0%83%E4%B8%9A%E5%8A%A1%E6%9C%8D%E5%8A%A1%E5%99%A8%E7%9A%84%E5%87%AD%E8%AF%81)
    * [带数据处理的凭证](/products/kodo/3-cpp#%E5%B8%A6%E6%95%B0%E6%8D%AE%E5%A4%84%E7%90%86%E7%9A%84%E5%87%AD%E8%AF%81)
    * [带自定义参数的凭证](/products/kodo/3-cpp#%E5%B8%A6%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%82%E6%95%B0%E7%9A%84%E5%87%AD%E8%AF%81)
    * [综合上传凭证](/products/kodo/3-cpp#%E7%BB%BC%E5%90%88%E4%B8%8A%E4%BC%A0%E5%87%AD%E8%AF%81)
* [服务器直传](/products/kodo/3-cpp#server-upload)
  * [构建配置流程](/products/kodo/3-cpp#%E6%9E%84%E5%BB%BA%E9%85%8D%E7%BD%AE%E6%B5%81%E7%A8%8B)
    * [文件上传（表单方式）](/products/kodo/3-cpp#%E6%96%87%E4%BB%B6%E4%B8%8A%E4%BC%A0%E8%A1%A8%E5%8D%95%E6%96%B9%E5%BC%8F)
    * [文件分片上传（断点续传）](/products/kodo/3-cpp#%E6%96%87%E4%BB%B6%E5%88%86%E7%89%87%E4%B8%8A%E4%BC%A0%E6%96%AD%E7%82%B9%E7%BB%AD%E4%BC%A0)
    * [解析自定义回复内容](/products/kodo/3-cpp#%E8%A7%A3%E6%9E%90%E8%87%AA%E5%AE%9A%E4%B9%89%E5%9B%9E%E5%A4%8D%E5%86%85%E5%AE%B9)
    * [业务服务器验证存储服务回调](/products/kodo/3-cpp#%E4%B8%9A%E5%8A%A1%E6%9C%8D%E5%8A%A1%E5%99%A8%E9%AA%8C%E8%AF%81%E5%AD%98%E5%82%A8%E6%9C%8D%E5%8A%A1%E5%9B%9E%E8%B0%83)

## 上传流程 [#上传流程]

在七牛云存储中，整个上传流程大致分为以下几步：

1. 业务服务器颁发 [上传凭证](/products/kodo/development-guidelines/security/2-upload-token) 给客户端（终端用户）
2. 客户端凭借上传凭证上传文件到七牛
3. 在七牛获得完整数据后，发起一个 HTTP 请求回调到业务服务器
4. 业务服务器保存相关信息，并返回一些信息给七牛
5. 七牛原封不动地将这些信息转发给客户端（终端用户）

\*\*注意：\*\*回调到业务服务器的过程是可选的，它取决于业务服务器颁发的上传凭证。如果没有回调，七牛会返回一些标准的信息（例如文件的 hash）给客户端。\
如果上传发生在业务服务器，以上流程简化为：

1. 业务服务器生成上传凭证
2. 凭借上传凭证上传文件到七牛
3. 后续工作，例如保存一些相关信息

## 上传凭证 [#上传凭证]

上传凭证实际上是用 AccessKey/SecretKey 进行数字签名的上传策略 Qiniu\_RS\_PutPolicy，它控制着整个上传流程的行为。具体上传策略参数的解释可见 [上传凭证](/products/kodo/development-guidelines/security/2-upload-token)

```
typedef struct _Qiniu_RS_PutPolicy {
    const char *scope;
    const char *saveKey;
    Qiniu_Uint32 isPrefixalScope;
    const char *callbackUrl;
    const char *callbackHost;
    const char *callbackBody;
    const char *callbackBodyType;
    const char *callbackFetchKey;
    const char *returnUrl;
    const char *returnBody;
    const char *endUser;
    const char *persistentOps;
    const char *persistentNotifyUrl;
    const char *persistentPipeline;
    const char *persistentWorkflowTemplateID;
    const char *mimeLimit;
    Qiniu_Uint64 fsizeLimit;
    Qiniu_Uint64 fsizeMin;
    Qiniu_Uint32 detectMime;
    Qiniu_Uint32 insertOnly;
    Qiniu_Uint32 expires;
    Qiniu_Uint32 deleteAfterDays;
    Qiniu_Uint32 fileType;
    Qiniu_Uint32 persistentType;
} Qiniu_RS_PutPolicy;
```

在构建上传凭证之前，我们首先要定义鉴权对象 Qiniu\_mac

```
Qiniu_Mac mac;
mac.accessKey = "your access key";
mac.secretKey = "your secret key";
```

<span id="simple-uptoken" />

### 简单上传的凭证 [#简单上传的凭证]

最简单的上传凭证只需要 `AccessKey` ， `SecretKey` 和 `Bucket` 就可以。

```
//简单上传凭证
char *bucket="your bucket name";
Qiniu_RS_PutPolicy putPolicy;
Qiniu_Zero(putPolicy);
putPolicy.scope = bucket;
char *uptoken = Qiniu_RS_PutPolicy_Token(&putPolicy, &mac);
printf("simple:\t%s\n\n", uptoken);
Qiniu_Free(uptoken);
```

默认情况下，在不指定上传凭证的有效时间情况下，默认有效期为 1 个小时。也可以自行指定上传凭证的有效期，例如：

```
//自定义凭证有效期（示例2小时，expires单位为秒，为上传凭证的有效时间）
Qiniu_RS_PutPolicy putPolicy;
Qiniu_Zero(putPolicy);
putPolicy.scope = bucket;
putPolicy.expires = 7200; //单位秒
char *uptoken = Qiniu_RS_PutPolicy_Token(&putPolicy, &mac);
printf("returnBody:\t%s\n\n", uptoken);
```

<span id="overwrite-uptoken" />

### 覆盖上传的凭证 [#覆盖上传的凭证]

覆盖上传除了需要 `简单上传` 所需要的信息之外，还需要想进行覆盖的文件名称，这个文件名称同时可是客户端上传代码中指定的文件名，两者必须一致。

```
//覆盖上传
Qiniu_RS_PutPolicy putPolicy;
Qiniu_Zero(putPolicy);
char *keyToOverwrite = "qiniu.png";
putPolicy.scope = Qiniu_String_Concat3(bucket, ":",keyToOverwrite);
char *uptoken = Qiniu_RS_PutPolicy_Token(&putPolicy, &mac);
printf("overwrite:\t%s\n\n", uptoken);
```

<span id="returnbody-uptoken" />

### 自定义上传回复的凭证 [#自定义上传回复的凭证]

默认情况下，文件上传到七牛之后，在没有设置 `returnBody` 或者 `回调` 相关的参数情况下，七牛返回给上传端的回复格式为 `hash` 和 `key` ，例如：

```
{"hash":"Ftgm-CkWePC9fzMBTRNmPMhGBcSV","key":"qiniu.jpg"}
```

有时候我们希望能自定义这个返回的 JSON 格式的内容，可以通过设置 `returnBody` 参数来实现，在 `returnBody` 中，我们可以使用七牛支持的 [魔法变量](/products/kodo/development-guidelines/upload-types/0-vars#%E9%AD%94%E6%B3%95%E5%8F%98%E9%87%8F) 和 [自定义变量](/products/kodo/development-guidelines/upload-types/0-vars#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%98%E9%87%8F) 。

```
//自定义返回值
Qiniu_RS_PutPolicy putPolicy;
Qiniu_Zero(putPolicy);
putPolicy.scope = bucket;
putPolicy.returnBody = "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"fsize\":$(fsize),\"bucket\":\"$(bucket)\",\"name\":\"$(x:name)\"}";
char *uptoken = Qiniu_RS_PutPolicy_Token(&putPolicy, &mac);
printf("returnBody:\t%s\n\n", uptoken);
```

则文件上传到七牛之后，收到的回复内容如下：

```
{"key":"qiniu.jpg","hash":"Ftgm-CkWePC9fzMBTRNmPMhGBcSV","bucket":"if-bc","fsize":39335,"name":"qiniu"}
```

### 带回调业务服务器的凭证 [#带回调业务服务器的凭证]

上面生成的 `自定义上传回复` 的上传凭证适用于上传端（无论是客户端还是服务端）和七牛服务器之间进行直接交互的情况下。在客户端上传的场景之下，有时候客户端需要在文件上传到七牛之后，从业务服务器获取相关的信息，这个时候就要用到七牛的上传回调及相关回调参数的设置。

```
Qiniu_RS_PutPolicy putPolicy;
Qiniu_Zero(putPolicy);
putPolicy.scope = bucket;
putPolicy.callbackUrl = "http://api.example.com/upload/callback";
putPolicy.callbackBodyType = "application/json";
putPolicy.callbackBody = "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"fsize\":$(fsize),\"bucket\":\"$(bucket)\",\"name\":\"$(x:name)\"}";
char *uptoken = Qiniu_RS_PutPolicy_Token(&putPolicy, &mac);
printf("callback(json):\t%s\n\n", uptoken);
```

在使用了上传回调的情况下，客户端收到的回复就是业务服务器响应七牛的 JSON 格式内容。\
通常情况下，我们建议使用 `application/json` 格式来设置 `callbackBody` ，保持数据格式的统一性。实际情况下， `callbackBody` 也支持 `application/x-www-form-urlencoded` 格式来组织内容，这个主要看业务服务器在接收到 `callbackBody` 的内容时如何解析。例如：

```
Qiniu_RS_PutPolicy putPolicy;
Qiniu_Zero(putPolicy);
putPolicy.scope = bucket;
putPolicy.callbackUrl = "http://api.example.com/upload/callback";
//putPolicy.callbackBodyType = "application/json";
putPolicy.callbackBody ="key=$(key)&hash=$(etag)&bucket=$(bucket)&fsize=$(fsize)&name=$(x:name)" ;
char *uptoken = Qiniu_RS_PutPolicy_Token(&putPolicy, &mac);
printf("callback(json):\t%s\n\n", uptoken);
```

### 带数据处理的凭证 [#带数据处理的凭证]

七牛支持在文件上传到七牛之后，立即对其进行多种指令的数据处理，这个只需要在生成的上传凭证中指定相关的处理参数即可。

```
//持久化数据处理的上传凭证
char *saveMp4Entry = Qiniu_String_Concat3(bucket, ":", "avthumb_test_target.mp4");
char *saveMp4EntryEncoded = Qiniu_String_Encode(saveMp4Entry);

char *saveJpgEntry = Qiniu_String_Concat3(bucket, ":", "vframe_test_target.jpg");
char *saveJpgEntryEncoded = Qiniu_String_Encode(saveJpgEntry);

Qiniu_Free(saveMp4Entry);
Qiniu_Free(saveJpgEntry);

char *avthumbMp4Fop = Qiniu_String_Concat2("avthumb/mp4|saveas/", saveMp4EntryEncoded);
char *vframeJpgFop = Qiniu_String_Concat2("vframe/jpg/offset/1|saveas/", saveJpgEntryEncoded);

Qiniu_Free(saveMp4EntryEncoded);
Qiniu_Free(saveJpgEntryEncoded);

char *fops[] = {avthumbMp4Fop, vframeJpgFop};
char *persistentFops = Qiniu_String_Join(";", fops, 2);

putPolicy.scope = bucket;
putPolicy.persistentPipeline = "sdktest";
putPolicy.persistentNotifyUrl = "http://api.example.com/pfop/notify";
putPolicy.persistentOps = persistentFops;
putPolicy.persistentType = 0; // 任务类型：0: 普通任务 1: 闲时任务（一旦指定闲时任务，就不能指定 persistentPipeline）

uptoken = Qiniu_RS_PutPolicy_Token(&putPolicy, &mac);
printf("persistent:\t%s\n\n", uptoken);
```

* 队列 pipeline 请参阅 [创建私有队列](https://portal.qiniu.com/dora/media-gate/pipeline) ；转码操作具体参数请参阅 [音视频转码](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) ；saveas 请参阅 [处理结果另存](/products/dora/processing-mechanism/0-processing-results-save-saveas) 。
* 闲时任务的功能介绍、使用场景、定价，详见 [闲时任务策略说明](/products/dora/processing-mechanism/persist/2-idle-time-task-strategy) 。

也可以支持使用工作流模版替代数据处理指令。工作流模板是预先编排好的一系列媒体处理流程（如转码、截图、视频拼接等各类处理），登录 [对象存储控制台](https://portal.qiniu.com/kodo/bucket) 进行创建，详情参考 [工作流模板操作指南](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template) ， `persistentWorkflowTemplateID` 对应工作流模板列表的 `名称` 字段

```
putPolicy.scope = bucket;
putPolicy.persistentPipeline = "sdktest";
putPolicy.persistentNotifyUrl = "http://api.example.com/pfop/notify";
putPolicy.persistentWorkflowTemplateID = "tempname";
putPolicy.persistentType = 0; // 任务类型：0: 普通任务 1: 闲时任务（一旦指定闲时任务，就不能指定 persistentPipeline）

uptoken = Qiniu_RS_PutPolicy_Token(&putPolicy, &mac);
printf("persistent:\t%s\n\n", uptoken);
```

* 需要注意的是， `persistentWorkflowTemplateID` 和 `persistentOps` 两个参数只能二选一。

### 带自定义参数的凭证 [#带自定义参数的凭证]

存储支持客户端上传文件的时候定义一些自定义参数，这些参数可以在 `returnBody` 和 `callbackBody` 里面和七牛内置支持的魔法变量（即系统变量）通过相同的方式来引用。这些自定义的参数名称必须以 `x:`开头。例如客户端上传的时候指定了自定义的参数 `x:name` 和 `x:age` 分别是 `string` 和 `int` 类型。那么可以通过下面的方式引用：

```
returnBody: '{"key":"$(key)","hash":"$(etag)","fsize":$(fsize),"bucket":"$(bucket)","name":"$(x:name)","age":$(x:age)}'
}
```

或者

```
callbackBody: '{"key":"$(key)","hash":"$(etag)","fsize":$(fsize),"bucket":"$(bucket)","name":"$(x:name)","age":$(x:age)}',
}
```

### 综合上传凭证 [#综合上传凭证]

上面的生成上传凭证的方法，都是通过设置 [上传策略 🔗](/products/kodo/development-guidelines/security/1-put-policy) 相关的参数来支持的，这些参数可以通过不同的组合方式来满足不同的业务需求，可以灵活地组织你所需要的上传凭证。

<span id="server-upload" />

## 服务端直传 [#服务端直传]

服务端直传是指客户利用七牛服务端 SDK 从服务端直接上传文件到七牛云，交互的双方一般都在机房里面，所以服务端可以自己生成上传凭证，然后利用 SDK 中的上传逻辑进行上传，最后从七牛云获取上传的结果，这个过程中由于双方都是业务服务器，所以很少利用到上传回调的功能，而是直接自定义 `returnBody` 来获取自定义的回复内容。

### 构建配置流程 [#构建配置流程]

存储支持空间创建在不同的区域，并且支持 http 和 https 上传。\
在使用七牛的 C-SDK 中的 `Qiniu_Client_EnableAutoQuery(&client, Qiniu_True)` 函数可以开启 `client` 的区域自动检测功能，参数 `Qiniu_True` 代表使用 https 方式上传。此外也可以手动指定区域，通过使用 `Qiniu_Region *region = Qiniu_Use_Region(regionId, Qiniu_True)` 函数可以生成对应的上传空间到 `region` 对象，参数 `regionId` 为七牛区域 ID 字符串，参数 `Qiniu_True` 代表使用 https 方式上传。然后调用 `Qiniu_Client_SpecifyRegion(&client, region)` 方法将 `region` 对象设置到 `client` 上，必须注意，在 `client` 被使用完毕后，需要额外调用 `Qiniu_Region_Free(region)` 回收 `region` 对象，否则会造成内存泄漏。

其中关于 `Region` 对象和区域的关系如下：

| 区域      | 对应函数                                        |
| ------- | ------------------------------------------- |
| 华东-浙江   | `Qiniu_Use_Region("z0", Qiniu_True)`        |
| 华北-河北   | `Qiniu_Use_Region("z1", Qiniu_True)`        |
| 华南-广东   | `Qiniu_Use_Region("z2", Qiniu_True)`        |
| 北美-洛杉矶  | `Qiniu_Use_Region("na0", Qiniu_True)`       |
| 亚太-新加坡  | `Qiniu_Use_Region("as0", Qiniu_True)`       |
| 华东-浙江 2 | `Qiniu_Use_Region("cn-east-2", Qiniu_True)` |

### 文件上传（表单方式） [#文件上传表单方式]

最简单的就是上传本地文件，直接指定文件的完整路径即可上传。

```
Qiniu_Global_Init(-1);

Qiniu_Mac mac;
mac.accessKey = "your access key";
mac.secretKey = "your secret key";

char *bucket = "your bucket name";
char *key = "qiniu.mp4";
char *localFile = "/Users/jemy/Documents/qiniu.mp4";

Qiniu_Io_PutRet putRet;
Qiniu_Client client;
Qiniu_RS_PutPolicy putPolicy;
Qiniu_Io_PutExtra putExtra;
Qiniu_Zero(putPolicy);
Qiniu_Zero(putExtra);

putPolicy.scope = bucket;

char *uptoken = Qiniu_RS_PutPolicy_Token(&putPolicy, &mac);

Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_Io_PutFile(&client, &putRet, uptoken, key, localFile, &putExtra);
if (error.code != 200) {
  printf("upload file %s:%s error.\n", bucket, key);
  debug_log(&client, error);
} else {
  /*200, 正确返回了, 你可以通过statRet变量查询一些关于这个文件的信息*/
  printf("upload file %s:%s success.\n\n", bucket, key);
  printf("key:\t%s\n",putRet.key);
  printf("hash:\t%s\n", putRet.hash);
}
Qiniu_Free(uptoken);
Qiniu_Client_Cleanup(&client);
```

<span id="upload-resumable" />

<span id="resume-upload-file" />

### 文件分片上传（断点续传） [#文件分片上传断点续传]

除了基本的上传外，七牛还支持将文件切成若干块。可以选择分片上传版本，推荐 Qiniu\_Multipart\_PutFile，表示 [分片上传 v2 版](/products/kodo/rs/multipartupload-interface) ，Qiniu\_Rio\_PutFile，表示 [分片上传 v1 版](/products/kodo/rs/shard-to-upload) 。\
断点续上传、分块上传的基本样例：

分片上传 v2 版 （v7.1.0 之上版本支持）

```
int resumable_upload(Qiniu_Client* client, char* uptoken, const char* key, const char* localFile, Qiniu_MultipartUpload_Result* putRet) {
    Qiniu_Error err;
    Qiniu_Recorder recorder;
    err = Qiniu_FileSystem_Recorder_New("/tmp", &recorder);
    if (err.code != 200) {
        return err.code;
    }
    Qiniu_Multipart_PutExtra extra;
    Qiniu_Zero(extra);
    extra.recorder = &recorder; // 支持断点续传
    extra.partSize = 4 << 20 // 分片上传 v2 支持自定义分片大小，公有云片的大小范围在 1MB ~ 1GB 。
    err = Qiniu_Multipart_PutFile(client, uptoken, key, localFile, &extra, putRet);
    recorder.free(&recorder);
    return err.code;
}
```

相比普通上传，断点续上传代码没有变复杂。基本上就只是将 Qiniu\_Io\_PutExtra 改为 Qiniu\_Multipart\_PutExtra，Qiniu\_Io\_PutFile 改为 Qiniu\_Multipart\_PutFile。

实际上 Qiniu\_Multipart\_PutFile 多了不少配置项，其中最重要的是：recorder，它被用来设置断点的存储方式，例如可以用 Qiniu\_FileSystem\_Recorder\_New 来创建基于文件系统的断点存储，你也可以基于 Qiniu\_Recorder 对象定义自己的断点存储方式。

分片上传 v1 版

```
int resumable_upload(Qiniu_Client* client, char* uptoken, const char* key, const char* localFile) {
    Qiniu_Error err;
    Qiniu_Recorder recorder;
    err = Qiniu_FileSystem_Recorder_New("/tmp", &recorder);
    if (err.code != 200) {
        return err.code;
    }
    Qiniu_Rio_PutExtra extra;
    Qiniu_Zero(extra);
    extra.bucket = bucket;
    extra.recorder = &recorder; // 支持断点续传
    err = Qiniu_Rio_PutFile(client, NULL, uptoken, key, localFile, &extra);
    recorder.free(&recorder);
    return err.code;
}
```

### 解析自定义回复内容 [#解析自定义回复内容]

有些情况下，七牛返回给上传端的内容不是默认的 `hash` 和 `key` 形式，这种情况下，可能出现在自定义 `returnBody` 或者自定义了 `callbackBody` 的情况下，前者一般是服务端直传的场景，而后者则是接受上传回调的场景，这两种场景之下，都涉及到需要将自定义的回复进行内容解析，一般建议在交互过程中，都采用 `JSON` 的方式，这样处理起来方法比较一致。

### 业务服务器验证存储服务回调 [#业务服务器验证存储服务回调]

在上传策略里面设置了上传回调相关参数的时候，七牛在文件上传到服务器之后，会主动地向 `callbackUrl` 发送 POST 请求的回调，回调的内容为 `callbackBody` 模版所定义的内容，如果这个模版里面引用了 [魔法变量](/products/kodo/development-guidelines/upload-types/0-vars#%E9%AD%94%E6%B3%95%E5%8F%98%E9%87%8F) 或者 [自定义变量](/products/kodo/development-guidelines/upload-types/0-vars#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%98%E9%87%8F) ，那么这些变量会被自动填充对应的值，然后在发送给业务服务器。

**注意** ：业务端服务器回调鉴权的 Content-Type 类型应该与上传策略中指定的 callbackBodyType 相同，默认为 application/x-www-form-urlencoded，当 Content-Type 为 application/x-www-form-urlencoded 时，签名内容必须包括请求内容。当 Content-Type 为 application/json 时，签名内容不包括请求内容。

业务服务器在收到来自七牛的回调请求的时候，可以根据请求头部的 `Authorization` 字段来进行验证，查看该请求是否是来自七牛的未经篡改的请求,具体可以参考七牛的 [回调鉴权](/faq/kodo/image-storage-common-problems/1376-seven-cattle-image-storage-instruction-manuals) 。

## 下载文件 [#下载文件]

* [公开空间](/products/kodo/3-cpp#%E5%85%AC%E5%BC%80%E7%A9%BA%E9%97%B4)
* [私有空间](/products/kodo/3-cpp#%E7%A7%81%E6%9C%89%E7%A9%BA%E9%97%B4)

文件下载分为公开空间的文件下载和私有空间的文件下载。

## 公开空间 [#公开空间]

每个 bucket 都会绑定一个或多个域名 (domain)。如果这个 bucket 是公开的，那么该 bucket 中的所有文件可以通过一个公开的下载 url 访问：

```
http://domain/key
```

其中 `domain` 是 bucket 对应的域名。七牛云存储为每一个 bucket 提供一个默认域名。默认域名可以到 [七牛开发者平台](https://portal.qiniu.com/) 中的存储空间查询。

假设某个 bucket 既绑定了七牛的二级域名，如：hello.qiniudn.com，也绑定了自定义域名（需要备案），如：hello.com。那么该 bucket 中 key 为 test.mp4 的文件可以通过 `http://hello.qiniudn.com/qiniu.mp4` 或 `http://hello.com/qiniu.mp4` 中任意一个 url 进行访问。

<span id="private-get" />

<span id="download-private" />

## 私有空间 [#私有空间]

如果某个 bucket 是私有的，那么这个 bucket 中的所有文件只能通过一个临时有效的 downloadUrl 访问：

```
http://domain/key?e=<deadline>&token=<dntoken>
```

其中 `dntoken` 是由业务服务器签发的一个临时 [下载凭证](/products/kodo/development-guidelines/security/0-download-token) ， `deadline` 是其有效期。下载凭证不需要单独生成，C-SDK 提供了生成完整 downloadUrl 的方法（包含了 dntoken），示例代码如下：

```
char* downloadUrl(const char* domain, const char* key, Qiniu_Mac* mac) {

    char* url = 0;
    char* baseUrl = 0;

    Qiniu_RS_GetPolicy getPolicy;
    Qiniu_Zero(getPolicy);

    baseUrl = Qiniu_RS_MakeBaseUrl(domain, key);
    url = Qiniu_RS_GetPolicy_MakeRequest(&getPolicy, baseUrl, mac);
    Qiniu_Free(baseUrl);
    return url;
}
```

生成 downloadUrl 后，服务端下发 downloadUrl 给客户端。客户端收到 downloadUrl 后，和公有资源类似，直接用任意的 HTTP 客户端就可以下载该资源了。需要注意的是，在 downloadUrl 失效却还没有完成下载时，需要重新向服务器申请授权。

## 资源管理 [#资源管理]

资源管理包括的主要功能有：\
资源管理包括对存储在七牛云存储上的文件进行查看、删除、复制和移动处理。同时七牛云存储也支持对文件进行相应的批量操作。所有操作都会返回一个 Qiniu\_Error 的结构体，用于记录本次操作的成功／失败信息。

* [获取文件信息](/products/kodo/3-cpp#%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E4%BF%A1%E6%81%AF)
* [修改文件 MimeType](/products/kodo/3-cpp#%E4%BF%AE%E6%94%B9%E6%96%87%E4%BB%B6-mimetype)
* [修改文件存储类型](/products/kodo/3-cpp#%E4%BF%AE%E6%94%B9%E6%96%87%E4%BB%B6%E5%AD%98%E5%82%A8%E7%B1%BB%E5%9E%8B)
* [移动或重命名文件](/products/kodo/3-cpp#%E7%A7%BB%E5%8A%A8%E6%88%96%E9%87%8D%E5%91%BD%E5%90%8D%E6%96%87%E4%BB%B6)
* [复制文件副本](/products/kodo/3-cpp#%E5%A4%8D%E5%88%B6%E6%96%87%E4%BB%B6%E5%89%AF%E6%9C%AC)
* [删除空间中的文件](/products/kodo/3-cpp#%E5%88%A0%E9%99%A4%E7%A9%BA%E9%97%B4%E4%B8%AD%E7%9A%84%E6%96%87%E4%BB%B6)
* [设置或更新文件生存时间](/products/kodo/3-cpp#rs-delete-after-days)
* [获取指定前缀文件列表](/products/kodo/3-cpp#rs-list)
* [抓取网络资源到空间](/products/kodo/3-cpp#%E6%8A%93%E5%8F%96%E7%BD%91%E7%BB%9C%E8%B5%84%E6%BA%90%E5%88%B0%E7%A9%BA%E9%97%B4)
* [更新镜像存储空间中文件内容](/products/kodo/3-cpp#rs-prefetch)
* [资源管理批量操作](/products/kodo/3-cpp#%E8%B5%84%E6%BA%90%E7%AE%A1%E7%90%86%E6%89%B9%E9%87%8F%E6%93%8D%E4%BD%9C)
  * [批量获取文件信息](/products/kodo/3-cpp#%E6%89%B9%E9%87%8F%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E4%BF%A1%E6%81%AF)
    * [批量修改文件类型](/products/kodo/3-cpp#%E6%89%B9%E9%87%8F%E4%BF%AE%E6%94%B9%E6%96%87%E4%BB%B6%E7%B1%BB%E5%9E%8B)
    * [批量删除文件](/products/kodo/3-cpp#%E6%89%B9%E9%87%8F%E5%88%A0%E9%99%A4%E6%96%87%E4%BB%B6)
    * [批量复制文件](/products/kodo/3-cpp#%E6%89%B9%E9%87%8F%E5%A4%8D%E5%88%B6%E6%96%87%E4%BB%B6)
    * [批量移动或重命名文件](/products/kodo/3-cpp#%E6%89%B9%E9%87%8F%E7%A7%BB%E5%8A%A8%E6%88%96%E9%87%8D%E5%91%BD%E5%90%8D%E6%96%87%E4%BB%B6)
    * [批量更新文件的有效期](/products/kodo/3-cpp#%E6%89%B9%E9%87%8F%E6%9B%B4%E6%96%B0%E6%96%87%E4%BB%B6%E7%9A%84%E6%9C%89%E6%95%88%E6%9C%9F)
    * [批量更新文件存储类型](/products/kodo/3-cpp#%E6%89%B9%E9%87%8F%E6%9B%B4%E6%96%B0%E6%96%87%E4%BB%B6%E5%AD%98%E5%82%A8%E7%B1%BB%E5%9E%8B)

<span id="rs-batch-stat" />

## 获取文件信息 [#获取文件信息]

通过调用 Qiniu\_RS\_Stat，可以得到指定文件的属性信息。除了会返回一个 Qiniu\_Error 结构体外，Qiniu\_RS\_Stat 还会返回 Qiniu\_RS\_StatRet 结构体，其中记录了被查询文件的一些属性信息。

```
char *bucket="if-pbl";
char *key="qiniu.mp4";
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_Stat(&client, &statRet, bucket, key);
if (error.code != 200) {
  printf("stat file %s:%s error.\n", bucket, key);
  debug_log(&client, error);
} else {
  /*200, 正确返回了, 你可以通过statRet变量查询一些关于这个文件的信息*/
  printf("stat file \t%s:%s success.\n\n", bucket, key);
  printf("file hash: \t%s\n", statRet.hash);
  printf("file size: \t%lld\n", statRet.fsize);
  printf("file put time: \t%lld\n", statRet.putTime);
  printf("file mime type: \t%s\n", statRet.mimeType);
  printf("file type: \t%lld\n", statRet.type);
}
Qiniu_Client_Cleanup(&client);
```

<span id="rs-chgm" />

## 修改文件 MimeType [#修改文件-mimetype]

```
char *bucket="if-pbl";
char *key="qiniu.mp4";
char *newMime="video/x-mp4";
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_ChangeMime(&client, bucket, key, newMime);
if (error.code != 200) {
  printf("change file mime %s:%s error.\n", bucket, key);
  debug_log(&client, error);
} else {
    printf("change file mime %s:%s success.\n\n", bucket, key);
}
Qiniu_Client_Cleanup(&client);
```

## 修改文件存储类型 [#修改文件存储类型]

```
char *bucket = "if-pbl";
char *key = "qiniu.mp4";
//fileType 为 0 表示普通存储，fileType 为 1 表示低频存储，fileType 为 2 表示归档存储，fileType 为 3 表示深度归档存储，fileType 为 4 表示归档直读存储
int fileType = 1;
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_ChangeType(&client, bucket, key, fileType);
if (error.code != 200) {
  printf("change file type %s:%s error.\n", bucket, key);
  debug_log(&client, error);
} else {
    printf("change file type %s:%s success.\n\n", bucket, key);
}
Qiniu_Client_Cleanup(&client);
```

<span id="rs-move" />

## 移动或重命名文件 [#移动或重命名文件]

移动操作本身支持移动文件到相同，不同空间中，在移动的同时也可以支持文件重命名。唯一的限制条件是，移动的源空间和目标空间必须在同一个区域。

| 源空间     | 目标空间    | 源文件名 | 目标文件名 | 描述                       |
| ------- | ------- | ---- | ----- | ------------------------ |
| BucketA | BucketA | KeyA | KeyB  | 相当于同空间文件重命名              |
| BucketA | BucketB | KeyA | KeyA  | 移动文件到 BucketB，文件名一致      |
| BucketA | BucketB | KeyA | KeyB  | 移动文件到 BucketB，文件名变成 KeyB |

`move` 操作支持强制覆盖选项，即如果目标文件已存在，可以设置强制覆盖选项 `force` 来覆盖那个文件的内容。

```
char *srcbucket="if-pbl";
char *srcKey = "qiniu.png";
char *destBucket = srcBucket;
char *destKey = "qiniu_move.png";
Qiniu_Bool force = Qiniu_True;
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_Move(&client, srcBucket, srcKey, destBucket, destKey, force);
if (error.code != 200) {
      printf("move file %s:%s -> %s:%s error.\n", srcBucket, srcKey, destBucket, destKey);
      debug_log(&client, error);
} else {
    printf("move file %s:%s -> %s:%s success.\n", srcBucket, srcKey, destBucket, destKey);
}
Qiniu_Client_Cleanup(&client);
```

<span id="rs-copy" />

## 复制文件副本 [#复制文件副本]

文件的复制和文件移动其实操作一样，主要的区别是移动后源文件不存在了，而复制的结果是源文件还存在，只是多了一个新的文件副本。

```
char *srcBucket="if-pbl";
char *srcKey = "qiniu.png";
char *destBucket = srcBucket;
char *destKey = "qiniu_copy.png";
Qiniu_Bool force = Qiniu_True;
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_Copy(&client, srcBucket, srcKey, destBucket, destKey, force);
if (error.code != 200) {
    printf("copy file %s:%s -> %s:%s error.\n", srcBucket, srcKey, destBucket, destKey);
    debug_log(&client, error);
} else {
    printf("copy file %s:%s -> %s:%s success.\n", srcBucket, srcKey, destBucket, destKey);
}
Qiniu_Client_Cleanup(&client);
```

<span id="rs-delete" />

## 删除空间中的文件 [#删除空间中的文件]

```
char *bucket="if-pbl";
char *key="qiniu.mp4";
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_Delete(&client, bucket, key);
if (error.code != 200) {
    printf("delete file %s:%s error.\n", bucket, key);
    debug_log(&client, error);
} else {
    printf("delete file %s:%s file success.\n", bucket, key);
}
Qiniu_Client_Cleanup(&client);
```

<span id="rs-delete-after-days" />

## 设置或更新文件的生存时间 [#设置或更新文件的生存时间]

可以给已经存在于空间中的文件设置文件生存时间，或者更新已设置了生存时间但尚未被删除的文件的新的生存时间。

```
char *bucket="if-pbl";
char *key="qiniu.mp4";
int days=7;
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_DeleteAfterDays(&client, bucket, key, days);
if (error.code != 200) {
    printf("deleteAfterDays file %s:%s error.\n", bucket, key);
    debug_log(&client, error);
} else {
    printf("deleteAfterDays file %s:%s file success.\n", bucket, key);
}
Qiniu_Client_Cleanup(&client);
```

<span id="rs-list" />

## 获取指定空间的文件列表 [#获取指定空间的文件列表]

```
// @param options 列举操作的可选参数
//                prefix    列举的文件前缀
//                marker    上一次列举返回的位置标记，作为本次列举的起点信息
//                limit     每次返回的最大列举文件数量
//                delimiter 指定目录分隔符
char *bucket="if-pbl";
char **commonPrefixes = NULL;
Qiniu_RSF_ListItem *items = NULL;
char *prefix = "";
char *delimiter = "/";
char *marker = "";
char *nextMarker = marker;
Qiniu_Bool isNewMarker = Qiniu_False;
Qiniu_RSF_ListRet listRet;
int limit = 10;
int i;

//init
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */

do {
    Qiniu_Error error = Qiniu_RSF_ListFiles(&client, &listRet, bucket, prefix, delimiter, nextMarker, limit);
    if (error.code != 200) {
        printf("list files of bucket %s error.\n", bucket);
        debug_log(&client, error);
        nextMarker = "";
    }
    else {
        /*200, 正确返回了, 你可以通过listRet变量查询文件列表信息*/
        printf("list files of bucket %s success.\n\n", bucket);

        //check next marker
        if (isNewMarker == Qiniu_True) {
            free(nextMarker);
        }

        if (!str_empty(listRet.marker)) {
            nextMarker = strdup(listRet.marker);
            isNewMarker = Qiniu_True;
        }
        else {
            nextMarker = NULL;
        }
        printf("next marker: %s\n", nextMarker);

        //common prefixes
        commonPrefixes = listRet.commonPrefixes;
        for (i = 0; i < listRet.commonPrefixesCount; i++) {
            printf("commonPrefix: %s\n", *commonPrefixes);
            ++commonPrefixes;
        }

        //items
        items = listRet.items;
        for (i = 0; i < listRet.itemsCount; i++) {
            Qiniu_RSF_ListItem item = listRet.items[i];
            printf("key: %s, hash: %s, fsize: %lld, mime: %s, putTime: %lld, endUser: %s, type: %lld\n",
                   item.key, item.hash, item.fsize, item.mimeType, item.putTime, item.endUser, item.type);
        }

        //free
        Qiniu_RSF_ListRet_Cleanup(&listRet);
    }
} while (!str_empty(nextMarker));

Qiniu_Client_Cleanup(&client);
```

## 抓取网络资源到空间 [#抓取网络资源到空间]

```
//fetch with key
Qiniu_RS_FetchRet fetchRet;
char *bucket="if-pbl";
char *resURL = "http://devtools.qiniu.com/qiniu.png";
char *key = "qiniu.png";
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_Fetch(&client, &fetchRet, resURL, bucket, key);
if (error.code != 200) {
    printf("fetch file %s -> %s:%s error.\n", resURL, bucket, key);
    debug_log(&client, error);
} else {
    /*200, 正确返回了, 你可以通过fetchRet变量查询一些关于这个文件的信息*/
    printf("fetch file %s -> %s:%s success.\n", resURL, bucket, key);
    printf("file key: \t%s\n", fetchRet.key);
    printf("file hash: \t%s\n", fetchRet.hash);
    printf("file size: \t%lld\n", fetchRet.fsize);
    printf("file mime type: \t%s\n", fetchRet.mimeType);
}
Qiniu_Client_Cleanup(&client);
```

<span id="rs-prefetch" />

## 更新镜像空间中存储的文件内容 [#更新镜像空间中存储的文件内容]

```
char *bucket="if-pbl";
char *key="qiniu.mp4";
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_Prefetch(&client, bucket, key);
if (error.code != 200) {
    printf("prefetch file %s:%s error.\n", bucket, key);
    debug_log(&client, error);
} else {
    printf("prefetch file \t%s:%s success.\n\n", bucket, key);
}
Qiniu_Client_Cleanup(&client);
```

<span id="rs-batch" />

## 资源管理批量操作 [#资源管理批量操作]

### \*\* 批量获取文件信息 \*\* [#-批量获取文件信息-]

```
Qiniu_RS_BatchStatRet *statRets;
int i;
char *bucket="if-pbl";
char *key="qiniu.mp4";
Qiniu_ItemCount entryCount = 10;
Qiniu_RS_EntryPath *entries = (Qiniu_RS_EntryPath *) malloc(sizeof(Qiniu_RS_EntryPath) * entryCount);
for (i = 0; i < entryCount; i++) {
    Qiniu_RS_EntryPath entry;
    entry.bucket = bucket;

    size_t indexLen = snprintf(NULL, 0, "%d", i) + 1;
    char *indexStr = (char *) calloc(sizeof(char), indexLen);
    snprintf(indexStr, indexLen, "%d", i);
    entry.key = Qiniu_String_Concat2(key, indexStr);
    Qiniu_Free(indexStr);
    entries[i] = entry;
}

statRets = (Qiniu_RS_BatchStatRet *) malloc(sizeof(Qiniu_RS_BatchStatRet) * entryCount);

//init
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_BatchStat(&client, statRets, entries, entryCount);
if (error.code / 100 != 2) {
    printf("batch stat file error.\n");
    debug_log(&client, error);
} else {
    /*200, 正确返回了, 你可以通过statRets变量查询一些关于这个文件的信息*/
    printf("batch stat file success.\n\n");

    for (i = 0; i < entryCount; i++) {
        Qiniu_RS_StatRet data = statRets[i].data;
        int code = statRets[i].code;
        if (code == 200) {
            printf("file hash: \t%s\n", data.hash);
            printf("file size: \t%lld\n", data.fsize);
            printf("file put time: \t%lld\n", data.putTime);
            printf("file mime type: \t%s\n", data.mimeType);
            printf("file type: \t%lld\n", data.type);
        } else {
            printf("error: %s\n", statRets[i].error);
        }
    }
}
Qiniu_Client_Cleanup(&client);
```

其中，entries 是一个指向 Qiniu\_RS\_EntryPath 结构体数组的指针，entryCount 为数组 entries 的长度。结构体 Qiniu\_RS\_EntryPath 中填写每个文件相应的 bucket 和 key：

```
typedef struct _Qiniu_RS_EntryPath {
    const char* bucket;
    const char* key;
} Qiniu_RS_EntryPath;
```

Qiniu\_RS\_BatchStat 会将文件信息（及成功／失败信息）依次写入一个由结构体 Qiniu\_RS\_BatchStatRet 组成的数组空间 rets。因此，调用之前，需要先给 rets 申请好相应长度的内存空间。

其中结构体 Qiniu\_RS\_BatchStatRet 的组成如下：

```
typedef struct _Qiniu_RS_BatchStatRet {
    Qiniu_RS_StatRet data;
    const char* error;
    int code;
}Qiniu_RS_BatchStatRet;
```

### 批量修改文件类型 [#批量修改文件类型]

```
Qiniu_RS_BatchItemRet *itemRets;
Qiniu_Client client;
int i;
char *key="qiniu.mp4";
Qiniu_ItemCount entryCount = 10;
Qiniu_RS_EntryChangeMime *entries = (Qiniu_RS_EntryChangeMime *) malloc(
        sizeof(Qiniu_RS_EntryChangeMime) * entryCount);
for (i = 0; i < entryCount; i++) {
    Qiniu_RS_EntryChangeMime entry;
    entry.bucket = bucket;

    size_t indexLen = snprintf(NULL, 0, "%d", i) + 1;
    char *indexStr = (char *) calloc(sizeof(char), indexLen);
    snprintf(indexStr, indexLen, "%d", i);
    entry.key = Qiniu_String_Concat2(key, indexStr);
    Qiniu_Free(indexStr);
    entry.mime = "image/x-png";
    entries[i] = entry;
}

itemRets = (Qiniu_RS_BatchItemRet *) malloc(sizeof(Qiniu_RS_BatchItemRet) * entryCount);

//init
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_BatchChangeMime(&client, itemRets, entries, entryCount);
if (error.code / 100 != 2) {
    printf("batch change file mime error.\n");
    debug_log(&client, error);
} else {
    /*200, 正确返回了, 你可以通过itemRets变量查询一些关于这个文件的信息*/
    printf("batch change file mime success.\n\n");

    for (i = 0; i < entryCount; i++) {
        int code = itemRets[i].code;
        if (code == 200) {
            printf("success: %d\n", code);
        } else {
            printf("code: %d, error: %s\n", code, itemRets[i].error);
        }
    }
}
Qiniu_Client_Cleanup(&client);
```

### 批量删除文件 [#批量删除文件]

```
Qiniu_RS_BatchItemRet *itemRets;
Qiniu_Client client;
int i;
char *key = "qiniu.png";
char *bucket="if-pbl";

Qiniu_ItemCount entryCount = 10;
Qiniu_RS_EntryPath *entries = (Qiniu_RS_EntryPath *) malloc(sizeof(Qiniu_RS_EntryPath) * entryCount);
for (i = 0; i < entryCount; i++) {
    Qiniu_RS_EntryPath entry;
    entry.bucket = bucket;

    size_t indexLen = snprintf(NULL, 0, "%d", i) + 1;
    char *indexStr = (char *) calloc(sizeof(char), indexLen);
    snprintf(indexStr, indexLen, "%d", i);
    entry.key = Qiniu_String_Concat2(key, indexStr);
    entries[i] = entry;
}

itemRets = (Qiniu_RS_BatchItemRet *) malloc(sizeof(Qiniu_RS_BatchItemRet) * entryCount);

//init
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_BatchDelete(&client, itemRets, entries, entryCount);
if (error.code / 100 != 2) {
    printf("batch delete file error.\n");
    debug_log(&client, error);
} else {
    printf("batch delete file success.\n\n");

    for (i = 0; i < entryCount; i++) {
        int code = itemRets[i].code;
        if (code == 200) {
            printf("success: %d\n", code);
        } else {
            printf("code: %d, error: %s\n", code, itemRets[i].error);
        }
    }
}
Qiniu_Client_Cleanup(&client);
```

### 批量复制文件 [#批量复制文件]

```
Qiniu_RS_BatchItemRet *itemRets;
Qiniu_Client client;
int i;

char *key = "qiniu.png";
char *bucket="if-pbl";

Qiniu_ItemCount entryCount = 10;
Qiniu_RS_EntryPathPair *entryPairs = (Qiniu_RS_EntryPathPair *) malloc(sizeof(Qiniu_RS_EntryPathPair) * entryCount);
for (i = 0; i < entryCount; i++) {
    //src
    Qiniu_RS_EntryPath srcEntry;
    srcEntry.bucket = bucket;
    srcEntry.key = key;

    //dest
    Qiniu_RS_EntryPath destEntry;
    destEntry.bucket = bucket;
    size_t indexLen = snprintf(NULL, 0, "%d", i) + 1;
    char *indexStr = (char *) calloc(sizeof(char), indexLen);
    snprintf(indexStr, indexLen, "%d", i);
    destEntry.key = Qiniu_String_Concat2(key, indexStr);
    Qiniu_Free(indexStr);

    //pack
    Qiniu_RS_EntryPathPair entryPair;
    entryPair.src = srcEntry;
    entryPair.dest = destEntry;
    entryPair.force = Qiniu_True;
    entryPairs[i] = entryPair;
}

itemRets = (Qiniu_RS_BatchItemRet *) malloc(sizeof(Qiniu_RS_BatchItemRet) * entryCount);

//init
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_BatchCopy(&client, itemRets, entryPairs, entryCount);
if (error.code / 100 != 2) {
    printf("batch copy file error.\n");
    debug_log(&client, error);
} else {
    printf("batch copy file success.\n\n");

    for (i = 0; i < entryCount; i++) {
        int code = itemRets[i].code;
        if (code == 200) {
            printf("success: %d\n", code);
        } else {
            printf("code: %d, error: %s\n", code, itemRets[i].error);
        }
    }
}
Qiniu_Client_Cleanup(&client);
```

<span id="rs-batch-move" />

### 批量移动或重命名文件 [#批量移动或重命名文件]

```
Qiniu_RS_BatchItemRet *itemRets;
Qiniu_Client client;
int i;

char *bucket="if-pbl";
char *key = "qiniu.png";

Qiniu_ItemCount entryCount = 10;
Qiniu_RS_EntryPathPair *entryPairs = (Qiniu_RS_EntryPathPair *) malloc(sizeof(Qiniu_RS_EntryPathPair) * entryCount);
for (i = 0; i < entryCount; i++) {

    size_t indexLen = snprintf(NULL, 0, "%d", i) + 1;
    char *indexStr = (char *) calloc(sizeof(char), indexLen);
    snprintf(indexStr, indexLen, "%d", i);

    //src
    Qiniu_RS_EntryPath srcEntry;
    srcEntry.bucket = bucket;
    srcEntry.key = Qiniu_String_Concat2(key, indexStr);

    //dest
    Qiniu_RS_EntryPath destEntry;
    destEntry.bucket = bucket;
    destEntry.key = Qiniu_String_Concat3(key, indexStr, "-move");

    Qiniu_Free(indexStr);

    //pack
    Qiniu_RS_EntryPathPair entryPair;
    entryPair.src = srcEntry;
    entryPair.dest = destEntry;
    entryPair.force = Qiniu_True;
    entryPairs[i] = entryPair;
}

itemRets = (Qiniu_RS_BatchItemRet *) malloc(sizeof(Qiniu_RS_BatchItemRet) * entryCount);

//init
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_BatchMove(&client, itemRets, entryPairs, entryCount);
if (error.code / 100 != 2) {
    printf("batch move file error.\n");
    debug_log(&client, error);
} else {
    printf("batch move file success.\n\n");

    for (i = 0; i < entryCount; i++) {
        int code = itemRets[i].code;
        if (code == 200) {
            printf("success: %d\n", code);
        } else {
            printf("code: %d, error: %s\n", code, itemRets[i].error);
        }
    }
}
Qiniu_Client_Cleanup(&client);
```

### 批量更新文件的有效期 [#批量更新文件的有效期]

```
Qiniu_RS_BatchItemRet *itemRets;
Qiniu_Client client;
int i;

char *bucket="if-pbl";
char *key = "qiniu.png";

Qiniu_ItemCount entryCount = 10;
Qiniu_RS_EntryDeleteAfterDays *entries = (Qiniu_RS_EntryDeleteAfterDays *) malloc(
        sizeof(Qiniu_RS_EntryDeleteAfterDays) * entryCount);
for (i = 0; i < entryCount; i++) {
    Qiniu_RS_EntryDeleteAfterDays entry;
    entry.bucket = bucket;

    size_t indexLen = snprintf(NULL, 0, "%d", i) + 1;
    char *indexStr = (char *) calloc(sizeof(char), indexLen);
    snprintf(indexStr, indexLen, "%d", i);
    entry.key = Qiniu_String_Concat2(key, indexStr);
    Qiniu_Free(indexStr);
    entry.days = 7;//设置7天有效期
    entries[i] = entry;
}

itemRets = (Qiniu_RS_BatchItemRet *) malloc(sizeof(Qiniu_RS_BatchItemRet) * entryCount);

//init
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_BatchDeleteAfterDays(&client, itemRets, entries, entryCount);
if (error.code / 100 != 2) {
    printf("batch deleteAfterDays file error.\n");
    debug_log(&client, error);
} else {
    /*200, 正确返回了, 你可以通过itemRets变量查询一些关于这个文件的信息*/
    printf("batch deleteAfterDays file success.\n\n");

    for (i = 0; i < entryCount; i++) {
        int code = itemRets[i].code;
        if (code == 200) {
            printf("success: %d\n", code);
        } else {
            printf("code: %d, error: %s\n", code, itemRets[i].error);
        }
    }
}
Qiniu_Client_Cleanup(&client);
```

### 批量更新文件存储类型 [#批量更新文件存储类型]

```
Qiniu_RS_BatchItemRet *itemRets;
Qiniu_Client client;
int i;
char *key = "qiniu.png";
char *bucket="if-pbl";

Qiniu_ItemCount entryCount = 10;
Qiniu_RS_EntryChangeType *entries = (Qiniu_RS_EntryChangeType *) malloc(
        sizeof(Qiniu_RS_EntryChangeType) * entryCount);
for (i = 0; i < entryCount; i++) {
    Qiniu_RS_EntryChangeType entry;
    entry.bucket = bucket;

    size_t indexLen = snprintf(NULL, 0, "%d", i) + 1;
    char *indexStr = (char *) calloc(sizeof(char), indexLen);
    snprintf(indexStr, indexLen, "%d", i);
    entry.key = Qiniu_String_Concat2(key, indexStr);
    Qiniu_Free(indexStr);
    entry.fileType = 1;//改为低频存储
    entries[i] = entry;
}

itemRets = (Qiniu_RS_BatchItemRet *) malloc(sizeof(Qiniu_RS_BatchItemRet) * entryCount);

//init
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */
Qiniu_Error error = Qiniu_RS_BatchChangeType(&client, itemRets, entries, entryCount);
if (error.code / 100 != 2) {
    printf("batch change file type error.\n");
    debug_log(&client, error);
} else {
    /*200, 正确返回了, 你可以通过itemRets变量查询一些关于这个文件的信息*/
    printf("batch change file type success.\n\n");

    for (i = 0; i < entryCount; i++) {
        int code = itemRets[i].code;
        if (code == 200) {
            printf("success: %d\n", code);
        } else {
            printf("code: %d, error: %s\n", code, itemRets[i].error);
        }
    }
}
Qiniu_Client_Cleanup(&client);
```

## 持久化数据处理 [#持久化数据处理]

## 发送数据处理请求（数据处理指令） [#发送数据处理请求数据处理指令]

对于已经保存到七牛空间的文件，可以通过发送持久化的数据处理指令来进行处理，这些指令支持七牛官方提供的指令，也包括客户自己开发的自定义数据处理的指令。数据处理的结果还可以通过七牛主动通知的方式告知业务服务器。

闲时任务的功能介绍、使用场景、定价，详见 [闲时任务策略说明](/products/dora/processing-mechanism/persist/2-idle-time-task-strategy) 。

```
char *bucket="if-pbl";
char *key = "qiniu.mp4";
char *pipeline = "sdktest";
char *notifyURL = NULL;
int force = 0;
//init
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */

char *saveMp4Entry = Qiniu_String_Concat3(bucket, ":", "avthumb_test_target.mp4");
char *saveMp4EntryEncoded = Qiniu_String_Encode(saveMp4Entry);
Qiniu_Free(saveMp4Entry);

char *saveJpgEntry = Qiniu_String_Concat3(bucket, ":", "vframe_test_target.jpg");
char *saveJpgEntryEncoded = Qiniu_String_Encode(saveJpgEntry);
Qiniu_Free(saveJpgEntry);

char *avthumbMp4Fop = Qiniu_String_Concat2("avthumb/mp4|saveas/", saveMp4EntryEncoded);
char *vframeJpgFop = Qiniu_String_Concat2("vframe/jpg/offset/1|saveas/", saveJpgEntryEncoded);

Qiniu_Free(saveMp4EntryEncoded);
Qiniu_Free(saveJpgEntryEncoded);

char *fops[] = {avthumbMp4Fop, vframeJpgFop};

Qiniu_FOP_PfopParams params = {
    .bucket = bucket,
    .key = key,
    .pipeline = pipeline,
    .notifyURL = notifyURL,
    .fops = fops,
    .fopCount = 2,
    .force = force,
    .type = 0, // 任务类型：0: 普通任务 1: 闲时任务（一旦指定闲时任务，就不能指定 pipeline）
};
Qiniu_Error error = Qiniu_FOP_Pfop_v2(&client, &pfopRet, &params);
if (error.code != 200) {
    printf("video file pfop %s:%s error.\n", bucket, key);
    debug_log(&client, error);
} else {
    /*200, 正确返回了, 你可以通过pfopRet变量查询任务ID*/
    printf("video file pfop %s:%s success, persistentId: %s .\n\n", bucket, key, pfopRet.persistentId);
}
Qiniu_Client_Cleanup(&client);
```

## 发送数据处理请求（工作流模版） [#发送数据处理请求工作流模版]

也可以支持使用工作流模版替代数据处理指令。工作流模板是预先编排好的一系列媒体处理流程（如转码、截图、视频拼接等各类处理），登录 [对象存储控制台](https://portal.qiniu.com/kodo/bucket) 进行创建，详情参考 [工作流模板操作指南](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template) ， `workflowTemplateID` 对应工作流模板列表的 `名称` 字段

```
char *bucket="if-pbl";
char *key = "qiniu.mp4";
char *workflowTemplateID = "tempname";
char *pipeline = "sdktest";
char *notifyURL = NULL;
int force = 0;
//init
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
Qiniu_Client_EnableAutoQuery(&client, Qiniu_True);   /* 启用区域自动查询，无需手动设置区域 */

Qiniu_FOP_PfopParams params = {
    .bucket = bucket,
    .key = key,
    .pipeline = pipeline,
    .notifyURL = notifyURL,
    .workflowTemplateID = workflowTemplateID,
    .force = force,
    .type = 0, // 任务类型：0: 普通任务 1: 闲时任务（一旦指定闲时任务，就不能指定 pipeline）
};
Qiniu_Error error = Qiniu_FOP_Pfop_v2(&client, &pfopRet, &params);
if (error.code != 200) {
    printf("video file pfop %s:%s error.\n", bucket, key);
    debug_log(&client, error);
} else {
    /*200, 正确返回了, 你可以通过pfopRet变量查询任务ID*/
    printf("video file pfop %s:%s success, persistentId: %s .\n\n", bucket, key, pfopRet.persistentId);
}
Qiniu_Client_Cleanup(&client);
```

## CDN 相关功能 [#cdn-相关功能]

* [文件刷新](/products/kodo/3-cpp#%E6%96%87%E4%BB%B6%E5%88%B7%E6%96%B0)
* [目录刷新](/products/kodo/3-cpp#%E7%9B%AE%E5%BD%95%E5%88%B7%E6%96%B0)
* [文件预取操作](/products/kodo/3-cpp#fusion-prefetch)
* [获取域名流量](/products/kodo/3-cpp#%E8%8E%B7%E5%8F%96%E5%9F%9F%E5%90%8D%E6%B5%81%E9%87%8F)
* [获取域名带宽](/products/kodo/3-cpp#%E8%8E%B7%E5%8F%96%E5%9F%9F%E5%90%8D%E5%B8%A6%E5%AE%BD)
* [获取日志下载链接](/products/kodo/3-cpp#%E8%8E%B7%E5%8F%96%E6%97%A5%E5%BF%97%E4%B8%8B%E8%BD%BD%E9%93%BE%E6%8E%A5)
* [构建时间戳防盗链访问链接](/products/kodo/3-cpp#%E6%9E%84%E5%BB%BA%E6%97%B6%E9%97%B4%E6%88%B3%E9%98%B2%E7%9B%97%E9%93%BE%E8%AE%BF%E9%97%AE%E9%93%BE%E6%8E%A5)

CDN 的主要函数主要可以在 cdn.h 中看到，下面列举了主要的功能。

<span id="fusion-refresh-urls" />

## 文件刷新 [#文件刷新]

```
Qiniu_CDN_RefreshRet ret;
Qiniu_Error error;
char **p;
int i;

//刷新链接，单次请求链接不可以超过100个，如果超过，请分批发送请求
//urls to refresh
char *urls[] = {
        "http://csdk.qiniudn.com/qiniu1.png",
        "http://csdk.qiniudn.com/qiniu2.png",
        "http://csdk.qiniudn.com/qiniu3.png"
};

//init
Qiniu_Zero(ret);
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
error = Qiniu_CDN_RefreshUrls(&client, &ret, urls, 3);
if (error.code != 200) {
    printf("refresh urls error.\n");
    debug_log(&client, error);
} else {
    printf("refresh urls success.\n");
    printf("Code: %d\n", ret.code);
    printf("Error: %s\n", ret.error);
    printf("RequestId: %s\n", ret.requestId);

    p = ret.invalidUrls;
    for (i = 0; i < ret.invalidUrlsCount; i++) {
        printf("InvalidUrl: %s\n", *p);
        ++p;
    }

    p = ret.invalidDirs;
    for (i = 0; i < ret.invalidDirsCount; i++) {
        printf("InvalidDir: %s\n", *p);
        ++p;
    }

    printf("UrlQuotaDay: %d\n", ret.urlQuotaDay);
    printf("UrlSurplusDay: %d\n", ret.urlSurplusDay);
    printf("DirQuotaDay: %d\n", ret.dirQuotaDay);
    printf("DirSurplusDay: %d\n", ret.dirSurplusDay);

    Qiniu_Free_CDNRefreshRet(&ret);
}
Qiniu_Client_Cleanup(&client);
```

<span id="fusion-refresh-dirs" />

## 目录刷新 [#目录刷新]

```
Qiniu_CDN_RefreshRet ret;
Qiniu_Error error;
char **p;
int i;
//刷新目录，刷新目录需要联系七牛技术支持开通权限
//单次请求链接不可以超过10个，如果超过，请分批发送请求
char *dirs[] = {
        "http://csdk.qiniudn.com/image1/",
        "http://csdk.qiniudn.com/image2/",
        "http://csdk.qiniudn.com/image3/"
};

//init
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
error = Qiniu_CDN_RefreshDirs(&client, &ret, dirs, 3);
if (error.code != 200) {
    printf("refresh dirs error.\n");
    debug_log(&client, error);
} else {
    printf("refresh dirs success.\n");
    printf("Code: %d\n", ret.code);
    printf("Error: %s\n", ret.error);
    printf("RequestId: %s\n", ret.requestId);

    p = ret.invalidUrls;
    for (i = 0; i < ret.invalidUrlsCount; i++) {
        printf("InvalidUrl: %s\n", *p);
        ++p;
    }

    p = ret.invalidDirs;
    for (i = 0; i < ret.invalidDirsCount; i++) {
        printf("InvalidDir: %s\n", *p);
        ++p;
    }

    printf("UrlQuotaDay: %d\n", ret.urlQuotaDay);
    printf("UrlSurplusDay: %d\n", ret.urlSurplusDay);
    printf("DirQuotaDay: %d\n", ret.dirQuotaDay);
    printf("DirSurplusDay: %d\n", ret.dirSurplusDay);

    Qiniu_Free_CDNRefreshRet(&ret);
}
Qiniu_Client_Cleanup(&client);
```

<span id="fusion-prefetch" />

## 文件预取 [#文件预取]

```
Qiniu_CDN_PrefetchRet ret;
Qiniu_Error error;
char **p;
int i;
//预取链接，单次请求链接不可以超过100个，如果超过，请分批发送请求
//urls to refresh
char *urls[] = {
        "http://csdk.qiniudn.com/qiniu1.png",
        "http://csdk.qiniudn.com/qiniu2.png",
        "http://csdk.qiniudn.com/qiniu3.png"
};
//init
Qiniu_Zero(ret);
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
error = Qiniu_CDN_PrefetchUrls(&client, &ret, urls, 3);
if (error.code != 200) {
    printf("prefetch urls error.\n");
    debug_log(&client, error);
} else {
    printf("prefetch urls success.\n");
    printf("Code: %d\n", ret.code);
    printf("Error: %s\n", ret.error);
    printf("RequestId: %s\n", ret.requestId);

    p = ret.invalidUrls;
    for (i = 0; i < ret.invalidUrlsCount; i++) {
        printf("InvalidUrl: %s\n", *p);
        ++p;
    }
    printf("QuotaDay: %d\n", ret.quotaDay);
    printf("SurplusDay: %d\n", ret.surplusDay);
    Qiniu_Free_CDNPrefetchRet(&ret);
}
Qiniu_Client_Cleanup(&client);
```

<span id="fusion-cdn_flux" />

## 获取域名流量 [#获取域名流量]

```
Qiniu_CDN_FluxRet ret;
Qiniu_Error error;
int i, j;
//urls to refresh
char *domains[] = {
        "csdk.qiniudn.com",
        "javasdk.qiniudn.com"
};
int domainsCount = 2;
char *startDate = "2017-08-01";
char *endDate = "2017-08-09";
char *g = "day";

//init
Qiniu_Zero(ret);
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
error = Qiniu_CDN_GetFluxData(&client, &ret, startDate, endDate, g, domains, domainsCount);
if (error.code != 200) {
    printf("get domain flux error.\n");
    debug_log(&client, error);
} else {
    printf("get domain flux success.\n\n");
    printf("Code: %d\n", ret.code);
    printf("Error: %s\n", ret.error);
    printf("Domains: %d\n", ret.domainsCount);

    printf("-----------\n");

    for (i = 0; i < ret.timeCount; i++) {
        printf("%s\t", ret.time[i]);
    }
    printf("\n");

    //data
    for (i = 0; i < ret.domainsCount; i++) {
        printf("Domain:%s\n", domains[i]);
        Qiniu_CDN_FluxData fluxData = ret.data[i];
        if (fluxData.chinaCount == 0) {
            printf("China: no flux data\n");
        } else {
            printf("China: flux data\n");
            for (j = 0; j < fluxData.chinaCount; j++) {
                printf("%lld\t", fluxData.china[j]);
            }
            printf("\n");
        }

        if (fluxData.overseaCount == 0) {
            printf("Oversea: no flux data\n");
        } else {
            printf("Oversea: flux data\n");
            for (j = 0; j < fluxData.overseaCount; j++) {
                printf("%lld\t", fluxData.oversea[j]);
            }
            printf("\n");
        }
        printf("-----------\n");
    }

    Qiniu_Free_CDNFluxRet(&ret);
}
Qiniu_Client_Cleanup(&client);
```

<span id="fusion-cdn_bandwidth" />

## 获取域名带宽 [#获取域名带宽]

```
Qiniu_CDN_BandwidthRet ret;
Qiniu_Error error;
int i, j;

//urls to refresh
char *domains[] = {
        "csdk.qiniudn.com",
        "javasdk.qiniudn.com"
};
int domainsCount = 2;
char *startDate = "2017-08-01";
char *endDate = "2017-08-09";
char *g = "day";

//init
Qiniu_Zero(ret);
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
error = Qiniu_CDN_GetBandwidthData(&client, &ret, startDate, endDate, g, domains, domainsCount);
if (error.code != 200) {
    printf("get domain bandwidth error.\n");
    debug_log(&client, error);
} else {
    printf("get domain bandwidth success.\n\n");
    printf("Code: %d\n", ret.code);
    printf("Error: %s\n", ret.error);
    printf("Domains: %d\n", ret.domainsCount);

    printf("-----------\n");

    for (i = 0; i < ret.timeCount; i++) {
        printf("%s\t", ret.time[i]);
    }
    printf("\n");

    //data
    for (i = 0; i < ret.domainsCount; i++) {
        printf("Domain:%s\n", domains[i]);
        Qiniu_CDN_BandwidthData bandData = ret.data[i];
        if (bandData.chinaCount == 0) {
            printf("China: no bandwidth data\n");
        } else {
            printf("China: bandwidth data\n");
            for (j = 0; j < bandData.chinaCount; j++) {
                printf("%lld\t", bandData.china[j]);
            }
            printf("\n");
        }

        if (bandData.overseaCount == 0) {
            printf("Oversea: no bandwidth data\n");
        } else {
            printf("Oversea: bandwidth data\n");
            for (j = 0; j < bandData.overseaCount; j++) {
                printf("%lld\t", bandData.oversea[j]);
            }
            printf("\n");
        }
        printf("-----------\n");
    }

    Qiniu_Free_CDNBandwidthRet(&ret);
}
Qiniu_Client_Cleanup(&client);
```

<span id="fusion-cdn_logs" />

<span id="qiniu-cdn-loglist" />

## 获取日志下载链接 [#获取日志下载链接]

```
Qiniu_CDN_LogListRet ret;
Qiniu_Error error;
int i, j;
//urls to refresh
char *domains[] = {
        "csdk.qiniudn.com",
        "javasdk.qiniudn.com"
};
int domainsCount = 2;
char *day = "2017-08-07";

//init
Qiniu_Zero(ret);
Qiniu_Client_InitMacAuth(&client, 1024, &mac);
error = Qiniu_CDN_GetLogList(&client, &ret, domains, domainsCount,day);
if (error.code != 200) {
    printf("get domain logs error.\n");
    debug_log(&client, error);
} else {
    printf("get domain logs success.\n\n");
    printf("Code: %d\n", ret.code);
    printf("Error: %s\n", ret.error);
    printf("Domains: %d\n", ret.domainsCount);

    printf("-----------\n");

    //data
    for (i = 0; i < ret.domainsCount; i++) {
        Qiniu_CDN_LogListData logData = ret.data[i];
        if (logData.itemsCount == 0) {
            printf("domain: %s, no log data\n", logData.domain);
            printf("-----------\n");
        } else {
            printf("domain: %s have %d log files\n", logData.domain, logData.itemsCount);
            for (j = 0; j < logData.itemsCount; j++) {
                printf("name: %s\n", logData.items[j].name);
            }
            printf("-----------\n");
        }
    }

    Qiniu_Free_CDNLogListRet(&ret);

}
Qiniu_Client_Cleanup(&client);
```

## 构建时间戳防盗链访问链接 [#构建时间戳防盗链访问链接]

具体算法可以参考： [时间戳防盗链](/products/cdn/configuration-management-fusion/access-control-configuration/1-timestamp-hotlinking-prevention-fusion)

```
#include "../qiniu/cdn.h"
#include "../qiniu/tm.h"
#include <stdio.h>

int main(int argc, char *argv[]) {
    char *host = "http://v1.cdn.example.com";
    char *fileName = "video/caipu/201708/0600/s/5985f37b37025.mp4/eGgxMDgwcA.m3u8";
    char *cryptKey = "xxx";
    char *queryStr = "name=七牛&age=27";

    char *finalUrl;
    Qiniu_Uint64 deadline = Qiniu_Tm_LocalTime() + 3600;

    finalUrl = Qiniu_CDN_CreateTimestampAntiLeechURL(host, fileName, queryStr, deadline, cryptKey);
    printf("%s\n", finalUrl);
    Qiniu_Free(finalUrl);
}
```

## API 参考 [#api-参考]

* [存储 API 参考](/products/kodo/kodo-console-guide/0-an-overview-of-the-console)
* [融合 CDN API 参考](/products/cdn/0-fusion-api-overview)
* [官方数据处理 API 参考](/faq/dora)

## 常见问题 [#常见问题]

* API 的使用，可以参考我们为大家精心准备的 [使用实例](https://github.com/qiniu/c-sdk/tree/master/examples) 。

## 相关资源 [#相关资源]

如果您有任何关于我们文档或产品的建议和想法，欢迎您通过以下方式与我们互动讨论：

* [技术论坛](http://segmentfault.com/qiniu) - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
* [提交工单](https://support.qiniu.com/tickets/new) - 如果您的问题不适合在论坛讨论或希望及时解决，您也可以提交一个工单，我们的技术支持人员会第一时间回复您
* [博客](http://blog.qiniu.com/) - 这里会持续更新发布市场活动和技术分享文章
* [微博](http://weibo.com/qiniutek)
* [常见问题](https://support.qiniu.com/question)

## 贡献代码 [#贡献代码]

1. Fork
2. 创建您的特性分支 git checkout -b my-new-feature
3. 提交您的改动 git commit -am ‘Added some feature’
4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature
5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

## 许可证 [#许可证]

Copyright © 2014 qiniu.com

基于 MIT 协议发布:

* [www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)


# Ruby SDK (/products/kodo/4-ruby)



最近更新时间: 2025-04-21 17:05:05

此 Ruby SDK 适用于 Ruby 2.1.x，2.2.x，2.3.x，JRuby 9.x 版本。

## 安装 [#安装]

在您 Ruby 应用程序的 `Gemfile` 文件中，添加如下一行代码：

```
gem 'qiniu', '~> 6.9.1'
```

然后，在应用程序所在的目录下，运行 `bundle` 安装依赖包：

```
$ bundle
```

或者，可以使用 Ruby 的包管理器 `gem` 进行安装：

```
$ gem install qiniu
```

**初始化**

在使用SDK 前，您需要一对有效的 AccessKey 和 SecretKey 签名授权。

可以通过如下步骤获得：

1. 开通开发者帐号
2. 如果已有账号，直接登录开发者后台，查看 Access Key 和 Secret Key

\*\*注意：\*\*用户应当妥善保存 SecretKey ，一旦发生泄露，请立刻到开发者平台更新。

在使用Ruby SDK之前，需要初始化环境，并且设置 AccessKey 和 SecretKey：

```
#!/usr/bin/env ruby

require 'qiniu'

Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'
```

如果您使用的是 [Ruby on Rails](http://rubyonrails.org/) 框架，我们建议您在应用初始化启动的过程中，调用上述方法即可，操作如下：

1. 在应用初始化脚本加载的目录中新建一个文件： *YOUR\_RAILS\_APP/config/initializers/qiniu\_sdk.rb*
2. 编辑 *YOUR\_RAILS\_APP/config/initializers/qiniu\_sdk.rb* 文件内容如下：

```
require 'qiniu'

Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'
```

这样，您就可以在您的 `RAILS_APP` 中使用 Ruby SDK 提供的其他任意方法了。

## 文件上传 [#文件上传]

## 上传流程 [#上传流程]

为了尽可能地改善终端用户的上传体验，首创了客户端直传功能。更多信息请参阅 [业务流程](/products/kodo/0-programming-model) 。

**上传代码：**

```
#!/usr/bin/env ruby

require 'qiniu'

# 构建鉴权对象
Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'

# 要上传的空间
bucket = 'Bucket_Name'

# 上传后保存的文件名
key = 'my-ruby-logo.png'

# 构建上传策略，上传策略的更多参数请参照 /products/kodo/development-guidelines/security/1-put-policy
put_policy = Qiniu::Auth::PutPolicy.new(
    bucket, # 存储空间
    key,    # 指定上传的资源名，如果传入 nil，就表示不指定资源名，将使用默认的资源名
    3600    # token 过期时间，默认为 3600 秒，即 1 小时
)

# 生成上传 Token
uptoken = Qiniu::Auth.generate_uptoken(put_policy)

# 要上传文件的本地路径
filePath = './ruby-logo.png'

# 调用 upload_with_token_2 方法上传
code, result, response_headers = Qiniu::Storage.upload_with_token_2(
     uptoken,
     filePath,
     key,
     nil, # 可以接受一个 Hash 作为自定义变量，请参照 /products/kodo/development-guidelines/upload-types/0-vars
     bucket: bucket
)

#打印上传返回的信息
puts code
puts result
```

## 上传 & 回调 [#上传--回调]

```
#!/usr/bin/env ruby

require 'qiniu'

# 构建鉴权对象
Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'

bucket = 'Bucket_Name'

key = 'my-ruby-logo.png'

put_policy = Qiniu::Auth::PutPolicy.new(
    bucket, # 存储空间
    key,    # 指定上传的资源名，如果传入 nil，就表示不指定资源名，将使用默认的资源名
    3600    # token 过期时间，默认为 3600 秒，即 1 小时
)

# 构建回调策略，这里上传文件后， 将文件名和文件大小回调给业务服务器.
callback_url = 'http://your.domain.com/callback'
callback_body = 'filename=$(fname)&filesize=$(fsize)' # 魔法变量的使用请参照 /products/kodo/development-guidelines/upload-types/0-vars

put_policy.callback_url= callback_url
put_policy.callback_body= callback_body

# 生成上传 Token
uptoken = Qiniu::Auth.generate_uptoken(put_policy)

# 要上传文件的本地路径
filePath = './ruby-logo.png'

# 调用 upload_with_token_2 方法上传
code, result, response_headers = Qiniu::Storage.upload_with_token_2(
     uptoken,
     filePath,
     key,
     nil, # 可以接受一个 Hash 作为自定义变量，请参照 /products/kodo/development-guidelines/upload-types/0-vars
     bucket: bucket
)

#打印上传返回的信息
puts code
puts result
```

## 上传 & 预转持续化 [#上传--预转持续化]

以视频转码为例：

```
#!/usr/bin/env ruby

require 'qiniu'

# 构建鉴权对象
Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'

bucket = 'Bucket_Name'

key = 'my-ruby-logo.png'

put_policy = Qiniu::Auth::PutPolicy.new(
    bucket, # 存储空间
    key,    # 指定上传的资源名，如果传入 nil，就表示不指定资源名，将使用默认的资源名
    3600    # token 过期时间，默认为 3600 秒，即 1 小时
)

# 转码时使用的队列名称。
pipeline = 'abc' # 设定自己账号下的队列名称

# 要进行的转码操作。
fops = "avthumb/mp4/s/640x360/vb/1.25m"

# 可以对转码后的文件进行使用 saveas 参数自定义资源名，当然也可以不指定会默认命名并保存在上传文件所在的存储空间。
saveas_key = Qiniu::Utils.urlsafe_base64_encode('<目标 Bucket_Name>:<自定义资源名>')
fops = fops+'|saveas/'+saveas_key

put_policy.persistent_ops = fops
put_policy.persistent_pipeline = pipeline

# 生成上传 Token
uptoken = Qiniu::Auth.generate_uptoken(put_policy)

# 要上传文件的本地路径
filePath = './ruby-logo.png'

# 调用upload_with_token_2方法上传
code, result, response_headers = Qiniu::Storage.upload_with_token_2(
     uptoken,
     filePath,
     key,
     nil, # 可以接受一个 Hash 作为自定义变量，请参照 /products/kodo/development-guidelines/upload-types/0-vars
     bucket: bucket
)

#打印上传返回的信息
puts code
puts result
```

队列 pipeline 请参阅 [创建私有队列](https://portal.qiniu.com/dora/media-gate/pipeline) ；转码操作 具体参数请参阅 [音视频转码](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) ；saveas 请参阅 [处理结果另存](/products/dora/processing-mechanism/0-processing-results-save-saveas) 。

\*\*Tips：\*\*上面的Demo只是针对视频转码功能，如果您需要使用比如音视频切片、视频截图、视频拼接等功能只需要修改上面 fops 后面的参数即可，如： &#x2A;fops = “vframe/jpg/offset/1/w/480/h/360/rotate/90”* 就表示视频截图了。

可以看到上传成功后的行为主要是由 [上传凭证](/products/kodo/development-guidelines/security/2-upload-token) 中的 **上传策略** 来指定。其中 **上传策略** 可以指定的行为不止这些，具体请参阅 [上传策略](/products/kodo/development-guidelines/security/1-put-policy) 。

## 文件下载 [#文件下载]

生成下载链接：

```
#!/usr/bin/env ruby

require 'qiniu'

Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'

# 构建私有空间的链接
primitive_url = 'http://domain/key'
download_url = Qiniu::Auth.authorize_download_url(primitive_url)
puts download_url
```

## 空间资源管理 [#空间资源管理]

## 获取文件信息 [#获取文件信息]

```
#!/usr/bin/env ruby

require 'qiniu'

Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'

# 要测试的存储空间，并且这个资源名在存储空间中存在
bucket = 'Bucket_Name'
key = 'ruby-logo.png'

# 获取文件信息
code, result, response_headers = Qiniu::Storage.stat(
    bucket,     # 存储空间
    key         # 资源名
)
puts code
puts result
puts response_headers
```

## 移动单个文件 [#移动单个文件]

```
#!/usr/bin/env ruby

require 'qiniu'

Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'

# 要移动的存储空间，并且这个资源名在存储空间中存在
bucket = 'Bucket_Name'
key = 'ruby-logo.png'

# 移动到的目标存储空间名和目标资源名
dst_bucket = 'dst_bucket'
dst_key = 'dst_key'

# 移动文件
code, result, response_headers = Qiniu::Storage.move(
    bucket,         # 原存储空间
    key,            # 原资源名
    dst_bucket,     # 目标存储空间
    dst_key         # 目标资源名
)
puts code
puts result
puts response_headers
```

## 复制单个文件 [#复制单个文件]

```
#!/usr/bin/env ruby

require 'qiniu'

Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'

# 要复制的存储空间，并且这个资源名在存储空间中存在
bucket = 'Bucket_Name'
key = 'ruby-logo.png'

# 复制到的目标存储空间名和目标资源名
dst_bucket = 'dst_bucket'
dst_key = 'dst_key'

# 复制文件
code, result, response_headers = Qiniu::Storage.copy(
    bucket,         # 原存储空间
    key,            # 原资源名
    dst_bucket,     # 目标存储空间
    dst_key         # 目标资源名
)
puts code
puts result
puts response_headers
```

## 删除单个文件 [#删除单个文件]

```
#!/usr/bin/env ruby

require 'qiniu'

Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'

# 要删除的存储空间，并且这个资源名在存储空间中存在
bucket = 'Bucket_Name'
key = 'ruby-logo.png'

# 删除资源
code, result, response_headers = Qiniu::Storage.delete(
    bucket,     # 存储空间
    key         # 资源名
)

puts code
puts result
puts response_headers
```

## 列举文件条目 [#列举文件条目]

```
#!/usr/bin/env ruby

require 'qiniu'

Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'

# 要列举的存储空间名
bucket = 'Bucket_Name'

# 调用 list 接口，参数可以参考 /products/kodo/rs/4-list
code, result, response_headers, s, d = Qiniu::Storage.list(Qiniu::Storage::ListPolicy.new(
    bucket,   # 存储空间
    100,      # 列举的条目数
    'photo/', # 指定前缀
    ''        # 指定目录分隔符
))

# 打印出返回的状态码和信息
puts code
puts result
puts response_headers
```

## 抓取文件 [#抓取文件]

```
#!/usr/bin/env ruby

require 'qiniu'

Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'

# 需要抓取操作保存到的空间名
bucket = 'Bucket_Name'

# 抓取的 URL，需要外网可以访问到
target_url = 'https://oerugfbxb.qnssl.com/wp-content/themes/Earthshaker-1/images/logo.png'

# 抓取后保存的资源名
key = 'qiniu.png'

# 调用fetch方法
code, result, response_headers = Qiniu::Storage.fetch(
    bucket,
    target_url,
    key
)

# 打印返回的状态码以及信息
puts code
puts result
puts response_headers
```

## 触发持久化操作 [#触发持久化操作]

以视频转码为例：

```
#!/usr/bin/env ruby

require 'qiniu'
require 'qiniu/utils'

# 构建鉴权对象
Qiniu.establish_connection! access_key: '<YOUR_APP_ACCESS_KEY>',
                            secret_key: '<YOUR_APP_SECRET_KEY>'

# 要转码的文件所在的存储空间和资源名。
bucket = 'Bucket_Name'
key = '1.mp4'

# 转码时使用的队列名称。
pipeline = 'abc' # 设定自己账号下的队列名称

# 要进行的转码操作。
fops = "avthumb/mp4/s/640x360/vb/1.25m"

# 可以对转码后的文件进行使用 saveas 参数自定义资源名，当然也可以不指定会默认命名并保存在原文件所在的存储空间。
saveas_key = Qiniu::Utils.urlsafe_base64_encode('<目标 Bucket_Name>:<自定义资源名>')
fops = fops+'|saveas/'+saveas_key

pfops = Qiniu::Fop::Persistance::PfopPolicy.new(
    bucket,         # 存储空间
    key,            # 指定上传的资源名，如果传入 nil，就表示不指定资源名，将使用默认的资源名
    fops,
    'http://www.baidu.com/notify' # 处理结果通知接收 URL
)
pfops.pipeline = pipeline

code, result, response_headers = Qiniu::Fop::Persistance.pfop(pfops)
puts code
puts result
puts response_headers
```

\*\*Tips：\*\*上面的Demo只是针对视频转码功能，如果您需要使用比如音视频切片、视频截图、视频拼接等功能只需要修改上面 fops 后面的参数即可，如： &#x2A;fops = “vframe/jpg/offset/1/w/480/h/360/rotate/90”* 就表示视频截图了。

但这个只是将转码这个耗时的操作提交到队列中，要想知道转码操作现在的状态，需要根据返回的 **persitentId** 进行查询。如果您不方便持续轮询每个异步处理的进度和状态，可以异步处理完成后通知您们的业务服务器。这样就需要您在视频转码的例子中, 初始化 **PersistentFop** 时添加上 **notifyUrl**, 来通知您们的业务服务器。

## 错误处理 [#错误处理]

如果遇到错误，请将各个方法返回的 code、result、response\_headers 以如下格式输出。

```
#!/usr/bin/env ruby

require 'qiniu'

# 已在某处调用某个SDK方法

puts code.inspect
puts result.inspect
puts response_headers.inspect
```

## API参考手册 [#api参考手册]

* [对象存储API参考手册](/products/kodo/kodo-console-guide/0-an-overview-of-the-console)
* [数据处理API参考手册](/faq/dora)

## 相关资源 [#相关资源]

如果您有任何关于我们文档或产品的建议和想法，欢迎您通过以下方式与我们互动讨论：

* [技术论坛](http://segmentfault.com/qiniu) - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
* [提交工单](http://support.qiniu.com/) - 如果您的问题不适合在论坛讨论或希望及时解决，您也可以提交一个工单，我们的技术支持人员会第一时间回复您
* [博客](http://blog.qiniu.com/) - 这里会持续更新发布市场活动和技术分享文章
* [微博](http://weibo.com/qiniutek)
* [常见问题](https://support.qiniu.com/)

## 贡献代码 [#贡献代码]

1. Fork
2. 创建您的特性分支 git checkout -b my-new-feature
3. 提交您的改动 git commit -am ‘Added some feature’
4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature
5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

## 许可证 [#许可证]

Copyright © 2014 qiniu.com

基于 MIT 协议发布:

* [www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)


# Flutter SDK (/products/kodo/5-flutter-sdk)



最近更新时间: 2023-11-01 16:41:11

Flutter SDK 只包含了最终用户使用场景中的必要功能。相比服务端 SDK 而言，客户端 SDK 不会包含对云存储服务的管理和配置功能。

* [Flutter SDK 源码地址](https://github.com/qiniu/dart-sdk/blob/master/flutter/README.md)
* [Flutter SDK 下载地址](https://github.com/qiniu/dart-sdk/releases)

# 安全机制 [#安全机制]

该 SDK 未包含凭证生成相关的功能。开发者对安全性的控制应遵循 [安全机制](/products/kodo/development-guidelines/security) 中建议的做法，即客户端应向业务服务器每隔一段时间请求 [上传凭证](/products/kodo/development-guidelines/security/2-upload-token) ，而不是直接在客户端使用 AccessKey / SecretKey 生成对应的凭证。在客户端使用 SecretKey 会导致严重的安全隐患。

开发者可以在生成上传凭证前通过配置 [上传策略](/products/kodo/development-guidelines/security/1-put-policy) 来控制上传的后续动作，例如在上传完成后通过回调机制通知业务服务器。该工作在业务服务器端进行，因此非本 SDK 的功能范畴。

存储的服务端 SDK 提供了上传凭证的生成功能，请参考各个服务端语言的 SDK 文档。

# 安装 [#安装]

编辑你的 pubspec.yaml 文件，在 dependencies 添加 qiniu-flutter-sdk，如下：

```
dependencies:
  ...
  qiniu_flutter_sdk: // 这里输入你需要的版本
```

推荐使用最新版：v0.1.0

# 上传文件 [#上传文件]

SDK 内置两种上传方式：表单上传和分片上传，并根据具体情况，内部做了自动切换。表单上传使用一个 HTTP POST 请求完成文件的上传，因此比较适合较小的文件和较好的网络环境。相比而言，分片上传更能适应不稳定的网络环境，也比较适合上传比较大的文件（例如数百 MB 或更大）。

若需深入了解上传方式之间的区别，请参阅上传类型中 [表单上传](/products/kodo/development-guidelines/upload-types/1-form-upload) 和 [分片上传 V2](/products/kodo/rs/multipartupload-interface) 接口说明。

```
import 'package:qiniu_flutter_sdk/qiniu_flutter_sdk.dart';
 // 创建 storage 对象
  storage = Storage();

  // 创建 Controller 对象
  putController = PutController();

  // 添加任务进度监听
  putController.onProgress((double percent) {
    print('任务进度变化：已发送：$percent');
  });

  // 添加文件发送进度监听
  putController.onSendProgress((double percent) {
    print('已上传进度变化：已发送：$percent');
  });

  // 添加任务状态监听
  putController.addStatusListener((StorageStatus status) {
    print('状态变化: 当前任务状态：$status');
  });

  // 指定上传对象key
  key = '指定object名称';

  // 使用 storage 的 putFile 对象进行文件上传
  storage.putFile(File('./file.txt'), 'TOKEN', PutOptions(
    controller: putController,
    key: key,
  ))
  // 取消当前任务
  putController.cancel()
```

**storage**
使用前必须创建一个 Storage 实例。同时，在构造 Storage 时可以传入一个 Config 控制内部的一些行为，如下

```
 // 创建 storage 对象
  storage = Storage(Config(
    // 通过自己的 hostProvider 来使用自己的 host 进行上传
    hostProvider: HostProvider,
    // 可以通过实现 cacheProvider 来自己实现缓存系统支持分片断点续传
    cacheProvider: CacheProvider,
    // 如果你需要对网络请求进行更基础的一些操作，你可以实现自己的 HttpClientAdapter 处理相关行为
    httpClientAdapter: HttpClientAdapter,
    // 设定网络请求重试次数
    retryLimit: 3,
  ));
```

**PutController**
这里是一个重要的内容，对于整个上传任务的一些交互被封装到了这里， PutController 用于对上传任务添加进度、状态的监听，同时可以通过 PutController.cancel() 对正在上传的任务进行取消，使用姿势参考上面代码示例。
**putFile**
该接口内部封装了分片上传和表单上传两种实现，会根据文件的尺寸和上传配置信息自动选择使用分片还是直传的方式来上传对象。File指定上传对象本地路径，Token为上传凭证。
**PutOptions**
SDK默认在对象大小超过4MB使用分片上传，默认分片之间采用并发上传，并发大小为5，可以通过PutOptions中的参数控制，参数如下：

```
class PutOptions {
  /// 资源名，如果不传则后端自动生成
  final String key;

  /// 强制使用直传，不使用分片
  final bool forceBySingle;

  /// 使用分片上传时的分片大小，默认值 4，单位为 MB
  final int partSize;

  /// 并发上传的队列长度，默认值为 5
  final int maxPartsRequestNumber;

  /// 控制器
  final PutController controller;
}
```

**其他*&#x2A;
&#x2A;**HostProvider**&#x2A;
SDK 会根据 TOKEN 自动获取上传域名，不需要客户关系上传域名，除非你使用的是七牛的专有云服务，则可以通过实现自己的 HostProvider 来向自己的服务进行上传。
&#x2A;**CacheProvider**&#x2A;
SDK 支持分片断点续传功能，断点续传的信息通过 CacheProvider 提供的能力进行存储，如果你需要更好的体验，可以自己实现这个接口来对信息进行持久化的存储。
&#x2A;**HttpClientAdapter***
如果你需要对网络请求进行进一步的自定义处理时，你可以通过实现一个 HttpClientAdapter 来接管 SDK 的所有请求。

# API 参考 [#api-参考]

* [存储 API 参考](/products/kodo/3939-overview-of-the-api)

# 贡献代码 [#贡献代码]

1. 登录 [https://github.com](https://github.com)
2. Fork [git@github.com](mailto:git@github.com):qiniu/dart-sdk.git
3. 创建您的特性分支 (git checkout -b new-feature)
4. 提交您的改动 (git commit -am 'Added some features or fixed a bug')
5. 将您的改动记录提交到远程 git 仓库 (git push origin new-feature)
6. 然后到 github 网站的该 git 远程仓库的 new-feature 分支下发起 Pull Request


# Rust SDK (/products/kodo/6-rust)



最近更新时间: 2023-11-01 16:41:11

### Rust SDK 使用指南 [#rust-sdk-使用指南]

Rust SDK 基于<span id="Productname">七牛云</span> API 参考手册构建。使用此 SDK 构建您的网络应用程序，能让您以非常便捷地方式将数据安全地存储到<span id="Productname">七牛云</span>上。无论您的网络应用是一个网站程序，还是包括从云端（服务端程序）到终端（手持设备应用）的架构的服务或应用，通过<span id="Productname">七牛云存储</span>及其 SDK，都能让您应用程序的终端用户高速上传和下载，同时也让您的服务端更加轻盈。

Rust SDK 属于服务端 SDK 之一，包含以下特性：

* 通过提供多个不同的 Crate，为不同层次的开发都提供了方便易用的编程接口。
* 同时提供阻塞 IO 接口和基于 Async/Await 的异步 IO 接口。
* 提供大量的可供二次开发的 Trait，方便灵活定制，例如 HTTP 客户端提供了 `ureq`，`reqwest` 和 `isahc` 三种不同的库实现，也可以基于 `qiniu-http` 自行定制开发接入其他 HTTP 客户端实现；又例如 DNS 客户端提供了 `libc`，`c-ares`，`trust-dns` 三种不同的库实现，也可以基于 [Resolver](https://docs.rs/qiniu-http-client/latest/qiniu_http_client/trait.Resolver.html) 自行定制开发接入其他 DNS 客户端实现。

# 开源 [#开源]

* [Rust SDK 项目地址](https://github.com/qiniu/rust-sdk)
* [Rust SDK 发布地址](https://github.com/qiniu/rust-sdk/releases)

# 安装 [#安装]

Qiniu SDK for Rust 包含以下 Crates:

| Crate 链接                                                                                                                                                                    | 文档                                                                                                                                              | 描述                                                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [![qiniu-etag](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/qiniu-etag-1b0c0b7c34b3.webp)](https://crates.io/crates/qiniu-etag)                                  | [![docs.rs](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/docs-latest-blue-3ece8ba30895.webp)](https://docs.rs/qiniu-etag)            | Etag 算法库，实现七牛 Etag 算法                                                                                                                                                                                          |
| [![qiniu-credential](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/qiniu-credential-1b0c0b7c34b3.webp)](https://crates.io/crates/qiniu-credential)                | [![docs.rs](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/docs-latest-blue-3ece8ba30895.webp)](https://docs.rs/qiniu-credential)      | 七牛认证库，实现七牛认证接口以及签名相关算法                                                                                                                                                                                         |
| [![qiniu-upload-token](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/qiniu-upload-token-1b0c0b7c34b3.webp)](https://crates.io/crates/qiniu-upload-token)          | [![docs.rs](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/docs-latest-blue-3ece8ba30895.webp)](https://docs.rs/qiniu-upload-token)    | 七牛上传凭证，实现七牛上传策略和上传凭证接口以及相关算法                                                                                                                                                                                   |
| [![qiniu-http](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/qiniu-http-1b0c0b7c34b3.webp)](https://crates.io/crates/qiniu-http)                                  | [![docs.rs](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/docs-latest-blue-3ece8ba30895.webp)](https://docs.rs/qiniu-http)            | 七牛客户端 HTTP 接口，为不同的 HTTP 客户端实现提供相同的基础接口                                                                                                                                                                         |
| [![qiniu-ureq](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/qiniu-ureq-1b0c0b7c34b3.webp)](https://crates.io/crates/qiniu-ureq)                                  | [![docs.rs](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/docs-latest-blue-3ece8ba30895.webp)](https://docs.rs/qiniu-ureq)            | 基于 [Ureq](https://docs.rs/ureq) 库实现七牛客户端 HTTP 接口，对于使用 `qiniu-http-request`，`qiniu-apis`，`qiniu-objects-manager` 或 `qiniu-upload-manager` 的用户，可以直接启用 `ureq` 功能，将默认使用该 HTTP 客户端实现。需要注意的是，如果需要使用异步接口，则不能选择 `ureq` |
| [![qiniu-isahc](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/qiniu-isahc-1b0c0b7c34b3.webp)](https://crates.io/crates/qiniu-isahc)                               | [![docs.rs](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/docs-latest-blue-3ece8ba30895.webp)](https://docs.rs/qiniu-isahc)           | 基于 [Isahc](https://docs.rs/isahc) 库实现七牛客户端 HTTP 接口，对于使用 `qiniu-http-request`，`qiniu-apis`，`qiniu-objects-manager` 或 `qiniu-upload-manager` 的用户，可以直接启用 `isahc` 功能，将默认使用该 HTTP 客户端实现                             |
| [![qiniu-reqwest](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/qiniu-reqwest-1b0c0b7c34b3.webp)](https://crates.io/crates/qiniu-reqwest)                         | [![docs.rs](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/docs-latest-blue-3ece8ba30895.webp)](https://docs.rs/qiniu-reqwest)         | 基于 [Reqwest](https://docs.rs/reqwest) 库实现七牛客户端 HTTP 接口，对于使用 `qiniu-http-request`，`qiniu-apis`，`qiniu-objects-manager` 或 `qiniu-upload-manager` 的用户，可以直接启用 `reqwest` 功能，将默认使用该 HTTP 客户端实现                       |
| [![qiniu-http-client](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/qiniu-http-client-1b0c0b7c34b3.webp)](https://crates.io/crates/qiniu-http-client)             | [![docs.rs](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/docs-latest-blue-3ece8ba30895.webp)](https://docs.rs/qiniu-http-client)     | 基于 [qiniu-http](https://docs.rs/qiniu-http) 提供具有重试功能的 HTTP 客户端                                                                                                                                                 |
| [![qiniu-apis](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/qiniu-apis-1b0c0b7c34b3.webp)](https://crates.io/crates/qiniu-apis)                                  | [![docs.rs](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/docs-latest-blue-3ece8ba30895.webp)](https://docs.rs/qiniu-apis)            | 实现七牛 API 调用客户端接口                                                                                                                                                                                               |
| [![qiniu-objects-manager](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/qiniu-objects-manager-1b0c0b7c34b3.webp)](https://crates.io/crates/qiniu-objects-manager) | [![docs.rs](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/docs-latest-blue-3ece8ba30895.webp)](https://docs.rs/qiniu-objects-manager) | 实现七牛对象相关管理接口，包含对象的列举和操作                                                                                                                                                                                        |
| [![qiniu-upload-manager](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/qiniu-upload-manager-1b0c0b7c34b3.webp)](https://crates.io/crates/qiniu-upload-manager)    | [![docs.rs](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/docs-latest-blue-3ece8ba30895.webp)](https://docs.rs/qiniu-upload-manager)  | 实现七牛对象上传功能                                                                                                                                                                                                     |
| [![qiniu-sdk](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/qiniu-sdk-1b0c0b7c34b3.webp)](https://crates.io/crates/qiniu-sdk)                                     | [![docs.rs](/docs-assets/products/kodo/%286-sdk-downloads%29/6-rust/docs-latest-blue-3ece8ba30895.webp)](https://docs.rs/qiniu-sdk)             | 七牛 SDK 入口                                                                                                                                                                                                      |

# 鉴权 [#鉴权]

Rust SDK 的所有的功能，都需要合法的授权。授权凭证的签算需要<span id="Productname">七牛</span>账号下的一对有效的`Access Key`和`Secret Key`，这对密钥可以通过如下步骤获得：

1. <span id="Null">点击[注册🔗](https://portal.qiniu.com/signup)</span>开通<span id="Productname">七牛</span>开发者帐号
2. 如果已有账号，直接登录<span id="Productname">七牛</span>开发者后台，<span id="Null">点击[这里🔗](https://portal.qiniu.com/user/key)</span>查看 Access Key 和 Secret Key

以下所有代码示例都以 `qiniu-sdk` 作为入口。

<a id="io-put" />

# 文件上传 [#文件上传]

* <a href="#upload-flow">
    上传流程
  </a>
* <a href="#upload-token">
    客户端上传凭证
  </a>
  * <a href="#simple-uptoken">
      简单上传凭证
    </a>
  * <a href="#overwrite-uptoken">
      覆盖上传凭证
    </a>
  * <a href="#returnbody-uptoken">
      自定义上传回复凭证
    </a>
  * <a href="#callback-uptoken">
      带回调业务服务器的凭证
    </a>
  * <a href="#param-uptoken">
      带自定义参数的凭证
    </a>
  * <a href="#general-uptoken">
      综合上传凭证
    </a>
* <a href="#server-upload">
    服务器直传
  </a>
  * <a href="#upload-file">
      文件上传
    </a>
  * <a href="#upload-bytes">
      字节数组上传 / 数据流上传
    </a>
  * <a href="#upload-selfdefineParam">
      自定义参数上传
    </a>

### 上传流程 [#上传流程]

文件上传分为客户端上传（主要是指网页端和移动端等面向终端用户的场景）和服务端上传两种场景，具体可以参考文档[业务流程](/products/kodo/0-programming-model)。

服务端 SDK 在上传方面主要提供两种功能，一种是生成客户端上传所需要的上传凭证，另外一种是直接上传文件到云端。

<a id="upload-token" />

### 客户端上传凭证（需要依赖 `qiniu-sdk` 启用 `upload-token` 功能） [#客户端上传凭证需要依赖-qiniu-sdk-启用-upload-token-功能]

客户端（移动端或者 Web 端）上传文件的时候，需要从客户自己的业务服务器获取上传凭证，而这些上传凭证是通过服务端的 SDK 来生成的，然后通过客户自己的业务 API 分发给客户端使用。根据上传的业务需求不同，Rust SDK支持丰富的上传凭证生成方式。

<a id="simple-uptoken" />

#### 简单上传的凭证 [#简单上传的凭证]

最简单的上传凭证只需要 `access key`，`secret key` 和 `bucket` 就可以，并指定上传凭证的有效期。

```rust
use qiniu_sdk::upload_token::{UploadPolicy, credential::Credential, prelude::*};
use std::time::Duration;

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let credential = Credential::new(access_key, secret_key);
let upload_token = UploadPolicy::new_for_bucket(bucket_name, Duration::from_secs(3600))
    .build_token(credential, Default::default())?;
println!("{}", upload_token);
```

<a id="overwrite-uptoken" />

#### 覆盖上传的凭证 [#覆盖上传的凭证]

覆盖上传除了需要简单上传所需要的信息之外，还需要想进行覆盖的对象名称 `object name`，这个对象名称同时是客户端上传代码中指定的对象名称，两者必须一致。

```rust
use qiniu_sdk::upload_token::{UploadPolicy, credential::Credential, prelude::*};
use std::time::Duration;

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let credential = Credential::new(access_key, secret_key);
let upload_token = UploadPolicy::new_for_object(bucket_name, object_name, Duration::from_secs(3600))
    .build_token(credential, Default::default())?;
println!("{}", upload_token);
```

<a id="returnbody-uptoken" />

#### 自定义上传回复的凭证 [#自定义上传回复的凭证]

默认情况下，文件上传到存储之后，在没有设置 `return_body` 或者`回调`相关的参数情况下，<span id="Productname">七牛</span>返回给上传端的回复格式为 `hash` 和 `key`，例如：

```json
{"hash":"Ftgm-CkWePC9fzMBTRNmPMhGBcSV","key":"qiniu.jpg"}
```

有时候我们希望能自定义这个返回的 JSON 格式的内容，可以通过设置 `return_body` 参数来实现，在 `return_body` 中，我们可以使用<span id="Productname">七牛</span>支持的[魔法变量](/products/kodo/development-guidelines/upload-types/0-vars#magicvar)和[自定义变量](/products/kodo/development-guidelines/upload-types/0-vars#xvar)。

```rust
use qiniu_sdk::upload_token::{UploadPolicy, credential::Credential, prelude::*};
use std::time::Duration;

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let credential = Credential::new(access_key, secret_key);
let upload_token = UploadPolicy::new_for_object(bucket_name, object_name, Duration::from_secs(3600))
    .return_body("{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"bucket\":\"$(bucket)\",\"fsize\":$(fsize)}")
    .build_token(credential, Default::default())?;
println!("{}", upload_token);
```

则文件上传到<span id="Productname">七牛</span>之后，收到的回复内容如下：

```json
{"key":"qiniu.jpg","hash":"Ftgm-CkWePC9fzMBTRNmPMhGBcSV","bucket":"if-bc","fsize":39335}
```

<a id="callback-uptoken" />

#### 带回调业务服务器的凭证 [#带回调业务服务器的凭证]

上面生成的自定义上传回复的上传凭证适用于上传端（无论是客户端还是服务端）和<span id="Productname">七牛</span>服务器之间进行直接交互的情况下。在客户端上传的场景之下，有时候客户端需要在文件上传到<span id="Productname">七牛</span>之后，从业务服务器获取相关的信息，这个时候就要用到<span id="Productname">七牛</span>的上传回调及相关回调参数的设置。

```rust
use qiniu_sdk::upload_token::{UploadPolicy, credential::Credential, prelude::*};
use std::time::Duration;

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let credential = Credential::new(access_key, secret_key);
let upload_token = UploadPolicy::new_for_object(bucket_name, object_name, Duration::from_secs(3600))
    .callback(&["http://api.example.com/qiniu/upload/callback"], "", "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"bucket\":\"$(bucket)\",\"fsize\":$(fsize)}", "application/json")
    .build_token(credential, Default::default())?;
println!("{}", upload_token);
```

在使用了上传回调的情况下，客户端收到的回复就是业务服务器响应<span id="Productname">七牛</span>的 JSON 格式内容。
通常情况下，我们建议使用 `application/json` 格式来设置 `callback_body`，保持数据格式的统一性。实际情况下，`callback_body` 也支持 `application/x-www-form-urlencoded` 格式来组织内容，这个主要看业务服务器在接收到 `callback_body` 的内容时如何解析。例如：

```rust
use qiniu_sdk::upload_token::{UploadPolicy, credential::Credential, prelude::*};
use std::time::Duration;

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let credential = Credential::new(access_key, secret_key);
let upload_token = UploadPolicy::new_for_object(bucket_name, object_name, Duration::from_secs(3600))
    .callback(&["http://api.example.com/qiniu/upload/callback"], "", "key=$(key)&hash=$(etag)&bucket=$(bucket)&fsize=$(fsize)", "")
    .build_token(credential, Default::default())?;
println!("{}", upload_token);
```

<a id="param-uptoken" />

#### 带自定义参数的凭证 [#带自定义参数的凭证]

存储服务支持客户端上传文件的时候定义一些自定义参数，这些参数可以在 `returnBody` 和 `callbackBody` 里面和<span id="Productname">七牛</span>内置支持的魔法变量（即系统变量）通过相同的方式来引用。这些自定义的参数名称必须以 `x:` 开头。例如客户端上传的时候指定了自定义的参数 `x:user` 和 `x:age` 分别是 `String` 和 `usize` 类型。那么可以通过下面的方式引用：

```rust
upload_policy_builder.return_body("{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"bucket\":\"$(bucket)\",\"fsize\":$(fsize),\"user\":\"$(x:user)\",\"age\",$(x:age)}");
```

或者

```rust
upload_policy_builder.callback(&["http://api.example.com/qiniu/upload/callback"], "", "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"bucket\":\"$(bucket)\",\"fsize\":$(fsize),\"user\":\"$(x:user)\",\"age\",$(x:age)}", "application/json")
```

<a id="general-uptoken" />

#### 综合上传凭证 [#综合上传凭证]

上面的生成上传凭证的方法，都是通过设置[上传策略🔗](/products/kodo/development-guidelines/security/1-put-policy)相关的参数来支持的，这些参数可以通过不同的组合方式来满足不同的业务需求，可以灵活地组织你所需要的上传凭证。

<a id="server-upload" />

### 服务端直传（需要依赖 `qiniu-sdk` 启用 `upload` 功能） [#服务端直传需要依赖-qiniu-sdk-启用-upload-功能]

服务端直传是指客户利用<span id="Productname">七牛</span>服务端 SDK 从服务端直接上传文件到<span id="Productname">七牛云</span>，交互的双方一般都在机房里面，所以服务端可以自己生成上传凭证，然后利用 SDK 中的上传逻辑进行上传，最后从<span id="Productname">七牛云</span>获取上传的结果，这个过程中由于双方都是业务服务器，所以很少利用到上传回调的功能，而是直接自定义 `return_body` 来获取自定义的回复内容。

<a id="upload-file" />

#### 文件上传 [#文件上传-1]

最简单的就是上传本地文件，直接指定文件的完整路径即可上传。

```rust
use qiniu_sdk::upload::{
    apis::credential::Credential, AutoUploader, AutoUploaderObjectParams, UploadManager,
    UploadTokenSigner,
};
use std::{time::Duration};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let credential = Credential::new(access_key, secret_key);
let upload_manager = UploadManager::builder(UploadTokenSigner::new_credential_provider(
    credential,
    bucket_name,
    Duration::from_secs(3600),
))
.build();
let uploader: AutoUploader = upload_manager.auto_uploader();

let params = AutoUploaderObjectParams::builder().object_name(object_name).file_name(object_name).build();
uploader.upload_path("/home/qiniu/test.png", params)?;
```

在这个场景下，`AutoUploader` 会自动根据文件尺寸判定是否启用断点续上传，如果文件较大，上传了一部分时因各种原因从而中断，再重新执行相同的代码时，SDK 会尝试找到先前没有完成的上传任务，从而继续进行上传。

<a id="upload-bytes" />

#### 字节数组上传 / 数据流上传 [#字节数组上传--数据流上传]

可以支持将内存中的字节数组或实现了 `std::io::Read` 的实例上传到空间中。

```rust
use qiniu_sdk::upload::{
    apis::credential::Credential, AutoUploader, AutoUploaderObjectParams, UploadManager,
    UploadTokenSigner,
};
use std::{io::Cursor, time::Duration};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let credential = Credential::new(access_key, secret_key);
let upload_manager = UploadManager::builder(UploadTokenSigner::new_credential_provider(
    credential,
    bucket_name,
    Duration::from_secs(3600),
))
.build();
let uploader: AutoUploader = upload_manager.auto_uploader();

let params = AutoUploaderObjectParams::builder().object_name(object_name).file_name(object_name).build();
uploader.upload_reader(Cursor::new("hello qiniu cloud"), params)?;
```

<a id="upload-selfdefineParam" />

#### 自定义参数上传 [#自定义参数上传]

```rust
use qiniu_sdk::upload::{
    apis::credential::Credential, AutoUploader, AutoUploaderObjectParams, UploadManager, UploadTokenSigner,
};
use std::{io::Cursor, time::Duration};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let credential = Credential::new(access_key, secret_key);
let upload_manager = UploadManager::builder(
    UploadTokenSigner::new_credential_provider_builder(credential, bucket_name, Duration::from_secs(3600))
        .on_policy_generated(|builder| {
            builder
                .return_body("{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"fname\":\"$(x:fname)\",\"age\",$(x:age)}");
        })
        .build(),
)
.build();
let uploader: AutoUploader = upload_manager.auto_uploader();

let params = AutoUploaderObjectParams::builder()
    .object_name(object_name)
    .file_name(object_name)
    .insert_custom_var("fname", "123.jpg")
    .insert_custom_var("age", "20")
    .build();
uploader.upload_path("/home/qiniu/test.mp4", params)?;
```

<a id="io-get" />

# 下载文件 [#下载文件]

* <a href="#public-get">
    公开空间
  </a>
* <a href="#private-get">
    私有空间
  </a>

文件下载分为公开空间的文件下载和私有空间的文件下载。

<a id="public-get" />

### 公开空间 [#公开空间]

对于公开空间，其访问的链接主要是将空间绑定的域名拼接上空间里面的文件名即可访问，标准情况下需要在拼接链接之前，将文件名进行 `urlencode` 以兼容不同的字符。如果有其他访问处理需求，在文件名之后继续拼接即可。这个过程实际上不需要使用<span id="Productname">七牛</span> SDK 也可以完成。

```rust
use http::Uri;

let object_name = "公司/存储/qiniu.jpg";
let domain = "devtools.qiniu.com";
let mut path = "/".to_string();
url_escape::encode_path_to_string(object_name, &mut path);
let url = Uri::builder()
    .scheme("http")
    .authority(domain)
    .path_and_query(path)
    .build()?;
println!("{}", url);
```

<a id="private-get" />

### 私有空间（需要依赖 `qiniu-sdk` 启用 `credential` 功能） [#私有空间需要依赖-qiniu-sdk-启用-credential-功能]

对于私有空间，首先需要按照公开空间的文件访问方式构建对应的公开空间访问链接，然后再对这个链接进行私有授权签名。

```rust
use qiniu_sdk::credential::Credential;
use http::Uri;

let access_key = "access key";
let secret_key = "secret key";
let object_name = "公司/存储/qiniu.jpg";
let domain = "devtools.qiniu.com";
let mut path = "/".to_string();
url_escape::encode_path_to_string(object_name, &mut path);
let url = Uri::builder()
    .scheme("http")
    .authority(domain)
    .path_and_query(path)
    .build()?;
let credential = Credential::new(access_key, secret_key);
let url = credential.sign_download_url(url, Duration::from_secs(3600));
println!("{}", url);
```

<a id="rs" />

# 资源管理（需要依赖 `qiniu-sdk` 启用 `objects` 功能） [#资源管理需要依赖-qiniu-sdk-启用-objects-功能]

资源管理包括的主要功能有：

* <a href="#rs-stat">
    获取文件信息
  </a>
* <a href="#rs-chgm">
    修改文件类型
  </a>
* <a href="#rs-move">
    移动或重命名文件
  </a>
* <a href="#rs-copy">
    复制文件副本
  </a>
* <a href="#rs-delete">
    删除空间中的文件
  </a>
* <a href="#rs-delete-after-days">
    设置或更新文件生存时间
  </a>
* <a href="#rs-list">
    获取空间文件列表
  </a>
* <a href="#rs-batch">
    资源管理批量操作
  </a>
  * <a href="#rs-batch-stat">
      批量获取文件信息
    </a>
  * <a href="#rs-batch-chgm">
      批量修改文件类型
    </a>
  * <a href="#rs-batch-delete">
      批量删除文件
    </a>
  * <a href="#rs-batch-move">
      批量移动或重命名文件
    </a>
  * <a href="#rs-batch-copy">
      批量复制文件
    </a>
  * <a href="#rs-batch-restoreAr">
      批量解冻归档存储类型文件
    </a>

<a id="rs-stat" />

#### 获取文件信息 [#获取文件信息]

```rust
use qiniu_sdk::objects::{apis::credential::Credential, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);

let response = bucket.stat_object(object_name).call()?;
let entry = response.into_body();
println!("{}", entry.get_hash_as_str());
println!("{}", entry.get_size_as_u64());
println!("{}", entry.get_mime_type_as_str());
println!("{}", entry.get_put_time_as_u64());
```

<a id="rs-chgm" />

#### 修改文件类型 [#修改文件类型]

```rust
use qiniu_sdk::objects::{apis::credential::Credential, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);

bucket
    .modify_object_metadata(object_name, mime::APPLICATION_JSON)
    .call()?;
```

<a id="rs-move" />

#### 移动或重命名文件 [#移动或重命名文件]

移动操作本身支持移动文件到相同，不同空间中，在移动的同时也可以支持文件重命名。唯一的限制条件是，移动的源空间和目标空间必须在同一个机房。

`move_object_to` 操作支持强制覆盖选项，即如果目标文件已存在，可以设置强制覆盖参数 `is_force(true)` 来覆盖那个文件的内容。

```rust
use qiniu_sdk::objects::{apis::credential::Credential, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let to_bucket_name = "to bucket name";
let to_object_name = "new object name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);

bucket
    .move_object_to(object_name, to_bucket_name, to_object_name);
    .call()?;
```

<a id="rs-copy" />

#### 复制文件副本 [#复制文件副本]

文件的复制和文件移动其实操作一样，主要的区别是移动后源文件不存在了，而复制的结果是源文件还存在，只是多了一个新的文件副本。

```rust
use qiniu_sdk::objects::{apis::credential::Credential, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let to_bucket_name = "to bucket name";
let to_object_name = "new object name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);

bucket
    .copy_object_to(object_name, to_bucket_name, to_object_name);
    .call()?;
```

<a id="rs-delete" />

#### 删除空间中的文件 [#删除空间中的文件]

```rust
use qiniu_sdk::objects::{apis::credential::Credential, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);

bucket
    .delete_object(object_name);
    .call()?;
```

<a id="rs-delete-after-days" />

#### 设置或更新文件的生存时间 [#设置或更新文件的生存时间]

可以给已经存在于空间中的文件设置文件生存时间，或者更新已设置了生存时间但尚未被删除的文件的新的生存时间。

```rust
use qiniu_sdk::objects::{apis::credential::Credential, AfterDays, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let object_name = "object name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);

bucket
    .modify_object_life_cycle(object_name)
    .delete_after_days(AfterDays::new(10)) // 过期天数，该文件将于 10 天后删除
    .call()?;
```

<a id="rs-list" />

#### 获取空间文件列表 [#获取空间文件列表]

```rust
use qiniu_sdk::objects::{apis::credential::Credential, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);

let mut iter = bucket.list().iter();
while let Some(entry) = iter.next() {
    let entry = entry?;
    println!(
        "{}\n  hash: {}\n  size: {}\n  mime type: {}",
        entry.get_key_as_str(),
        entry.get_hash_as_str(),
        entry.get_size_as_u64(),
        entry.get_mime_type_as_str(),
    );
}
```

<a id="rs-batch" />

## 资源管理批量操作 [#资源管理批量操作]

<a id="rs-batch-stat" />

#### 批量获取文件信息 [#批量获取文件信息]

```rust
use qiniu_sdk::objects::{apis::credential::Credential, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);
let mut ops = bucket.batch_ops();
ops.add_operation(bucket.stat_object("qiniu.jpg"));
ops.add_operation(bucket.stat_object("qiniu.mp4"));
ops.add_operation(bucket.stat_object("qiniu.png"));

let mut iter = ops.call();
while let Some(result) = iter.next() {
    match result {
        Ok(entry) => {
            println!(
                "hash: {:?}\n  size: {:?}\n  mime type: {:?}",
                entry.get_hash_as_str(),
                entry.get_size_as_u64(),
                entry.get_mime_type_as_str(),
            );
        }
        Err(err) => {
            println!("{:?}", err);
        }
    }
}
```

<a id="rs-batch-chgm" />

#### 批量修改文件类型 [#批量修改文件类型]

```rust
use qiniu_sdk::objects::{apis::credential::Credential, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);
let mut ops = bucket.batch_ops();
ops.add_operation(bucket.modify_object_metadata("qiniu.jpg", mime::IMAGE_JPEG));
ops.add_operation(bucket.modify_object_metadata("qiniu.png", mime::IMAGE_PNG));
ops.add_operation(bucket.modify_object_metadata("qiniu.mp4", "video/mp4".parse()?));

let mut iter = ops.call();
while let Some(result) = iter.next() {
    match result {
        Ok(_) => {
            println!("Ok");
        }
        Err(err) => {
            println!("{:?}", err);
        }
    }
}
```

<a id="rs-batch-delete" />

#### 批量删除文件 [#批量删除文件]

```rust
use qiniu_sdk::objects::{apis::credential::Credential, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);
let mut ops = bucket.batch_ops();
ops.add_operation(bucket.delete_object("qiniu.jpg"));
ops.add_operation(bucket.delete_object("qiniu.png"));
ops.add_operation(bucket.delete_object("qiniu.mp4"));

let mut iter = ops.call();
while let Some(result) = iter.next() {
    match result {
        Ok(_) => {
            println!("Ok");
        }
        Err(err) => {
            println!("{:?}", err);
        }
    }
}
```

<a id="rs-batch-move" />

#### 批量移动或重命名文件 [#批量移动或重命名文件]

```rust
use qiniu_sdk::objects::{apis::credential::Credential, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);
let mut ops = bucket.batch_ops();
ops.add_operation(bucket.move_object_to("qiniu.jpg", bucket_name, "qiniu.jpg.move"));
ops.add_operation(bucket.move_object_to("qiniu.png", bucket_name, "qiniu.png.move"));
ops.add_operation(bucket.move_object_to("qiniu.mp4", bucket_name, "qiniu.mp4.move"));

let mut iter = ops.call();
while let Some(result) = iter.next() {
    match result {
        Ok(_) => {
            println!("Ok");
        }
        Err(err) => {
            println!("{:?}", err);
        }
    }
}
```

<a id="rs-batch-copy" />

#### 批量复制文件 [#批量复制文件]

```rust
use qiniu_sdk::objects::{apis::credential::Credential, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);
let mut ops = bucket.batch_ops();
ops.add_operation(bucket.copy_object_to("qiniu.jpg", bucket_name, "qiniu.jpg.move"));
ops.add_operation(bucket.copy_object_to("qiniu.png", bucket_name, "qiniu.png.move"));
ops.add_operation(bucket.copy_object_to("qiniu.mp4", bucket_name, "qiniu.mp4.move"));

let mut iter = ops.call();
while let Some(result) = iter.next() {
    match result {
        Ok(_) => {
            println!("Ok");
        }
        Err(err) => {
            println!("{:?}", err);
        }
    }
}
```

<a id="rs-batch-restoreAr" />

#### 批量解冻归档存储类型文件 [#批量解冻归档存储类型文件]

```rust
use qiniu_sdk::objects::{apis::credential::Credential, ObjectsManager};

let access_key = "access key";
let secret_key = "secret key";
let bucket_name = "bucket name";
let credential = Credential::new(access_key, secret_key);
let object_manager = ObjectsManager::builder(credential).build();
let bucket = object_manager.bucket(bucket_name);
let mut ops = bucket.batch_ops();
ops.add_operation(bucket.restore_archived_object("qiniu.jpg", 7));
ops.add_operation(bucket.restore_archived_object("qiniu.png", 7));
ops.add_operation(bucket.restore_archived_object("qiniu.mp4", 7));

let mut iter = ops.call();
while let Some(result) = iter.next() {
    match result {
        Ok(_) => {
            println!("Ok");
        }
        Err(err) => {
            println!("{:?}", err);
        }
    }
}
```

<a id="api-references" />

# API 参考 [#api-参考]

* [存储 API 参考](/products/kodo/3939-overview-of-the-api)

<a id="faq" />

# 最低支持的 Rust 版本（MSRV） [#最低支持的-rust-版本msrv]

* 1.60.0 Stable

<a id="related-resources" />

# 相关资源 [#相关资源]

如果您有任何关于我们文档或产品的建议和想法，欢迎您通过以下方式与我们互动讨论：

* [技术论坛](http://segmentfault.com/qiniu) - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
* [提交工单](https://support.qiniu.com/tickets/new) - 如果您的问题不适合在论坛讨论或希望及时解决，您也可以提交一个工单，我们的技术支持人员会第一时间回复您
* [博客](http://blog.qiniu.com) - 这里会持续更新发布市场活动和技术分享文章
* [微博](http://weibo.com/qiniutek)
* [常见问题](https://support.qiniu.com/question)

<span id="del_in_kodoe_docs_block_end" />

<a id="contribute-code" />

# 贡献代码 [#贡献代码]

1. Fork

2. 创建您的特性分支 git checkout -b my-new-feature

3. 提交您的改动 git commit -am 'Added some feature'

4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature

5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

<a id="license" />

# 许可证 [#许可证]

Copyright (c) 2022 qiniu.com

基于 MIT 协议发布:

* [www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)


# SDK 隐私政策 (/products/kodo/7-the-sdk-privacy-policy)



最近更新时间: 2026-08-27 19:29:04

# 引言 [#引言]

七牛严格遵守法律法规，按照业界成熟的安全与隐私标准，保护第三方开发者和其终端用户的个人信息。 《七牛 SDK 隐私政策》主要向第三方开发者和其终端用户说明我们如何处理个人信息（处理包括“收集、存储、使用、加工、传输、提供、公开等”）。

在注册、接入、使用七牛 SDK 产品和/或服务前，请第三方开发者和终端用户务必仔细阅读本声明。同时，请第三方开发者将本声明提供给第三方的终端用户，以便最终用户了解本声明相关内容并获得用户同意。如果第三方开发者或终端用户不同意本声明，应立即停止接入及使用七牛 SDK 产品和/或服务。 如对本声明内容有任何疑问、意见或建议，可随时通过本声明第十条提供的方式与我们联系。

 

本文将按如下顺序进行说明：

* 1、如何收集和使用第三方开发者和/或终端用户的个人信息

* 2、第三方终端用户的授权同意

* 3、如何使用 Cookie 等同类技术

* 4、如何共享、转让、公开披露第三方开发者和/或终端用户的个人信息

* 5、如何存储第三方开发者和/或终端用户的个人信息

* 6、如何保护第三方开发者和/或终端用户的个人信息安全

* 7、第三方开发者和/或终端用户如何管理其个人信息

* 8、如何处理儿童个人信息

* 9、如何变更与更新本声明

* 10、如何联系我们

本政策仅适用于七牛直接处理的个人信息。七牛主要为企业客户提供服务。若我们企业客户在他们的产品内嵌入了我们的存储服务，而您作为该企业客户的终端用户在与我们的产品互动过程中提供了您的个人信息。在这种场景下，我们作为信息处理方，遵照我们与企业客户的协议以及企业客户的指令处理您的个人信息，企业客户作为信息控制方对处理您的个人信息承担责任，并负有义务向您披露如何处理、保护您的个人信息。若您希望了解企业客户如何处理、分享、保护您的个人信息，请参阅该企业客户的隐私政策。若您对此有任何问题，请直接联系该企业客户。

# 一、如何收集和使用第三方开发者和/或终端用户的个人信息 [#一如何收集和使用第三方开发者和或终端用户的个人信息]

我们遵循正当、合法、必要的原则，基于本声明所述的以下目的，收集和使用：

* 1.第三方开发者和/或终端用户主动提供或我们直接收集的个人信息；

* 2.第三方终端用户在使用七牛 SDK 产品和/或服务过程中产生的个人信息；

* 3.从第三方开发者或者其他第三方获取的第三方开发者和/或终端用户的个人信息。

我们通常会在征得第三方开发者和/或终端用户同意后收集个人信息。我们会在本声明中载明收集的个人信息用途，如果我们要将收集个人信息用于本声明未载明的其它用途，我们会以合理的方式向第三方开发者和/或终端用户告知，并在使用前再次征得第三方开发者和/或终端用户的同意。

### 1. 第三方开发者和/或终端用户主动提供或我们直接收集的个人信息 [#1-第三方开发者和或终端用户主动提供或我们直接收集的个人信息]

为实现七牛 SDK 的存储功能，我们可能需要向第三方开发者和/或终端用户收集相关个人信息。以下将详细列出七牛 SDK 的业务功能及为实现该功能所需收集的个人信息情况，请在下述列表中了解七牛 SDK（包括调用的第三方
SDK）针对的具体功能、收集个人信息的类型，实现的功能目的。

七牛 SDK 除自身提供相关服务并需收集相关信息外，第三方开发者还有可能集成其他辅助业务的第三方 SDK，此部分第三方 SDK 所收集的个人信息请开发者和终端用户查看第三方 SDK 的隐私政策。

关于七牛 SDK 的信息清单如下：

<table>
  <tbody><tr><td>SDK 名称</td><td>操作系统</td><td>收集的个人信息</td><td>实现的功能目的</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="9">七牛上传 SDK</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="3">iOS</td></tr><tr><td>厂商、机型、系统版本</td><td>用于判断用户的的手机类型，以备兼容性及问题排查</td></tr><tr><td>网络类型（例如 Wi-FI、3G、4G）</td><td>用于通信质量不佳时的问题排查</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="3">Android</td></tr><tr><td>厂商、机型、系统版本</td><td>用于判断用户的的手机类型，以备兼容性及问题排查</td></tr><tr><td>网络类型（例如 Wi-FI、3G、4G）</td><td>用于通信质量不佳时的问题排查</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="2">鸿蒙</td></tr><tr><td>无</td><td>无</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="8">HappyDns SDK</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="2">iOS</td></tr><tr><td>用户 IP</td><td>静默状态或后台运行时周期性获取，用于监听用户是否切换运营商，以及时刷新 DNS 预解析结果，优化上传。</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="2">Android</td></tr><tr><td>用户 IP</td><td>静默状态或后台运行时周期性获取，用于监听用户是否切换运营商，以及时刷新 DNS 预解析结果，优化上传。</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="2">鸿蒙</td></tr><tr><td>无</td><td>无</td></tr></tbody>
</table>

### 2. 为实现 SDK 产品功能所需的权限 [#2-为实现-sdk-产品功能所需的权限]

为实现 SDK 产品的相应功能，我们需要通过开发者的应用申请开启客户端设备操作系统的特定权限。

<table>
  <tbody><tr><td>SDK名称</td><td>操作系统</td><td>权限名称</td><td>使用目的</td><td>是否必须</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="13">七牛上传 SDK</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="2">iOS</td></tr><tr><td>无</td><td>无</td><td>无</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="7">Android</td></tr><tr><td>android.permission.READ_EXTERNAL_STORAGE</td><td>用于读取 SDK 的配置和日志文件</td><td>必须</td></tr><tr><td>android.permission.WRITE_EXTERNAL_STORAGE</td><td>用于存储 SDK 的配置和日志文件</td><td>必须</td></tr><tr><td>android.permission.INTERNET</td><td>用于实现联网功能</td><td>必须</td></tr><tr><td>android.permission.ACCESS_WIFI_STATE</td><td>用于监控 WIFI 状态变化，提示用户当前网络环境</td><td>可选</td></tr><tr><td>android.permission.ACCESS_NETWORK_STATE</td><td>用于监控网络状态变化，提示用户当前网络环境</td><td>可选</td></tr><tr><td>android.permission.READ_PHONE_STATE</td><td>用于获取设备信息，用于排查用户问题</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="3">鸿蒙</td></tr><tr><td>SystemCapability.Communication.NetStack</td><td>用于实现联网功能</td><td>必须</td></tr><tr><td>SystemCapability.FileManagement.File.FileIO</td><td>临时缓存上传文件，优化上传操作</td><td>必须</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="8">HappyDns SDK</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="2">iOS</td></tr><tr><td>无</td><td>无</td><td>无</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="3">Android</td></tr><tr><td>android.net.conn.CONNECTIVITY_CHANGE</td><td rowspan="2">用于监听网络变化、辅助支持 DNS 预解析，便于提前对上传的域名进行解析并进行缓存、以提高在弱网环境下文件上传的成功率</td><td>可选</td></tr><tr><td>android.intent.action.USER_PRESENT</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="2">鸿蒙</td></tr><tr><td>无</td><td>无</td><td>无</td></tr></tbody>
</table>

请注意，在不同设备和系统中，权限显示方式及关闭方式可能有所不同，请终端用户参考其使用的设备及操作系统开发方的说明或指引。当终端用户关闭权限即代表其取消了相应的授权，我们和开发者将无法继续收集和使用对应的个人信息，也无法为终端用户提供上述与该等授权所对应的功能。

### 3. 我们从第三方获得的第三方开发者和/或终端用户的个人信息 [#3-我们从第三方获得的第三方开发者和或终端用户的个人信息]

我们可能从第三方开发者授权同意的第三方（我们的合作方）处间接获取第三方开发者和/或终端用户的个人信息，获取的个人信息是为实现七牛SDK产品和/或服务必要功能所必需的最少数量。如我们收集的信息无法单独或结合其他信息识别到第三方开发者和/或终端用户的个人身份，其不属于法律意义上的个人信息。

我们会在收集前要求第三方对个人信息来源的合法性作出承诺，并向第三方开发者和/或终端用户告知共享的目的、信息等内容，在依法取得第三方开发者和/或终端用户同意后收集个人信息，确保在已获得的个人信息处理的授权同意范围内进行共享。

如第三方有违反法律法规要求或约定的行为，我们会立即停止从该方收集信息、停止合作并采取相应的补救措施将损失减少到最小；同时，我们会使用不低于对自身用户个人信息同等的保护水平对间接获取的个人信息进行保护，在间接获取个人敏感信息时，我们会采用更加严格的（如传输加密等）安全保障措施。

### 4. 以下情形中，我们收集、使用个人信息无需征得第三方开发者和/或终端用户的授权同意 [#4-以下情形中我们收集使用个人信息无需征得第三方开发者和或终端用户的授权同意]

* 4.1 与个人信息控制者履行法律法规规定的义务相关的；
* 4.2 与国家安全、国防安全直接相关的；
* 4.3 与公共安全、公共卫生、重大公共利益直接相关的；
* 4.4 与刑事侦查、起诉、审判和判决执行等直接相关的；
* 4.5 出于维护个人信息主体或其他个人的生命、财产等重大合法权益但又很难得到本人同意的；
* 4.6 所涉及的个人信息是个人信息主体自行向社会公众公开的；
* 4.7 根据个人信息主体要求签订和履行合同所必需的；
* 4.8 从合法公开披露的信息中收集的第三方开发者和/或终端用户的个人信息的，如合法的新闻报道、政府信息公开等渠道；
* 4.9 维护所提供产品或服务的安全稳定运行所必需的，例如发现、处置产品或服务的故障。

### 5. 个人信息的使用规则 [#5-个人信息的使用规则]

我们会根据本声明和/或与第三方开发者的合同约定，并仅为实现七牛 SDK
产品和/或服务功能，对所收集的个人信息进行处理。若需要将收集的个人信息用于其他目的，我们会以合理方式告知第三方开发者和/或终端用户，并在第三方开发者获得终端用户同意后和/或单独获得终端用户同意后进行使用。 我们向第三方开发者提供的 SDK
产品和/或服务停止运营后，或者第三方开发者和/或终端用户撤回个人信息的授权后，或者在第三方开发者和/或终端用户注销账号后，我们将会于合理的时间内销毁或匿名化处理从第三方开发者和/或终端用户处接收的所有个人信息，除非法律另有规定。

# 二、第三方终端用户的授权同意 [#二第三方终端用户的授权同意]

第三方开发者将七牛 SDK 产品和/或服务集成到其第三方中，为向终端用户提供七牛 SDK 产品和/或服务，我们会以合法合规的方式收集、存储、加工来自于第三方开发者和/或终端用户的个人信息。

请第三方开发者知悉并同意：

第三方开发者已经遵守并将持续遵守适用的法律、法规和监管要求收集、使用和处理第三方终端用户的个人信息，包括但不限于制定和公布有关个人信息保护声明或隐私政策等；

第三方开发者已经告知第三方终端用户并且已经获得终端用户充分、必要且明确的授权、同意和许可（包括获取了儿童监护人对提供终端用户是儿童的个人信息的授权同意）、为提供七牛 SDK
产品和/或服务以及与第三方功能对应的目的，我们会收集和共享以及如何使用（包括允许我们根据本声明的规定收集和处理）第三方终端用户的个人信息；

除非适用法律另有规定，第三方开发者已经告知终端用户并且获得终端用户充分必要的授权、同意和许可，允许我们对已经收集的个人信息进行去标识化处理，并且在符合相关法律法规的前提下，可以将收集、处理的信息用于本声明第一条列明的用途；

第三方开发者已经向终端用户提供了易于操作的用户权利实现机制，并说明了终端用户可以如何以及何时行使选择权、如何访问、更正其个人信息，以及行使删除权、更改其授权同意的范围等操作。

# 三、如何使用 Cookie 等同类技术 [#三如何使用-cookie-等同类技术]

当第三方开发者访问、登录、使用七牛 SDK 时，为确保网站正常运转，我们可能会在第三方开发者的计算机或移动设备上通过 Cookie 缓存功能使用相关信息。Cookie 通常包含当前登录帐号、站点地址、浏览次数。运用 Cookie
技术，我们能够为第三方开发者提供更加周到的个性化服务，并允许第三方开发者设定第三方开发者特定的服务选项。

### 1.什么是Cookie？ [#1什么是cookie]

Cookie 是一种可让网站服务器将数据存储于客户端或从客户端中读取数据的中立技术。

Cookie 文件是存储了一些与用户访问网站有关信息的文件，格式为.txt。

Cookie 内容通常均经过加密。

安全的Cookie技术会为用户在上网时提供更为便捷的服务。

### 2.七牛使用Cookie的目的 [#2七牛使用cookie的目的]

Cookie 对提升用户的网络使用体验十分重要，七牛使用Cookie一般出于以下目的：

* 2.1 身份验证

Cookie可在您接入我们的服务时通知我们，以使我们可验证您的身份信息，以确保您的账号安全。

例如，Cookie技术可在您登入七牛服务时通知我们，因此，我们能够在您访问所有七牛服务的站点时，识别是否您本人安全登录，向您显示与您相关的信息。

* 2.1 偏好设置

Cookie可帮助我们按照您所希望的服务样式、外观的个性化设置为您提供服务。

例如， Cookie技术可记录您是否已经阅读过一些提示性的展现，防止重复提示对您造成骚扰；一些阅读展现(如字体大小等)方面您本人偏好的设定，我们也会存放于Cookie中，在您访问时自动为您调整到您上次设定的值。

* 2.3 安全

Cookie可帮助我们保障数据和服务的安全性，排查针对我们的产品和服务的作弊、黑客、欺诈行为。

例如，Cookie可以存放票据信息，能够由服务器验证是否是您自主在本站点的正常登录，通过票据中的加密信息，阻止多种类型的攻击，防止跨站信息窃取访问，防止身份冒充访问。

* 2.4 功能与服务

Cookie可帮助我们为用户提供更好的产品和服务。

例如，Cookie可以在您进行登录时，通过存储的信息，帮您填入您最后一次登入的账户名称，提高您的操作效率。

* 2.5 效率

Cookie可以避免不必要的服务器负载，提高服务效率，节省资源、能源。

例如，Cookie可帮助我们优化在服务器之间路由流量，并且了解不同用户加载我们服务时的速度，有时，我们或会利用Cookie让您正在使用时加载及响应得更快。

* 2.6 分析与研究

我们使用这些Cookie来了解、改善我们的产品和服务，为新产品或功能的研发提供参考数据。

例如，我们会使用Cookie来了解您使用我们服务的方式，以求改善用户体验。

例如您在接入我们服务时，在各个步骤所耗费的时间，我们会收集此信息用以分析研究能够进一步优化和改善的方面。

* 2.7 如何管理Cookie

大多数浏览器均为用户提供了管理Cookie 的功能。

当用户在进行浏览器的Cookie设置时，可以允许自己信任的网站启用 Cookie功能，禁止其他网站使用Cookie功能。

但请注意，如果停用Cookie，您可能无法享受最佳的服务体验，某些服务也可能无法正常使用。

# 四、如何共享、转让、公开披露第三方开发者和/或终端用户的个人信息 [#四如何共享转让公开披露第三方开发者和或终端用户的个人信息]

### 1. 共享 [#1-共享]

一般情况下，我们不会与我们的关联公司、合作伙伴及第三方共享第三方开发者和/或终端用户的必要的个人信息，除非为实现本声明第一条中所提及目的的需要。

如存在分享的行为，我们会要求关联公司、合作伙伴及第三方提供数据安全能力和信息安全资质（如等级保护测评、信息安全管理体系等）证明。在个人敏感信息的处理上，我们会要求第三方采用数据脱敏加密技术，从而更好地保护个人信息。如果第三方开发者和/或终端用户对第三方处理个人信息有异议或发现这些第三方存在风险时，请按照本声明第十条所述方式联系我们。

我们的关联公司、合作伙伴及第三方如要改变个人信息的处理目的，我们会再次征求第三方开发者和/或终端用户的同意。

### 2. 转让 [#2-转让]

我们不会将第三方开发者和/或终端用户的个人信息转让给任何公司、组织和个人，但以下情况除外： 2.1 事先获得第三方开发者和/或终端用户明确的同意或授权； 2.2
在涉及合并、收购、资产转让或类似的交易时，如涉及到个人信息转让，我们会要求新的持有第三方开发者和/或终端用户个人信息的公司、组织继续受本隐私声明的约束，否则，我们将要求该公司、组织重新向第三方开发者和/或终端用户征求授权同意。

### 3. 公开披露 [#3-公开披露]

我们不会公开披露第三方开发者和/或终端用户的个人信息，除非：

* 3.1 获得第三方开发者和/或终端用户的明确同意后；
* 3.2 在法律法规、法律程序、诉讼或政府主管部门强制要求的情况下。

### 4. 共享、转让、公开披露个人信息时事先征得授权同意的例外 [#4-共享转让公开披露个人信息时事先征得授权同意的例外]

请理解，在以下情形中，根据法律法规及国家标准，我们共享、转让、公开披露第三方开发者和/或终端用户的个人信息，无需事先征得第三方开发者和/或终端用户的授权同意：

* 4.1 与个人信息控制者履行法律法规规定的义务相关的；
* 4.2 与国家安全、国防安全有关的；
* 4.3 与公共安全、公共卫生、重大公共利益直接相关的；
* 4.4 与刑事侦查、起诉、审判和判决执行等直接相关的；
* 4.5 出于维护第三方开发者和/或终端用户或其他个人的生命、财产等重大合法权益但又很难得到本人同意的；
* 4.6 第三方开发者和/或终端用户自行向社会公众公开的个人信息；
* 4.7 从合法公开披露的信息中收集个人信息的，如合法的新闻报道、政府信息公开等渠道。

请知悉，如我们收集的信息无法单独或结合其他信息识别到第三方开发者和/或终端用户的个人身份，其不属于法律意义上的个人信息，此类处理后数据的共享、转让、公开披露，无需另行向第三方开发者和/或终端用户通知并征得同意。

# 五、如何存储第三方开发者和/或终端用户的个人信息 [#五如何存储第三方开发者和或终端用户的个人信息]

### 1. 存储方式和期限 [#1-存储方式和期限]

我们会通过安全的方式存储第三方开发者和/或终端用户的信息，包括本地存储、数据库和服务器日志。
一般情况下，我们只会在为实现本声明所述目的所必需的最短时间内或法律法规规定或个人信息主体另行授权同意的条件/范围内存储第三方开发者和/或终端用户的个人信息。但在下列情况下，且仅出于下列情况相关的目的，我们有可能需要较长时间保留第三方开发者和/或终端用户的个人信息：

* 1.1 遵守适用的法律法规等有关规定；
* 1.2 遵守法院判决、裁定或其他法律程序的要求；
* 1.3 遵守相关政府机关或其他有权机关的要求；
* 1.4 为执行相关服务协议或本声明、维护社会公共利益、处理投诉/纠纷，保护我们的客户、我们或我们的关联公司、其他用户或雇员的人身和财产安全或合法权益所合理必需的用途。

### 2. 存储地域 [#2-存储地域]

我们会按照法律法规规定，将境内收集的个人信息存储于中国境内。 如需跨境传输或存储的，我们会向第三方开发者和/或终端用户告知个人信息出境的目的、接收方、安全保证措施和安全风险，并征得第三方开发者和/或终端用户的同意。

# 六、如何保护第三方开发者和/或终端用户的个人信息安全 [#六如何保护第三方开发者和或终端用户的个人信息安全]

### 1. 安全保护措施 [#1-安全保护措施]

我们已使用符合业界标准的安全防护措施保护第三方开发者和/或终端用户提供的个人信息，防止数据遭到未经授权访问、公开披露、使用、修改、损毁、泄漏或丢失。 我们采用业界领先的技术保护措施。我们使用的技术手段包括但不限于防火墙、加密（例如
SSL）、去标识化或匿名化处理、访问控制措施等。此外，我们还会不断加强将 SDK 集成到第三方上的安全能力。
我们建立了专门保障个人信息安全的管理制度、流程和组织。我们也会审查该管理制度、流程和组织，以防未经授权的人员擅自访问、使用或披露用户的信息。

### 2. 安全事件处置措施 [#2-安全事件处置措施]

若发生个人信息泄露、损毁、丢失等安全事件，我们会启动应急预案，阻止安全事件扩大。安全事件发生后，我们会及时以推送通知、邮件等形式向第三方开发者和/或终端用户告知安全事件的基本情况、我们即将或已经采取的处置措施和补救措施，以及我们对第三方开发者和/或终端用户的应对建议。

# 七、第三方开发者和/或终端用户如何管理其个人信息 [#七第三方开发者和或终端用户如何管理其个人信息]

我们非常重视第三方开发者和/或终端用户对个人信息的管理，并尽全力提供对个人信息的查询、访问、修改、删除、投诉举报以及设置隐私功能等的相关权利，以使第三方开发者和/或终端用户有能力保障自身的隐私和信息安全。

### 1. 针对第三方开发者 [#1-针对第三方开发者]

第三方开发者访问、修改和删除个人信息的范围和方式将取决于第三方开发者使用的开发者平台的功能设置，也可以按照本声明第十条所述方式与我们联系。

### 2. 针对第三方终端用户 [#2-针对第三方终端用户]

由于第三方终端用户不是我们的直接用户，我们建议：

* 2.1 当终端用户所使用的第三方中某项功能由七牛SDK产品和/或服务提供，终端用户可以在使用我们服务的过程中，访问、修改和删除第三方开发者提供的注册信息和其他个人信息，也可按照本声明第十条所述方式与我们联系；
* 2.2 当终端用户直接向我们主张个人信息主体权利时，应提供必要的证明文件，我们还会对终端用户进行身份验证。我们会向第三方开发者核实终端用户身份以保障终端用户第三方账号安全的情况下，响应终端用户的相关请求；
* 2.3 当终端用户直接向我们主张个人信息主体权利时，根据第三方开发者的隐私政策或个人信息保护声明，我们还可能将与终端用户个人信息相关的请求直接发送给该第三方开发者，要求其处理和/或寻求帮助。

### 3. 响应第三方开发者和/或终端用户的合理请求 [#3-响应第三方开发者和或终端用户的合理请求]

我们会响应第三方开发者和/或终端用户上述的合理请求，如无端重复、需要过多技术手段（例如，需要开发新系统或从根本上改变现行惯例）、给他人合法权益带来风险或者非常不切实际（例如，涉及备份磁盘上存放的信息）的请求，我们可能会予以拒绝。
在以下情形中，我们将无法响应第三方开发者和/或终端用户的请求：

* 3.1 与我们履行法律法规规定的义务相关的；
* 3.2 与国家安全、国防安全直接相关的；
* 3.3 与公共安公共卫生、重大公共利益直接相关的；
* 3.4 与犯罪侦查、起诉、审判和执行判决等直接相关的；
* 3.5 我们有充分证据表明第三方开发者和/或终端用户存在主观恶意或滥用权利的；
* 3.6 出于维护第三方开发者和/或终端用户或其他个人的生命、财产等重大合法权益但又很难得到本人同意的；
* 3.7 响应第三方开发者和/或终端用户的请求将导致第三方开发者或其他个人、组织的合法权益受到严重损害的；
* 3.8 涉及商业秘密的。 如第三方开发者和/或终端用户的对上述权利实现存在疑问，可以根据本声明第十条所述方式与我们联系。

# 八、如何处理儿童个人信息 [#八如何处理儿童个人信息]

请第三方开发者确保是18周岁（含）以上人士。请第三方开发者理解并知悉，如果第三方是针对儿童用户的，请第三方开发者务必确保第三方终端用户（儿童）的监护人已经阅读并同意了第三方的隐私政策以及本文，并且经其同意后提供儿童个人信息给我们，以实现第三方在隐私政策中所述的相关功能。

如果第三方开发者的第三方是针对儿童并为儿童用户设计和开发的，请务必确保该第三方终端用户（儿童）的监护人已经阅读并同意了第三方的隐私政策/个人信息保护声明以及本文，并且授权同意提供儿童个人信息给我们以实现第三方的相关功能。

如果我们在不知情的情况下收集了儿童的个人信息，我们将及时对其进行删除，除非法律法规要求我们保留此类资料。如果第三方开发者和/或终端用户认为我们错误或意外地向儿童收集了信息，请按本声明第十条所述方式及时联系我们。如果经我们发现第三方开发者未获得儿童的监护人同意向我们提供儿童个人信息的，我们将尽快删除该儿童的个人信息并确保不对其进一步处理。

# 九、如何变更与更新本声明 [#九如何变更与更新本声明]

为给第三方开发者提供更好的服务以及随着本平台产品和/或服务的不断发展与变化，我们可能会适时对本声明进行修订。

当本声明的条款发生变更时，我们会在版本更新时以弹窗、红点提示、网站公告等方式进行提示，并说明生效日期。此外，如果更新后的本声明对第三方终端用户的权利有所影响，还需要请第三方开发者适时更新第三方的隐私政策。

对于重大变更，我们还会提供更为显著的通知（包括对于某些服务，我们会通过电子邮件或站内信形式或公告形式发送通知，说明本声明的具体变更内容）。因此，请随时查看和了解本声明内容。如果第三方开发者和/或终端用户不同意接受本声明，请停止接入和使用我们的服务。
本声明所指的重大变更包括但不限于：

我们的服务模式发生重大变化。如处理个人信息的目的、类型、个人信息的使用方式等；

我们在所有权结构、组织架构等方面发生重大变化。如业务调整、破产、并购等引起的所有者变更等；

个人信息共享、转让或公开披露的主要对象发生变化；

个人信息处理方面的权利及其行使方式发生重大变化；

负责处理个人信息安全的责任部门、联络方式及投诉渠道发生变化；

个人信息安全影响评估报告表明存在高风险。

本声明是七牛各 SDK 开发者平台服务协议的重要组成部分。我们还会将本声明的旧版本存档，供第三方开发者和/或终端用户查阅。

# 十、如何联系我们 [#十如何联系我们]

如第三方开发者和/或终端用户对本声明或个人信息相关事宜有疑问，可以通过以下方式与我们取得联系：

通过七牛客服电话 400-101-8589 与我们联系进行在线咨询；

邮寄信件至：中国上海市浦东新区浦东软件园Q座七牛云法务部（收）邮编：201203。

我们将及时验证请求人身份并尽快审核所涉问题，并于十五个工作日内予以回复。

# 十一、其它 [#十一其它]

《七牛隐私政策》是七牛统一适用的一般性隐私条款，其中所规定的用户权利及信息安全保障措施均适用于第三方开发者和/或终端用户。如《七牛隐私政策》与本声明存在不一致或矛盾之处，请以本声明为准。

我们请第三方开发者特别注意：当第三方开发者进行个人信息的处理活动，如果符合以下任何一项条件，请第三方开发者注意同时遵守《欧盟通用数据保护条例》（General Data Protection Regulation，以下简称 “GDPR”）：

* 第三方开发者在欧盟经济区域（“EEA”），无论该处理活动是否在欧盟进行；
* 向在 EEA 的个人提供商品或服务（不论是否有偿），或者监视其在 EEA 内的行为；
* 不在 EEA 内，但根据国际公法适用欧盟成员国法律（例如 EEA 成员国的使馆或领事馆）。

如果第三方开发者和/或终端用户来自EEA，我们收集和使用上述个人信息的法律依据将取决于相关个人信息以及我们收集信息的具体背景。 对于 EEA
中的第三方开发者和/或终端用户，有权根据适用的数据保护法律向主管数据保护机构投诉或向具有管辖权的法院提起诉讼。 如果第三方开发者和/或终端用户对我们收集和使用个人信息的法律依据有疑问或需要进一步信息的，请根据本声明第十条所述方式与我们联系。


# 鸿蒙(Harmony) SDK (/products/kodo/8-kodo-harmony-sdk)



最近更新时间: 2024-05-08 10:58:48

## 快速使用 [#快速使用]

1. 安装SDK

```bash
ohpm install @qiniu/upload
```

2. 导入SDK

```typescript
import { createDirectUploadTask, createMultipartUploadV1Task, createMultipartUploadV2Task, UploadFile } from '@qiniu/upload';
```

3. 创建上传任务

```typescript
// 创建上传数据
const file = UploadFile.fromUri('datashare://xxxx')
const file = UploadFile.fromPath('/data/storage/xxx')
const file = UploadFile.fromString('string content')
const file = UploadFile.fromArrayBuffer(new ArrayBuffer(1e3))

// 创建直传任务
const uploadTask = createDirectUploadTask(file, config);

// 创建分片上传任务
const uploadTask = createMultipartUploadV2Task(file, config);

// 部分老私有云不支持 v2，推荐用 v1
const uploadTask = createMultipartUploadV1Task(file, config);
```

1. 设置任务回调函数

```typescript
// 设置进度回调函数
uploadTask.onProgress((progress, context) => {
  // 处理进度回调
});

// 设置完成回调函数
uploadTask.onComplete((result, context) => {
  // 处理完成回调
});

// 设置错误回调函数
uploadTask.onError((error, context) => {
  // 处理错误回调
});
```

5. 启动任务

```typescript
uploadTask.start()
```

6. 简单模式

如果你不需要关心进度信息，可以通过 start 快速获取任务的状态信息

```
createMultipartUploadV2Task(file, config).start()
 .then((result) => {
    // 处理任务完成结果
  })
  .catch((error) => {
    // 处理任务启动失败错误
  });
```

## 接口说明 [#接口说明]

### TokenProvider [#tokenprovider]

```typescript
type TokenProvider = () => Promise<string>
```

* 一个用于获取上传所需 token 的函数类型。
* 返回一个 Promise，该 Promise 提供上传所需的 token。

### Context [#context]

```typescript
interface Context<ProgressKey extends string = string> {
  host?: Host;
  token?: Token;
  result?: string;
  error?: UploadError;
  progress: Progress<ProgressKey>;
}
```

* 上传的上下文接口，用于存储任务相关的信息。
* `host`：上传使用的 host。
* `token`：上传使用的 token。
* `result`：上传成功的信息。
* `error`：队列的错误。
* `progress`：整体的任务进度信息。

### UploadConfig [#uploadconfig]

```typescript
interface UploadConfig {
  tokenProvider: TokenProvider;
  apiServerUrl?: string;
  uploadHosts?: []string;
  logLevel?: LogLevel;
  protocol?: HttpProtocol;
  vars?: Record<string, string>;
}
```

* 上传配置接口，用于配置上传任务的相关参数。
* `tokenProvider`：用于获取上传所需 token 的函数，必传。
* `apiServerUrl`：服务的接口地址，可选；默认为七牛公有云，示例：\<[https://api.qiniu.com](https://api.qiniu.com)> 该配置仅当未设置 `uploadHosts` 时生效，SDK 将会通过指定的 api 服务提供的接口来动态获取上传地址，私有云请联系集群运维人员，并确认集群是否支持 `v4/query` 接口
* `uploadHosts`: 上传服务地址，可选；手动指定上传服务地址，示例：up.qiniu.com
* `protocol`：HTTP 协议，可选，默认 HTTPS。
* `logLevel`：日志级别，可选。
* `vars`: 上传过程中的自定义变量，可选。

### OnError [#onerror]

```typescript
type OnError = (error: UploadError, context: Context) => void;
```

* 错误回调函数类型。

### OnProgress [#onprogress]

```typescript
type OnProgress = (progress: Progress, context: Context) => void;
```

* 进度回调函数类型。

#### Progress [#progress]

```typescript
type Progress<Key extends string = string> = {
  /** 上传的文件总大小；单位 byte */
  size: number
  /** 目前处理的百分比进度；范围 0-1 */
  percent: number
  /** 具体每个部分的进度信息； */
  details: Record<Key, {
    /** 子任务的处理数据大小；单位 byte */
    size: number
    /** 目前处理的百分比进度；范围 0-1 */
    percent: number
    /** 该处理是否复用了缓存； */
    fromCache: boolean
  }>
}
```

### OnComplete [#oncomplete]

```typescript
type OnComplete = (result: string, context: Context) => void;
```

* 完成回调函数类型。
* 接收一个上下文参数，并返回 `void`。

### UploadTask [#uploadtask]

```typescript
interface UploadTask {
  onProgress(fn: OnProgress): void;
  onComplete(fn: OnComplete): void;
  onError(fn: OnError): void;
  cancel(): Promise<Result>;
  start(): Promise<Result>;
}
```

* 上传任务接口，用于控制上传任务的执行和处理回调函数。
* `onProgress(fn: OnProgress)`：设置进度回调函数。
* `onComplete(fn: OnComplete)`：设置完成回调函数。
* `onError(fn: OnError)`：设置错误回调函数。
* `cancel()`：取消上传任务，并返回一个 Promise，该 Promise 在解析时提供任务结果。
* `start()`：启动上传任务，并返回一个 Promise， 该 Promise 在解析时提供任务结果。

## 贡献代码 [#贡献代码]

1. 登录 \<[https://github.com](https://github.com)>

2. Fork [git@github.com](mailto:git@github.com):qiniu/js-sdk.git

3. 创建您的特性分支 (git checkout -b new-feature)

4. 提交您的改动 (git commit -am 'Added some features or fixed a bug')

5. 将您的改动记录提交到远程 git 仓库 (git push origin new-feature)

6. 然后到 github 网站的该 git 远程仓库的 new-feature 分支下发起 Pull Request

<a id="license" />

### 许可证 [#许可证]

> Copyright (c) 2023 qiniu.com

### 基于 MIT 协议发布 [#基于-mit-协议发布]


# 服务等级协议（SLA） (/products/kodo/0-sla)



最近更新时间: 2023-12-25 14:18:14

**版本生效日期：2019 年 4 月 28 日**

**为使用七牛云对象存储服务（以下简称“本服务”），您应当阅读并遵守《七牛云对象存储服务等级协议》（以下简称“本协议”或“SLA”），以及[《七牛云服务用户协议》](https://www.qiniu.com/user-agreement)和[《七牛云隐私权政策》](https://www.qiniu.com/privacy-right)。本协议包含本服务的术语和定义、服务可用性/服务成功率等级指标、赔偿方案、免责条款等相关内容。请您务必审慎阅读、充分理解各条款内容，特别是限制、免责条款或者其他涉及您重大权益的条款，这类条款可能会以加粗等形式提示您重点注意。**

**除非您已充分阅读、完全理解并接受本协议所有条款，否则，请您不要购买本服务。您单击“同意”、“下一步”或您的购买、使用等行为或者您以其他任何明示或者默示方式表示接受本协议的，即视为您已阅读并同意本协议的约束。本协议即在您与七牛云之间产生法律效力，成为对双方均具有约束力的法律文件。**

<br />

## **1.术语和定义** [#1术语和定义]

**七牛云对象存储**：对象存储是一种基于 HTTP 协议网络接口上传、下载和管理数据资源，按需扩容的非结构化数据存储服务。对象存储以预付费或后付费的方式提供服务。

**服务周期**：服务周期是指购买本服务的服务期限所包含的自然月。如用户是3月11日开通服务，则服务周期计算到3月31日。

**月度服务费用**：指客户的某一个七牛云账号在一个自然月中使用七牛云对象存储服务按地域和存储类型分别统计的服务费用。

**有效请求**：七牛云对象存储服务端收到的请求视为有效请求，**但不包括以下类型的请求**：

（1）未通过身份验证和鉴权失败的请求或欠费停服状态下的请求；

（2）跨区域同步数据和生命周期管理等各类后端异步处理发起的所有请求；

（3）获取Bucket列表发起的所有请求；

（4）查询统计数据的请求；

（5）客户的应用程序受到黑客攻击而发起的请求。

**失败请求**：七牛云对象存储服务将HTTP状态码为5XX的请求和因七牛对象存储服务故障导致的用户正常请求未能到达服务端的请求均视为失败请求，**但不包括以下类型的请求**：

（1）因采用不适当的访问模式导致请求超出对象存储服务的规定配额，造成请求被对象存储限制的错误请求 (HTTP状态码573)；

（2）跨区域同步数据和生命周期管理等各类后端异步处理的失败请求；

（3）获取Bucket列表产生的失败请求；

（4）非七牛服务造成的慢请求或失败请求 (HTTP状态码579)：

    1）镜像回源超时或失败的请求；

    2）Callback超时或失败的请求；

（5）查询统计数据的失败请求；

（6）由七牛云对象存储服务发起的合理升级、变更、停机而导致的错误请求或服务不可用情况；

（7）客户的应用程序受到黑客攻击而导致被七牛云存储服务限制的请求。

**每5分钟错误率**：根据地域和存储类型分别统计的失败请求占5分钟内客户有效请求数的比例，同一账号下相同地域、相同存储类型的多个Bucket，将合并计算错误率。具体计算方式如下：

    &#x2A;*每 5 分钟错误率 = (每 5 分钟失败请求数 / 每 5 分钟有效请求数) × 100%**

<br />

## **2.服务可用性**  <br /> [#2服务可用性--]

### **2.1 服务可用性计算**<br /> [#21-服务可用性计算]

七牛云对象存储根据不同地域和存储类型统计对应的服务可用性，同一账号下相同地域、相同存储类型的多个Bucket，将合并计算服务可用性。服务可用性的具体计算方式如下：

    &#x2A;*服务可用性 = (1 - (服务周期内的每 5 分钟错误率之和 / 服务周期内的 5 分钟总个数)) × 100%**

注：服务周期内的5分钟总个数=12 x 24 x 该服务周期的天数<br />

### **2.2 服务可用性承诺** <br /> [#22-服务可用性承诺-]

客户可以通过七牛云对象存储提供的API、SDK、控制台或工具对数据进行上传、下载和管理。针对不同的存储类型，七牛云对象存储分别承诺服务可用性如下：

| 存储类型                          | 服务可用性标准 |
| ----------------------------- | ------- |
| 标准存储                          | 99.9%   |
| 低频存储 / 归档直读存储 / 归档存储 / 深度归档存储 | 99.0%   |

**如七牛云对象存储服务未达到上述服务可用性承诺，客户可依据本协议第3条约定获得赔偿**<br />

## **3.赔偿方案**  <br /> [#3赔偿方案--]

客户账号按地域及存储类型分别统计各服务周期内的服务可用性，如低于2.2承诺的可用性标准，可按照以下条款约定获得赔偿

### **3.1 赔偿标准**  <br /> [#31-赔偿标准--]

（1）&#x2A;*赔偿只针对已经使用七牛云对象存储服务并且正常支付费用的客户（除法律法规另有规定外，免费型服务不在赔偿范围内）；赔偿方式仅限于用于支付七牛云对象存储的抵用券，抵用券的使用遵循七牛云发布的相关规则。**

（2）&#x2A;*赔偿额按照服务可用性未达标的服务月度单独计算，且不超过该服务周期内该地域该存储类型所支付月度服务费用的50%（不含抵用券、优惠券等抵扣费用）。赔偿额具体计算方式如下：**

![image.png](/docs-assets/products/kodo/%289-service-agreement%29/0-sla/FrOp6MN1TjXEVAPOVaTntlmhfjqX-83f19ec9038c.webp)

### **3.2 赔偿申请时限**  <br /> [#32-赔偿申请时限--]

（1）客户可以每月**第五(5)个**工作日后，对上个服务周期没有达到可用性的服务，通过账户的工单系统提出赔偿申请。赔偿申请提出后七牛云会进行相应审核，对于服务周期的服务可用性计算，若双方出现争议，**双方均同意最终以七牛云的后台记录为准**。

（2）&#x2A;*赔偿申请必须在服务可用性未达标的服务周期结束后两（2）个月内提出。若在两（2）个月内未提出赔偿申请，或是在服务可用性未达标的服务周期结束后的两（2）个月以后才提出赔偿申请，均视为客户主动放弃要求赔偿及向七牛云主张其他权利的权利，七牛云有权不受理客户的赔偿申请，不对客户进行任何赔偿或补偿。**

<br />

## **4.免责条款** <br /> [#4免责条款-]

由于以下原因造成的服务不可用，相应服务不可用时间不属于服务不可用的计算范畴和七牛云的赔偿范围，七牛云无需向客户承担责任：

**4.1 七牛云预先通知客户后进行系统维护所引起的，包括割接、维修、升级和模拟故障演练；**

**4.2 任何七牛云所属设备以外的网络、设备或配置调整引起的故障;**

**4.3 客户的应用程序或数据信息受到黑客攻击而引起的；**

**4.4 客户维护不当或保密不当致使数据、口令、密码等丢失或泄漏所引起的；**

**4.5 客户自行升级操作系统所引起的；**

**4.6 客户的应用程序或安装活动所引起的；**

**4.7 客户的疏忽或由用户授权的操作所引起的；**

**4.8 不可抗力以及意外事件引起的；**

**4.9 其他非七牛云原因所造成的不可用或服务不达标；**

**4.10 属于相关法律法规、相关协议、相关规则或七牛云单独发布的相关规则、说明等中所述的七牛云可以免责、免除赔偿责任等的情况**

<br />

## **5.其他** <br /> [#5其他-]

**5.1 七牛云有权根据变化适时或必要时对本协议条款做出修改，您可以在七牛云官网的最新版本中查阅相关协议条款。如您不同意七牛云对协议所做的修改，您有权停止使用本服务，如您继续使用本服务，则视为您接受修改后的协议。** <br />

**5.2 本协议作为[《七牛云服务用户协议》](https://www.qiniu.com/user-agreement)的附属协议，具有与[《七牛云服务用户协议》](https://www.qiniu.com/user-agreement)同等效力，本协议未约定事项，您需遵守[《七牛云服务用户协议》](https://www.qiniu.com/user-agreement)的相关约定。若本协议与[《七牛云服务用户协议》](https://www.qiniu.com/user-agreement)中的条款相冲突或不一致，则以本协议为准，但仅在该冲突或不一致范围内适用。**


# 文件系统挂载存储桶 (/products/kodo/0-mount-bucket-as-file-system)



最近更新时间: 2025-09-30 14:42:43

借助一些开源软件可以挂载存储桶作为本地文件系统使用。这类开源软件较多，经过筛选，我们推荐使用 `rclone mount` 的方式。具体 rclone 的配置和使用方式的介绍，详情见 [rclone ](/products/kodo/the-third-party-software-extension-support/1-docking-rclone) 。

```
rclone mount qiniu:bucket-name/dest-directory-path mount-point --daemon
--daemon 为进程守护参数，可后台运行
```

**注意**： 在 MacOS 中使用 `rclone mount` 命令，需要安装类似 [macFUSE](https://github.com/osxfuse/osxfuse) 等支持，可以根据您的系统版本和处理器选择合适的 macFUSE 版本。


# 数据备份 (/products/kodo/1-data-backup)



最近更新时间: 2025-09-30 14:42:43

将您的本地数据方便的备份到七牛云对象存储空间，可以借助开源的备份工具。这类开源软件较多，经过筛选，我们推荐使用 `restic`，具体 restic 的配置和使用方式的介绍，详情见 [使用 Restic 备份工具对接对象存储 Kodo](/products/kodo/the-third-party-software-extension-support/3-restic-s3-kodo)。


# 在容器中挂载存储桶 (/products/kodo/2-kubernetes-csi-mount-bucket)



最近更新时间: 2025-09-30 14:42:43

七牛云对象存储支持挂载在容器中使用。
在 Kubernetes 中，我们支持通过 Container Storage Interface (CSI) 驱动将七牛云对象存储 Kodo 的存储空间以卷的形式直接在 Kubernetes 容器内挂载，并通过 POSIX 接口直接读写对象存储中的数据。关于 Kodo CSI 驱动的详细介绍，请见 [使用 Kubernetes CSI 挂载对象存储 Kodo](/products/kodo/the-third-party-software-extension-support/2-use-kubernetes-csi-kodo-mount-object-storage)。


# 基于 MCP 使用大模型访问对象存储 Kodo (/products/kodo/3-mcp-aimodel-kodo)



最近更新时间: 2026-09-17 15:02:57

# **1 概述** [#1-概述]

七牛云对象存储 Kodo 基于 S3 协议构建 Model Context Protocol (MCP) Server，支持用户在 AI 大模型客户端的上下文中通过该 MCP Server 来访问七牛云存储的空间和对象。

Model Context Protocol (MCP) 是一种专为大型语言模型（LLM）和 AI 系统设计的协议，旨在通过结构化上下文管理优化模型交互的效率和准确性，使 AI 模型能够安全地与本地和远程资源进行交互。

* [关于 MCP](https://modelcontextprotocol.io/introduction)
* MCP 的核心能力
  * 列举所有的资源、读取资源内容 [Resources](https://modelcontextprotocol.io/docs/concepts/resources)
  * 提供工具 [Tools](https://modelcontextprotocol.io/docs/concepts/tools)

基于 MCP，七牛云拓展集成 API 支持访问对象存储 Kodo，功能特性包括：

* 资源
  * 列举资源（受 AI 上下文限制，列举资源时默认只会列举 20 个资源，如果需要列举所有可使用工具分批次列举）
  * 读取资源
* 工具
  * 支持列举存储空间（Buckets）
  * 支持列举对象（Objects）
  * 支持读取对象内容
  * 支持上传本地文件，以及提供文件内容进行上传

<br />

# **2 环境要求** [#2-环境要求]

* Python 3.12 或更高版本
* uv 包管理器

如果还没有安装 uv，可以使用以下命令安装：

```bash
# Mac（推荐使用 brew 安装）
brew install uv


# Linux & Mac
# 1. 安装
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. 安装完成后，请确保将软件包安装路径（包含 uv 和 uvx 可执行文件的目录）添加到系统的 PATH 环境变量中。
# 假设安装包路径为 /Users/xxx/.local/bin（见安装执行输出）
### 临时生效（当前会话），在当前终端中执行以下命令：
export PATH="/Users/xxx/.local/bin:$PATH"
### 永久生效（推荐），在当前终端中执行以下命令：
echo 'export PATH="/Users/xxx/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile


# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

具体安装方式参考 [uv 安装](https://docs.astral.sh/uv/getting-started/installation/#pypi)

# **3 使用** [#3-使用]

## **3.1 通过 MCP 的 inspector 验证 MCP Server** [#31-通过-mcp-的-inspector-验证-mcp-server]

1、需要提前配置 node 环境，本示例环境：node v22.4.0
2、在终端中运行如下命令：

```
cd ${工程目录}
npx @modelcontextprotocol/inspector uvx qiniu-mcp-server
```

3、启动后，终端中会展示链接 URL，然后在浏览器中访问此 URL，通常是：[http://localhost:5173](http://localhost:5173)
4、在界面中点击 connect，connect 之后就可以列举资源了。

<br />

## **3.2 通过 Cline 验证 MCP Server** [#32-通过-cline-验证-mcp-server]

通过 Cline 可以用与 AI 大模型聊天的方式来操作七牛云对象存储，接下来展示怎么通过 Cline 进行操作。
下述演示是通过在 vscode 中下载 Cline 插件的方式进行的。
1、首先下载 [vscode](https://code.visualstudio.com/)，在 vscode 中搜索 Cline 插件并安装
2、安装成功后，需要在 Cline 配置大模型，可以按需指定并配置模型（如 deekseek OpenRounter 等）
3、大模型配置完成之后，开始配置 MCP server，如下图
配置信息参考：

```
{
  "mcpServers": {
    "qiniu": {
      "command": "uvx",
      "args": [
        "qiniu-mcp-server"
      ],
      "env": {
        "QINIU_ACCESS_KEY": "YOUR_QINIU_ACCESS_KEY",
        "QINIU_SECRET_KEY": "YOUR_QINIU_SECRET_KEY",
        "QINIU_REGION_NAME": "YOUR_QINIU_S3_REGION_NAME",
        "QINIU_ENDPOINT_URL": "YOUR_QINIU_S3_ENDPOINT_URL",
        "QINIU_BUCKETS": "YOUR_QINIU_BUCKETS"
      },
      "disabled": false
    }
  }
}

# 注：
# cursor 中创建 MCP Server 可直接使用上述配置。
```

参数说明：

```
# 下面信息均是必配项
# S3/Kodo 认证信息
QINIU_ACCESS_KEY: 七牛 Access Key
QINIU_SECRET_KEY: 七牛 Secret Key
# 区域信息，区域和 Endpint URL 在七牛 Bucket 管理信息界面可以查到，它们都是 Bucket s3 域名的一部分
# Bucket s3 域名样式：https://<Bucket>.s3.<Region>.qiniucs.com
QINIU_REGION_NAME: s3 区域名称，eg: cn-east-1
QINIU_ENDPOINT_URL: EndpointURL # eg:https://s3.cn-east-1.qiniucs.com
QINIU_BUCKETS: 配置 Bucket，多个 Bucket 使用逗号隔开，所有 Bucket 在同一个区域，建议最多配置 20 个 Bucket
```

4、当前配置已完成，我们可以在聊天界面通过聊天方式操作七牛云对象存储了。下面给出一些示例：

* 请列举 qiniu 下以 xxx 为前缀的空间
* 请列举 qiniu 下 xxx 空间中以 yyy 为前缀的文件
* 继续列举示例：上次列举只列举了部分文件，请继续帮我列举剩下的文件
* 读取下 qiniu 下 xxx 空间中以 yyy 文件内容


# Agent 场景中的 Markdown 最佳实践 (/products/kodo/4-html2markdown-ai)



最近更新时间: 2026-05-19 18:48:05

# **为什么需要 Markdown** [#为什么需要-markdown]

大语言模型（LLM）的推理成本与输入 Token 数量直接相关。Web 内容的主要格式是 HTML，但 HTML 对 AI 而言存在两个根本性问题：

* **Token 浪费严重**：HTML 标签本身不携带语义，却消耗大量 Token。
* **噪声干扰推理质量**：HTML 页面中混杂着导航栏、广告、Cookie 提示、内联 CSS/JS 等与内容无关的结构，这些"噪声"会分散模型注意力，降低问答和摘要的准确率。

Markdown 已成为 AI Agent 的**通用语言**：结构清晰、语义明确、Token 高效，是目前 RAG（检索增强生成）、文档问答、内容摘要等场景的首选输入格式。

# **对象存储 Kodo 支持 HTML2Markdown 转换** [#对象存储-kodo-支持-html2markdown-转换]

支持两种姿势：

| 使用方式                                                                                              | 适用场景                 |
| ------------------------------------------------------------------------------------------------- | -------------------- |
| [HTML2Markdown 自适应](/products/kodo/development-guidelines/dev-the-data-processing/6-auto-html2md) | 存量 HTML 文件批量转换、AI 抓取 |
| [html2md 数据处理命令](/products/dora/file-processing/5-html2md)                                        | 流水线处理、管道组合、按需转换      |

# **在 Agent 常见场景中的使用** [#在-agent-常见场景中的使用]

## **RAG 知识库构建** [#rag-知识库构建]

将 **HTML2Markdown 自适应**和 **html2md 数据处理命令**结合使用：入库时触发 html2md 预转换，检索时直接消费 Markdown，两个阶段均无额外延迟。

```
────────────────────────────────────────────────────────
数据入库阶段
  网页抓取 / 文档上传
      ↓
  HTML 文件存入 Kodo (html-bucket)
      ↓
  触发 pfop: html2md|saveas(markdown-bucket)
      ↓
  Markdown 文件落盘 (markdown-bucket)
────────────────────────────────────────────────────────
                          ↓
────────────────────────────────────────────────────────
Embedding 阶段
  读取 markdown-bucket 中的 .md 文件
      ↓
  按标题层级（# ## ###）切分 chunk  ← 语义边界天然清晰
      ↓
  Embedding 模型向量化
      ↓
  写入向量数据库/向量空间
────────────────────────────────────────────────────────
                          ↓
────────────────────────────────────────────────────────
检索推理阶段
  用户提问 → 向量检索 → 召回 Markdown chunk
       ↓
  拼装 Prompt（Token 节省 80%）
       ↓
  LLM 推理 → 回答
────────────────────────────────────────────────────────
```

**chunk 切分建议**：Markdown 标题（`#` `##` `###`）是天然的语义边界，优于基于字符数的硬切分。

## **实时文档问答** [#实时文档问答]

对于用户上传的 HTML 文件或提供的网页 URL，使用 HTML2Markdown 自适应做实时转换后直接送入 LLM：

```python
def answer_from_html(file_url: str, user_question: str) -> str:
    # 1. 携带 Accept: text/markdown 下载，触发自动转换
    resp = requests.get(file_url, headers={"Accept": "text/markdown"})
    content_type = resp.headers.get("Content-Type", "")

    if content_type.startswith("text/markdown"):
        context = resp.text
    else:
        # 降级：自行处理 HTML 或提示用户
        context = extract_text_from_html(resp.text)

    # 2. 构造 Prompt，送入 LLM
    prompt = f"""基于以下文档内容回答问题：

{context}

问题：{user_question}
"""
    return llm.chat(prompt)
```

## **多格式文档统一接入** [#多格式文档统一接入]

企业知识库通常包含 Word、PDF、HTML 等多种格式，可通过 html2md 数据处理命令统一转换为 Markdown 后入库：

```
Word (.docx)  →  转 html  →  html2md  →  .md
HTML  (.html) →           →  html2md  →  .md
PDF   (.pdf)  →  转 html  →  html2md  →  .md
```

# **Markdown Token 预估参考** [#markdown-token-预估参考]

| 原始 HTML 大小         | 预估 Markdown Token | 典型场景    |
| ------------------ | ----------------- | ------- |
| \~16 KB            | \~3,000           | 一篇博客文章  |
| \~100 KB           | \~18,000          | 中型文档页面  |
| \~500 KB           | \~90,000          | 长篇技术文档  |
| 2 MB（上限）           | \~360,000         | 建议预处理分段 |
| *注：以实际 Token 用量为准* |                   |         |

对于体积超过 100 KB 的 HTML 页面，建议在存入 Kodo 前做正文提取，进一步压缩无效内容。

# **对象存储 Kodo 支持 Markdown2HTML 形成双向链路** [#对象存储-kodo-支持-markdown2html-形成双向链路]

| 使用方式                                                           | 适用场景                     |
| -------------------------------------------------------------- | ------------------------ |
| 调用 [MD转HTML](/products/dora/file-processing/1-md-html-md2html) | Agent 生成 Markdown 后转网页展示 |


# 产品概述 (/products/las/0-las-product-introduction)



最近更新时间: 2025-10-29 14:16:52

## 什么是全栈应用服务器（Layered Application Server）？ [#什么是全栈应用服务器layered-application-server]

<br />

全栈应用服务器（Layered Application Server）是新一代开箱即用、面向全栈应用场景的云服务器产品，助力中小企业和开发者便捷高效的在云端构建网站、小程序/小游戏、电商、云盘/图床以及各类开发测试和学习环境，相比普通云服务器更加简单易用，提供带宽流量包并以套餐形式整体售卖基础云资源，将热门开源软件融合打包实现一键构建应用。

## 为什么选择全栈应用服务器？ [#为什么选择全栈应用服务器]

<br />

使用七牛云全栈应用服务器，您可以获取以下收益：

* 入门简单，使用便捷，单击鼠标即可快速搭建云端环境或构建应用。
* 无需自己采购服务器，无需管理硬件基础设施，随用随取、开箱即用。
* 节省成本，按需使用，能够获取高性价比且优质的产品和服务。
* 稳定可靠，安全性高。

全栈应用服务器适用多种应用场景：

* 网站搭建
* Web 应用
* 小程序后台
* 跨境电商
* 云端学习/实训/开发测试环境


# 注意事项 (/products/las/1-las-limits)



最近更新时间: 2025-12-26 18:16:26

## **通用限制** [#通用限制]

1. <u>**全栈应用服务器的系统盘如使用本地 SSD 磁盘，不具备数据高可用能力**</u>，如您对高可用有要求，请使用 SSD 云盘。
2. 全栈应用服务器配置的公网 IP，不支持更换，服务器到期后不支持保留。
3. 全栈应用服务器的峰值带宽为出、入方向公网带宽的峰值上限，不作为业务承诺指标。当出现资源争抢时，带宽峰值可能会受到限制。不适合应用于对公网质量有强保障诉求的场景，如您对带宽质量或稳定性有要求，请使用固定带宽。

## **网络与安全** [#网络与安全]

1. 公网访问端口

* 基于安全考虑，**中国大陆区域**的全栈应用服务器会默认<u>**封禁25端口的出向访问**</u>，建议您[使用SSL加密端口（通常是465端口）来对外发送邮件](/products/las/0-las-port-465-for-email)。
* 基于合规要求，**中国大陆区域**的全栈应用服务器会默认<u>**封禁53端口的入向访问**</u>，详情参见[关于53端口默认关闭的说明](/faq/las/12987-las-faq-port-53)


# 区域列表 (/products/las/13536-las-regions)



最近更新时间: 2026-08-27 11:14:15

本文介绍全栈应用服务器支持的区域。

| 区域名称     | 区域 ID            | 与对象存储内网互通  | 备注 |
| -------- | ---------------- | ---------- | -- |
| 中国（常山2）  | cn-changshan-2   | 支持（标准网络模式） |    |
| 中国（香港2）  | cn-hongkong-2    | -          |    |
| 日本（东京2）  | ap-norththeast-2 | -          |    |
| 美国（达拉斯2） | us-south-2       | 支持（标准网络模式） |    |
| 新加坡2     | ap-southeast-4   | 支持（标准网络模式） |    |
| 胡志明2     | ap-southeast-5   | 支持（标准网络模式） |    |

### 与对象存储 Kodo 内网互通域名 [#与对象存储-kodo-内网互通域名]

| 区域名称     | S3 协议                                          | 七牛 Kodo 协议                                                                                          |
| -------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| 中国（常山2）  | internal-s3-las-cn-north-1-cs.qiniucs.com      | internal-up-las-z1-cs.qiniup.com <br />internal-io-las-z1-cs.qiniuio.com                            |
| 美国（达拉斯2） | internal-s3-las-us-north-1-dal.qiniucs.com     | internal-up-las-na0-dal.qiniup.com <br />internal-io-las-na0-dal.qiniuio.com                        |
| 新加坡2     | internal-s3-las-ap-southeast-1-sg.qiniucs.com  | internal-up-las-as0-sg.qiniup.com <br />internal-io-las-as0-sg.qiniuio.com                          |
| 胡志明2     | internal-s3-las-ap-southeast-3-hcm.qiniucs.com | internal-up-las-ap-southeast-3-hcm.qiniup.com <br /> internal-io-las-ap-southeast-3-hcm.qiniuio.com |


# 计费说明 (/products/las/0-las-billing-instructions)



最近更新时间: 2025-12-25 15:42:47

全栈应用服务器提供服务器套餐售卖模式，套餐包含了 CPU、内存、SSD 云硬盘、网络流量包等云服务器资源，并以优惠价格售卖。

## 计费模式 [#计费模式]

目前仅支持包年包月模式售卖。包年包月是一种预付费模式，需提前一次性支付一个月或多个月甚至多年的费用。

其中计费周期以一个整点为一个结算周期（均以 UTC+8 时间为准），计费周期从创建开始付费，到释放结束付费，整点结算完进入新的结算周期。

例如： 2024-03-11 15:55:23 购买全栈应用服务器，时长为1个月，2024-04-11 16:00:00 实例到期。

## 到期保护 [#到期保护]

实例到期后将处于停机保护状态，7天内用户可以通过续费恢复实例可用状态。 若在实例处于保护期内不进行续费操作，则将释放实例，释放后实例中的数据将被清除且不可恢复，详情请参见 [到期与续费说明](/products/las/1-las-expiration-and-renewal-instructions)。请关注实例状态，及时续费或转移数据。

## 欠费说明 [#欠费说明]

1. 如果您的账户发生欠费，您包年包月购买的资源不会受影响，可以正常使用，直到资源有效期到期；
2. 如果您的账户发生欠费，您的账户可能会被冻结，账户冻结后，您按量购买的资源将会停机，IP 将会限速，冻结 7 天后，您按量购买的资源将会被销毁，相关数据将被永久删除、无法恢复。


# 到期与续费说明 (/products/las/1-las-expiration-and-renewal-instructions)



最近更新时间: 2025-10-29 15:50:17

全栈应用服务器对所购资源实施严格的生命周期管理，包年包月实例在到期后将经历停机和最终释放等阶段。

* 实例到期前 7 天、3 天、1 天，用户均会收到短信和邮件提醒
* 实例到期后7天内（保护期）：实例到期后，将会立刻停机、停止服务，即不能再访问该实例。续费后即可恢复访问，<u>**在保护期内对资源续费，资源在保护期内产生的相关费用将在您续费时一并收取（抵扣续费周期时长）**</u>
* 实例到期超过7天：实例到期后第8天，实例及相关资源释放。在实例释放前一天会发送短信/邮件提醒，实例配置和数据将被永久删除、无法恢复。

建议用户在到期前及时续订，续订成功后实例正常使用不停机、确保服务的连续性。
续费操作说明参见[管理服务器-续费服务器实例](/products/las/cloud-server/section-18fitr/4-las-renew-server)


# 退款说明 (/products/las/2-las-refund-instructions)



最近更新时间: 2026-10-10 11:31:03

本说明旨在向用户明确七牛云全栈应用服务器服务退费相关的条件、规则及流程等事项，且该说明仅适用于全栈应用服务器服务。

## **退费规则**： [#退费规则]

1. 仅限于付费方式为订单预付费（包年包月）的订单或资源，包括但不限于全栈应用服务器实例、磁盘、云盘、弹性公网 IP、应用实例等。
2. 退订类型：五天无理由退订、非五天无理由退订，**五天无理由退款**为每个用户限每个月五天内最多可发起 1 次无理由退款申请， 超过 1 次或五天后为**非五天无理由退款**。退款金额将根据“实付现金 - 已消费金额”计算。

* 五天无理由已消费金额公式为：
  * 已消费金额 = 已使用时长 / 总购买时长 \* 官网折扣价
* 非五天无理由已消费金额公式为：
  * 已消费金额 = 已使用时长 / 总购买时长 \* 官网折扣价 \* 1.35
* 说明：
  * 订单实付金额：即您现金支付/充值部分，不含使用代金券/抵用券等方式抵扣的费用金额。
  * 官网折扣价：即您购买时官网显示的现价，不含 VIP 的折扣价。
  * 剩余使用时长：以小时为单位，剩余时长不足 1 小时的部分不予计算。
  * 按照退款金额计算公式得出的退款金额如小于 0.01 元，则不予退款。
  * 五天为资源创建时间起算，如资源创建时间超过五天，则不支持五天无理由退款。
  * 退订续费订单时，按照续费起止时间计算使用时间。
  * 退款资金流向：参见[七牛云订单退款-退款资金流向](https://developer-doc.qiniu.com/account/order-management/0-order-a-refund#%E9%80%80%E6%AC%BE%E8%B5%84%E9%87%91%E6%B5%81%E5%90%91)说明

3. 对于使用代金券/抵用券等代币支付购买全栈应用服务器服务的用户，若在申请退费时服务尚未使用，七牛云将退还尚未过期的代金券/抵用券至您的账户。
4. 对于参与活动购买服务的用户，如活动说明中有退费相关规则且该规则与本退费说明不一致的，则以活动说明为准。
5. 七牛云有权对您的退费申请进行审核，如经审核发现为恶意退费或存在其他影响七牛云合法权利的情形的，七牛云有权驳回您的退费申请。
6. 以下情形不支持退费：

* 后付费的订单或资源不支持退费。
* 活动限制：如您购买了参加活动（包括但不限于优惠类活动等）的服务且该活动规则不支持退费。
* 因违规使用被封禁的资源不支持退费。
* 因账户被封禁或冻结的，其所有资源不支持退费。
* 参与恶意退订，例如同一用户通过一个或多个账号频繁退订，或通过非正常手段退订，七牛云有权拒绝退费。

## **解释权归属及其他**： [#解释权归属及其他]

1. 本规则自发布之日起生效，且七牛云保留后续根据实际情况对本规则进行修改的权利。
2. 本规则的最终解释权归属于七牛云公司。


# 扩容云盘 (/products/las/13547-las-disk-resize)



最近更新时间: 2026-09-10 16:35:13

当云盘空间不足以应对业务的数据存储需求时，您可以通过扩容完成对容量的提升，避免因容量不足影响业务使用甚至丢失数据。

# 扩容流程 [#扩容流程]

1. 扩容云盘容量
   当云盘空间不足时，您首先需要扩容云盘的容量。
2. 扩容分区和文件系统
   云盘扩容完成后，还需要扩展分区及文件系统、才能为实例识别并使用。

# 扩容云盘容量 [#扩容云盘容量]

**注意事项**

* 云盘仅支持扩容，不支持缩容。
* 可用、使用中的云盘才支持扩容。使用中（已挂载到实例）的云盘还要求实例必须是运行中或是已关机状态才支持扩容。
* 云盘扩容完成后，还需要完成扩容分区和文件系统等操作后新增容量才可以被实例使用。
* 强烈建议您在执行扩容操作前<u>**对云盘制作快照**</u>，防止因误操作造成文件系统损坏。

## **操作步骤** [#操作步骤]

**方式一**

1. 登录[LAS 控制台-实例](https://portal.qiniu.com/las/vm/instances)
2. 从列表中找到扩容磁盘挂载的实例

* 在操作列表中点击**更多-磁盘与镜像-扩容云盘**
* 或是进入实例详情，在磁盘列表中找到待扩容的磁盘，点击**扩容**

3. 在打开的扩容云盘弹窗中

* 核实实例、云盘信息
* 选择扩容方式
  * 在线扩容：只有实例是**运行中**状态时支持
  * 离线扩容：只有实例是**关机**状态时支持
* 设置目标容量（必须大于当前容量且为10的倍数）
* 查看**扩容分区和文件系统**操作的提示
* 了解相关费用
  * 按量付费的云盘：界面会显示扩容完成后云盘每小时的费用
  * 包年包月的云盘：界面会显示扩容需要预付的费用（新增的容量对齐到磁盘有效期内的费用）
* 勾选**我已知悉，确认扩容**，点击**确定**即可提交扩容请求

<img src="/docs-assets/products/las/%282-development-guidelines%29/13547-las-disk-resize/FrzG7yGZ5-n1xe5PIFZdEaXR3pAp-2b15eb94a410.webp" width="450" />

4. 之后磁盘会显示**扩容中**的状态，扩容完成后恢复成**使用中**

**方式二**

1. 登录[LAS 控制台-磁盘](https://portal.qiniu.com/las/vm/disks)
2. 选择目标资源所在的区域
3. 在列表中找到要扩容的磁盘，点击操作列表**更多-扩容**
4. 在打开的扩容云盘弹窗中

* 核实实例、云盘信息
* 选择扩容方式
  * 在线扩容：只有实例是运行中状态时支持
  * 离线扩容：只有实例是关机状态时支持
* 设置目标容量（必须大于当前容量且为10的倍数）
* 查看**扩容分区和文件系统**操作的提示
* 了解相关费用
  * 按量付费的云盘：界面会显示扩容完成后云盘每小时的费用
  * 包年包月的云盘：界面会显示扩容需要预付的费用（新增的容量对齐到磁盘有效期内的费用）
* 勾选**我已知悉，确认扩容**，点击**确定**即可提交扩容请求

<img src="/docs-assets/products/las/%282-development-guidelines%29/13547-las-disk-resize/FrzG7yGZ5-n1xe5PIFZdEaXR3pAp-2b15eb94a410.webp" width="450" />

4. 之后磁盘会显示**扩容中**的状态，扩容完成后恢复成**使用中**

# 扩容分区和文件系统 [#扩容分区和文件系统]

在完成 **扩容云盘容量** 后，需要按照情况扩容分区和文件系统、实例才能识别新增容量。您可参考本文进行 Linux 系统下的相关操作。

**前提条件**

* 实例状态为运行中。
* 云盘状态为使用中（已扩容云盘容量且该盘已挂载至云服务器）。
* 系统盘使用率未达到 100%。

## **操作步骤** [#操作步骤-1]

**步骤一：确认云盘是否分区**
1.登录云服务器。
2.执行以下命令，查询需要扩容的云盘的分区信息。

```
sudo fdisk -l
```

返回结果有类似下图的信息：

<img src="/docs-assets/products/las/%282-development-guidelines%29/13547-las-disk-resize/FsAAx4bJZkeXL4dAkBl9zwteGcTF-622450154fb3.webp" width="350" />

<img src="/docs-assets/products/las/%282-development-guidelines%29/13547-las-disk-resize/FgZl5c27wNCYC0tv3tnYlX3_bLbK-facde6cd5e81.webp" width="350" />

<img src="/docs-assets/products/las/%282-development-guidelines%29/13547-las-disk-resize/FrfEByvILyTDR3n_ODnTWfw5ctuz-a952429a561e.webp" width="350" />

其中：

* 若 Disk /dev/vdx 下没有同名前缀的形如 /dev/vdx1 、/dev/vdx2 等的 Device，则表示该云盘是**裸设备没有分区**。
* 若 Disk /dev/vdx 下有同名前缀的形如 /dev/vdx1 、/dev/vdx2 等的 Device，则表示该云盘**有分区**。

<u>
  **注意：系统盘都有形如 /dev/vda1 的分区。**
</u>

**步骤二：查看文件系统类型**
执行以下命令，查询步骤一中需要扩容的裸设备或分区的文件系统类型。

```
sudo file -s 裸设备名（如/dev/vdb)或分区名（如/dev/vda1）
```

返回结果有类似下图的信息：

<img src="/docs-assets/products/las/%282-development-guidelines%29/13547-las-disk-resize/FjBBQC34lDo404HpORwNP9xWMu2s-ff905b2c297d.webp" width="550" />

其中：

* XFS filesystem 表示文件系统为 XFS
* ext4 filesystem表示文件系统为 EXT4
* ext3 filesystem 表示文件系统为 EXT3

综上，经过步骤一至步骤二，在本示例中可获取以下信息：

* /dev/vda 系统盘，包含 MBR 分区 /dev/vda1，文件系统为 XFS。
* /dev/vdb 数据盘无分区，文件系统为 XFS。
* /dev/vdc 数据盘有分区 /dev/vdc1，文件系统为 EXT4。

**步骤三：判断后续操作**
根据步骤一至步骤二获取的信息，判断后续操作

| 分区和文件系统情况               | 后续操作                           |
| ----------------------- | ------------------------------ |
| 无分区的裸设备，无文件系统           | 初始化云盘                          |
| 无分区的裸设备，有文件系统           | 步骤五：扩容文件系统                     |
| 有分区，分区格式为 GPT/MBR，有文件系统 | 1.步骤四：扩容分区 <br /> 2.步骤五：扩容文件系统 |

**步骤四：扩容分区**

1. 请依照 **步骤三：根据步骤一至步骤二获得的信息，判断后续操作**，确认云盘是否需要执行扩容分区操作。
2. 根据实际情况执行命令，安装 gdisk 工具。

* 若分区类型为 MBR，无需安装此工具，直接执行下一步安装 growpart 工具。
* 若分区类型为 GPT，则请对应云服务器操作系统类型，执行以下命令安装工具。
  * CentOS：`sudo yum install gdisk -y`
  * Ubuntu/Debian：`sudo apt-get install gdisk -y`

3. 对应云服务器操作系统类型，执行以下命令，安装 growpart 工具。

* CentOS：`sudo yum install -y cloud-utils-growpart`
* Ubuntu/Debian：`sudo apt-get install -y cloud-guest-utils`

4. 执行以下命令，使用 growpart 工具扩容分区。
   注：本示例以扩容系统盘 /dev/vda1 分区为例，命令中 /dev/vda 与 1 间需使用空格分隔。您需要按需修改命令。

```
sudo LC_ALL=en_US.UTF-8 growpart /dev/vda 1
```

扩容分区前（系统盘已扩容至 60 GiB，分区仍只有 50GiB）：

<img src="https://dn-odum9helk.qbox.me/FsAAx4bJZkeXL4dAkBl9zwteGcTF" width="350" />

返回结果如下图所示，则表示分区扩容成功。

<img src="/docs-assets/products/las/%282-development-guidelines%29/13547-las-disk-resize/Fi31JhAvKpX0oREWPYDGriXtcDYr-37e9de64c417.webp" width="500" />

说明：

* 请注意，若返回结果如下图所示，则表示分区扩容失败，根据提示信息需要重启机器，重启机器后再重新执行上述命令查看是否扩容成功。

<img src="/docs-assets/products/las/%282-development-guidelines%29/13547-las-disk-resize/FrWYvQHFNBMh7PPVIGWpWiuJBXoG-35000d864ef1.webp" width="350" />

**步骤五：扩容文件系统**

1. 根据 **步骤二：查看文件系统类型** 获取到的文件系统类型，执行对应命令扩容文件系统

* ext 文件系统
  * 执行以下命令，扩容 ext 文件系统
    ```
    resize2fs 裸设备名（如/dev/vdb）或分区名（如/dev/vdb1）
    ```
  * 本示例中数据盘分区 /dev/vdc1为 EXT4 文件系统，因此执行 resize2fs /dev/vdc1，执行过程中按照系统提示，可能需要执行esfsck相关指令。执行返回结果如下图所示
  <img src="/docs-assets/products/las/%282-development-guidelines%29/13547-las-disk-resize/Fi22SU5ZwJXB-fu1203htzVsxnYs-19051095ede7.webp" width="350" />
* xfs 文件系统
  * 执行以下命令，扩容 xfs 文件系统。其中文件系统的挂载点可以通过命令 df -TH查看。
    ```
    xfs_growfs <挂载点>
    ```
  * 本文示例为/dev/vda1 挂载至 /， /dev/vdb 挂载至 /data1，则执行以下命令。
    ```
    xfs_growfs /
    xfs_growfs /data1
    ```
    返回结果如下图所示：
    <img src="/docs-assets/products/las/%282-development-guidelines%29/13547-las-disk-resize/Fvkw93X2XXFrpCe5zkueIIt6t5Rr-9a8ec6ce4501.webp" width="350" />
    <img src="/docs-assets/products/las/%282-development-guidelines%29/13547-las-disk-resize/Fg5YwdTDn-W6UkyYeI5sHqKXZZKC-ec597b0030cc.webp" width="350" />

2. 执行以下命令，查看扩容结果。
   ```
   df -TH
   ```
   本示例返回结果如下图所示，系统盘（/dev/vda1）和数据盘（/dev/vdb和/dev/vdc1）均已完成扩容。
   <img src="/docs-assets/products/las/%282-development-guidelines%29/13547-las-disk-resize/FidwGVFNYO77xx3-xBOgUvY_RuDC-e0633da54ec5.webp" width="350" />

3. 扩容成功后请检查数据完整性，观察云服务器中的业务是否正常运行。
   如果有异常可以使用回滚快照的方式进行数据恢复，详情请参见[使用快照回滚云盘](/products/las/snapshots/13541-snapshots-rollback)。


# 一键部署 (/products/las/13567-deployment-overview)



最近更新时间: 2026-09-10 16:35:13

# 产品概述 [#产品概述]

一键部署是 LAS 提供的 GitHub 仓库部署能力，适合发布演示站点、文档站点、前端应用和轻量 HTTP 服务。平台按照仓库中的部署配置，在 Sandbox 中执行安装和启动命令，并在服务通过健康检查后提供公网访问地址。

## 工作方式 [#工作方式]

一次部署包含以下步骤：

1. 读取公开 GitHub 仓库和用户选择的 branch 或 Tag。
2. 将可变引用固定为完整的 Commit SHA，并读取该 Commit 中的 `.qiniu/deploy.yaml`。
3. 按用户选择的区域和模板创建 Sandbox。
4. 在 Sandbox 中拉取固定 Commit，执行安装命令和启动命令。
5. 访问健康检查路径；检查通过后返回服务地址。

## 资源和版本 [#资源和版本]

### Deployment [#deployment]

Deployment 是一个长期存在的部署记录。它绑定 GitHub 仓库、部署配置路径和 Sandbox 目标。每个 Deployment 都有稳定的 Deployment ID，可在 Portal 中查看、停止、删除或重新部署。

### Revision [#revision]

Revision 是一次具体的部署版本，保存其 Commit SHA、配置摘要、执行状态和部署日志。Revision 创建后不会被覆盖，因此历史版本仍然可以查看和重新部署。

### Sandbox [#sandbox]

Sandbox 是当前唯一支持的部署目标。模板、CPU、内存、磁盘和实际到期时间以 Sandbox 返回的信息为准。服务地址由 Sandbox 提供，只有健康检查通过后才会展示。

## 当前限制 [#当前限制]

* 仅支持公开 GitHub 仓库；私有仓库授权尚未开放。
* 当前仅支持 Sandbox，不能选择 Cloud Host 等其他目标。
* 创建请求的 `timeoutSeconds` 当前固定为 `3600` 秒。
* 当前使用手动部署；GitHub Push 自动更新尚未开放。

## 计费和资源释放 [#计费和资源释放]

使用一键部署会创建 Sandbox，并按 Sandbox 的实际资源和运行时长计费。停止 Deployment 后，计算资源会进入清理流程；删除 Deployment 会立即从用户列表隐藏，并继续由后台清理尚存的目标资源。

Sandbox 的具体价格、区域可用性和账户配额，以 [Sandbox 服务概述](/products/las/sandbox-overview) 和控制台当前展示为准。


# API 概述 (/products/las/0-api-ecs-overview)



最近更新时间: 2026-05-06 18:06:12

该 API 用于管理全栈应用服务器。

## API 请求凭证 [#api-请求凭证]

> 详见 [《管理凭证》](/products/kodo/development-guidelines/security/access-token)

## API 请求域名 [#api-请求域名]

> 详见 [《服务接入点》](/products/las/regions-specs/2-api-ecs-endpoint)

注意：服务接入点仅支持 https 访问


# 沙箱概述 (/products/las/13479-sandbox-api-overview)



最近更新时间: 2026-09-11 17:43:19

# 沙箱概述 [#沙箱概述]

七牛沙箱 Open API 用于通过 HTTP 直接管理沙箱实例、模板和密钥注入规则。所有接口均以区域接入点为 Host，请根据沙箱所在区域选择对应的 Endpoint。

# 服务接入点 [#服务接入点]

| 区域       | 区域标识符           | API Endpoint                                 |
| -------- | --------------- | -------------------------------------------- |
| 中国（扬州1）  | `cn-yangzhou-1` | `https://cn-yangzhou-1-sandbox.qiniuapi.com` |
| 美国（达拉斯1） | `us-south-1`    | `https://us-south-1-sandbox.qiniuapi.com`    |

# 认证方式 [#认证方式]

沙箱实例和模板管理接口使用 `X-API-Key` 请求头认证：

```http
X-API-Key: <QINIU_API_KEY>
```

部分模板构建接口也接受 Bearer 形式的 API Key：

```http
Authorization: Bearer <QINIU_API_KEY>
```

Go SDK 和 qshell 会同时设置 `X-API-Key` 与 `Authorization: Bearer <QINIU_API_KEY>`，一般不需要手动处理这两个请求头的差异。

密钥注入规则管理接口使用七牛账户鉴权请求头：

```http
Authorization: Qiniu <SignedToken>
```

`SignedToken` 由七牛 AK/SK 对请求签名生成。Go SDK 和 qshell 会使用客户端配置的七牛凭证自动签名。

`QINIU_API_KEY` 可从[七牛云 API 密钥管理](https://portal.qiniu.com/developer/user/api-key)获取。

# 通用请求头 [#通用请求头]

| 请求头             | 是否必填    | 说明                                    |
| --------------- | ------- | ------------------------------------- |
| `X-API-Key`     | 部分接口必填  | 沙箱实例和模板管理接口的 API Key                  |
| `Authorization` | 部分接口必填  | 模板构建接口的 Bearer API Key，或密钥注入规则接口的七牛签名 |
| `Content-Type`  | 有请求体时必填 | 固定为 `application/json`                |

# API 分组 [#api-分组]

| 分组    | 文档                                                                      | 说明                             |
| ----- | ----------------------------------------------------------------------- | ------------------------------ |
| 沙箱实例  | [沙箱实例](/products/las/sandbox-api-overview/13480-sandbox-api-sandboxes)  | 创建、查询、连接、暂停、恢复、删除沙箱，并查看日志和监控指标 |
| 模板    | [模板](/products/las/sandbox-api-overview/13481-sandbox-api-templates)    | 创建模板、上传构建文件、启动构建、查看模板和构建状态     |
| 密钥注入  | [密钥注入](/products/las/sandbox-api-overview/11-sandbox-injection-rules)   | 管理平台侧保存的 HTTPS 请求密钥注入规则        |
| 沙箱运行时 | [沙箱运行时](/products/las/sandbox-api-overview/13483-sandbox-api-envd)      | 访问 envd 运行时状态、环境变量和资源指标        |
| 进程与终端 | [进程与终端](/products/las/sandbox-api-overview/13484-sandbox-api-processes) | 通过 envd 启动命令、连接进程、发送输入和管理 PTY  |
| 文件系统  | [文件系统](/products/las/sandbox-api-overview/13485-sandbox-api-filesystem) | 通过 envd 读写文件、列目录、移动删除文件和监听目录变化 |

# 错误响应 [#错误响应]

接口错误响应统一返回 JSON：

| 字段        | 类型        | 说明   |
| --------- | --------- | ---- |
| `code`    | `integer` | 错误码  |
| `message` | `string`  | 错误信息 |

示例：

```json
{
  "code": 400,
  "message": "invalid request"
}
```

# 状态码 [#状态码]

| 状态码   | 说明            |
| ----- | ------------- |
| `200` | 请求成功          |
| `201` | 资源创建成功        |
| `202` | 请求已接受，异步任务已开始 |
| `204` | 请求成功，无响应体     |
| `400` | 请求参数错误        |
| `401` | 认证失败          |
| `403` | 无权限访问         |
| `404` | 资源不存在         |
| `409` | 当前资源状态冲突      |
| `500` | 服务端错误         |

# 请求示例 [#请求示例]

```bash
curl -X GET "$QINIU_SANDBOX_API_URL/v2/sandboxes" \
  -H "X-API-Key: $QINIU_API_KEY"
```

# 相关文档 [#相关文档]

* [沙箱实例](/products/las/sandbox-api-overview/13480-sandbox-api-sandboxes)
* [模板](/products/las/sandbox-api-overview/13481-sandbox-api-templates)
* [密钥注入](/products/las/sandbox-api-overview/11-sandbox-injection-rules)
* [沙箱运行时](/products/las/sandbox-api-overview/13483-sandbox-api-envd)
* [进程与终端](/products/las/sandbox-api-overview/13484-sandbox-api-processes)
* [文件系统](/products/las/sandbox-api-overview/13485-sandbox-api-filesystem)


# 使用 SSL 加密 465 端口发送邮件 (/products/las/0-las-port-465-for-email)



最近更新时间: 2025-10-31 14:06:42

基于安全考虑，全栈应用服务器的25端口默认封禁，如果您有发送邮件的需求，建议使用 SSL 加密端口（465端口）来对外发送邮件。

## **基本原理** [#基本原理]

使用 SSL 加密端口发送邮件的基本原理与本地主机使用客户端（例如 Outlook 等）连接邮箱服务器发送邮件一致。即主机通过连接外部邮箱的发邮件服务器，并通过程序配置的账号密码鉴权验证来发送邮件，而不是服务器本身来发送邮件。

## **实现要点** [#实现要点]

使用 SSL 加密端口发送邮件的基本实现方式与使用25端口发送邮件的基本实现方式一致，但改为 SSL 加密协议后，需要特别注意以下几点：

* 编写好的程序调用外部邮箱发送邮件时，邮箱服务器需支持 SSL 加密功能。
* 主机连接邮箱服务器时，请在编写好的程序中启用 SSL 加密协议。
* 将连接外部邮箱服务器的端口改为 SSL 加密端口（465端口），具体配置信息可以咨询邮箱服务商。

## **操作步骤** [#操作步骤]

1. 联系邮箱服务商获取发送邮件的配置信息。通常包含以下配置信息：

* 发邮件服务器地址：例如：t\*\*\*.example.com。
* 发邮件服务器端口号：465。
* 邮箱用户名：可能是 Email 地址，也可能是 Email 地址前缀，具体可以咨询邮箱服务商。
* 邮箱客户端密码：部分邮箱服务商 Web 浏览器登录界面的登录密码和客户端密码并不相同，可能需要单独设置，具体可咨询邮箱服务商。

2. 在本地主机使用客户端软件（Outlook、Foxmail 等），使用已获取的邮件配置信息设置本地客户端，并发送邮件测试。
   如果邮件发送失败，表示获取的配置信息不正确，您需要联系邮箱服务商解决。
3. 根据实际的开发语言选择对应的程序样例，并将程序样例下载到本地。
4. 使用已通过测试的配置信息，编写程序样例中的邮箱服务器配置项。
5. 将编写好的程序上传到云服务器上，并实际发送邮件测试。


# 一键部署 OpenClaw (/products/las/1-las-one-click-deployment-of-openclaw)



最近更新时间: 2026-06-25 15:41:26

OpenClaw 作为硅谷爆火的开源 AI 智能体，凭借系统级行动力、持久化记忆和多 IM 工具无缝集成的特性，成为新一代「数字员工」标杆。本地部署需解决硬件成本、公网 IP、环境配置等问题，而七牛云全栈应用服务器 LAS 支持开箱即用的一键部署，无需自建环境、无需购置硬件，成本仅为传统硬件部署的 1/500。

**Windows 安装视频教程**：[点击观看](http://www.bilibili.com/video/BV16tDXBrEzx/)
**MacOS 安装视频教程**：[点击观看](https://www.bilibili.com/video/BV1z4dSBVEWa)

# 部署前准备 [#部署前准备]

1. 七牛云账号，开通两步验证，且账户余额或额度不低于 100 元：完成七牛云账号注册与实名认证（个人 / 企业均可），登录[七牛云控制台](https://portal.qiniu.com)，并开通两步验证；
2. 已获取[七牛云 MaaS API Key](https://portal.qiniu.com/ai-inference/api-key)
3. 工具准备：本地电脑安装 SSH 远程连接工具（如 FinalShell、Xshell、Putty），浏览器支持主流内核（Chrome/Edge/Firefox）；
4. 网络要求：本地设备可访问外网，七牛云 LAS 实例默认放行 22（SSH）、18789（OpenClaw 主端口）端口，无需额外配置防火墙。

# 基于云主机专属镜像的一键部署 [#基于云主机专属镜像的一键部署]

## **1. 创建 LAS 实例，选择 OpenClaw 专属镜像** [#1-创建-las-实例选择-openclaw-专属镜像]

登录七牛云控制台，进入云基础资源 - 全栈应用服务器 LAS 页面，点击「实例」-「创建服务器」；

<img src="/docs-assets/products/las/%286-best-practices%29/1-las-one-click-deployment-of-openclaw/Fk89acKCHW-m3B_B_p98x1txNuRD-9a696e7ab9b3.webp" width="650" />

## **2. 实例配置选择** [#2-实例配置选择]

* 地域：按需选择（中国、亚太等多区域已部署，推荐就近选择降低延迟）；
* 实例规格：个人测试推荐轻量型 T1S（ecs.t1s.c1m2，1 核 2GiB），也可选择更高规格（如ecs.t1s.c2m4，2 核 4GiB）；
* 镜像：必须选择应用镜像 **OpenClaw-v2026.5.18**，操作系统为 **Ubuntu 24.04LTS**，已预装 OpenClaw 核心环境；
* 网络：为了便于后续一键配置，这里建议开启SSH登录
* 填写并确认实例密码（需牢记，后续 SSH 登录使用，后续也可重置），点击「立即购买并创建」，等待 1-2 分钟，实例即可运行。

<img src="/docs-assets/products/las/%286-best-practices%29/1-las-one-click-deployment-of-openclaw/FlGP_ROsIA2yNV8P8dx0mtYj8ooC-b2f2ee72b14a.webp" width="650" />

<img src="/docs-assets/products/las/%286-best-practices%29/1-las-one-click-deployment-of-openclaw/FkdyCTeuLuBkncprhpAjC_yl8ccD-2cc64c335960.webp" width="350" />

## **3. 本地终端配置、访问 OpenClaw** [#3-本地终端配置访问-openclaw]

### Windows系统 [#windows系统]

在PowerShell中输入以下命令开始配置

```powershell
# 允许运行本地脚本
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# 开始配置
$u='https://kodo-toolbox.qiniu.com/las/openclaw/openclaw-tunnel.ps1'; $f="$env:TEMP\openclaw-tunnel.ps1"; Invoke-WebRequest -Uri $u -OutFile $f; powershell -ExecutionPolicy Bypass -File $f <七牛云 LAS 服务器 IP> --open
```

其中 &#x2A;*【七牛云 LAS 服务器 IP】** 需替换为实际实例的公网 IP。特别的，如果是共享 IP 机型，此处应替换为 `公网IP:port`。

### Mac/Linux系统 [#maclinux系统]

在 `本地电脑终端` 登录输入以下命令配置 OpenClaw：

```
bash <(curl -fsSL https://kodo-toolbox.qiniu.com/las/openclaw/openclaw-tunnel.sh) --open 【这里填写你七牛云服务器的公网ip 注意黑括号也要删，如果命令行提示错误可能是断行了，建议直接从七牛开发文档复制粘贴修改】
```

其中 &#x2A;*【七牛云 LAS 服务器 IP】** 需替换为实际实例的公网 IP。特别的，如果是共享 IP 机型，此处应替换为 `公网IP:port`。

按界面提示输入 LAS 服务器登录密码和你的[七牛云 MaaS API Key](https://portal.qiniu.com/ai-inference/api-key)，系统就会自行完成 OpenClaw 的基础配置、打印输出 DashBoard URL（例如[http://localhost:18789/?token=xxxx），并在浏览器中自动打开](http://localhost:18789/?token=xxxx），并在浏览器中自动打开) OpenClaw DashBoard 界面。

<img src="/docs-assets/products/las/%286-best-practices%29/1-las-one-click-deployment-of-openclaw/Fsq9Jti8n-Ld-rxaHus3kvb5uzpg-3050fd46913e.webp" width="650" />

## **常见问题** [#常见问题]

**Q: SSH 登录失败怎么办？**
检查实例是否处于「运行中」状态，公网 IP 是否正确，密码是否输入无误。如果是共享 IP 机型，需添加内网 22 端口的映射规则；
&#x2A;*Q: 18789 端口未监听怎么处理？**
确认配置文件修改正确，执行openclaw gateway restart重启网关，或重新执行安装程序；
**Q: 模型调用失败怎么排查**
检查七牛云 MaaS API Key 是否正确，是否已领取七牛云 Token 资源包，模型 ID 是否与七牛云模型广场一致；
&#x2A;*Q: 如何切换模型？**
编辑 OpenClaw 配置文件的配置模型参数可以切换模型

* 执行 `ssh root@<七牛云 LAS 服务器公网IP>` 登录到服务器
* 执行 `su - openclaw` 切换到 openclaw 账号
* 执行命令打开模型配置文件 `nano .openclaw/openclaw.json `找到 "models" 配置段

<img src="/docs-assets/products/las/%286-best-practices%29/1-las-one-click-deployment-of-openclaw/FoIJISyOc6VsSvH8YrMXfduy_LE2-030217a25cae.webp" width="450" />

若需使用 DeepSeek、Qwen、Kimi 等其他模型，可在七牛云模型广场复制目标模型的「ID」和「名称」，直接替换上述配置中的 **minimax/minimax-m2.5** 和 **MiniMax-M2.5** 即可；修改完成之后，按 `ctrl x`，然后 `y` `回车` 保存退出。
之后重启 OpenClaw 网关，加载新的模型配置：`openclaw gateway restart`
设置新的模型为默认模型：`openclaw models set qiniu/<模型ID>`
&#x2A;*Q: 控制台无法访问如何排查？**
确认本地端口映射命令是否正常运行，未关闭终端，Token 是否复制完整。


# 部署Hermes Agent调用七牛AI模型 (/products/las/13493-hermes-agent-how-to-use-ai)



最近更新时间: 2026-06-01 18:28:55

Hermes Agent 是 Nous Research 开源的自主 AI Agent 框架；Hermes 的核心特色在于其内置的闭环学习（Closed Learning Loop）机制。

# 部署前准备 [#部署前准备]

1. 七牛云账号，开通两步验证，且账户余额或额度不低于 100 元：完成七牛云账号注册与实名认证（个人 / 企业均可），登录[七牛云控制台](https://portal.qiniu.com)，并开通两步验证；
2. 已获取[七牛云 MaaS API Key](https://portal.qiniu.com/ai-inference/api-key)
3. 工具准备：本地电脑安装 SSH 远程连接工具（如 FinalShell、Xshell、Putty）；
4. 网络要求：本地设备可访问外网，七牛云 LAS 实例默认放行 22（SSH）端口，无需额外配置防火墙。

<a name="ecs" />

# 基于云主机专属镜像的一键部署 [#基于云主机专属镜像的一键部署]

## **1. 创建 LAS 实例，选择 HermesAgent-v2026.4.13.lf 专属镜像** [#1-创建-las-实例选择-hermesagent-v2026413lf-专属镜像]

登录七牛云控制台，进入云基础资源 - 全栈应用服务器 LAS 页面，点击「实例」-「创建服务器」；

<img src="/docs-assets/products/las/%286-best-practices%29/13493-hermes-agent-how-to-use-ai/Fk89acKCHW-m3B_B_p98x1txNuRD-9a696e7ab9b3.webp" width="500" />

## **2. 实例配置选择** [#2-实例配置选择]

* 地域：按需选择（中国、亚太等多区域已部署，推荐就近选择降低延迟）；
* 实例规格：个人测试推荐轻量型 T1（ecs.t1.c1m2，1 核 2GiB），企业使用可选择计算型 C1 系列（ecs.c1.c2m4，2 核 4GiB）；
* 镜像：必须选择社区镜像 **HermesAgent-v2026.4.13.lf**，操作系统为 **Ubuntu 24.04LTS**，已预装 Hermes Agent 核心环境；
* 填写并确认实例密码（需牢记，后续 SSH 登录使用，后续也可重置），点击「立即购买并创建」，等待 1-2 分钟，实例即可运行。

<img src="/docs-assets/products/las/%286-best-practices%29/13493-hermes-agent-how-to-use-ai/Fp9-apPofD5RMf6czS02GPd71AN-0252571f952b.webp" width="650" />

## **3. 本地终端配置配置 Hermes Agent** [#3-本地终端配置配置-hermes-agent]

### 配置 Hermes Agent说明 [#配置-hermes-agent说明]

`说明：&#x60; &#x2A;*【七牛云 LAS 服务器 IP】** 需替换为实际实例的公网 IP。特别的，如果是共享 IP 机型，此处应替换为 `公网IP:port`。

```powershell
1、登录服务器（Windows推荐使用PowerShell、xshell工具登录；Mac/Linux系统可直接在本地终端执行命令登录）
ssh root@<七牛云 LAS 服务器 IP>  然后输入服务器登录密码
2、登录成功后，输入以下命令开始配置调用七牛模型
hermes model
```

`注意：` <br /> 1、API base URL填写：[https://api.qnaigc.com/v1](https://api.qnaigc.com/v1) 或 [https://anthropic.qnaigc.com](https://anthropic.qnaigc.com) <br /> 2、API key在 [七牛控制台](https://portal.qiniu.com/ai-inference/api-key) 查询获取；<br /> 3、模型ID可以在七牛控制台 [模型广场](https://portal.qiniu.com/ai-inference/model) 查询
![image.png](/docs-assets/products/las/%286-best-practices%29/13493-hermes-agent-how-to-use-ai/FllegkA_UYaPznvUIma2yumHYhAY-f8abdba6ac4f.webp)
![image.png](/docs-assets/products/las/%286-best-practices%29/13493-hermes-agent-how-to-use-ai/Fsl2YCOUUf7HeFu9VI5mAU4Sqp9v-041499143358.webp)
![image.png](/docs-assets/products/las/%286-best-practices%29/13493-hermes-agent-how-to-use-ai/FlaFPDTqK_WTMzWqVadvcPPprxig-f9c9425592d6.webp&#x29;
&#x2A;*`说明：Context length配置可以直接回车，使用默认值；配置信息默认保存位置：.hermes/config.yaml`**

## **4. 运行Hermes Agent** [#4-运行hermes-agent]

```powershell
在终端中输入以下命令，回车即可
hermes
```

![image.png](/docs-assets/products/las/%286-best-practices%29/13493-hermes-agent-how-to-use-ai/FmjFTW_y1fpxfJEkNLm0UV10vPkt-f902c8248b16.webp)

## **常见问题** [#常见问题]

**Q1: SSH 登录失败怎么办？**
检查实例是否处于「运行中」状态，公网 IP 是否正确，密码是否输入无误，七牛云 LAS 默认放行 22 端口，无需额外配置；

**Q2: 模型调用失败怎么排查**
检查七牛云 MaaS API Key 是否正确，是否已领取七牛云 Token 资源包，模型 ID 是否与七牛云模型广场一致；

**Q3: 如何切换模型？**
编辑 .hermes/config.yaml 配置文件的配置模型参数可以切换模型

* 执行 `ssh root@<七牛云 LAS 服务器公网IP>` 登录到服务器

* 执行命令打开模型配置文件 `vim .hermes/config.yaml `找到 "custom\_providers中的model" 字段设置单个模型ID
  ![image.png](/docs-assets/products/las/%286-best-practices%29/13493-hermes-agent-how-to-use-ai/Fiv__vDG5J2BooNo-7OHXMUiyZo7-5f6c82857104.webp)

* 如果需要设置多个模型ID，可以把 "custom\_providers中的model修改为models" 设置多个
  ![image.png](/docs-assets/products/las/%286-best-practices%29/13493-hermes-agent-how-to-use-ai/FoM0PMho-iCBZ5rpZGu7aOus9Ffh-0a782c7d9093.webp)
  若需使用 DeepSeek、Qwen、Kimi 等其他模型，可在七牛云模型广场复制目标模型的「ID」和「名称」，直接替换上述配置中的 id（模型ID） 和 name（本地模型备注名称） 即可；修改完成之后，按 `esc`，然后 `:x` `回车` 保存退出。
  之后重新执行 hermes 命令重启hermes即可


# LAS服务器的端口禁用或ssh功能不可用(防火墙/配置等原因)，如何处理？ (/products/las/2-las-serial-console)



最近更新时间: 2026-03-12 15:00:34

## **1、全栈应用服务器LAS控制台支持的远程连接方式** [#1全栈应用服务器las控制台支持的远程连接方式]

* **Web 命令行**：是通过 ssh 协议进行连接，可以同时开多个，前提是虚机ssh、网络正常才可以连接，虚机正常情况下使用 web 命令行操作体验会更好一些。
* **串口控制台**：类似给虚机接了显示器、键盘，虚机网络/ssh异常也可以操作，但是只能开一个，第二个连接上的之后第一个会断开。

## **2、端口禁用或ssh功能不可用(防火墙/配置等原因)导致无法远程链接服务器时，可通过【串口控制台】进入主机处理。** [#2端口禁用或ssh功能不可用防火墙配置等原因导致无法远程链接服务器时可通过串口控制台进入主机处理]

### **操作说明** [#操作说明]

1）、在 &#x2A;*[七牛控制台](https://portal.qiniu.com/las/vm/instances)*&#x2A; 找到对应实例，
2）、点击 &#x2A;*【更多】*&#x2A;-&#x2A;*【串口控制台】** 即可进入主机
<img src="/docs-assets/products/las/%286-best-practices%29/2-las-serial-console/FuZbH7dKYVjFxhI8XT1P1jnFWQEf-caab4ac33914.webp" width="1000" />|


# OpenClaw 安全加固指南 (/products/las/3-las-openclaw-security-guide)



最近更新时间: 2026-03-23 10:33:20

开源 AI 智能体框架 OpenClaw（又称“龙虾”）因其强大的自动化能力在全球范围内广受关注。但国家工信部网络安全威胁和漏洞信息共享平台（NVDB）及各大高校、安全机构已相继发布预警：OpenClaw 在默认或不当配置下存在较高安全风险，易引发网络攻击、信息泄露等严重后果。
本文整理了 OpenClaw 的部署及应用安全最佳实践，帮助您在使用我司全栈应用服务器部署 OpenClaw 时能够“先守安全、再用AI”。

## **严格控制网络访问** [#严格控制网络访问]

### **1、避免服务端口公网暴露** [#1避免服务端口公网暴露]

检查 OpenClaw 配置文件 `openclaw.json`，确保服务未监听在 `0.0.0.0`，避免服务默认绑定到所有网络接口，导致公网可直达。建议服务监听 127.0.0.1:18789 ，然后通过 ssh 隧道访问，监听配置如下：

```
{
  "gateway": {
     "mode": "local",
     "port": 18789,
     "bind": "loopback"
  }
}
```

### **2、来源 IP 控制** [#2来源-ip-控制]

在 iptables 中添加 IP 白名单限制访问来源。

```
# 创建自定义链：
sudo iptables -N ALLOWED_IPS
# 添加允许的IP（IP地址为示例，操作时需替换为实际IP地址）：
sudo iptables -A ALLOWED_IPS -s 192.168.1.100 -j ACCEPT
sudo iptables -A ALLOWED_IPS -s 10.0.0.5 -j ACCEPT
sudo iptables -A ALLOWED_IPS -j RETURN
# 应用到SSH端口：
sudo iptables -A INPUT -p tcp --dport 22 -j ALLOWED_IPS
```

### **3、身份认证** [#3身份认证]

在 OpenClaw 配置文件中强制开启认证，防止未授权用户远程连接并操控您的 AI 助手。

```
{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "loopback",
    "auth": {
      "token": "使用至少32位随机字符串"
    }
  }
}
```

生成随机 Token 的命令：

```
openssl rand -hex 32
```

## **权限控制** [#权限控制]

### **1、使用 OpenClaw 账户** [#1使用-openclaw-账户]

禁止使用 root 或管理员身份运行 OpenClaw，创建专用的 OpenClaw 账户运行进程，防止攻击者通过 OpenClaw 漏洞获得主机最高权限。

### **2、文件权限最小化** [#2文件权限最小化]

设置配置文件权限，防止其他系统用户读取您的敏感配置 `chmod 600 /path/to/openclaw.json`。

### **3、禁用 Skill 自动安装** [#3禁用-skill-自动安装]

防止恶意技能自动加载 `openclaw config set skills.autoInstall false`。

## **Skill 安全审计** [#skill-安全审计]

### **1、安装官方安全审计工具** [#1安装官方安全审计工具]

安装并使用安全审计工具，可以有效地从源头阻断恶意代码入侵，如 skill-vetter 或 yidun-skill-sec（虾壳）。

```
openclaw plugin install skill-vetter
openclaw plugin enable skill-vetter
```

### **2、Skill 扫描** [#2skill-扫描]

安装 Skill 前务必执行扫描，自动化检测 Skill 中的高危行为（如读取敏感目录、执行 shell、外联未知域名）。

```
openclaw skill scan <skill-name>
openclaw skill report <skill-name>
```

### **3、开启全局自动扫描** [#3开启全局自动扫描]

在安装任何 Skill 时自动执行拦截，避免误操作安装恶意插件。

```
openclaw config set plugins.skill-vetter.autoScan true
openclaw config set plugins.skill-vetter.blockCritical true
```

## **运维安全** [#运维安全]

### **1、开启审计日志** [#1开启审计日志]

```
# 配置日志级别
openclaw config set logging.level info

# 开启会话日志
openclaw config set logging.session true

# 日志输出位置
tail -f /opt/openclaw/logs/openclaw.log
```

定期审查 OpenClaw 应用日志及 `/var/log/auth.log` 等系统日志，发现可疑的登录尝试或异常操作行为。

### **2、定期安全体检** [#2定期安全体检]

自动检查 OpenClaw 运行环境的安全状态。

```
# OpenClaw 系统体检
openclaw doctor

# 检查所有已安装插件的安全状态
openclaw plugin list --check-security
```

### **3、定期更新** [#3定期更新]

及时关注 OpenClaw 相关漏洞，定期更新版本，规避 RCE 风险。

```
# 更新 OpenClaw
openclaw update
# 重新运行部署命令

# 更新插件
clawhub update --all
```

## **应急响应** [#应急响应]

如您发现 OpenClaw 行为异常或疑似被入侵，请立即执行以下操作：

1. 立即隔离：修改 iptables 规则，将入方向流量来源 IP 限制为您自己的 IP，或直接关闭 18789 端口。
2. 暂停服务：`openclaw gateway stop`。注意：先不要删除应用，保留现场。
3. 轮换凭证：立即更换所有存储在服务器上的密钥。
4. 分析排查：检查最近的登录记录（last）、可疑进程、cron 任务以及 OpenClaw 的 Skill 安装记录。
5. 重建恢复：最佳实践是：创建一台新的云主机实例，从备份中恢复已验证安全的数据，并严格按照本加固指南重新部署。

**参考资料**

* [OpenClaw 官方安全文档](https://docs.openclaw.ai/gateway/security)
* [NVBD 关于防范OpenClaw（“龙虾”）开源智能体安全风险的“六要六不要”建议](https://mp.weixin.qq.com/s/iBibKhHwn95pGqovJeQ0KA)


# 基于自定义镜像实现系统盘的扩容/缩容 (/products/las/4-instance-disk-upgrade)



最近更新时间: 2026-05-08 18:20:04

**LAS 实例暂不支持在线扩缩容。**

如您确需调整实例配置，可以尝试 **通过自定义镜像重建实例** ，即「创建镜像 → 基于镜像新建目标配置实例 → 验证后释放原实例退款」。

> 📌 注意：自定义镜像暂**不支持跨区域使用**，配置变更需在同一地域内完成。

## 操作流程 [#操作流程]

### 步骤 1：在原实例创建自定义镜像 [#步骤-1在原实例创建自定义镜像]

1. 登录 [七牛云控制台](https://portal.qiniu.com/las/vm/instances) → 进入 **LAS 实例管理页**；
2. 选中**运行中**的目标实例 → 点击【更多】→【创建自定义镜像】；
   ![image.png](/docs-assets/products/las/%286-best-practices%29/4-instance-disk-upgrade/Flb58vulVm7vF929jL95WcJ24eqw-820e362ad260.webp)
3. 填写镜像名称与描述（建议包含变更类型+日期，如 `backup-upgrade-20260414`），点击确认关机并创建自定义镜像；
   ![image.png](/docs-assets/products/las/%286-best-practices%29/4-instance-disk-upgrade/FqxuXxSSBUkrcV9QStDqEiwblv_b-bdaae4af70a9.webp)

> 💡 最佳实践：
>
> * 关键数据请提前备份至对象存储或本地；
> * 记录原实例配置，便于新实例还原。

### 步骤 2：基于镜像创建新实例（选择目标配置） [#步骤-2基于镜像创建新实例选择目标配置]

1. 打开【[自定义镜像管理](https://portal.qiniu.com/las/vm/images/custom)】并等待镜像状态变为「可用」。
2. 选中刚创建的镜像 → 点击【创建实例】；
   ![image.png](/docs-assets/products/las/%286-best-practices%29/4-instance-disk-upgrade/FokhnBVr-7hHzC-bwLTUZkAEnAOE-210306959554.webp)
3. 在实例配置向导中调整目标参数：
   * **系统盘**：选择新容量（扩容/缩容）；
   * **其他配置**：建议保持与原实例一致；
4. 确认配置与费用，完成支付并创建新实例。

### 步骤 3：验证新实例并释放原实例 [#步骤-3验证新实例并释放原实例]

1. 登录新实例，确认新实例无误；
2. 选择旧的实例点击【更多】→【释放/退订】；
3. 按提示确认操作，系统将按剩余时长退还费用至账户余额，约 5～10 天到账；
4. （可选）保留原实例快照/镜像 7 天作为回滚缓冲，确认无误后再清理。

> ⚠️ 警告：释放操作不可逆，请务必完成充分验证 + 备份后再执行。


# 全栈应用服务器服务协议 (/products/las/0-las-the-terms-of-service)



最近更新时间: 2025-10-30 10:36:13

<div>
  版本生效日期：2025年04月23日
</div>

<br />

本协议是上海七牛信息技术有限公司(以下简称“七牛云”)与用户（以下简称“您”）就您使用七牛云提供的全栈应用服务器服务所订立的有效合约。<u>本协议由通用服务条款和专用服务条款共同构成，如遇通用服务条款与专用服务条款二者不一致之处，优先适用专用服务条款。 &#x2A;*您通过打印件加盖公章并寄回、付款、或在七牛云官方网站（即 [www.qiniu.com，以下称“七牛云官网”）相关版面点击确认，或以其它另行约定的方式加以确认后，即表示您与七牛云已达成约定，同意接受本协议所列全部条款内容。在签订本协议之前，请您仔细阅读本协议所列全部条款内容。如果您对本协议的条款内容有疑问，请联系七牛云商务部门垂询，七牛云将为您解释各项条款内容。如果您不同意本协议的任一条款内容，或者无法准确理解七牛云对相关条款的解释，请勿进行后续操作。您知晓进行后续操作或点击确认即视为无条件接受本协议全部条款的约束。](http://www.qiniu.com，以下称“七牛云官网”）相关版面点击确认，或以其它另行约定的方式加以确认后，即表示您与七牛云已达成约定，同意接受本协议所列全部条款内容。在签订本协议之前，请您仔细阅读本协议所列全部条款内容。如果您对本协议的条款内容有疑问，请联系七牛云商务部门垂询，七牛云将为您解释各项条款内容。如果您不同意本协议的任一条款内容，或者无法准确理解七牛云对相关条款的解释，请勿进行后续操作。您知晓进行后续操作或点击确认即视为无条件接受本协议全部条款的约束。)**</u>

<h3>
  通用服务条款
</h3>

<br />

本协议通用服务条款，详见[《七牛云服务用户协议》](https://www.qiniu.com/agreements/user-agreement)。

<h3>
  专用服务条款
</h3>

<br />

1.您购买七牛云全栈应用服务器服务，服务期到期或您发生欠费的，您应及时续费，否则七牛云有权停止服务，且没有义务继续存储您的数据，具体为：

1.1 <u>就包月的实例，服务期到期后，如您需继续使用七牛云服务的，您应及时续费</u>：

1.1.1 <u>**您服务器到期后，如您未及时续费，七牛云将对实例停机，但仍保留该实例，并继续存储您的数据**</u>；

1.1.2 <u>**如您未在服务器到期之时起7日届满（自停机开始时刻起算至第7日相同时刻为期限届满）前续费，七牛云将释放您的到期实例，并删除实例数据**</u>。

2.就您购买的全栈应用服务器服务，七牛云承诺按照七牛云在官网上公布的《服务等级协议》提供服务。


# 全栈应用服务器服务等级协议 (/products/las/1-las-sla)



最近更新时间: 2025-10-30 10:36:30

详细信息，请参见 [《七牛云全栈应用服务器服务等级协议》](https://www.qiniu.com/agreements/sla/las)


# 产品简介 (/products/mikustream/0-miku-live-streaming)



最近更新时间: 2026-02-10 14:29:12

七牛云 Miku 快直播流媒体平台是依托云边一体化架构和海量节点资源调度能力，构建高效的直播流媒体服务。
它支持多协议的 RTMP/SRT 推流、大规模的 FLV/HLS 直播 CDN 分发、和超低延时的 WHEP 协议拉流直播，也支持 RTC 连麦互动。
用户可以通过 API、SDK、及 MCP 方式调用直播平台功能、查询流量数据等。
![image.png](/docs-assets/products/mikustream/%280-product-introduction%29/0-miku-live-streaming/FowmhE9BFj9mWL-_V-AlEwymCJS0-a7273e041121.webp)


# 快速入门 (/products/mikustream/1-mikustream-quick-start)



最近更新时间: 2026-05-28 14:12:48

<a id="overview" />

# 概述 [#概述]

快速入门介绍了如何通过七牛开发者平台快速创建直播空间、直播流及获取推流播放地址等操作，一站式完成直播业务的基本推流及播放。本文档适用于通过七牛开发者平台管理直播业务的用户。

快速入门使用流程如下：

![image.png](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/FnY-ntR1-7dKkJd_ATf3hNsKOlNW-30a9b5797245.webp)

<a id="console-login" />

# 登录七牛开发者平台 [#登录七牛开发者平台]

* 访问[七牛官网](http://www.qiniu.com/)，点击右上角的 **登录**，进入[七牛开发者平台](https://portal.qiniu.com/create)
  ![image.png](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/signup1-f08b015111f4.webp)
* 输入账号登录七牛开发者平台，若尚未注册，单击[注册](https://portal.qiniu.com/signup)，进行七牛帐号注册。
  ![image.png](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/signup2-3f6f4f0b03ac.webp)

<a id="open-apply" />

# 实名认证 [#实名认证]

* 登录控制台后进入[实名认证页面](https://portal.qiniu.com/identity/choice)
  ![image.png](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/signup4-7fd606275814.webp)
* 选择对应的认证类型进行认证，根据需要填写认证信息，提交认证后公司会尽快对您的账号进行认证。
* 未认证的用户无法进行直播空间，因此请您先进行实名认证，审核通过后即可使用直播云。

<a id="bucket-create" />

# 创建直播空间 [#创建直播空间]

* 在[七牛开发者平台首页](https://portal.qiniu.com/home)定位到 **侧边栏——> Miku 快直播**
  ![miku.png](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/miku_0f3e9a7c2b1d8e4a6c5f9b7d2e1a0-d270b827356e.webp)
* 在[直播空间](https://portal.qiniu.com/mikustream/buckets)页面，点击新建直播空间，并填写直播空间基本信息
  ![image.png](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/createbucket2-a8c22073096c.webp)

<a id="bucket-create" />

# 绑定域名 [#绑定域名]

* 进入直播空间 -> 域名管理 -> 绑定域名
  ![image.png](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/miku_a9c4e2b7d0f13c6e8b5a2d7f9c4e1a6b-4b16f2fe48de.webp)
  直播域名需要进行ICP备案和公安备案，如不明确公安备案流程，请点击[帮助文档](/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information)协助您进行备案。
  HTTPS配置
  点击域名右边 -> 配置 -> HTTPS配置，可以进行https配置
  ![image.png](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/FjuSYRJ28Kt6eu3qoVWynJ8KakCs-6e25ecdbee4b.webp)

<a id="cname-domain" />

# CNAME直播域名 [#cname直播域名]

* 进入直播空间——>域名管理，查看域名、CNAME
  ![image.png](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/cname-9ac240cf2af6.webp)
* 根据域名及 CNAME，到域名所归属的 DNS 管理平台配置 CNAME

<a id="streaming-create" />

# 创建直播流 [#创建直播流]

1. 在[直播流](https://portal.qiniu.com/mikustream/streams)，点击新建直播流
   ![image.png](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/createstream-0d1ace256230.webp)

<a id="address-access" />

# 获取推流地址和播放地址 [#获取推流地址和播放地址]

1. 在直播空间——>目标空间——>域名管理中，查看各类型域名。
   推流地址，例： rtmp\://domain/bucket/stream
   拉流地址，例： [http://domain/bucket/stream.flv](http://domain/bucket/stream.flv)

<a id="obs-streaming" />

# OBS推流 [#obs推流]

1. 打开 OBS 推流软件，在设置——>直播中进行配置；
   ![服务器](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/obs1-bdabf05d0ff8.webp)
2. **服务** 选择自定义，将获取到的推流地址 rtmp\://domain/bucket/ 填入 **服务器**，流名与鉴权填入 **推流码**。若推流地址为无校验鉴权，则推流码处只需要输入流名即可。如图：
   ![串流类型](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/obs2-00deb4872e12.webp)
3. 点击 **开始直播**，进行推流；
   ![推流](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/obs3-773f06f227e2.webp)
4. 在[直播流](https://portal.qiniu.com/mikustream/streams)中可查看当前推流的状态和信息。

<a id="play" />

# 播放 [#播放]

1. 打开[播放器](https://live-player-demo.qiniu.com)，输入播放地址，点击播放
   ![image.png](/docs-assets/products/mikustream/%280-product-introduction%29/1-mikustream-quick-start/miku_6e1f8a3c0b9d4e7f2a5c8b1d9e6a4-311224e06181.webp)
2. 可通过[直播流数据](https://portal.qiniu.com/mikustream/statistics/stream)，查看直播流的当前在线人数，实时码率和帧率等信息。


# Pili 迁移指南 (/products/mikustream/2-pili-migrate)



最近更新时间: 2026-04-09 17:32:43

# 从 Pili 迁移到 Miku 快直播指南 [#从-pili-迁移到-miku-快直播指南]

## 迁移前注意事项 [#迁移前注意事项]

在开始迁移之前，请注意以下重要事项：

* **海外域名限制**：当前暂不支持覆盖海外区域的域名迁移，请联系客服获取解决方案
* **推流 SDK 兼容性**：如果需要使用 PILI 推流 SDK 请联系技术支持
* **控制台操作限制**：目前云导播和 Pub 转推功能尚未开放 API，需通过控制台手动操作

> **操作指引**：
>
> * 导播台：[https://portal.qiniu.com/mikustream/caster](https://portal.qiniu.com/mikustream/caster)
> * Pub 转推：[https://portal.qiniu.com/mikustream/pub/tasks](https://portal.qiniu.com/mikustream/pub/tasks)

# 迁移步骤详解 [#迁移步骤详解]

## 1. 创建直播空间 [#1-创建直播空间]

1. 登录 [Miku 快直播控制台](https://portal.qiniu.com/mikustream/buckets)
2. 新建直播空间

![新建直播空间](/docs-assets/products/mikustream/%280-product-introduction%29/2-pili-migrate/miku_5c7a9e1d4b8f0e2a6c3d9f1b7a4e8-e98da6cddc42.webp)

## 2. 域名绑定 [#2-域名绑定]

将原 Pili 推拉流域名迁移至 Miku 平台

![绑定域名](/docs-assets/products/mikustream/%280-product-introduction%29/2-pili-migrate/miku_e3a7b9c1d8f4a0e6b2c5d9f7a1e4-acd6fdee5e0c.webp)

**Miku 推流协议支持：**

```
# RTMP 推流
rtmp://<domain>/<bucket>/<stream>

# SRT 推流
srt://<domain>:1935?streamid=#!::h=<bucket>/<stream>,m=publish,domain=<domain>

# WHIP 推流
https://<domain>/<bucket>/<stream>.whip
```

**Miku 拉流协议支持：**

```
# RTMP 拉流
rtmp://<domain>/<bucket>/<stream>

# WHEP 拉流
http://<domain>/<bucket>/<stream>.whep

# HLS 拉流
http://<domain>/<bucket>/<stream>.m3u8

# FLV 拉流
http://<domain>/<bucket>/<stream>.flv

# SRT 拉流
srt://<domain>:1935?streamid=#!::h=<bucket>/<stream>,m=request,domain=<domain>

# DASH 拉流
http://<domain>/<bucket>/<stream>.mpd
```

> **性能优化建议**：经测试，Miku 使用 FLV 格式播放性能最优

> **备案要求**：直播域名需完成 ICP 备案和公安备案。如不确定备案流程，请参考[备案帮助文档](/faq/account-finance/3987-how-to-make-website-and-inquires-the-police-put-on-record-information)

## 3. CNAME 配置 [#3-cname-配置]

1. 获取 Miku 平台分配的域名和 CNAME
2. 在您的 DNS 管理平台配置该 CNAME 记录

![cname](/docs-assets/products/mikustream/%280-product-introduction%29/2-pili-migrate/miku_7ab39d84c2ef4a46b1da3f9c0e5d17bf-3dcdf7106b75.webp)

## 4. 录制配置 [#4-录制配置]

![录制设置](/docs-assets/products/mikustream/%280-product-introduction%29/2-pili-migrate/miku_8d2e9f4a7c1b5e0a6d3f9c2e8b1-15b4f1fc0eab.webp)

> **重要提示**：与 Pili 不同，Miku 在控制台中暂不支持存储过期时间设置，需要调用 [修改空间配置](/products/mikustream/mikustream-live-bucket-api/3-mikustream-live-bucket-config-update-api#recording-object) API 进行设置

## 5. 推流鉴权迁移 [#5-推流鉴权迁移]

如原 Pili 配置了推流鉴权，迁移至 Miku 时需调整签名算法。具体方法请参考：[Miku 鉴权文档](/products/mikustream/6-mikustream-live-authentication)

## 6. 拉流鉴权迁移 [#6-拉流鉴权迁移]

如原 Pili 配置了拉流鉴权，仅需将过期时间参数从 16 进制调整为 10 进制，其余逻辑保持不变。

**PILI:**
![PILI](/docs-assets/products/mikustream/%280-product-introduction%29/2-pili-migrate/miku_ae49c0d13f7b45c0b82e5f4d09a8c73d-fe59ffd82a34.webp)

**MIKU:**
![MIKU](/docs-assets/products/mikustream/%280-product-introduction%29/2-pili-migrate/miku_59e4c3ab7fdc49f88a3b15d607e1c4fb-168aa9909cab.webp)

## 7. 创建直播流 [#7-创建直播流]

![创建直播流](/docs-assets/products/mikustream/%280-product-introduction%29/2-pili-migrate/miku_c4e7a1f9d0b6e8c2a5d3f1b9e4-e3809cb10959.webp)

生成推流地址和拉流地址用于直播推流和观看

## 高级功能说明 [#高级功能说明]

### URL 重写规则 [#url-重写规则]

Pili 采用 break 模式（匹配即终止），而 Miku 采用 continue 模式（匹配后继续），使用 URL 重写时需特别注意此差异

### 直播流管理 [#直播流管理]

MIKU 默认开启 **自动创建流**，默认关闭 **自动删除过期流**

![直播流管理](/docs-assets/products/mikustream/%280-product-introduction%29/2-pili-migrate/miku_d4b1f3a9c2e6471b9f0a2e5c7d8b3f6a-964271bc730b.webp)

在 MIKU 内目前不支持设置开关

# 服务端 API 迁移指南 [#服务端-api-迁移指南]

API 详细文档请参考：[Miku API 概览](/products/mikustream/0-mikustream-live-an-overview-of-the-api)

> 与 PILI 相比，MIKU API 的接口路径、入参、出参存在较大差异。建议在调用前参考官方文档。以下为整体调用差异对比

## 接口域名替换 [#接口域名替换]

* **直播空间管理**：`pili.qiniuapi.com` → `mls.cn-east-1.qiniumiku.com`
* **功能接口**：`pili.qiniuapi.com` → `<bucket>.mls.cn-east-1.qiniumiku.com`

## 鉴权方案选项 [#鉴权方案选项]

### 方案 A：AK/SK（QiniuToken） [#方案-aakskqiniutoken]

* 可复用现有 Pili 签名代码
* 修改签名串和 Host 为 `mls.<region>.qiniumiku.com`
* [AK/SK 认证文档](/products/mikustream/3-mikustream-live-http-requests-authentication#2)

### 方案 B：Bearer API Key [#方案-bbearer-api-key]

1. 创建 API Key：`POST http://mls.<region>.qiniumiku.com/?apikey`
2. 请求鉴权：`Authorization: Bearer <Miku API Key>`

* [Bearer Token 认证文档](/products/mikustream/3-mikustream-live-http-requests-authentication#1)

### 方案 C：IAM 子账号 [#方案-ciam-子账号]

* 使用 `AccessKey: IAM-xxxx` + `SecretKey`
* 保持 QiniuToken 签名方式
* [IAM 认证文档](/products/mikustream/3-mikustream-live-http-requests-authentication#3)

**变更要点：**

* IAM 子账号不再需要专用域名 `pili-iam.qiniuapi.com`
* AK/SK 鉴权与 Pili 保持一致
* 新增 Bearer Token 支持
* 详见 [API 请求鉴权](/products/mikustream/3-mikustream-live-http-requests-authentication)

# 快直播适配说明 [#快直播适配说明]

**原 Pili 快直播用户：**

* 如需使用 whep 拉流，可升级至最新版 [快直播 SDK](/products/mikustream/miku-fast-live-sdk/0-miku-fast-live-sdk-download-experience)
* quic 协议暂不支持
* 其余功能可顺畅迁移

***

# 技术支持服务 [#技术支持服务]

如有任何迁移问题或技术疑问，欢迎通过右下角联系我们的技术支持团队获取专业协助。


# 计费概述 (/products/mikustream/0-mikustream-the-billing-summary)



最近更新时间: 2026-06-16 17:13:37

1. [标准协议直播计费](#tutorial1)
2. [超低延时协议直播计费](#tutorial2)
3. [直播转码计费](#tutorial3)

# **直播云计费组成** [#直播云计费组成]

直播云的计费有三部分组成：基础服务费用、增值业务费用、其他云产品费用
各计费项均支持按量付费，部分支持资源包，前购买资源的使用额度和时长，获取更多的优惠。
视频直播的详细价格信息，请参见[直播云价格文档](https://www.qiniu.com/prices/mikustream)

# **基础服务费用** [#基础服务费用]

使用直播云进行推流和播流会产生基础直播服务费用

| 类型     | 计费方式                     | 付费方式 | 相关文档                                                |
| ------ | ------------------------ | ---- | --------------------------------------------------- |
| 直播基础服务 | 标准协议直播计费<br />超低延时协议直播计费 | 后付费  | [直播基础服务费用](https://www.qiniu.com/prices/mikustream) |
| 直播基础服务 | 直播流量资源包                  | 预付费  |                                                     |

## <span id="tutorial1">**标准协议直播计费**</span> [#标准协议直播计费]

直播计费为使用RTMP推流，RTMP/FLV/HLS拉流产生的带宽或者流量计费
**日峰值带宽计费**
以当日直播区域所在节点直播加速服务分别产生的带宽最高值（单位Mbps）为结算标准
三大直播加速区域：中国大陆、港澳台和海外

* 备注一：不同区域，收费价格不同。如果在三个区域都有观众拉流观看，三个区域均会收费，以三个区域各自的峰值带宽进行收费
* 备注二：日峰值峰值为当日下行带宽峰值+上行带宽峰值的最高值
  （举例：某日的5点：下行峰值带宽是1Gbps，上行峰值带宽是0.3Gbps;10点：下行峰值是1.2Gbps，上行峰值是0.2Gbps
  那么这天的峰值带宽是10点的下行峰值1.2Gbps+上行峰值0.2Gbps=1.4Gbps)

计费方式：每月出账后付费（账单）
计费规则：按直播日峰值带宽的阶梯价格计费，统计一个自然日内产生的带宽最高值（单位：Mbps）乘以对应的阶梯价格，为最终结算标准
计费周期：按月出账，具体出账时间以系统为准

**流量计费**
按不同区域流量阶梯价格计费，流量累积到自然月底，下月自动清零重新累积。
三大直播加速区域：中国大陆、港澳台和海外

* 备注一：不同区域，收费价格不同。如果在三个区域都有观众拉流观看，三个区域均会收费，以三个区域各自的流量累计进行收费
* 备注二：推流上行也会进行对应区域的流量累计

计费规则：按月到达阶梯计费，统计一个自然月内的流量累计值乘以对应的阶梯价格
计费周期：按月出账，具体出账时间以系统为准

## <span id="tutorial2">**超低延时协议直播计费**</span> [#超低延时协议直播计费]

超低延时协议直播计费是使用七牛云 WHEP(RTC) 直播拉流产生的下行带宽或者流量费用
**日峰值带宽计费**
以当日直播区域所在节点直播加速服务分别产生的带宽最高值（单位Mbps）为结算标准
三大直播加速区域：中国大陆、港澳台和海外

* 备注一：不同区域，收费价格不同。如果在三个区域都有观众拉流观看，三个区域均会收费，以三个区域各自的峰值带宽进行收费

计费方式：每月出账后付费（账单）
计费规则：按直播日峰值带宽的阶梯价格计费，统计一个自然日内产生的带宽最高值（单位：Mbps）乘以对应的阶梯价格，为最终结算标准
计费周期：按月出账，具体出账时间以系统为准

**流量计费**
按不同区域流量阶梯价格计费，流量累积到自然月底，下月自动清零重新累积。
三大直播加速区域：中国大陆、港澳台和海外

* 备注一：不同区域，收费价格不同。如果在三个区域都有观众拉流观看，三个区域均会收费，以三个区域各自的流量累计进行收费

计费规则：按月到达阶梯计费，统计一个自然月内的流量累计值乘以对应的阶梯价格
计费周期：按月出账，具体出账时间以系统为准

# **增值业务费用** [#增值业务费用]

直播云除了基础服务之外，还提供了一些额外的增值功能，不使用则不会产生对应的费用

| 类型   | 计费方式   | 付费方式         | 相关文档                                                                                                                                  |
| ---- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| 直播转码 | 转码时长计费 | 后付费<br />预付费 | [直播转码时长费用](https://www.qiniu.com/prices/mikustream)\<br>[转码资源包](https://qmall.qiniu.com/template/MzE?ref=category\&spec_combo=MTUyMg) |

## <span id="tutorial3">**直播转码计费**</span> [#直播转码计费]

直播转码按使用的不同转码标准、不同分辨率规格及对应总时长为结算标准
分辨率分为480p、720p、1080p、2K、4K
分辨率说明：

1. 长边小于等于640 且 短边小于等于480，统计为480p
2. 长边小于等于1280 且 短边小于等于720，统计为720p
3. 长边小于等于1920 且 短边小于等于1080，统计为1080p
4. 长边小于等于2560 且 短边小于等于1440，统计为2K
5. 长边大于等于2560 或 短边大于等于2160，统计为4K

计费规则：以编码方式和分辨率计费，按不同编码标准和不同分辨率规格的转码时长乘以对应的单价，以分钟为计费单位，不足一分钟计一分钟
计费周期：按月计费，具体出账时间以系统为准

# **其他云产品使用费用** [#其他云产品使用费用]

在使用直播云的同时，会依赖使用其他云产品，其他云产品也会同步产生费用

| 产品            | 产生费用方式                                                   | 相关文档                                                         |
| ------------- | -------------------------------------------------------- | ------------------------------------------------------------ |
| 对象存储（Kodo）    | 直播录制视频、直播截图存储、生成点播视频和云导播台上传静态文件等会使用到对象存储产品，把相关文件存储在对象存储上 | [对象存储计费说明](https://www.qiniu.com/prices/kodo?source=kodo)    |
| 智能多媒体服务（Dora） | 直播截图、直播封面、主动录制mp4/flv视频将会用到智能多媒体服务产品                     | [智能多媒体服务计费说明](https://www.qiniu.com/prices/dora?source=dora) |
| CDN           | 使用点播域名播放、访问直播封面或直播截图                                     | [CDN计费说明](https://www.qiniu.com/prices/qcdn)                 |


# 回源拉流 (/products/mikustream/1-originpulling)



最近更新时间: 2026-06-16 17:13:44

# 回源拉流 [#回源拉流]

针对特定业务需求，当您已自建流媒体服务器并使用RTMP协议推流到自有节点时，若面临以下挑战：

* **高并发压力** - 源站服务器负载能力有限
* **直播延迟** - 实时性要求无法满足

配置七牛直播云回源拉流功能，由七牛云主动从您的源站拉取直播流，再利用七牛云的分布式节点进行内容分发。

***

# 访问控制台 [#访问控制台]

1. 登录 [七牛云 MikuStream 控制台](https://portal.qiniu.com/mikustream/buckets)
2. 选择目标直播空间

# 配置播放域名 [#配置播放域名]

1. 进入「域名管理」页面
2. 选择需要启用回源拉流的播放域名

![回源拉流](/docs-assets/products/mikustream/%282-development-guidelines%29/1-originpulling/miku_3a9d7f4c2e8b41d0b6f5c1e9a27d8b6c-9378334cf4d7.webp)

# 启用回源拉流 [#启用回源拉流]

1. 点击「高级设置」
2. 开启「回源拉流」功能

![回源拉流配置示意图](/docs-assets/products/mikustream/%282-development-guidelines%29/1-originpulling/miku_3b9fa1e4d6c4420e9c87f52ab014c8de-2d4e6aafb85a.webp)

> 注意：当前回源地址仅支持 FLV 与 RTMP 协议。如需回源 M3U8，请联系技术支持开通或确认支持方案。

# 设置回源拉流超时时间 [#设置回源拉流超时时间]

设置后，回源拉流闲置超过设定时长，断开连接，默认 30 s

![回源拉流超时](/docs-assets/products/mikustream/%282-development-guidelines%29/1-originpulling/miku_f7c2a9b1e6d8430d9c54e18b2a6f0c3d-f9ac431aa9a6.webp)

***

配置完成后，使用该播放域名进行流播放：

* **流名规则**：可任意指定流名
* **播放流程**：七牛云将自动从您的源站拉取对应直播流
* **兼容性**：支持标准播放协议

通过以上配置，您即可享受七牛直播云带来的高性能分发服务，同时保持对源站内容的完全控制。


# 直播转码 (/products/mikustream/2-livetranscoding)



最近更新时间: 2026-01-28 17:00:21

# 直播转码 [#直播转码]

直播转码模板需要绑定到 **直播空间** 或 **直播流** 才能生效。每个账号最多可设置 **50 个转码模板**。使用转码模板会产生额外费用，具体价格请参考 [转码计费规则](https://www.qiniu.com/prices/mikustream)。

***

# 创建转码模板 [#创建转码模板]

1. 打开 [直播转码模板管理](https://portal.qiniu.com/mikustream/templates)。
2. 点击 **新建模板**。
3. 配置转码参数，包括分辨率、码率、帧率等。

![转码设置](/docs-assets/products/mikustream/%282-development-guidelines%29/2-livetranscoding/miku_a7c4e9f132bd4a0c9f85d672b13e4f8c-0c5abcbfaa17.webp)
![转码设置](/docs-assets/products/mikustream/%282-development-guidelines%29/2-livetranscoding/miku_f29c7e1bd4a4410e8c36a95f7b12e8cf-4a8c9df03348.webp)

## 配置项详细说明 [#配置项详细说明]

| 配置项        | 配置参数                    | 详细说明                                                                                                                               |
| ---------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **模板名称**   | 英文或数字                   | 自定义模板名称，方便管理。支持字母、数字、中划线、下划线，长度 4-64 个字符，例如 `hd_720p` 或 `live_1080p`                                                               |
| **模板描述**   | 任意文字                    | 对模板用途的说明，例如“高清直播用”，不超过 200 个字符                                                                                                     |
| **音视频输出**  | 音视频同时输出 / 只输出视频 / 只输出音频 | 决定转码后输出内容：<br />- 音视频同时输出 → 保留画面和声音<br />- 只输出视频 → 无声音<br />- 只输出音频 → 无画面，适合音乐或播客直播                                                |
| **视频编码**   | H264 / H265             | 视频压缩格式：<br />- H264 → 兼容性好，设备支持广<br />- H265 → 压缩率高，文件小，但部分设备不支持                                                                   |
| **分辨率**    | 固定分辨率 / 长边或短边设置         | 输出视频的清晰度：<br />- 固定分辨率，例如 1280x720\<br>- 长边/短边设置 → 根据画面长宽，自行确认宽高分辨率                                                                |
| **视频码率**   | kbps                    | 影响画面清晰度和网络流量：<br />- 高码率 → 画面清晰，但占用带宽大<br />- 低码率 → 节省带宽，但可能模糊<br />参考：480p 800–1200 kbps，720p 1500–2500 kbps，1080p 3000–5000 kbps |
| **视频帧率**   | fps                     | 视频每秒播放帧数：<br />- 30fps → 普通直播够用<br />- 60fps → 动作更流畅，适合游戏或体育直播                                                                     |
| **关键帧间隔**  | 秒                       | I 帧出现间隔                                                                                                                            |
| **去 B 帧**  | 布尔值                     | B 帧用于压缩，去掉可减少延迟，如果有 RTC 观众且推流端无法控制 B 帧，建议开启                                                                                        |
| **保留 SEI** | 布尔值                     | SEI 是视频中的附加信息，可用于字幕或时间戳，需要可关闭                                                                                                      |
| **音频编码**   | AAC                     | 音频压缩格式，固定为 AAC，兼容性和音质好                                                                                                             |
| **声道数**    | 原声道 / 单声道 / 双声道 / 更多    | 音频通道设置：<br />- 单声道 → 文件小，适合语音<br />- 双声道 → 常用，适合直播音乐<br />- 原声道 → 保持原视频声道                                                          |

**小贴士**：

* 不确定码率或帧率，可参考常用直播标准，避免画面模糊或卡顿。
* 推流端去 B 帧操作可参考 [OBS 推不含 B 帧指南](/products/mikustream/0-obs-streaming-excluding-b-frame-guidelines)。

***

# 绑定转码模板 [#绑定转码模板]

1. 打开 [直播空间列表](https://portal.qiniu.com/mikustream/buckets)。
2. 点击目标直播空间，绑定所需转码模板。

![转码模板绑定](/docs-assets/products/mikustream/%282-development-guidelines%29/2-livetranscoding/miku_92e4c7b1a0d5f83c6e1b4a9d2f8c7e0a-696e93a45323.webp)

## 注意事项 [#注意事项]

* 模板绑定后不会影响正在推流的直播流，需要 **重新推流** 才能生效。
* **被动转码**：有对应播放请求时触发。
* **主动转码**：推流时立即触发。

***

# 获取转码播放地址 [#获取转码播放地址]

1. 打开 [地址生成器](https://portal.qiniu.com/mikustream/tools/address-generator)。
2. 填写相关信息，即可生成转码播放地址，用于播放或分享。

![地址生成器](/docs-assets/products/mikustream/%282-development-guidelines%29/2-livetranscoding/miku_ef29c7d1b43a4f0e9d8a62f7c104b3de-86d8399f1987.webp)

**建议**：
在绑定模板前，先规划好转码方案和输出分辨率，避免重复操作导致额外费用。


# 直播推拉流时间戳防盗链 (/products/mikustream/3-miku-live-authentication)



最近更新时间: 2026-01-28 17:00:21

# 七牛直播推流/拉流时间戳防盗链 [#七牛直播推流拉流时间戳防盗链]

本文覆盖两部分：

* **推流时间戳防盗链**：RTMP 推流
* **拉流时间戳防盗链**：HLS（.m3u8）、FLV（.flv）、RTMP 播放等

## 术语 [#术语]

* **publishDomain**：推流域名
* **playDomain**：播放域名
* **bucket**：直播空间名称
* **stream**：直播流名称
* **publishKey**：推流鉴权密钥（配置在**推流域名/空间**）
* **playKey**：播放防盗链密钥（配置在**播放域名**）
* **t（expireAt）**：过期时间的 &#x2A;*UNIX 时间戳（秒）**
* **path**：URL 的路径部分，**必须以 `/` 开头**；如 `rtmp://test.miku.com/sdk-live/test` 的 path 为 `/sdk-live/test`

> 签名串中涉及 URL 编码时，需&#x2A;*保留斜杠 `/`**（参考下文示例代码的处理方式）。

***

## 一、推流时间戳防盗链 [#一推流时间戳防盗链]

在**推流域名**上设置 **publishKey**，并在推流地址后追加 `?sign=...&t=...`。

**签名公式**

```
sign = md5(publishKey + path + t).to_lower()
```

* `path`：如 `/sdk-live/test`
* `t`：过期时间 UNIX 时间戳（秒）

**示例**

```
publishDomain: test.miku.com
bucket: sdk-live
stream: test
publishKey: test
t (expireAt): 1756110618
path: /sdk-live/test

SignStr = "test/sdk-live/test1756110618"
sign = md5(SignStr).to_lower() = 6a1b665f529c8b57d6408b72e4d21350

最终推流地址:
rtmp://test.miku.com/sdk-live/test?sign=6a1b665f529c8b57d6408b72e4d21350&t=1756110618
```

> Portal 中主/副密钥（均可以进行鉴权）均可使用；建议使用**副密钥**进行轮换，降低主密钥更换风险。

***

## 二、拉流时间戳防盗链 [#二拉流时间戳防盗链]

播放防盗链可以有效避免直播资源被非法盗用的问题。
在**播放域名**上开启“时间戳防盗链”并设置 **playKey**。访问播放地址时，边缘节点按相同规则校验，非法则拒绝（常见表现：HLS/FLV 403；RTMP 播放连接失败/服务返回错误）。

**推流地址格式**

```
[rtmp/http]://<playDomain>/<bucket>/<stream>.[flv/m3u8]
```

**签名公式**

```
sign = md5(playKey + path + t).to_lower()
```

**path 取值示例**

| 协议     | 地址示例                                         | 用于签名的 `path`          |
| ------ | -------------------------------------------- | --------------------- |
| HLS    | `http://play.example.com/bucket/stream.m3u8` | `/bucket/stream.m3u8` |
| FLV    | `http://play.example.com/bucket/stream.flv`  | `/bucket/stream.flv`  |
| RTMP播放 | `rtmp://play.example.com/bucket/stream`      | `/bucket/stream`      |

> **注意**：不同协议的 `path` 不同

### 生成步骤 [#生成步骤]

1. **开启时间戳防盗链并获取 playKey**
   控制台 → 直播空间 → 播放域名 → 开启时间戳防盗链 → 配置主/副密钥
2. **确定过期时间 `t`（秒）**
   ```bash
   # macOS:
   t=$(date -j -f "%Y-%m-%d %H:%M:%S" '2025-10-29 20:00:00' +%s)
   # 结果示例：1761739200
   ```
3. **计算 `sign`**
   ```bash
   sign=md5(playKey + path + t).to_lower()
   ```

### HLS 示例 [#hls-示例]

未鉴权地址：

```
http://pili-hls.pilitest.com/bucket/stream.m3u8
```

开启后：

```
playDomain: pili-hls.pilitest.com
playKey = test
path    = /bucket/stream.m3u8
t       = 1761739200

sign    = md5("test/bucket/stream.m3u81761739200").to_lower()
        = 3acc8aa865f23adfdbceba694e7dc4b9

最终播放地址：
http://pili-hls.pilitest.com/bucket/stream.m3u8?sign=3acc8aa865f23adfdbceba694e7dc4b9&t=1761739200
```

***

## 三、参考代码（兼容推流/拉流） [#三参考代码兼容推流拉流]

> 同一签名方法适用于推流与拉流。区别仅在于：&#x2A;*使用的 Key（publishKey/playKey）** 与 **path**（推拉流 RTMP `/bucket/stream`；拉流 HLS `/bucket/stream.m3u8`；拉流 FLV `/bucket/stream.flv`）。

### Java [#java]

```java
package com.qiniu.hugo.miku;

import java.net.URLEncoder;
import java.nio.charset.Charset;
import java.security.MessageDigest;

public class TimestampAntiLeechUrl {

    private static final char[] DIGITS_LOWER = {
        '0','1','2','3','4','5','6','7','8','9','a','b','c','d','e','f'
    };

    public static void main(String[] args) {
        // 推流（Publish）
        String publishUrl = "rtmp://test.miku.com/sdk-live/test";
        long t1 = System.currentTimeMillis()/1000 + 20*60;
        String publishKey = "test";
        System.out.println(signUrl(publishUrl, publishKey, t1));

        // HLS 播放（Play）
        String hlsUrl = "http://test.miku.com/sdk-live/test.m3u8";
        long t2 = System.currentTimeMillis()/1000 + 20*60;
        String playKey = "test";
        System.out.println(signUrl(hlsUrl, playKey, t2));
    }

    public static String signUrl(String url, String key, long expireTs) {
        try {
            String path = url.substring(url.indexOf("/", url.indexOf("//") + 2));
            // 保留斜杠，仅编码其他字符
            String encodedPath = URLEncoder.encode(path, "UTF-8").replace("%2F", "/");
            String t = String.valueOf(expireTs);
            String toSign = key + encodedPath + t;
            String sign = md5Lower(toSign);
            return String.format("%s?sign=%s&t=%s", url, sign, t);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    private static String md5Lower(String src) throws Exception {
        MessageDigest md = MessageDigest.getInstance("MD5");
        md.update(src.getBytes(Charset.forName("UTF-8")));
        byte[] bytes = md.digest();
        return encodeHex(bytes);
    }

    private static String encodeHex(byte[] data) {
        char[] out = new char[data.length << 1];
        for (int i = 0, j = 0; i < data.length; i++) {
            out[j++] = DIGITS_LOWER[(0xF0 & data[i]) >>> 4];
            out[j++] = DIGITS_LOWER[0x0F & data[i]];
        }
        return new String(out);
    }
}
```

### Go [#go]

```go
package main

import (
	"crypto/md5"
	"encoding/hex"
	"fmt"
	"net/url"
	"strings"
	"time"
)

func main() {
	// 推流（Publish）
	pub := "rtmp://test.miku.com/sdk-live/test"
	fmt.Println(SignURL(pub, "test", time.Now().Unix()+20*60))

	// HLS 播放（Play）
	hls := "http://test.miku.com/sdk-live/test.m3u8"
	fmt.Println(SignURL(hls, "test", time.Now().Unix()+20*60))
}

func SignURL(baseURL, key string, expire int64) (string, error) {
	u, err := url.Parse(baseURL)
	if err != nil {
		return "", err
	}
	// path 必须以 / 开头
	path := u.Path
	// 保留斜杠，仅编码其他字符
	encodedPath := strings.ReplaceAll(url.QueryEscape(path), "%2F", "/")
	t := fmt.Sprintf("%d", expire)
	toSign := key + encodedPath + t
	sign := md5Lower(toSign)
	return fmt.Sprintf("%s?sign=%s&t=%s", baseURL, sign, t), nil
}

func md5Lower(s string) string {
	sum := md5.Sum([]byte(s))
	return hex.EncodeToString(sum[:])
}
```

***

## 四、易错点与最佳实践 [#四易错点与最佳实践]

1. **密钥配置位置**
   * 推流鉴权用 **publishKey**（配置在**推流域名/空间**）
   * 播放防盗链用 **playKey**（配置在**播放域名**）

2. **path 必须准确**
   * 推拉流 RTMP：`/bucket/stream`
   * 拉流 HLS：`/bucket/stream.m3u8`
   * 拉流 FLV：`/bucket/stream.flv`

3. **URL 编码**
   * 仅编码必要字符并&#x2A;*保留 `/`**，参考示例代码

4. **时间戳单位**
   * `t` 为**秒级** UNIX 时间戳

5. **主/副密钥轮换**
   * 支持主/副密钥；使用副密钥灰度切换更稳妥

6. **排查清单**
   * 403/连接失败：检查 `path` 是否正确、`t` 是否过期、签名大小写、是否双重编码
   * 跨协议失败：核对协议对应的 `path` 后缀（`.m3u8`/`.flv`）
   * 同一域名多密钥：确认实际启用的是哪一把（主/副）

***


# 超低延时协议直播 B 帧兼容性 (/products/mikustream/0-obs-streaming-excluding-b-frame-guidelines)



最近更新时间: 2026-02-10 14:30:21

# 什么是 B 帧？ [#什么是-b-帧]

B 帧（Bidirectional Predictive Frame）是 H.264/H.265 编码中的双向预测帧，通过参考前后帧实现更高的压缩效率，但解码需要依赖前后帧，因此会带来额外的延迟和复杂度。

**特点：**

* 压缩率高
* 解码依赖更多参考帧
* 存在 PTS/DTS 重排序

# 为什么超低延时协议直播播放器可能不兼容 B 帧？ [#为什么超低延时协议直播播放器可能不兼容-b-帧]

RTC（实时通信）场景对延迟极度敏感，默认要求无 B 帧，而且 B 帧会引入帧重排和解码等待，会影响实时性。

可能带来的问题包括：

* **延迟增加**：需要等待后续帧才能解码 B 帧
* **丢帧风险更高**：参考帧丢失导致 B 帧无法恢复

# 超低延时协议直播播放器中的不兼容表现 [#超低延时协议直播播放器中的不兼容表现]

当推流中包含 B 帧时，可能出现：

* 黑屏
* 卡顿、跳帧
* 花屏、画面错乱
* 延迟明显增加

# 如何解决 B 帧兼容问题？ [#如何解决-b-帧兼容问题]

## 方案 1（推荐方案）：推流端禁用 B 帧 [#方案-1推荐方案推流端禁用-b-帧]

以 OBS 为例：

### 步骤 1：进入设置 [#步骤-1进入设置]

OBS → 设置
![OBS设置页面](/docs-assets/products/mikustream/%285-best-practices%29/0-obs-streaming-excluding-b-frame-guidelines/FjqAtnQAaJgqdLd66TrZTbaeZ9C7-a9968e9c6609.webp)

### 步骤 2：输出配置 [#步骤-2输出配置]

根据下图配置OBS的输出配置。

![输出配置](/docs-assets/products/mikustream/%285-best-practices%29/0-obs-streaming-excluding-b-frame-guidelines/FhW7PA_yBvY6ARNIQxGFOp-f4Ihg-2149dab14f9f.webp)

### 步骤 3：推流配置 [#步骤-3推流配置]

进入推流设置，服务选择自定义，将七牛云的推流地址复制粘贴到服务器和串流密钥上，点击确定。
![输出配置](/docs-assets/products/mikustream/%285-best-practices%29/0-obs-streaming-excluding-b-frame-guidelines/FhW7PA_yBvY6ARNIQxGFOp-f4Ihg-2149dab14f9f.webp)

### 步骤 4：开始推流 [#步骤-4开始推流]

点击开始推流，即可推不含B帧的直播流到七牛云直播服务上。

> 此方案是最推荐方式，零成本且从源头规避 B 帧问题。

## 方案 2：使用云端转码去除 B 帧（无法控制推流端时） [#方案-2使用云端转码去除-b-帧无法控制推流端时]

若推流设备无法关闭 B 帧，可在 Miku 快直播控制台使用“去 B 帧”转码模板。

### 步骤 1 [#步骤-1]

打开[直播转码控制台](https://portal.qiniu.com/mikustream/templates)

### 步骤 2 [#步骤-2]

创建转码模板并勾选“去 B 帧”。
![](/docs-assets/products/mikustream/%285-best-practices%29/0-obs-streaming-excluding-b-frame-guidelines/miku_e47c1a92fb8f4d5cbe3c0f7a91d2e6f3-04ee11643483.webp)

### 步骤 3 [#步骤-3]

直播空间绑定转码模版。
![转码模板绑定](/docs-assets/products/mikustream/%285-best-practices%29/0-obs-streaming-excluding-b-frame-guidelines/miku_b8e1c9f4a0d7e2a6c5b3f9d1e8a7c4-2a3805df970c.webp)

> 注意：使用转码模板会产生额外费用，具体价格请参考 [转码计费规则](https://www.qiniu.com/prices/mikustream)

# 如何检查视频流是否包含 B 帧？ [#如何检查视频流是否包含-b-帧]

使用 ffprobe（推荐）：

```bash
ffprobe -v error -show_frames -select_streams v:0 <流地址>
```

检查输出中的 pict\_type：

* I = 关键帧
* P = 前向预测帧
* B = 双向预测帧（即 B 帧）

若看到 pict\_type=B，说明流中存在 B 帧。


# 如何使用直播MCP Server (Live Streaming) (/products/mikustream/1-miku-live-streaming-mcp-server)



最近更新时间: 2026-01-14 17:40:22

> 引用本文档展示在VS Code中使用AI编程工具`Kilo`来调用 [`七牛云Miku快直播MCP Server`](https://github.com/qiniu/qiniu-mcp-server)的对话过程。

# 一 环境配置 [#一-环境配置]

## 1. 在本地运行MCP Server [#1-在本地运行mcp-server]

```shell
# 克隆MCP代码
git clone git@github.com:qiniu/qiniu-mcp-server.git
# 参考 README.md 安装配置
cd qiniu-mcp-server
uv --directory . run qiniu-mcp-server --transport sse --port 8000
```

## 2. 在Kilo中配置MCP Servers [#2-在kilo中配置mcp-servers]

```json
{
  "mcpServers": {
    "qiniu-miku-live-streaming": {
	"url": "http://localhost:8000/sse",
	"disabled": false
     }
  }
}
```

![kilo-mcp.png](/docs-assets/products/mikustream/%285-best-practices%29/1-miku-live-streaming-mcp-server/FmTVzuB1SSnY2aC6x-1-Qp1qs9uM-d9655378ee50.webp)

## 3. 为Kilo配置大模型 [#3-为kilo配置大模型]

![kilo-live.png](/docs-assets/products/mikustream/%285-best-practices%29/1-miku-live-streaming-mcp-server/FkYvLE__4VYIGMqYwihQvg6FDg9m-4ea9bd6f0513.webp)

***

# 二 对话过程 [#二-对话过程]

## 1. 查看直播空间 [#1-查看直播空间]

### **User:** [#user]

```xml
<task>
查看下我的直播空间
</task>
<environment_details>
# VSCode Visible Files
../.config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json

# Current Mode

<slug>code</slug>
<name>Code</name>
<model>glm-4.5-air</model>

# Current Workspace Directory (/home/teric/Documents) Files
</environment_details>
```

***

### **Assistant:** [#assistant]

```shell
I'll help you view the live streaming spaces. Let me use the available MCP tool to list all live streaming buckets/spaces.

<use_mcp_tool>
<server_name>remote-live-streaming</server_name>
<tool_name>live_streaming_list_buckets</tool_name>
<arguments>
{}
</arguments>
</use_mcp_tool>
```

***

```shell
[use_mcp_tool for 'remote-live-streaming'] Result:
```

```json
{'status': 'success', 'data': '{"buckets":[{"name":"dfddd","region":"cn-east-1","status":"Enabled","creationDate":"2025-10-28T22:33:46.145+08:00"}],"connectId":"YmgAAJpKaC_cInsY"}', 'message': 'Buckets listed successfully', 'status_code': 200}
```

```shell
<environment_details>
# VSCode Visible Files
../.config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json

# VSCode Open Tabs

# Current Time

# Current Cost
$0.00

# Current Mode
<slug>code</slug>
<name>Code</name>
<model>glm-4.5-air</model>
You have not created a todo list yet. Create one with `update_todo_list` if your task is complicated or involves multiple steps.
</environment_details>
```

***

### **Assistant:** [#assistant-1]

已成功查看到直播空间信息：

**直播空间列表：**

1. **空间名称：** dfddd
   * **区域：** cn-east-1
   * **状态：** Enabled（已启用）
   * **创建时间：** 2025-10-28T22:33:46.145+08:00

**连接ID：** YmgAAJpKaC\_cInsY

目前有1个可用的直播空间，状态为已启用。

***

## 2. 查看直播流、及流量情况 [#2-查看直播流及流量情况]

### **User:** [#user-1]

```shell
[attempt_completion] Result:
The user has provided feedback on the results. Consider their input to continue the task, and then attempt completion again.
<feedback>
查看直播流和流量
</feedback>
<environment_details>
# VSCode Visible Files
../.config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json

# VSCode Open Tabs

# Current Time
Current time in ISO 8601 UTC format: 2025-11-25T03:40:24.570Z
User time zone: Asia/Singapore, UTC+8:00

# Current Cost
$0.00

# Current Mode
<slug>code</slug>
<name>Code</name>
<model>glm-4.5-air</model>
You have not created a todo list yet. Create one with `update_todo_list` if your task is complicated or involves multiple steps.
</environment_details>
```

***

### **Assistant:** [#assistant-2]

```shell
我将帮您查看直播流和流量信息。首先让我查看直播空间中的流列表，然后获取流量统计数据。

<use_mcp_tool>
<server_name>remote-live-streaming</server_name>
<tool_name>live_streaming_list_streams</tool_name>
<arguments>
{
  "bucket_id": "dfddd"
}
</arguments>
</use_mcp_tool>
```

***

```shell
[use_mcp_tool for 'remote-live-streaming'] Result:
```

```json
{'status': 'success', 'bucket_id': 'dfddd', 'data': '{"items":[{"key":"eeeee","forbidden":false,"creationDate":"2025-10-28T22:33:52.811+08:00","status":"offline","lastStartAt":0,"publishUrl":"","isConverted":false,"streamOnlineInfo":null}],"total":1,"totalPage":1,"pageIndex":1,"pageSize":10}', 'message': "Streams in bucket 'dfddd' listed successfully", 'status_code': 200}
```

```shell
<environment_details>
# VSCode Visible Files
../.config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json

# VSCode Open Tabs

# Current Time
Current time in ISO 8601 UTC format: 2025-11-25T03:40:29.908Z
User time zone: Asia/Singapore, UTC+8:00

# Current Cost
$0.00

# Current Mode
<slug>code</slug>
<name>Code</name>
<model>glm-4.5-air</model>
You have not created a todo list yet. Create one with `update_todo_list` if your task is complicated or involves multiple steps.
</environment_details>
```

***

### **Assistant:** [#assistant-3]

```shell
现在让我获取直播流量统计数据。我将查询最近24小时的流量信息：

<use_mcp_tool>
<server_name>remote-live-streaming</server_name>
<tool_name>live_streaming_query_live_traffic_stats</tool_name>
<arguments>
{
  "begin": "20241125000000",
  "end": "20241125235959"
}
</arguments>
</use_mcp_tool>
```

***

```
[use_mcp_tool for 'remote-live-streaming'] Result:
{'status': 'success', 'begin': '20241125000000', 'end': '20241125235959', 'data': '[{"time":"2024-11-25T00:00:00+08:00","values":{"flow":0}},{"time":"2024-11-25T00:05:00+08:00","values":{"flow":0}},{"time":"2024-11-25T00:10:00+08:00","values":{"flow":0}},{"time":"2024-11-25T00:15:00+08:00","values":{"flow":0}},{"time":"2024-11-25T00:20:00+08:00","values":{"flow":0}},{"time":"2024-11-25T00:25:00+08:00","values":{"flow":0}},{"time":"2024-11-25T00:30:00+08:00","values":{"flow":0}},{"time":"2024-11-25T00:35:00+08:00","values":{"flow":0}},{"time":"2024-11-25T23:25:00+08:00","values":{"flow":0}},{"time":"2024-11-25T23:30:00+08:00","values":{"flow":0}},{"time":"2024-11-25T23:35:00+08:00","values":{"flow":0}},{"time":"2024-11-25T23:40:00+08:00","values":{"flow":0}},{"time":"2024-11-25T23:45:00+08:00","values":{"flow":0}},{"time":"2024-11-25T23:50:00+08:00","values":{"flow":0}},{"time":"2024-11-25T23:55:00+08:00","values":{"flow":0}}]', 'message': 'Traffic statistics retrieved successfully', 'status_code': 200}
<environment_details>
# VSCode Visible Files
../.config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json

# VSCode Open Tabs

# Current Time
Current time in ISO 8601 UTC format: 2025-11-25T03:40:36.790Z
User time zone: Asia/Singapore, UTC+8:00

# Current Cost
$0.00

# Current Mode
<slug>code</slug>
<name>Code</name>
<model>glm-4.5-air</model>
You have not created a todo list yet. Create one with `update_todo_list` if your task is complicated or involves multiple steps.
</environment_details>
```

***

### **Assistant:** [#assistant-4]

已成功查看到直播流和流量信息：

### 直播流信息 [#直播流信息]

**空间：** dfddd

**直播流列表：**

1. **流名称：** eeeee
   * **状态：** offline（离线）
   * **创建时间：** 2025-10-28T22:33:52.811+08:00
   * **最后开始时间：** 0（从未开始）
   * **发布URL：** 空
   * **是否已转换：** 否
   * **在线信息：** 无

**总计：** 1个流，当前页面1，每页显示10个流

### 流量统计信息 [#流量统计信息]

**查询时间范围：** 2024-11-25 00:00:00 - 2024-11-25 23:59:59

**流量统计结果：**

* **总流量：** 0 字节
* **平均流量：** 0 字节/5分钟
* **峰值流量：** 0 字节/5分钟
* **时间段：** 全天288个时间点（每5分钟一个统计点）

**流量分析：**

* 整天内所有时间点的流量均为0
* 当前没有活跃的直播流
* 系统处于空闲状态，无流量消耗

**总结：** 当前直播空间中有1个名为"eeeeee"的流，但该流当前处于离线状态，且整个时间范围内没有任何流量产生。

***

## 3. 创建直播流 [#3-创建直播流]

### **User:** [#user-2]

```
[attempt_completion] Result:
The user has provided feedback on the results. Consider their input to continue the task, and then attempt completion again.
<feedback>
在当前空间创建一个stream-abc的直播流，显示推流、拉流地址
</feedback>
<environment_details>
# VSCode Visible Files
../.config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json

# VSCode Open Tabs

# Current Time
Current time in ISO 8601 UTC format: 2025-11-25T03:42:01.541Z
User time zone: Asia/Singapore, UTC+8:00

# Current Cost
$0.00

# Current Mode
<slug>code</slug>
<name>Code</name>
<model>glm-4.5-air</model>
You have not created a todo list yet. Create one with `update_todo_list` if your task is complicated or involves multiple steps.
</environment_details>
```

***

### **Assistant:** [#assistant-5]

```shell
我将为您创建名为"stream-abc"的直播流，然后获取推流和拉流地址。

<use_mcp_tool>
<server_name>remote-live-streaming</server_name>
<tool_name>live_streaming_create_stream</tool_name>
<arguments>
{
  "bucket": "dfddd",
  "stream": "stream-abc"
}
</arguments>
</use_mcp_tool>
```

***

```shell
[use_mcp_tool for 'remote-live-streaming'] Result:
```

```json
{'status': 'success', 'bucket': 'dfddd', 'stream': 'stream-abc', 'url': 'https://dfddd.mls.cn-east-1.qiniumiku.com/stream-abc', 'message': "Stream 'stream-abc' created successfully in bucket 'dfddd'", 'status_code': 200}
```

```shell
<environment_details>
# VSCode Visible Files
../.config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json

# VSCode Open Tabs

# Current Time
Current time in ISO 8601 UTC format: 2025-11-25T03:42:09.501Z
User time zone: Asia/Singapore, UTC+8:00

# Current Cost
$0.00

# Current Mode
<slug>code</slug>
<name>Code</name>
<model>glm-4.5-air</model>
You have not created a todo list yet. Create one with `update_todo_list` if your task is complicated or involves multiple steps.
</environment_details>
```

***

### **Assistant:** [#assistant-6]

```shell
现在我将获取推流地址。我需要使用推流域名来获取推流URL：

<use_mcp_tool>
<server_name>remote-live-streaming</server_name>
<tool_name>live_streaming_get_push_urls</tool_name>
<arguments>
{
  "push_domain": "mcp-push1.qiniu.com",
  "bucket": "dfddd",
  "stream_name": "stream-abc"
}
</arguments>
</use_mcp_tool>
```

***

```shell
[use_mcp_tool for 'remote-live-streaming'] Result:
```

```json
{'status': 'success', 'push_domain': 'mcp-push1.qiniu.com', 'bucket': 'dfddd', 'stream_name': 'stream-abc', 'rtmp_url': 'rtmp://mcp-push1.qiniu.com/dfddd/stream-abc', 'whip_url': 'https://mcp-push1.qiniu.com/dfddd/stream-abc.whip', 'message': 'Push URLs generated successfully'}
```

```shell
<environment_details>
# VSCode Visible Files
../.config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json

# VSCode Open Tabs

# Current Time
Current time in ISO 8601 UTC format: 2025-11-25T03:42:16.362Z
User time zone: Asia/Singapore, UTC+8:00

# Current Cost
$0.00

# Current Mode
<slug>code</slug>
<name>Code</name>
<model>glm-4.5-air</model>
You have not created a todo list yet. Create one with `update_todo_list` if your task is complicated or involves multiple steps.
</environment_details>
```

***

### **Assistant:** [#assistant-7]

```shell
现在我将获取拉流地址：

<use_mcp_tool>
<server_name>remote-live-streaming</server_name>
<tool_name>live_streaming_get_play_urls</tool_name>
<arguments>
{
  "play_domain": "mcp-play1.qiniu.com",
  "bucket": "dfddd",
  "stream_name": "stream-abc"
}
</arguments>
</use_mcp_tool>
```

***

```shell
[use_mcp_tool for 'remote-live-streaming'] Result:
```

```json
{'status': 'success', 'play_domain': 'mcp-play1.qiniu.com', 'bucket': 'dfddd', 'stream_name': 'stream-abc', 'flv_url': 'https://mcp-play1.qiniu.com/dfddd/stream-abc.flv', 'm3u8_url': 'https://mcp-play1.qiniu.com/dfddd/stream-abc.m3u8', 'whep_url': 'https://mcp-play1.qiniu.com/dfddd/stream-abc.whep', 'message': 'Playback URLs generated successfully'}
```

```shell
<environment_details>
# VSCode Visible Files
../.config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json

# VSCode Open Tabs

# Current Time
Current time in ISO 8601 UTC format: 2025-11-25T03:43:31.988Z
User time zone: Asia/Singapore, UTC+8:00

# Current Cost
$0.00

# Current Mode
<slug>code</slug>
<name>Code</name>
<model>glm-4.5-air</model>
You have not created a todo list yet. Create one with `update_todo_list` if your task is complicated or involves multiple steps.
</environment_details>
```

***

### **Assistant:** [#assistant-8]

已成功在当前空间创建直播流并获取推流和拉流地址：

### 直播流创建成功 [#直播流创建成功]

**流名称：** stream-abc
&#x2A;*所属空间：** dfddd
&#x2A;*流地址：** [https://dfddd.mls.cn-east-1.qiniumiku.com/stream-abc](https://dfddd.mls.cn-east-1.qiniumiku.com/stream-abc)

### 推流地址 [#推流地址]

**RTMP 推流地址：**

rtmp\://mcp-push1.qiniu.com/dfddd/stream-abc

**WHIP 推流地址：**

[https://mcp-push1.qiniu.com/dfddd/stream-abc.whip](https://mcp-push1.qiniu.com/dfddd/stream-abc.whip)

### 拉流地址 [#拉流地址]

**FLV 拉流地址：**

[https://mcp-play1.qiniu.com/dfddd/stream-abc.flv](https://mcp-play1.qiniu.com/dfddd/stream-abc.flv)

**M3U8 拉流地址：**

[https://mcp-play1.qiniu.com/dfddd/stream-abc.m3u8](https://mcp-play1.qiniu.com/dfddd/stream-abc.m3u8)

**WHEP 拉流地址：**

[https://mcp-play1.qiniu.com/dfddd/stream-abc.whep](https://mcp-play1.qiniu.com/dfddd/stream-abc.whep)

### 使用说明 [#使用说明]

1. **推流：** 使用OBS等推流软件，选择RTMP协议并填写对应的推流地址和流密钥
2. **拉流：** 支持多种播放格式：
   * FLV格式适用于大多数播放器
   * M3U8格式适用于HLS播放
   * WHEP格式适用于WebRTC播放

**提示：** 推流时需要提供对应的流密钥，请联系管理员获取推流密钥信息。


# API概览 (/products/mikustream/0-mikustream-live-an-overview-of-the-api)



最近更新时间: 2026-04-30 13:55:28

本文为您介绍了七牛云直播服务的所有API列表，建议您使用服务端 SDK 进行调用

## 空间管理 [#空间管理]

| 接口名称                                                                                                 | 描述                       |
| :--------------------------------------------------------------------------------------------------- | :----------------------- |
| [创建空间](/products/mikustream/mikustream-live-bucket-api/1-mikustream-live-bucket-create-api)          | 创建一个新的空间（Bucket）         |
| [删除空间](/products/mikustream/mikustream-live-bucket-api/2-mikustream-live-bucket-delete-api)          | 删除指定的空间（Bucket）          |
| [列举空间](/products/mikustream/mikustream-live-bucket-api/0-mikustream-live-bucket-list-api)            | 获取当前账号下所有空间（Bucket）的列表信息 |
| [修改空间配置](/products/mikustream/mikustream-live-bucket-api/3-mikustream-live-bucket-config-update-api) | 修改指定空间（Bucket）的配置        |
| [获取空间配置](/products/mikustream/mikustream-live-bucket-api/4-mikustream-live-bucket-config-api)        | 获取指定直播空间（Bucket）的配置信息    |

## 域名管理 [#域名管理]

| 接口名称                                                                                                              | 描述                     |
| :---------------------------------------------------------------------------------------------------------------- | :--------------------- |
| [绑定上行域名](/products/mikustream/mikustream-live-domain-api/0-mikustream-live-bind-upstream-domain-api)              | 为指定直播空间绑定上行域名（推流域名）    |
| [解绑上行域名](/products/mikustream/mikustream-live-domain-api/1-mikustream-live-unbind-upstream-domain-api)            | 为指定直播空间解绑上行域名（推流域名）    |
| [列举上行域名](/products/mikustream/mikustream-live-domain-api/2-mikustream-live-list-upstream-domain-api)              | 列举指定直播空间的所有上行域名（推流域名）  |
| [修改上行域名配置](/products/mikustream/mikustream-live-domain-api/4-mikustream-live-update-upstream-domain-config-api)   | 修改指定直播空间中某个上行域名的配置     |
| [获取上行域名配置](/products/mikustream/mikustream-live-domain-api/3-mikustream-live-get-upstream-domain-config-api)      | 获取指定直播空间中某个上行域名的详细配置信息 |
| [绑定下行域名](/products/mikustream/mikustream-live-domain-api/5-mikustream-live-bind-downstream-domain-api)            | 为指定直播空间绑定下行域名（播放域名）    |
| [解绑下行域名](/products/mikustream/mikustream-live-domain-api/6-mikustream-live-unbind-downstream-domain-api)          | 为指定直播空间解绑下行域名（播放域名）    |
| [列举下行域名](/products/mikustream/mikustream-live-domain-api/7-mikustream-live-list-downstream-domain-api)            | 列举指定直播空间的所有下行域名（播放域名）  |
| [修改下行域名配置](/products/mikustream/mikustream-live-domain-api/9-mikustream-live-update-downstream-domain-config-api) | 修改指定直播空间中某个下行域名的配置     |
| [获取下行域名配置](/products/mikustream/mikustream-live-domain-api/8-mikustream-live-get-downstream-domain-config-api)    | 获取指定直播空间中某个下行域名的详细配置信息 |

## 证书管理 [#证书管理]

| 接口名称                                                                                                    | 描述                |
| :------------------------------------------------------------------------------------------------------ | :---------------- |
| [上传域名证书](/products/mikustream/mikustream-live-certificate-api/0-mikustream-live-certificate-upload-api) | 为直播服务上传域名 SSL 证书） |
| [删除域名证书](/products/mikustream/mikustream-live-certificate-api/1-mikustream-live-certificate-delete-api) | 删除指定域名 SSL 证书     |
| [列举域名证书](/products/mikustream/mikustream-live-certificate-api/3-mikustream-live-certificate-list-api)   | 列举所有已上传的域名 SSL 证书 |
| [更新证书](/products/mikustream/mikustream-live-certificate-api/2-mikustream-live-certificate-update-api)   | 更新指定域名 SSL 证书内容   |

## 直播流管理 [#直播流管理]

| 接口名称                                                                                             | 描述                  |
| :----------------------------------------------------------------------------------------------- | :------------------ |
| [创建流](/products/mikustream/mikustream-live-stream-api/0-mikustream-live-stream-create-api)       | 在指定直播空间中创建一个新的直播流   |
| [获取流信息](/products/mikustream/mikustream-live-stream-api/2-mikustream-live-stream-query-api)      | 获取指定直播流的详细信息        |
| [删除流](/products/mikustream/mikustream-live-stream-api/1-mikustream-live-stream-ban-api)          | 删除指定的直播流            |
| [封禁流](/products/mikustream/mikustream-live-stream-api/1-mikustream-live-stream-ban-api)          | 封禁指定的直播流，禁止其推流和播放   |
| [解封流](/products/mikustream/mikustream-live-stream-api/3-mikustream-live-stream-permit-api)       | 解封指定的直播流，恢复其推流和播放功能 |
| [列举流列表](/products/mikustream/mikustream-live-stream-api/4-mikustream-live-stream-query-list-api) | 列举指定直播空间中的活跃流信息     |

## 实时流转码模版 [#实时流转码模版]

| 接口名称                                                                                                      | 描述            |
| :-------------------------------------------------------------------------------------------------------- | :------------ |
| [新增实时流转码模版](/products/mikustream/mikustream-live-transcoding-api/0-mikustream-live-templete-create-api)   | 创建一条新的实时转码模板  |
| [更新实时流转码模版](/products/mikustream/mikustream-live-transcoding-api/1-mikustream-live-templete-update-api)   | 修改指定的实时转码模板配置 |
| [删除实时流转码模版](/products/mikustream/mikustream-live-transcoding-api/2-mikustream-live-templete-delete-api)   | 删除指定的实时转码模板   |
| [获取实时流转码模版具体信息](/products/mikustream/mikustream-live-transcoding-api/3-mikustream-live-templete-info-api) | 查询单个实时转码模板的详情 |
| [获取实时流转码模版列表](/products/mikustream/mikustream-live-transcoding-api/4-mikustream-live-templete-list-api)   | 获取实时转码模板列表    |

## 录制管理 [#录制管理]

| 接口名称                                                                                                   | 描述             |
| :----------------------------------------------------------------------------------------------------- | :------------- |
| [生成指定时间范围录制文件](/products/mikustream/mikustream-live-recording-api/0-mikustream-live-record-create-api) | 根据时间范围触发生成录制文件 |
| [保存直播截图](/products/mikustream/mikustream-live-recording-api/1-mikustream-live-record-snapshot-api)     | 保存指定流的截图文件     |

## 实用工具 [#实用工具]

| 接口名称                                                                                                    | 描述           |
| :------------------------------------------------------------------------------------------------------ | :----------- |
| [推流地址拼接](/products/mikustream/mikustream-live-tools-api/5-mikustream-live-tool-query-publishdomain-api) | 生成推流地址       |
| [播放地址拼接](/products/mikustream/mikustream-live-tools-api/4-mikustream-live-tool-query-playdomain-api)    | 生成播放地址       |
| [创建 apikey](/products/mikustream/mikustream-live-tools-api/0-mikustream-live-tool-create-apikey-api)    | 创建新的 apikey  |
| [删除 apikey](/products/mikustream/mikustream-live-tools-api/1-mikustream-live-tool-delete-apikey-api)    | 删除指定 apikey  |
| [重命名 apikey](/products/mikustream/mikustream-live-tools-api/2-mikustream-live-tool-rename-apikey-api)   | 修改 apikey 名称 |
| [apikey 列表](/products/mikustream/mikustream-live-tools-api/3-mikustream-live-tool-apikey-list-api)      | 查询 apikey 列表 |

## 数据统计 [#数据统计]

| 接口名称                                                                                               | 描述          |
| :------------------------------------------------------------------------------------------------- | :---------- |
| [查询直播上行流量](/products/mikustream/mikustream-live-statistics-api/3-mikustream-live-log-upflow-api)   | 按时间粒度查询上行流量 |
| [查询直播下行流量](/products/mikustream/mikustream-live-statistics-api/4-mikustream-live-log-downflow-api) | 按时间粒度查询下行流量 |
| [查询流历史数据](/products/mikustream/mikustream-live-statistics-api/1-mikustream-live-log-history-api)   | 查询单条流的历史指标  |
| [查询离线日志](/products/mikustream/mikustream-live-statistics-api/0-mikustream-live-log-offline-api)    | 查询离线日志列表    |


# API规范 (/products/mikustream/1-mikustream-live-api-standard)



最近更新时间: 2026-01-16 10:31:22

遵循 RESTful API 设计规范，使用名词表示操作的对象

* `https://<service-code>.<region-code>.qiniumiku.com` 表示公共接入点，用于列举空间
* `https://<bucket>.<service-code>.<region-code>.qiniumiku.com` 表示空间
* `https://<bucket>.<service-code>.<region-code>.qiniumiku.com/<key>` 表示空间中的对象

使用 HTTP Request Method 与 资源(Resource) 配合，表示具体操作，常用的 HTTP Request Method 列表:

* `GET` 获取资源
* `POST` 创建资源
* `PUT` 全量更新资源（AWS 基本采用 PUT，表示创建资源）
* `PATCH` 部分更新资源
* `DELETE` 删除资源
* `HEAD` 获取资源元数据
* `OPTIONS` preflight 请求，需要响应正确的 access-control 信息

以 `domain` 作为一类资源(Resource)举例：

* `GET /?domain` 表示获取空间的域名列表
* `POST /?domain` 表示绑定域名
* `DELETE /?domain&name=<domain>` 表示解绑域名

S3风格接口
`https://<bucket>.domain/?path&params=<params>&params2=<params2>`
`https://<bucket>.domain/<streamtitle>?path&params=<params>&params2=<params2>`


# 请求结构 (/products/mikustream/2-mikustream-live-api-request-structure)



最近更新时间: 2026-01-16 10:31:22

## 服务地址 [#服务地址]

* 列举空间：mls.cn-east-1.qiniumiku.com
* 其他: \&lt;bucket>.mls.cn-east-1.qiniumiku.com

## 通信协议 [#通信协议]

支持通过 HTTP 或 HTTPS 进行通信，为了更高的安全性，建议使用 HTTPS 发送API请求。

## 字符编码 [#字符编码]

请求及返回结果都使用 UTF-8 字符集进行编码。


# API请求鉴权 (/products/mikustream/3-mikustream-live-http-requests-authentication)



最近更新时间: 2026-01-16 10:31:22

# 七牛云 MLS API 鉴权指南 [#七牛云-mls-api-鉴权指南]

本文档介绍三种常用的 MLS API 鉴权方式：

1. AK/SK 签名鉴权（QiniuToken）
2. IAM 子账号鉴权
3. Bearer Token 鉴权

每种方式都提供签名生成规则和请求示例。

***

## 1 AK/SK 签名鉴权（QiniuToken） [#1-aksk-签名鉴权qiniutoken]

七牛云管理 API 请求必须经过 AK/SK 签名生成 **QiniuToken**，并在 `Authorization` 头中使用。

### 1.1 获取密钥 [#11-获取密钥]

1. 登录 [七牛开发者平台](https://portal.qiniu.com/)
2. 打开 &#x2A;*个人中心 → [密钥管理](https://portal.qiniu.com/developer/user/key)**
3. 获取 **AccessKey** 和 **SecretKey**

> 注意：密钥非常重要，请勿放在客户端或公开仓库。

### 1.2 构造待签名字符串 [#12-构造待签名字符串]

签名字符串规则：

```text
data = <Method> + " " + <Path> + "?" + <RawQuery> + "\nHost: " + <Host> + "\nContent-Type: " + <contentType> + "\n\n" + <bodyStr>
```

> 注意：1.\< Method > 与 \< Path > 中间有一个空格

**参数说明：**

| 参数           | 必填 | 说明                                                           |
| ------------ | -- | ------------------------------------------------------------ |
| Method       | 是  | HTTP 方法：GET/POST/PUT/DELETE，大写                               |
| Path         | 是  | 请求路径，如 `/v2/hubs/PiliSDKTest/streams/xxx`                    |
| RawQuery     | 否  | URL 查询参数，如无可不加 `?`                                           |
| Host         | 是  | 域名，如 `mls.cn-east-1.qiniumiku.com`                           |
| Content-Type | 否  | 请求体类型，如为空可不加该字段                                              |
| bodyStr      | 否  | 请求体内容，如有且 Content-Type 不为空且不为 `application/octet-stream`，需加入 |

> 注意：无论 Content-Type 或 body 是否为空，中间都必须保留 `\n\n`。

### 1.3 计算签名 [#13-计算签名]

使用 **HMAC-SHA1** 算法并进行 URL-safe Base64 编码：

```go
sign = hmac_sha1(data, "Your_Secret_Key")
encodedSign = urlsafe_base64_encode(sign)
```

### 1.4 生成 QiniuToken [#14-生成-qiniutoken]

```text
QiniuToken = "Qiniu " + "<AccessKey>" + ":" + "<encodedSign>"
```

### 1.5 请求示例 [#15-请求示例]

ak = test1
sk = test2
QiniuToken = "Qiniu test1:KI-VgUTKszBmF2b0r3ssQMbnA5Q="

```bash
curl -v -XPOST 'http://mls.cn-east-1.qiniumiku.com/?apikey' \
-d '{"name": "test"}' \
-H 'Authorization: Qiniu test1:KI-VgUTKszBmF2b0r3ssQMbnA5Q=' \
-H 'Host: mls.cn-east-1.qiniumiku.com' \
-H 'Content-Type: application/json'
```

>

**Go 语言示例：**

```go
package main

import (
	"crypto/hmac"
	"crypto/sha1"
	"encoding/base64"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"strings"
	"time"
)

func main() {
	// 从环境变量获取Access Key和Secret Key
	ak := os.Getenv("Access_key")
	sk := os.Getenv("Secret_key")

	// 请求体
	body := `{"data":{"uri":"http://oayjpradp.bkt.clouddn.com/Audrey_Hepburn.jpg"},"params":{"scenes":["pulp","terror","politician","ads"]}}`

	// 构建HTTP请求
	targetURL := "http://ai.qiniuapi.com/v3/image/censor"

	// 生成签名并发送请求
	signature := generateSignature("POST", targetURL, body, ak, sk)
	fmt.Printf("生成的签名: %s\n", signature)

	response, err := sendHttpRequest(targetURL, "POST", body, signature, 2)
	if err != nil {
		fmt.Printf("请求失败: %v\n", err)
		return
	}
	fmt.Printf("响应内容: %s\n", response)
}

// generateSignature 生成七牛签名
func generateSignature(method, urlStr, body, ak, sk string) string {
	parsedURL, err := url.Parse(urlStr)
	if err != nil {
		panic(err)
	}

	// 构建签名数据
	var data strings.Builder
	data.WriteString(method)
	data.WriteString(" ")
	data.WriteString(parsedURL.Path)

	if parsedURL.RawQuery != "" {
		data.WriteString("?")
		data.WriteString(parsedURL.RawQuery)
	}

	data.WriteString("\nHost: ")
	data.WriteString(parsedURL.Host)
	data.WriteString("\nContent-Type: application/json")
	data.WriteString("\n\n")

	if body != "" {
		data.WriteString(body)
	}

	// 使用HMAC-SHA1进行签名
	hmacSha1 := hmac.New(sha1.New, []byte(sk))
	hmacSha1.Write([]byte(data.String()))
	hmacResult := hmacSha1.Sum(nil)

	sign := "Qiniu " + ak + ":" + base64UrlSafeEncode(hmacResult)
	return sign
}

// sendHttpRequest 发送HTTP请求
func sendHttpRequest(urlStr, method, data, signature string, timeout int) (string, error) {
	client := &http.Client{
		Timeout: time.Duration(timeout) * time.Second,
	}

	var bodyReader io.Reader
	if data != "" {
		bodyReader = strings.NewReader(data)
	}

	req, err := http.NewRequest(method, urlStr, bodyReader)
	if err != nil {
		return "", err
	}

	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", signature)

	resp, err := client.Do(req)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()

	bodyBytes, err := io.ReadAll(resp.Body)
	if err != nil {
		return "", err
	}

	return fmt.Sprintf("HTTP %d: %s", resp.StatusCode, string(bodyBytes)), nil
}

// base64UrlSafeEncode URL安全的base64编码
func base64UrlSafeEncode(data []byte) string {
	encoded := base64.StdEncoding.EncodeToString(data)
	encoded = strings.ReplaceAll(encoded, "+", "-")
	encoded = strings.ReplaceAll(encoded, "/", "_")
	return encoded
}

```

## 2 Bearer Token 鉴权（API Key） [#2-bearer-token-鉴权api-key]

通过管理员 AK/SK 生成 API Key，然后使用 **Bearer Token** 调用 API。

### 2.1 创建 API Key [#21-创建-api-key]

```bash
curl -v -XPOST 'http://mls.cn-east-1.qiniumiku.com/?apikey' \
-d '{"name": "name"}' \
-H 'Authorization: Qiniu <AK/SK签名生成的Token>' \
-H 'Content-Type: application/json'
```

> 注意：name 自定义，长度 1\~20，内容不做校验。

### 2.2 使用 API Key 调用接口 [#22-使用-api-key-调用接口]

```bash
curl https://mls.cn-east-1.qiniumiku.com/stream?info=test \
-H "Authorization: Bearer <Miku API Key>"
```

> 可以通过调用 api 获取创建的 apikey 列表或者通过 [miku portal](https://portal.qiniu.com/mikustream/api-key) 创建对应的 apikey

## 3 IAM 子账号鉴权 [#3-iam-子账号鉴权]

IAM 子账号可访问 Miku 的 S3 风格接口，签名方式与 AK/SK 相同。

### 3.1 S3 风格接口示例 [#31-s3-风格接口示例]

* 普通接口：

```
https://domain/{bucket}/{streamtitle}/path?params={params}&params2={params2}
```

* S3 风格接口：

```
https://{bucket}.domain/{streamtitle}?path&params={params}&params2={params2}
```

### 3.2 请求示例 [#32-请求示例]

```bash
curl -v 'http://mls.cn-east-1.qiniumiku.com/?trafficStats&begin=20240101000000&end=20240129105148&g=5min&select=flow&flow=downflow' \
-H 'Content-Type: application/json' \
-H 'Authorization: Qiniu <IAM-AccessKey>:<signToken>'
```

> 注意：签名生成方式与 AK/SK QiniuToken 完全一致，只是 AccessKey 和 SecretKey 使用子账号凭证。

***

### 总结 [#总结]

1. **AK/SK 签名**：管理类 API 使用，生成 QiniuToken
2. **IAM 子账号**：适用于 S3 风格接口
3. **Bearer Token**：基于 API Key 调用接口

**关键点**：

* Method / Path / Query / Host / Content-Type / Body 必须与签名一致
* HMAC-SHA1 输出必须 URL-safe Base64 编码


# 错误信息 (/products/mikustream/4-mikustream-live-error-code)



最近更新时间: 2026-01-16 10:31:22

通用错误返回格式

```
{
    "code": <string>,     // 错误码
    "message": <string>,  // 详细错误信息
    "document": <string>, // 错误信息对应的文档 URL, omitempty
    "resource": <string>, // 错误涉及的空间或对象
    "requestID": <string> // 唯一请求 ID
}
```

常见错误列表

| HTTP Status Code |       Error Code       |        描述       |
| :--------------: | :--------------------: | :-------------: |
|        400       |     InvalidArgument    |      请求参数错误     |
|        400       | MissingSecurityElement |      缺少鉴权信息     |
|        400       |      MalformedXML      |     XML 格式错误    |
|        400       |     InCorrectRegion    | 请求的区域与空间所在区域不一致 |
|        403       |  SignatureDoesNotMatch |      签名信息错误     |
|        403       |      AccessDenied      |       访问限制      |
|        404       |      NoSuchBucket      |      空间不存在      |
|        404       |      NoSuchDomain      |      域名不存在      |
|        404       |       NoSuchCert       |      证书不存在      |
|        404       |        NoSuchKey       |      对象不存在      |
|        501       |     NotImplemented     |      功能未实现      |


# 直播地址 (/products/mikustream/5-mikustream-live-address)



最近更新时间: 2026-01-16 10:31:22

#### 推流格式 [#推流格式]

```
rtmp推流
rtmp://<domain/<bucket>/<stream>

whip 推流
http://<domain>/<bucket>/<stream>.whip

srt推流
srt://<domain>:1935?streamid=#!::h=<bucket>/<stream>,m=publish,domain=<domain>
```

#### 拉流格式 [#拉流格式]

```
rtmp拉流
rtmp://<domain>/<bucket>/<stream>

whep拉流
http://<domain>/<bucket>/<stream>.whep

hls拉流
http://<domain>/<bucket>/<stream>.m3u8

flv拉流
http://<domain>/<bucket>/<stream>.flv

srt拉流
srt://<domain>:1935?streamid=#!::h=<bucket>/<stream>,m=request,domain=<domain>
```


# 直播推拉流时间戳防盗链 (/products/mikustream/6-mikustream-live-authentication)



最近更新时间: 2026-01-16 10:31:22

# 七牛直播推流/拉流时间戳防盗链 [#七牛直播推流拉流时间戳防盗链]

本文覆盖两部分：

* **推流时间戳防盗链**：RTMP 推流
* **拉流时间戳防盗链**：HLS（.m3u8）、FLV（.flv）、RTMP 播放等

## 术语 [#术语]

* **publishDomain**：推流域名
* **playDomain**：播放域名
* **bucket**：直播空间名称
* **stream**：直播流名称
* **publishKey**：推流鉴权密钥（配置在**推流域名/空间**）
* **playKey**：播放防盗链密钥（配置在**播放域名**）
* **t（expireAt）**：过期时间的 &#x2A;*UNIX 时间戳（秒）**
* **path**：URL 的路径部分，**必须以 `/` 开头**；如 `rtmp://test.miku.com/sdk-live/test` 的 path 为 `/sdk-live/test`

> 签名串中涉及 URL 编码时，需&#x2A;*保留斜杠 `/`**（参考下文示例代码的处理方式）。

***

## 一、推流时间戳防盗链 [#一推流时间戳防盗链]

在**推流域名**上设置 **publishKey**，并在推流地址后追加 `?sign=...&t=...`。

**签名公式**

```
sign = md5(publishKey + path + t).to_lower()
```

* `path`：如 `/sdk-live/test`
* `t`：过期时间 UNIX 时间戳（秒）

**示例**

```
publishDomain: test.miku.com
bucket: sdk-live
stream: test
publishKey: test
t (expireAt): 1756110618
path: /sdk-live/test

SignStr = "test/sdk-live/test1756110618"
sign = md5(SignStr).to_lower() = 6a1b665f529c8b57d6408b72e4d21350

最终推流地址:
rtmp://test.miku.com/sdk-live/test?sign=6a1b665f529c8b57d6408b72e4d21350&t=1756110618
```

> Portal 中主/副密钥（均可以进行鉴权）均可使用；建议使用**副密钥**进行轮换，降低主密钥更换风险。

***

## 二、拉流时间戳防盗链 [#二拉流时间戳防盗链]

播放防盗链可以有效避免直播资源被非法盗用的问题。
在**播放域名**上开启“时间戳防盗链”并设置 **playKey**。访问播放地址时，边缘节点按相同规则校验，非法则拒绝（常见表现：HLS/FLV 403；RTMP 播放连接失败/服务返回错误）。

**推流地址格式**

```
[rtmp/http]://<playDomain>/<bucket>/<stream>.[flv/m3u8]
```

**签名公式**

```
sign = md5(playKey + path + t).to_lower()
```

**path 取值示例**

| 协议     | 地址示例                                         | 用于签名的 `path`          |
| ------ | -------------------------------------------- | --------------------- |
| HLS    | `http://play.example.com/bucket/stream.m3u8` | `/bucket/stream.m3u8` |
| FLV    | `http://play.example.com/bucket/stream.flv`  | `/bucket/stream.flv`  |
| RTMP播放 | `rtmp://play.example.com/bucket/stream`      | `/bucket/stream`      |

> **注意**：不同协议的 `path` 不同

### 生成步骤 [#生成步骤]

1. **开启时间戳防盗链并获取 playKey**
   控制台 → 直播空间 → 播放域名 → 开启时间戳防盗链 → 配置主/副密钥
2. **确定过期时间 `t`（秒）**
   ```bash
   # macOS:
   t=$(date -j -f "%Y-%m-%d %H:%M:%S" '2025-10-29 20:00:00' +%s)
   # 结果示例：1761739200
   ```
3. **计算 `sign`**
   ```bash
   sign=md5(playKey + path + t).to_lower()
   ```

### HLS 示例 [#hls-示例]

未鉴权地址：

```
http://pili-hls.pilitest.com/bucket/stream.m3u8
```

开启后：

```
playDomain: pili-hls.pilitest.com
playKey = test
path    = /bucket/stream.m3u8
t       = 1761739200

sign    = md5("test/bucket/stream.m3u81761739200").to_lower()
        = 3acc8aa865f23adfdbceba694e7dc4b9

最终播放地址：
http://pili-hls.pilitest.com/bucket/stream.m3u8?sign=3acc8aa865f23adfdbceba694e7dc4b9&t=1761739200
```

***

## 三、参考代码（兼容推流/拉流） [#三参考代码兼容推流拉流]

> 同一签名方法适用于推流与拉流。区别仅在于：&#x2A;*使用的 Key（publishKey/playKey）** 与 **path**（推拉流 RTMP `/bucket/stream`；拉流 HLS `/bucket/stream.m3u8`；拉流 FLV `/bucket/stream.flv`）。

### Java [#java]

```java
package com.qiniu.hugo.miku;

import java.net.URLEncoder;
import java.nio.charset.Charset;
import java.security.MessageDigest;

public class TimestampAntiLeechUrl {

    private static final char[] DIGITS_LOWER = {
        '0','1','2','3','4','5','6','7','8','9','a','b','c','d','e','f'
    };

    public static void main(String[] args) {
        // 推流（Publish）
        String publishUrl = "rtmp://test.miku.com/sdk-live/test";
        long t1 = System.currentTimeMillis()/1000 + 20*60;
        String publishKey = "test";
        System.out.println(signUrl(publishUrl, publishKey, t1));

        // HLS 播放（Play）
        String hlsUrl = "http://test.miku.com/sdk-live/test.m3u8";
        long t2 = System.currentTimeMillis()/1000 + 20*60;
        String playKey = "test";
        System.out.println(signUrl(hlsUrl, playKey, t2));
    }

    public static String signUrl(String url, String key, long expireTs) {
        try {
            String path = url.substring(url.indexOf("/", url.indexOf("//") + 2));
            // 保留斜杠，仅编码其他字符
            String encodedPath = URLEncoder.encode(path, "UTF-8").replace("%2F", "/");
            String t = String.valueOf(expireTs);
            String toSign = key + encodedPath + t;
            String sign = md5Lower(toSign);
            return String.format("%s?sign=%s&t=%s", url, sign, t);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    private static String md5Lower(String src) throws Exception {
        MessageDigest md = MessageDigest.getInstance("MD5");
        md.update(src.getBytes(Charset.forName("UTF-8")));
        byte[] bytes = md.digest();
        return encodeHex(bytes);
    }

    private static String encodeHex(byte[] data) {
        char[] out = new char[data.length << 1];
        for (int i = 0, j = 0; i < data.length; i++) {
            out[j++] = DIGITS_LOWER[(0xF0 & data[i]) >>> 4];
            out[j++] = DIGITS_LOWER[0x0F & data[i]];
        }
        return new String(out);
    }
}
```

### Go [#go]

```go
package main

import (
	"crypto/md5"
	"encoding/hex"
	"fmt"
	"net/url"
	"strings"
	"time"
)

func main() {
	// 推流（Publish）
	pub := "rtmp://test.miku.com/sdk-live/test"
	fmt.Println(SignURL(pub, "test", time.Now().Unix()+20*60))

	// HLS 播放（Play）
	hls := "http://test.miku.com/sdk-live/test.m3u8"
	fmt.Println(SignURL(hls, "test", time.Now().Unix()+20*60))
}

func SignURL(baseURL, key string, expire int64) (string, error) {
	u, err := url.Parse(baseURL)
	if err != nil {
		return "", err
	}
	// path 必须以 / 开头
	path := u.Path
	// 保留斜杠，仅编码其他字符
	encodedPath := strings.ReplaceAll(url.QueryEscape(path), "%2F", "/")
	t := fmt.Sprintf("%d", expire)
	toSign := key + encodedPath + t
	sign := md5Lower(toSign)
	return fmt.Sprintf("%s?sign=%s&t=%s", baseURL, sign, t), nil
}

func md5Lower(s string) string {
	sum := md5.Sum([]byte(s))
	return hex.EncodeToString(sum[:])
}
```

***

## 四、易错点与最佳实践 [#四易错点与最佳实践]

1. **密钥配置位置**
   * 推流鉴权用 **publishKey**（配置在**推流域名/空间**）
   * 播放防盗链用 **playKey**（配置在**播放域名**）

2. **path 必须准确**
   * 推拉流 RTMP：`/bucket/stream`
   * 拉流 HLS：`/bucket/stream.m3u8`
   * 拉流 FLV：`/bucket/stream.flv`

3. **URL 编码**
   * 仅编码必要字符并&#x2A;*保留 `/`**，参考示例代码

4. **时间戳单位**
   * `t` 为**秒级** UNIX 时间戳

5. **主/副密钥轮换**
   * 支持主/副密钥；使用副密钥灰度切换更稳妥

6. **排查清单**
   * 403/连接失败：检查 `path` 是否正确、`t` 是否过期、签名大小写、是否双重编码
   * 跨协议失败：核对协议对应的 `path` 后缀（`.m3u8`/`.flv`）
   * 同一域名多密钥：确认实际启用的是哪一把（主/副）

***


# 直播录制国家相关规定 (/products/mikustream/0-mikustream-live-recording-rules)



最近更新时间: 2025-12-23 17:21:16

# 依据《网络表演经营活动管理办法》规定 [#依据网络表演经营活动管理办法规定]

第十三条　网络表演经营单位应当建立内部巡查监督管理制度，对网络表演进行实时监管。网络表演经营单位应当记录全部网络表演视频资料并妥善保存，**资料保存时间不得少于60日**，并在有关部门依法查询时予以提供。
网络表演经营单位向公众提供的非实时的网络表演音视频（包括用户上传的），应当严格实行先自审后上线。

法律法规详细信息：[文化部关于印发《网络表演经营活动管理办法》的通知（国务院公报2017年第21号）](http://www.gov.cn/gongbao/content/2017/content_5213209.htm)

# 依据《网络交易监督管理办法》规定 [#依据网络交易监督管理办法规定]

第二十条  通过网络社交、网络直播等网络服务开展网络交易活动的网络交易经营者，应当以显著方式展示商品或者服务及其实际经营主体、售后服务等信息，或者上述信息的链接标识。
**网络直播服务提供者对网络交易活动的直播视频保存时间自直播结束之日起不少于三年**。

法律法规详细信息：[《网络交易监督管理办法》（2021年3月15日国家市场监督管理总局令第37号公布）](https://www.gov.cn/zhengce/zhengceku/2021-03/16/content_5593226.htm)

依据上诉办法规定，在七牛云使用互动直播时，直播录制至少保存 60 天，电商直播客户存储周期必须选择保存 1095 天（3年）

# 依据国家网信办《互联网直播服务管理规定》 [#依据国家网信办互联网直播服务管理规定]

第十六条 互联网直播服务提供者应当记录互联网直播服务使用者发布内容和日志信息，保存六十日。
**保存时间自直播结束之日起不少于六十日**

***

法律法规详细信息：[《互联网直播服务管理规定》](https://www.cac.gov.cn/2016-11/04/c_1119847629.htm)


# 七牛 SDK 合规使用说明 (/products/mikustream/1-compliance-instructions)



最近更新时间: 2026-08-18 15:15:41

应国家法律法规及监管部门规章等的要求，App 开发运营者（以下简称“开发者”或“您”）在提供网络产品服务时应尊重和保护最终用户个人信息，不得违法违规收集使用个人信息，保证和承诺个人信息处理行为获得最终用户的授权同意，遵循最小必要原则，并且应当采取有效的技术措施和组织措施，确保个人信息安全。

为帮助开发者在满足个人信息安全保护相关的法律法规、政策和监管标准的前提下，合规地接入与使用我们的SDK（App的第三方SDK），避免出现侵害用户个人信息权益情形，上海七牛信息技术有限公司（以下简称“七牛”）特制定本 **SDK 合规说明文档** （以下简称“文档”）。

请您在接入、使用我们的SDK之前，请充分阅读和理解本文档内容。

# 一、App 个人信息保护的合规要求 [#一app-个人信息保护的合规要求]

为保护 App 最终用户的个人信息，App 及 App 的开发者需要满足如下合规要求：

* App 开发者应该制定隐私政策，并在 App 界面中显著展示。隐私政策（或命名为个人信息保护政策等类似名称），是说明 APP 的个人信息收集和使用情况，获得用户的合法授权以及保护用户个人信息主体权利的重要文档。可参考《GB/T 35273-2020 信息安全技术 个人信息安全规范》，该文件对个人信息保护要求和隐私政策编写具有重要的参考价值。
* App 隐私政策应该单独成文，而不是作为用户协议等文件中的一部分进行展示。
* App 隐私政策应该明示收集和使用个人信息的目的、方式和范围，并且确保隐私政策链接正常有效，易于访问和阅读。
* App 隐私政策应逐项说明 App 各项业务功能以及对应收集的个人信息类型，不应使用“等、例如”等方式概括说明。
* App 隐私政策应显著标识个人敏感信息类型（如：字体加粗等）。
* App 隐私政策应逐项说明调用的第三方 SDK，包括明示 SDK 名称、SDK 开发者名称；SDK 收集和处理的个人信息类型、目的、方式、范围；SDK 隐私政策链接。

# 二、SDK 合规声明 [#二sdk-合规声明]

## SDK 所需权限声明 [#sdk-所需权限声明]

SDK 需要用户授权相应的权限后，方可正常运行，其所需权限列表如下：

###

### **上传 SDK** [#上传-sdk]

Android 平台所需应用权限列表：

| **权限**                   | **说明**                    | **可选性** |
| :----------------------- | :------------------------ | :------ |
| READ\_EXTERNAL\_STORAGE  | 用于读取 SDK 的配置和日志文件         | 必须      |
| WRITE\_EXTERNAL\_STORAGE | 用于存储 SDK 的配置和日志文件         | 必须      |
| INTERNET                 | 用于联网上传文件至七牛云              | 必须      |
| ACCESS\_WIFI\_STATE      | 用于监控 WIFI 状态变化，提示用户当前网络环境 | 可选      |
| ACCESS\_NETWORK\_STATE   | 用于监控网络状态变化，提示用户当前网络环境     | 可选      |
| READ\_PHONE\_STATE       | 用于获取设备信息，用于排查用户问题         | 可选      |

iOS 平台所需应用权限列表：

| **权限** | **说明** | **可选性** |
| :----- | :----- | :------ |
| 无      | 无      | 无       |

### **推流 SDK** [#推流-sdk]

Android 平台所需应用权限列表：

| **权限**                   | **说明**                        | **可选性** |
| :----------------------- | :---------------------------- | :------ |
| INTERNET                 | 网络权限，用于实现联网功能                 | 必选      |
| CAMERA                   | 摄像头权限，用于开启摄像头实现视频采集功能         | 可选      |
| RECORD\_AUDIO            | 麦克风权限，用于开启麦克风实现音频采集功能         | 可选      |
| MODIFY\_AUDIO\_SETTINGS  | 音频设置权限，用于修改全局音频配置             | 可选      |
| BLUETOOTH                | 蓝牙连接权限，用于支持蓝牙设备的连接            | 可选      |
| ACCESS\_NETWORK\_STATE   | 访问网络状态权限，用于监控并提示用户当前网络环境的变化   | 可选      |
| ACCESS\_WIFI\_STATE      | 访问 Wi-Fi 状态权限，用于监控 Wi-Fi 连接状态 | 可选      |
| WRITE\_EXTERNAL\_STORAGE | 访问存储权限，用于进行日志文件的存储            | 可选      |
| FOREGROUND\_SERVICE      | 前台服务权限，用于屏幕录制功能               | 可选      |

iOS 平台所需应用权限列表：

| **权限**                                 | **说明**                | **可选性** |
| :------------------------------------- | :-------------------- | :------ |
| Privacy - Camera Usage Description     | 摄像头权限，用于开启摄像头实现视频采集功能 | 可选      |
| Privacy - Microphone Usage Description | 麦克风权限，用于开启麦克风实现音频采集功能 | 可选      |

Harmony Next 平台所需应用权限列表：

| **权限**                                    | **说明**                | **可选性** |
| :---------------------------------------- | :-------------------- | :------ |
| ohos.permission.INTERNET                  | 网络权限，用于实现联网功能         | 必选      |
| ohos.permission.CAMERA                    | 摄像头权限，用于开启摄像头实现视频采集功能 | 可选      |
| ohos.permission.MICROPHONE                | 麦克风权限，用于开启麦克风实现音频采集功能 | 可选      |
| ohos.permission.KEEP\_BACKGROUND\_RUNNING | 退出后台后，继续采集数据          | 可选      |

### **短视频 SDK** [#短视频-sdk]

Android 平台所需应用权限列表：

| **权限**                   | **说明**                  | **可选性** |
| :----------------------- | :---------------------- | :------ |
| INTERNET                 | 网络权限，用于实现联网功能           | 可选      |
| CAMERA                   | 摄像头权限，用于开启摄像头实现视频采集功能   | 可选      |
| RECORD\_AUDIO            | 麦克风权限，用于开启麦克风实现音频采集功能   | 可选      |
| ACCESS\_NETWORK\_STATE   | 网络状态权限，用于提示用户当前网络环境     | 可选      |
| READ\_EXTERNAL\_STORAGE  | 访问存储权限，用于读取媒体文件进行编辑     | 可选      |
| WRITE\_EXTERNAL\_STORAGE | 访问存储权限，用于将编辑或录制后的数据写入文件 | 可选      |
| FOREGROUND\_SERVICE      | 前台服务权限，用于屏幕录制功能         | 可选      |

iOS 平台所需应用权限列表：

| **权限**                                 | **说明**                | **可选性** |
| :------------------------------------- | :-------------------- | :------ |
| Privacy - Camera Usage Description     | 摄像头权限，用于开启摄像头实现视频采集功能 | 可选      |
| Privacy - Microphone Usage Description | 麦克风权限，用于开启麦克风实现音频采集功能 | 可选      |

Harmony Next 平台所需应用权限列表：

| **权限**                     | **说明**                | **可选性** |
| :------------------------- | :-------------------- | :------ |
| ohos.permission.CAMERA     | 摄像头权限，用于开启摄像头实现视频采集功能 | 可选      |
| ohos.permission.MICROPHONE | 麦克风权限，用于开启麦克风实现音频采集功能 | 可选      |

### **实时音视频 SDK** [#实时音视频-sdk]

Android 平台所需应用权限列表：

| **权限**                   | **说明**                        | **可选性** |
| :----------------------- | :---------------------------- | :------ |
| INTERNET                 | 网络权限，用于实现联网功能                 | 必选      |
| CAMERA                   | 摄像头权限，用于开启摄像头实现视频采集功能         | 可选      |
| RECORD\_AUDIO            | 麦克风权限，用于开启麦克风实现音频采集功能         | 可选      |
| MODIFY\_AUDIO\_SETTINGS  | 音频设置权限，用于修改全局音频配置             | 可选      |
| BLUETOOTH                | 蓝牙连接权限，用于支持蓝牙设备的连接            | 可选      |
| ACCESS\_NETWORK\_STATE   | 访问网络状态权限，用于监控并提示用户当前网络环境的变化   | 可选      |
| ACCESS\_WIFI\_STATE      | 访问 Wi-Fi 状态权限，用于监控 Wi-Fi 连接状态 | 可选      |
| WRITE\_EXTERNAL\_STORAGE | 访问存储权限，用于进行日志文件的存储            | 可选      |
| FOREGROUND\_SERVICE      | 前台服务权限，用于屏幕录制功能               | 可选      |

iOS 平台所需应用权限列表：

| **权限**                                 | **说明**                | **可选性** |
| :------------------------------------- | :-------------------- | :------ |
| Privacy - Camera Usage Description     | 摄像头权限，用于开启摄像头实现视频采集功能 | 可选      |
| Privacy - Microphone Usage Description | 麦克风权限，用于开启麦克风实现音频采集功能 | 可选      |

HarmonyOS Next 平台所需应用权限列表：

| **权限**                                    | **说明**                      | **可选性** |
| :---------------------------------------- | :-------------------------- | :------ |
| ohos.permission.CAMERA                    | 摄像头权限，用于开启摄像头实现视频采集功能       | 可选      |
| ohos.permission.MICROPHONE                | 麦克风权限，用于开启麦克风实现音频采集功能       | 可选      |
| ohos.permission.INTERNET                  | 访问网络状态权限，用于监控并提示用户当前网络环境的变化 | 可选      |
| ohos.permission.KEEP\_BACKGROUND\_RUNNING | 退出后台后，继续采集数据                | 可选      |

### **播放器 SDK** [#播放器-sdk]

Android 平台所需应用权限列表：

| **权限**                                    | **说明**                      | **可选性** |
| :---------------------------------------- | :-------------------------- | :------ |
| android.permission.ACCESS\_NETWORK\_STATE | 访问网络状态权限，用于监控并提示用户当前网络环境的变化 | 可选      |
| android.permission.INTERNET               | 网络权限，用于实现联网功能               | 可选      |

iOS 平台所需应用权限列表：

| **权限**                                    | **说明**        | **可选性** |
| :---------------------------------------- | :------------ | :------ |
| Privacy - Local Network Usage Description | 网络权限，用于实现联网功能 | 可选      |

Harmony Next 平台所需应用权限列表：

| **权限**                                    | **说明**        | **可选性** |
| :---------------------------------------- | :------------ | :------ |
| ohos.permission.KEEP\_BACKGROUND\_RUNNING | 用于后台播放        | 可选      |
| ohos.permission.INTERNET                  | 网络权限，用于实现联网功能 | 可选      |
| ohos.permission.GET\_NETWORK\_INFO        | 获取网络信息        | 可选      |

### **Miku 超低延时协议直播 SDK** [#miku-超低延时协议直播-sdk]

Android 平台所需应用权限列表：

| **权限**                                      | **说明**                      | **可选性** |
| :------------------------------------------ | :-------------------------- | :------ |
| android.permission.INTERNET                 | 网络权限，用于实现联网功能               | 必选      |
| android.permission.ACCESS\_NETWORK\_STATE   | 访问网络状态权限，用于监控并提示用户当前网络环境的变化 | 可选      |
| android.permission.WRITE\_EXTERNAL\_STORAGE | 存储权限，用于日志文件的存储              | 可选      |

iOS 平台所需应用权限列表：

| **权限**                                    | **说明**        | **可选性** |
| :---------------------------------------- | :------------ | :------ |
| Privacy - Local Network Usage Description | 网络权限，用于实现联网功能 | 可选      |

### **号码认证SDK** [#号码认证sdk]

Android 平台所需应用权限列表：

| 权限                     | 说明                     | 可选性 |
| :--------------------- | :--------------------- | :-- |
| INTERNET               | 允许应用程序联网，用于访问网关和认证服务器。 | 必选  |
| ACCESS\_WIFI\_STATE    | 允许应用程序访问WiFi 网络状态信息    | 必选  |
| ACCESS\_NETWORK\_STATE | 获取网络状态，判断是否数据，WiFi 等   | 必选  |
| CHANGE\_NETWORK\_STATE | 允许程序改变网络连接状态。          | 必选  |

iOS 平台所需应用权限列表：

| 权限                                        | 说明                     | 可选性 |
| :---------------------------------------- | :--------------------- | :-- |
| Privacy - Local Network Usage Description | 允许应用程序联网，用于访问网关和认证服务器。 | 必选  |

### **互动直播低代码 SDK** [#互动直播低代码-sdk]

Android 平台所需应用权限列表：

| **权限**                   | **说明**                        | **可选性** |
| :----------------------- | :---------------------------- | :------ |
| INTERNET                 | 网络权限，用于实现联网功能                 | 必选      |
| CAMERA                   | 摄像头权限，用于开启摄像头实现视频采集功能         | 可选      |
| RECORD\_AUDIO            | 麦克风权限，用于开启麦克风实现音频采集功能         | 可选      |
| MODIFY\_AUDIO\_SETTINGS  | 音频设置权限，用于修改全局音频配置             | 可选      |
| BLUETOOTH                | 蓝牙连接权限，用于支持蓝牙设备的连接            | 可选      |
| ACCESS\_NETWORK\_STATE   | 访问网络状态权限，用于监控并提示用户当前网络环境的变化   | 可选      |
| ACCESS\_WIFI\_STATE      | 访问 Wi-Fi 状态权限，用于监控 Wi-Fi 连接状态 | 可选      |
| WRITE\_EXTERNAL\_STORAGE | 访问存储权限，用于进行日志文件的存储            | 可选      |

iOS 平台所需应用权限列表：

| **权限**                                 | **说明**                | **可选性** |
| :------------------------------------- | :-------------------- | :------ |
| Privacy - Camera Usage Description     | 摄像头权限，用于开启摄像头实现视频采集功能 | 可选      |
| Privacy - Microphone Usage Description | 麦克风权限，用于开启麦克风实现音频采集功能 | 可选      |

**注：SDK 只会根据具体的场景判断是否获取相应的授权，并不会主动向用户申请权限**

### **容器轻应用平台 SDK** [#容器轻应用平台-sdk]

容器轻应用平台 SDK 仅用于进行服务端请求，不会向用户申请权限

**注：SDK 只会根据具体的场景判断是否获取相应的授权，并不会主动向用户申请权限**

### **云主机 SDK** [#云主机-sdk]

云主机 SDK 仅用于进行服务端请求帮助用户管理七牛云主机实例不会向用户申请权限

**注：SDK 只会根据具体的场景判断是否获取相应的授权，并不会主动向用户申请权限**

## SDK 个人信息搜集声明 [#sdk-个人信息搜集声明]

为了保证产品可以提供更好的使用体验，SDK 将会在合理的范围内搜集用户的个人信息，且**信息均将通过加密的方式得以处理**。

SDK 将会搜集如下个人信息：

### **上传 SDK** [#上传-sdk-1]

| **个人信息类型** | **说明**                  | **可选性** | **平台**      |
| :--------- | :---------------------- | :------ | :---------- |
| 设备厂商       | 用于判断用户的的手机类型，以备兼容性及问题排查 | 必选      | Android、iOS |
| 设备机型       | 用于判断用户的的手机类型，以备兼容性及问题排查 | 必选      | Android、iOS |
| 设备系统信息     | 用于判断用户的的手机类型，以备兼容性及问题排查 | 必选      | Android、iOS |
| IP 地址      | 用于上传优化路由，提升用户体验         | 可选      | Android、iOS |

### **推流 SDK** [#推流-sdk-1]

推流 SDK 将会搜集的个人信息说明如下：

| **个人信息类型** | **说明**                      | **可选性** | **平台**                     |
| :--------- | :-------------------------- | :------ | :------------------------- |
| 设备品牌       | 用于判断用户的手机品牌，以备兼容性及问题排查      | 必选      | Android、iOS                |
| 设备型号       | 用于判断用户的手机设备型号，以备兼容性及问题排查    | 必选      | Android、iOS                |
| 设备版本ID     | 用于判断用户的设备版本ID，以备兼容性及问题排查    | 必选      | HarmonyOS Next             |
| 操作系统版本     | 用于判断用户的操作系统版本，以备兼容性及问题排查    | 必选      | Android、iOS                |
| 处理器信息      | 用于判断用户的处理器信息，以备兼容性及问题排查     | 必选      | Android、iOS                |
| 网络连接信息     | 用于通信质量不佳时的问题排查              | 必选      | Android、iOS                |
| 内存使用情况     | 用于进行推流质量的监控和调优              | 必选      | Android、iOS、HarmonyOS Next |
| IP 地址      | 用于优化路由，提升用户体验以及通信质量不佳时的问题排查 | 必选      | Android、iOS                |
| Idfv       | 用于判断是否是真机，防止黑产及外部恶意攻击       | 必选      | iOS                        |

### **短视频 SDK** [#短视频-sdk-1]

短视频 SDK 将会搜集的个人信息说明如下：

| **个人信息类型**        | **说明**                   | **可选性** | **平台**      |
| :---------------- | :----------------------- | :------ | :---------- |
| 设备品牌              | 用于判断用户的手机品牌，以备兼容性及问题排查   | 必选      | Android、iOS |
| 设备型号              | 用于判断用户的手机设备型号，以备兼容性及问题排查 | 必选      | Android、iOS |
| 操作系统版本            | 用于判断用户的操作系统版本，以备兼容性及问题排查 | 必选      | Android、iOS |
| 设备识别码（Android ID） | 用于区分用户设备，以备兼容性及问题排查      | 必选      | Android     |
| Idfv              | 用于判断是否是真机，防止黑产及外部恶意攻击    | 必选      | iOS         |

其中，在 v3.4.1 版本后已移除对设备识别码（Android ID）的获取

### **实时音视频 SDK** [#实时音视频-sdk-1]

实时音视频 SDK 将会搜集的个人信息说明如下：

| **个人信息类型** | **说明**                   | **可选性** | **平台**                     |
| :--------- | :----------------------- | :------ | :------------------------- |
| 设备品牌       | 用于判断用户的手机品牌，以备兼容性及问题排查   | 必选      | Android、iOS、HarmonyOS Next |
| 设备型号       | 用于判断用户的手机设备型号，以备兼容性及问题排查 | 必选      | Android、iOS、HarmonyOS Next |
| 操作系统版本     | 用于判断用户的操作系统版本，以备兼容性及问题排查 | 必选      | Android、iOS、HarmonyOS Next |
| 处理器信息      | 用于判断用户的处理器信息，以备兼容性及问题排查  | 必选      | Android、iOS、HarmonyOS Next |
| 网络连接信息     | 用于通信质量不佳时的问题排查           | 必选      | Android、iOS、HarmonyOS Next |
| Idfv       | 用于判断是否是真机，防止黑产及外部恶意攻击    | 必选      | iOS                        |

### **播放器 SDK** [#播放器-sdk-1]

QPlayer2 播放器 SDK 将会搜集的个人信息说明如下：

| **个人信息类型** | **说明**                          | **可选性** | **平台**                     |
| :--------- | :------------------------------ | :------ | :------------------------- |
| 设备品牌       | 用于判断用户的手机品牌，以备兼容性及问题排查和统计性能信息   | 必选      | Android、iOS、HarmonyOS Next |
| 设备型号       | 用于判断用户的手机设备型号，以备兼容性及问题排查和统计性能信息 | 必选      | Android、iOS、HarmonyOS Next |
| 操作系统版本     | 用于判断用户的操作系统版本，以备兼容性及问题排查和统计性能信息 | 必选      | Android、iOS、HarmonyOS Next |
| 处理器信息      | 用于判断用户的处理器信息，以备兼容性及问题排查和统计性能信息  | 必选      | Android、iOS、HarmonyOS Next |
| 网络连接信息     | 用于通信质量不佳时的问题排查和统计性能信息           | 必选      | Android、iOS、HarmonyOS Next |
| Idfv       | 用于判断是否是真机，防止黑产及外部恶意攻击           | 必选      | iOS                        |

### **号码认证SDK** [#号码认证sdk-1]

| 个人信息类型         | 说明                                                             | 可选性 | 平台          |
| :------------- | :------------------------------------------------------------- | :-- | :---------- |
| 设备类型、操作系统、硬件厂商 | 用于性能分析，采集机型、系统信息进行机型适配和优化                                      | 必选  | Android，iOS |
| 网络类型           | 用于性能分析，分仅数据流量、仅WiFi、数据流量+WiFi三种情况；分析不同网络环境对取号成功率和时延的影响，进行针对性优化 | 必选  | Android，iOS |
| 网络地址           | 用于风控。                                                          | 必选  | Android，iOS |
| 运营商类型          | 根据用户当前手机号运营商类型，调用对应运营商的取号接口。                                   | 必选  | Android，iOS |

### **互动直播低代码 SDK** [#互动直播低代码-sdk-1]

互动直播低代码 SDK 将会搜集的个人信息说明如下：

| **个人信息类型** | **说明**                   | **可选性** | **平台**      |
| :--------- | :----------------------- | :------ | :---------- |
| 设备品牌       | 用于判断用户的手机品牌，以备兼容性及问题排查   | 必选      | Android、iOS |
| 设备型号       | 用于判断用户的手机设备型号，以备兼容性及问题排查 | 必选      | Android、iOS |
| 操作系统版本     | 用于判断用户的操作系统版本，以备兼容性及问题排查 | 必选      | Android、iOS |
| 处理器信息      | 用于判断用户的处理器信息，以备兼容性及问题排查  | 必选      | Android、iOS |
| 网络连接信息     | 用于通信质量不佳时的问题排查           | 必选      | Android、iOS |
| Idfv       | 用于判断是否是真机，防止黑产及外部恶意攻击    | 必选      | iOS         |

### **Miku 超低延时协议直播 SDK** [#miku-超低延时协议直播-sdk-1]

Miku 超低延时协议直播 SDK 仅用于进行音视频低延时直播的播放，不会搜集个人信息

### **容器轻应用平台 SDK** [#容器轻应用平台-sdk-1]

容器轻应用平台 SDK 仅用于进行服务端请求，不会搜集个人信息

### **云主机SDK** [#云主机sdk]

云主机 SDK 仅用于进行服务端请求，不会搜集个人信息

## SDK 隐私政策披露要求与示例声明 [#sdk-隐私政策披露要求与示例声明]

为了满足相关要求，您需要根据集成 SDK 的实际情况，在您的 app 隐私政策中提供如下内容：

* 第三方 SDK 名称
* SDK 公司名称
* SDK 主要功能
* SDK 涉及的个人信息
* SDK 所需的系统权限
* SDK 隐私政策链接
  &#x2A;*各 SDK 隐私政策披露示例如下：**

### **上传 SDK** [#上传-sdk-2]

**Android 示例：**

* SDK 名称：上传 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供文件上传至七牛云功能
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、IP 地址、网络类型
* SDK 所需的系统权限：网络、存储权限
* SDK 隐私政策链接：[/products/kodo/7-the-sdk-privacy-policy](/products/kodo/7-the-sdk-privacy-policy)

**iOS 示例：**

* SDK 名称：推流 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供文件上传至七牛云功能
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、IP 地址、网络类型
* SDK 所需的系统权限：无
* SDK 隐私政策链接：[/products/kodo/7-the-sdk-privacy-policy](/products/kodo/7-the-sdk-privacy-policy)

### **推流 SDK** [#推流-sdk-2]

七牛推流 SDK 第三方 SDK 隐私政策声明示例如下（仅供参考）：

**Android 示例：**

* SDK 名称：推流 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供实时的音视频直播服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、处理器信息、内存使用情况、IP 地址、网络类型及连接信息
* SDK 所需的系统权限：网络、摄像头、麦克风、麦克风设置、蓝牙连接、存储权限
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

**iOS 示例：**

* SDK 名称：推流 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供实时的音视频直播服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、处理器信息、内存使用情况、IP 地址、网络类型及连接信息、Idfv
* SDK 所需的系统权限：摄像头、麦克风
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

**HarmonyOS Next 示例：**

* SDK 名称：推流 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供实时的音视频直播服务
* SDK 涉及的个人信息：内存使用情况、设备版本ID
* SDK 所需的系统权限：网络、摄像头、麦克风、后台运行
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

### **短视频 SDK** [#短视频-sdk-2]

七牛短视频 SDK 第三方 SDK 隐私政策声明示例如下（仅供参考）：

**Android 示例：**

* SDK 名称：短视频 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供短视频的拍摄编辑服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本
* SDK 所需的系统权限：网络、摄像头、麦克风、麦克风设置、蓝牙连接、存储权限
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

**iOS 示例：**

* SDK 名称：短视频 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供短视频的拍摄编辑服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、Idfv
* SDK 所需的系统权限：摄像头、麦克风
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

### **实时音视频 SDK** [#实时音视频-sdk-2]

七牛实时音视频 SDK 第三方 SDK 隐私政策声明示例如下（仅供参考）：

**Android 示例：**

* SDK 名称：实时音视频 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供实时的音视频通话服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、处理器信息、网络类型及连接信息
* SDK 所需的系统权限：网络、摄像头、麦克风、麦克风设置、蓝牙连接、存储权限
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

**iOS 示例：**

* SDK 名称：实时音视频 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供实时的音视频通话服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、处理器信息、网络类型及连接信息、Idfv
* SDK 所需的系统权限：摄像头、麦克风
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

**HarmonyOS Next 示例：**

* SDK 名称：实时音视频 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供实时的音视频通话服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、处理器信息、网络类型及连接信息
* SDK 所需的系统权限：网络、摄像头、麦克风、后台
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

### **播放器 SDK** [#播放器-sdk-2]

播放器 SDK 第三方 SDK 隐私政策声明示例如下（仅供参考）：

**Android 示例：**

* SDK 名称：QPlayer2 播放器 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供音视频播放服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、处理器信息、网络类型及连接信息
* SDK 所需的系统权限：网络权限
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

**iOS 示例：**

* SDK 名称：QPlayer2 播放器 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供音视频播放服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、处理器信息、网络类型及连接信息、Idfv
* SDK 所需的系统权限：网络权限
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

### **HarmonyOS Next** [#harmonyos-next]

* SDK 名称：QPlayer2 播放器 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供音视频播放服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、处理器信息、网络类型及连接信息、Idfv
* SDK 所需的系统权限：网络权限、后台播放权限
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

### **Miku 超低延时协议直播 SDK** [#miku-超低延时协议直播-sdk-2]

Miku 超低延时协议直播 SDK 第三方 SDK 隐私政策声明示例如下（仅供参考）：

**Android 示例：**

* SDK 名称：Miku 超低延时协议直播 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供音视频低延时播放服务
* SDK 涉及的个人信息：无
* SDK 所需的系统权限：网络权限、存储权限
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

**iOS 示例：**

* SDK 名称：Miku 超低延时协议直播 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供音视频低延时播放服务
* SDK 涉及的个人信息：无
* SDK 所需的系统权限：网络权限
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

### **号码认证 SDK** [#号码认证-sdk]

号码认证 SDK 第三方 SDK 隐私政策声明示例如下（仅供参考）：

**Android 示例：**

* SDK 名称：号码认证 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供号码认证服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、处理器信息、网络类型及连接信息
* SDK 所需的系统权限：网络权限
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

**iOS 示例：**

* SDK 名称：号码认证 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供号码认证服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、处理器信息、网络类型及连接信息、Idfv
* SDK 所需的系统权限：网络权限
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

### **容器轻应用平台 SDK** [#容器轻应用平台-sdk-2]

容器轻应用平台 GO SDK 隐私声明示例如下（仅供参考）：

**服务端示例：**

* SDK 名称：容器轻应用平台 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供将任务发给容器集群进行调度执行
* SDK 涉及的个人信息：无
* SDK 所需的系统权限：无
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

### **云主机 SDK** [#云主机-sdk-1]

云主机 SDK 第三方 SDK 隐私政策声明示例如下（仅供参考）：

**服务端示例：**

* SDK 名称：云主机 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供七牛云主机资源的管理功能
* SDK 涉及的个人信息：无
* SDK 所需的系统权限：无
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

### **互动直播低代码 SDK** [#互动直播低代码-sdk-2]

互动直播低代码 SDK 第三方 SDK 隐私政策声明示例如下（仅供参考）：

**Android 示例：**

* SDK 名称：互动直播低代码 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供快速搭建互动直播业务服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、处理器信息、网络类型及连接信息
* SDK 所需的系统权限：网络、摄像头、麦克风、麦克风设置、蓝牙连接、存储权限
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

**iOS 示例：**

* SDK 名称：互动直播低代码 SDK
* SDK 公司名称：上海七牛信息技术有限公司
* SDK 主要功能：提供快速搭建互动直播业务服务
* SDK 涉及的个人信息：设备品牌、型号、操作系统版本、处理器信息、网络类型及连接信息、Idfv
* SDK 所需的系统权限：摄像头、麦克风
* SDK 隐私政策链接：[/products/mikustream/2-privacy-policy](/products/mikustream/2-privacy-policy)

## 隐私政策使用建议 [#隐私政策使用建议]

App 首次运行时应当有隐私弹窗，隐私弹窗中应公示隐私政策内容并附完整隐私政策链接，并明确提示最终用户阅读并选择是否同意隐私政策；隐私弹窗应提供同意按钮和拒绝同意的按钮，并由最终用户主动选择。

App 取得敏感权限前，应通过隐私弹窗获得用户单独授权同意（如：麦克风权限、摄像头权限等）。

为满足法律法规和相关监管要求，您应确保在获得终端用户的同意后再初始化 SDK。如果最终用户不同意 App 隐私政策，则不能初始化视频 SDK，无法使用 SDK 功能。

# 三、联系方式 [#三联系方式]

如第三方开发者和/或终端用户对本声明或个人信息相关事宜有疑问，可以通过以下方式与我们取得联系：

* [提交工单](https://support.qiniu.com/tickets/new)
* 通过七牛客服电话 400-101-8589转1
* 发送邮件至 [bd@qiniu.com](mailto:bd@qiniu.com)
* 邮寄信件至：中国上海市浦东新区浦东软件园Q座七牛云客服中心（收）邮编：201203
  为保障我们高效处理您的问题并及时向您反馈，我们可能需要您提交身份证明、有效联系方式和书面请求及相关证据，我们将在验证请求人身份后尽快审核所涉问题，并于十五个工作日内予以回复。


# 七牛 SDK 隐私策略 (/products/mikustream/2-privacy-policy)



最近更新时间: 2026-04-30 18:06:27

# 引言 [#引言]

上海七牛信息技术有限公司（下称“七牛”）严格遵守法律法规，按照业界成熟的安全与隐私标准，保护第三方开发者和其终端用户的个人信息。

本《七牛 SDK 隐私声明》（下称“本声明”）主要向第三方开发者和其终端用户说明我们如何处理个人信息（处理包括“收集、存储、使用、加工、传输、提供、公开等”）。

在注册、接入、使用七牛 SDK （下称“七牛SDK”）产品和/或服务前，请第三方开发者和终端用户务必仔细阅读本声明。同时，请第三方开发者将本声明提供给第三方的终端用户，以便最终用户了解本声明相关内容并获得用户同意。&#x2A;*如果第三方开发者或终端用户不同意本声明，应立即停止接入及使用七牛 SDK 产品和/或服务。**

**我们对个人敏感信息以及本隐私政策中的部分重点条款采用“加粗”的书写方式进行特别提醒**。如对本声明内容有任何疑问、意见或建议，可随时通过本声明第九条提供的方式与我们联系。

 

本文将按如下顺序进行说明：

一、如何收集和使用第三方开发者和/或终端用户的个人信息

二、第三方终端用户的授权同意

三、如何共享、转让、公开披露第三方开发者和/或终端用户的个人信息

四、如何存储第三方开发者和/或终端用户的个人信息

五、如何保护第三方开发者和/或终端用户的个人信息安全

六、第三方开发者和/或终端用户如何管理其个人信息

七、如何处理儿童个人信息

八、如何变更与更新本声明

九、如何联系我们

十、其它

**本声明仅适用于七牛 SDK 处理的个人信息。七牛主要为企业客户提供服务。若我们企业客户在他们的产品内嵌入了我们的服务（如我们的实时音视频服务、鉴黄服务、直播服务、点播服务、短视频服务、存储服务等），而您作为该企业客户的终端用户在与我们的产品互动过程中提供了您的个人信息。在这种场景下，我们作为接受企业客户委托处理信息的受托方，遵照我们与企业客户的协议以及企业客户的指令处理您的个人信息，企业客户作为个人信息处理者对处理您的个人信息承担责任，并负有义务向您披露如何处理、保护您的个人信息。若您希望了解企业客户如何处理、分享、保护您的个人信息，请参阅该企业客户的隐私政策。若您对此有任何问题，请直接联系该企业客户。**

# 一、如何收集和使用第三方开发者和/或终端用户的个人信息 [#一如何收集和使用第三方开发者和或终端用户的个人信息]

我们遵循正当、合法、必要的原则，基于本声明所述的以下目的，收集和使用：

* 1.第三方开发者和/或终端用户主动提供或我们直接收集的个人信息；
* 2.第三方终端用户在使用七牛 SDK 产品和/或服务过程中产生的个人信息；
* 3.从第三方开发者或者其他第三方获取的第三方开发者和/或终端用户的个人信息。

我们通常会在征得第三方开发者和/或终端用户同意后收集个人信息。我们会在本声明中载明收集的个人信息用途，如果我们要将收集个人信息用于本声明未载明的其它用途，我们会以合理的方式向第三方开发者和/或终端用户告知，并在使用前再次征得第三方开发者和/或终端用户的同意。

### 1. 第三方开发者和/或终端用户主动提供或我们直接收集的个人信息 [#1-第三方开发者和或终端用户主动提供或我们直接收集的个人信息]

为实现七牛 SDK 的各项业务功能，我们可能需要向第三方开发者和/或终端用户收集相关个人信息。以下将详细列出七牛 SDK 的各项业务功能及为实现该功能所需收集的个人信息情况，请仔细阅读下述信息清单了解各类七牛SDK（包括调用的第三方 SDK（如有））收集个人信息的类型、用途以及实现的功能目的。

七牛 SDK 除自身提供相关服务并需收集相关信息外，第三方开发者还有可能集成其他辅助业务的第三方 SDK，&#x2A;*此部分第三方 SDK 所收集的个人信息请开发者和终端用户查看第三方 SDK 的隐私政策。**

关于七牛 SDK 的信息清单如下：

<table>
  <tbody><tr><td>SDK 类型</td><td>收集的个人信息字段</td><td>实现的功能目的</td><td>可选性</td><td>平台</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="8">推流 SDK</td></tr><tr><td>厂商、机型</td><td>用于判断用户的的手机类型，以备兼容性及问题排查</td><td>必选</td><td>Android、iOS</td></tr><tr><td>设备版本ID</td><td>用于判断用户的设备版本ID，以备兼容性及问题排查</td><td>必选</td><td>HarmonyOS Next</td></tr><tr><td>网络类型（例如 Wi-Fi、3G、4G）</td><td>用于通信质量不佳时的问题排查</td><td>必选</td><td>Android、iOS</td></tr><tr><td>IP 地址</td><td>用于优化路由，提升用户体验，也用于通信质量不佳时的问题排查</td><td>必选</td><td>Android、iOS</td></tr><tr><td>处理器信息</td><td>用于判断用户的处理器信息，以备兼容性及问题排查</td><td>必选</td><td>Android、iOS</td></tr><tr><td>内存使用情况</td><td>用于进行推流质量的监控和调优</td><td>必选</td><td>Android、iOS、HarmonyOS Next</td></tr><tr><td>Idfv</td><td>用于判断是否是真机，防止黑产及外部恶意攻击。</td><td>必选</td><td>iOS</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="5">短视频 SDK</td></tr><tr><td>厂商、机型、系统版本</td><td>用于兼容性处理及问题排查</td><td>必选</td><td>Android、iOS、HarmonyOS Next</td></tr><tr><td>网络状况（是否有网）</td><td>用于内部鉴权与上传逻辑的判断</td><td>必选</td><td>Android、iOS、HarmonyOS Next</td></tr><tr><td>设备识别码（Android ID）</td><td>用于区分设备，以便兼容性处理及问题排查</td><td>必选（v3.4.1 版本后已移除）</td><td>Android</td></tr><tr><td>Idfv</td><td>用于判断是否是真机，防止黑产及外部恶意攻击。</td><td>必选</td><td>iOS</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="5">实时音视频 SDK</td></tr><tr><td>厂商、机型、系统版本</td><td>用于判断用户的的手机类型，以备兼容性及问题排查</td><td>必选</td><td>Android、iOS、HarmonyOS Next</td></tr><tr><td>网络类型（例如 Wi-Fi、3G、4G）</td><td>用于通信质量不佳时的问题排查</td><td>必选</td><td>Android、iOS、HarmonyOS Next</td></tr><tr><td>处理器信息</td><td>用于判断用户的处理器信息，以备兼容性及问题排查</td><td>必选</td><td>Android、iOS、HarmonyOS Next</td></tr><tr><td>Idfv</td><td>用于判断是否是真机，防止黑产及外部恶意攻击。</td><td>必选</td><td>iOS</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="4">播放器 SDK</td></tr><tr><td>厂商、机型、系统版本</td><td>用于判断用户的的手机类型，以备兼容性及问题排查和性能统计</td><td>必选</td><td>Android、iOS、HarmonyOS Next</td></tr><tr><td>网络类型（例如 Wi-Fi、3G、4G）</td><td>用于监听网络类型状态改变后的处理和性能统计</td><td>必选</td><td>Android、iOS、HarmonyOS Next</td></tr><tr><td>Idfv</td><td>用于判断是否是真机，防止黑产及外部恶意攻击。</td><td>必选</td><td>iOS</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="2">Miku 超低延时协议直播 SDK</td></tr><tr><td>无</td><td>无</td><td>无</td><td>无</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="5">号码认证 SDK</td></tr><tr><td>设备类型、操作系统、硬件厂商</td><td>用于性能分析，采集机型、系统信息进行机型适配和优化。</td><td>必选</td><td>Android，iOS</td></tr><tr><td>网络类型</td><td>用于性能分析，分仅数据流量、仅WiFi、数据流量+WiFi三种情况；分析不同网络环境对取号成功率和时延的影响，进行针对性优化。</td><td>必选</td><td>Android，iOS</td></tr><tr><td>网络地址</td><td>用于风控。</td><td>必选</td><td>Android，iOS</td></tr><tr><td>运营商类型</td><td>根据用户当前手机号运营商类型，调用对应运营商的取号接口。</td><td>必选</td><td>Android，iOS</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="2">云短信SDK</td></tr><tr><td>无</td><td>无</td><td>无</td><td>无</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="2">云主机SDK</td></tr><tr><td>无</td><td>无</td><td>无</td><td>无</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="5">互动直播低代码 SDK</td></tr><tr><td>厂商、机型、系统版本</td><td>用于判断用户的的手机类型，以备兼容性及问题排查</td><td>必选</td><td>Android、iOS</td></tr><tr><td>网络类型（例如 Wi-Fi、3G、4G）</td><td>用于通信质量不佳时的问题排查</td><td>必选</td><td>Android、iOS</td></tr><tr><td>处理器信息</td><td>用于判断用户的处理器信息，以备兼容性及问题排查</td><td>必选</td><td>Android、iOS</td></tr><tr><td>Idfv</td><td>用于判断是否是真机，防止黑产及外部恶意攻击。</td><td>必选</td><td>iOS</td></tr></tbody>
</table>

### 2. 为实现七牛 SDK 产品功能所需的权限 [#2-为实现七牛-sdk-产品功能所需的权限]

为实现七牛 SDK 产品的相应功能，我们需要通过开发者的应用 申请开启客户端设备操作系统的特定权限，所需权限及使用目的如下：

<table>
  <tbody><tr><td>SDK类型</td><td>操作系统</td><td>权限名称</td><td>使用目的</td><td>可选性</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="18">推流 SDK</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="9">Android</td></tr><tr><td>android.permission.INTERNET</td><td>用于实现联网功能</td><td>必选</td></tr><tr><td>android.permission.CAMERA</td><td>用于在使用 SDK 进行直播推流时，开启摄像头采集视频画面</td><td>可选</td></tr><tr><td>android.permission.RECORD_AUDIO</td><td>用于在使用 SDK 进行直播推流时，开启麦克风采集音频数据</td><td>可选</td></tr><tr><td>android.permission.WRITE_EXTERNAL_STORAGE</td><td>用于存储 SDK 的配置和日志文件</td><td>可选</td></tr><tr><td>android.permission.BLUETOOTH</td><td>用于支持蓝牙设备的连接</td><td>可选</td></tr><tr><td>android.permission.ACCESS_WIFI_STATE</td><td>用于监控 WIFI 状态变化，提示用户当前网络环境</td><td>可选</td></tr><tr><td>android.permission.ACCESS_NETWORK_STATE</td><td>用于监控网络状态变化，提示用户当前网络环境</td><td>可选</td></tr><tr><td>android.permission.MODIFY_AUDIO_SETTINGS</td><td>用于修改全局音频配置，如在直播中开启蓝牙采集音频等场景</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="3">iOS</td></tr><tr><td>Privacy - Camera Usage Description</td><td>用于在使用 SDK 进行直播推流时，开启摄像头采集视频数据</td><td>可选</td></tr><tr><td>Privacy - Microphone Usage Description</td><td>用于在使用 SDK 进行直播推流时，开启麦克风采集音频数据</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="5">HarmonyOS Next</td></tr><tr><td>ohos.permission.CAMERA</td><td>用于在使用 SDK 进行直播推流时，开启摄像头采集视频数据</td><td>可选</td></tr><tr><td>ohos.permission.MICROPHONE</td><td>用于在使用 SDK 进行直播推流时，开启麦克风采集音频数据</td><td>可选</td></tr><tr><td>ohos.permission.KEEP_BACKGROUND_RUNNING</td><td>用于在使用 SDK 退出后台后，继续采集数据</td><td>可选</td></tr><tr><td>ohos.permission.INTERNET</td><td>用于实现联网功能</td><td>必选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="20">短视频 SDK</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="8">Android</td></tr><tr><td>android.permission.CAMERA</td><td>用于在使用 SDK 进行摄像头录制时，开启摄像头采集视频画面</td><td>可选</td></tr><tr><td>android.permission.RECORD_AUDIO</td><td>用于在使用 SDK 进行音频录制时，开启麦克风采集音频数据</td><td>可选</td></tr><tr><td>android.permission.READ_EXTERNAL_STORAGE</td><td>用于读取外部音视频文件进行视频编辑操作</td><td>可选</td></tr><tr><td>android.permission.WRITE_EXTERNAL_STORAGE</td><td>用于存储 SDK 录制和编辑后产生的视频文件</td><td>可选</td></tr><tr><td>android.permission.FOREGROUND_SERVICE</td><td>用于录制屏幕，在录屏场景下使用</td><td>可选</td></tr><tr><td>android.permission.INTERNET</td><td>用于实现联网功能</td><td>可选</td></tr><tr><td>android.permission.ACCESS_NETWORK_STATE</td><td>用于监控网络状态变化，提示用户当前网络环境</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="4">iOS</td></tr><tr><td>Privacy - Camera Usage Description</td><td>用于在使用 SDK 进行摄像头录制时，开启摄像头采集视频数据</td><td>可选</td></tr><tr><td>Privacy - Microphone Usage Description</td><td>用于在使用 SDK 进行麦克风录制时，开启麦克风采集音频数据</td><td>可选</td></tr><tr><td>Privacy - Photo Library Additions Usage Description</td><td>用于在使用 SDK 进行视频编辑时，从系统相册中读取与写入视频文件</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="7">HarmonyOS Next</td></tr><tr><td>ohos.permission.CAMERA</td><td>用于在使用 SDK 进行视频录制时，开启摄像头采集视频数据</td><td>可选</td></tr><tr><td>ohos.permission.MICROPHONE</td><td>用于在使用 SDK 进行麦克风录制时，开启麦克风采集音频数据</td><td>可选</td></tr><tr><td>ohos.permission.READ_MEDIA</td><td>短视频编辑需要媒体读权限</td><td>可选</td></tr><tr><td>ohos.permission.WRITE_MEDIA</td><td>短视频编辑需要媒体写权限</td><td>可选</td></tr><tr><td>ohos.permission.WRITE_IMAGEVIDEO</td><td>短视频编辑需要相册写权限</td><td>可选</td></tr><tr><td>ohos.permission.READ_IMAGEVIDEO</td><td>短视频编辑需要相册读权限</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="18">实时音视频 SDK</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="5">HarmonyOS Next</td></tr><tr><td>ohos.permission.CAMERA</td><td>用于在使用 SDK 进行实时音视频通话时，开启摄像头采集视频数据</td><td>可选</td></tr><tr><td>ohos.permission.MICROPHONE</td><td>用于在使用 SDK 进行实时音视频通话时，开启麦克风采集音频数据</td><td>可选</td></tr><tr><td>ohos.permission.KEEP_BACKGROUND_RUNNING</td><td>用于在使用 SDK 退出后台后，继续采集数据</td><td>可选</td></tr><tr><td>ohos.permission.INTERNET</td><td>用于实现联网功能</td><td>必选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="9">Android</td></tr><tr><td>android.permission.INTERNET</td><td>用于实现联网功能</td><td>必选</td></tr><tr><td>android.permission.CAMERA</td><td>用于在使用 SDK 进行实时音视频通话时，开启摄像头采集视频画面</td><td>可选</td></tr><tr><td>android.permission.RECORD_AUDIO</td><td>用于在使用 SDK 进行实时音视频通话时，开启麦克风采集音频数据</td><td>可选</td></tr><tr><td>android.permission.BLUETOOTH</td><td>用于需要支持蓝牙耳机和耳麦的接入</td><td>可选</td></tr><tr><td>android.permission.ACCESS_WIFI_STATE</td><td>用于监控 WIFI 状态变化，提示用户当前网络环境</td><td>可选</td></tr><tr><td>android.permission.ACCESS_NETWORK_STATE</td><td>用于监控网络状态变化，提示用户当前网络环境</td><td>可选</td></tr><tr><td>android.permission.MODIFY_AUDIO_SETTINGS</td><td>用于修改全局音频配置，如在直播中开启蓝牙采集音频等场景</td><td>可选</td></tr><tr><td>android.permission.WRITE_EXTERNAL_STORAGE</td><td>用于进行自定义路径下的日志文件的存储</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="3">iOS</td></tr><tr><td>Privacy - Camera Usage Description</td><td>用于在使用 SDK 进行实时音视频通话时，开启摄像头采集视频数据</td><td>可选</td></tr><tr><td>Privacy - Microphone Usage Description</td><td>用于在使用 SDK 进行实时音视频通话时，开启麦克风采集音频数据</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="10">播放器SDK</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="3">Android</td></tr><tr><td>android.permission.INTERNET</td><td>用于实现联网功能</td><td>可选</td></tr><tr><td>android.permission.ACCESS_NETWORK_STATE</td><td>用于监控网络状态</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="4">HarmonyOS Next</td></tr><tr><td>ohos.permission.INTERNET</td><td>网络权限，用于实现联网功能</td><td>可选</td></tr><tr><td>ohos.permission.GET_NETWORK_INFO</td><td>获取网络信息</td><td>可选</td></tr><tr><td>ohos.permission.KEEP_BACKGROUND_RUNNING</td><td>用于后台播放</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="3">iOS</td></tr><tr><td>Privacy - Local Network Usage Description</td><td>用于实现联网功能</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="7">Miku 超低延时协议直播 SDK</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="4">Android</td></tr><tr><td>android.permission.INTERNET</td><td>用于实现联网功能</td><td>必选</td></tr><tr><td>android.permission.ACCESS_NETWORK_STATE</td><td>用于监控网络状态</td><td>可选</td></tr><tr><td>android.permission.WRITE_EXTERNAL_STORAGE</td><td>用于日志文件的存储</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="3">iOS</td></tr><tr><td>Privacy - Local Network Usage Description</td><td>用于实现联网功能</td><td>必选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="8">号码认证 SDK</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="5">Android</td></tr><tr><td>android.permission.INTERNET</td><td>允许应用程序联网，用于访问网关和认证服务器。</td><td>必选</td></tr><tr><td>android.permission.ACCESS_WIFI_STATE</td><td>允许应用程序访问WiFi 网络状态信息。</td><td>必选</td></tr><tr><td>android.permission.ACCESS_NETWORK_STATE</td><td>获取网络状态，判断是否数据，WiFi 等</td><td>必选</td></tr><tr><td>android.permission.CHANGE_NETWORK_STATE</td><td>允许程序改变网络连接状态。</td><td>必选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="2">iOS</td></tr><tr><td>Privacy - Local Network Usage Description</td><td>允许应用程序联网，用于访问网关和认证服务器。</td><td>必选</td></tr><tr><td>云短信SDK</td><td>Linux等</td><td>无</td><td>用于服务端云短信请求</td><td>无</td></tr><tr><td>容器轻应用平台SDK</td><td>Linux等</td><td>无</td><td>用于服务端容器集群调度请求</td><td>无</td></tr><tr><td>云主机SDK</td><td>Linux等</td><td>无</td><td>用于服务端云主机请求</td><td>无</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="13">互动直播低代码 SDK</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="9">Android</td></tr><tr><td>android.permission.INTERNET</td><td>用于实现联网功能</td><td>必选</td></tr><tr><td>android.permission.CAMERA</td><td>用于在使用 SDK 进行实时音视频通话时，开启摄像头采集视频画面</td><td>可选</td></tr><tr><td>android.permission.RECORD_AUDIO</td><td>用于在使用 SDK 进行实时音视频通话时，开启麦克风采集音频数据</td><td>可选</td></tr><tr><td>android.permission.BLUETOOTH</td><td>用于需要支持蓝牙耳机和耳麦的接入</td><td>可选</td></tr><tr><td>android.permission.ACCESS_WIFI_STATE</td><td>用于监控 WIFI 状态变化，提示用户当前网络环境</td><td>可选</td></tr><tr><td>android.permission.ACCESS_NETWORK_STATE</td><td>用于监控网络状态变化，提示用户当前网络环境</td><td>可选</td></tr><tr><td>android.permission.MODIFY_AUDIO_SETTINGS</td><td>用于修改全局音频配置，如在直播中开启蓝牙采集音频等场景</td><td>可选</td></tr><tr><td>android.permission.WRITE_EXTERNAL_STORAGE</td><td>用于进行自定义路径下的日志文件的存储</td><td>可选</td></tr><tr><td font-weight="nomal" text-align="center" colspan="1" rowspan="3">iOS</td></tr><tr><td>Privacy - Camera Usage Description</td><td>用于在使用 SDK 进行实时音视频通话时，开启摄像头采集视频数据</td><td>可选</td></tr><tr><td>Privacy - Microphone Usage Description</td><td>用于在使用 SDK 进行实时音视频通话时，开启麦克风采集音频数据</td><td>可选</td></tr></tbody>
</table>

请注意，在不同设备和系统中，权限显示方式及关闭方式可能有所不同，请终端用户参考其使用的设备及操作系统开发方的说明或指引。当终端用户关闭权限即代表其取消了相应的授权，我们和开发者将无法继续收集和使用对应的个人信息，也无法为终端用户提供上述与该等授权所对应的功能。

### 3. 我们从第三方获得的第三方开发者和/或终端用户的个人信息 [#3-我们从第三方获得的第三方开发者和或终端用户的个人信息]

我们可能从第三方开发者授权同意的第三方（我们的合作方）处间接获取第三方开发者和/或终端用户的个人信息，获取的个人信息是为实现七牛 SDK 产品和/或服务必要功能所必需的最少数量。&#x2A;*如我们收集的信息无法单独或结合其他信息识别到第三方开发者和/或终端用户的个人身份，其不属于法律意义上的个人信息。**

我们会在收集前要求第三方对个人信息来源的合法性作出承诺，并向第三方开发者和/或终端用户告知共享的目的、信息等内容，在依法取得第三方开发者和/或终端用户同意后收集个人信息，确保在已获得的个人信息处理的授权同意范围内进行共享。

如第三方有违反法律法规要求或约定的行为，我们会立即停止从该方收集信息、停止合作并采取相应的补救措施将损失减少到最小；同时，我们会使用不低于对自身用户个人信息同等的保护水平对间接获取的个人信息进行保护，在间接获取个人敏感信息时，我们会采用更加严格的（如传输加密等）安全保障措施。

### 4. 以下情形中，我们收集、使用个人信息无需征得第三方开发者和/或终端用户的授权同意 [#4-以下情形中我们收集使用个人信息无需征得第三方开发者和或终端用户的授权同意]

4.1 为订立、履行个人作为一方当事人的合同所必需，或者按照依法制定的劳动规章制度和依法签订的集体合同实施人力资源管理所必需；

4.2 为履行法定职责或者法定义务所必需；

4.3 为应对突发公共卫生事件，或者紧急情况下为保护自然人的生命健康和财产安全所必需；

4.4 为公共利益实施新闻报道、舆论监督等行为，在合理的范围内处理个人信息；

4.5 依照本法规定在合理的范围内处理个人自行公开或者其他已经合法公开的个人信息；

4.6 法律、行政法规规定的其他情形。

### 5. 个人信息的使用规则 [#5-个人信息的使用规则]

我们会根据本声明和/或与第三方开发者的合同约定，并仅为实现七牛 SDK 产品和/或服务功能，对所收集的个人信息进行处理。若需要将收集的个人信息用于其他目的，我们会以合理方式告知第三方开发者和/或终端用户，并在第三方开发者获得终端用户同意后和/或单独获得终端用户同意后进行使用。
我们向第三方开发者提供的 SDK 产品和/或服务停止运营后，或者第三方开发者和/或终端用户撤回个人信息的授权后，或者在第三方开发者和/或终端用户注销账号后，我们将会于合理的时间内销毁或匿名化处理从第三方开发者和/或终端用户处接收的所有个人信息，除非法律另有规定。

# 二、第三方终端用户的授权同意 [#二第三方终端用户的授权同意]

第三方开发者将七牛 SDK 产品和/或服务集成到其第三方中，为向终端用户提供七牛 SDK 产品和/或服务，我们会以合法合规的方式收集、存储、加工来自于第三方开发者和/或终端用户的个人信息。

**请第三方开发者知悉并同意：**

**第三方开发者已经遵守并将持续遵守适用的法律、法规和监管要求收集、使用和处理第三方终端用户的个人信息，包括但不限于制定和公布有关个人信息保护声明或隐私政策等；**

**在集成七牛 SDK 前，第三方开发者已经告知第三方终端用户并且已经获得终端用户充分、必要且明确的授权、同意和许可（包括获取了儿童监护人对提供终端用户是儿童的个人信息的授权同意）、为提供七牛 SDK 产品和/或服务以及与第三方功能对应的目的，我们会收集和共享以及如何使用（包括允许我们根据本声明的规定收集和处理）第三方终端用户的个人信息；**

**除非适用法律另有规定，第三方开发者已经告知终端用户并且获得终端用户充分必要的授权、同意和许可，允许我们对已经收集的个人信息进行去标识化处理，并且在符合相关法律法规的前提下，可以将收集、处理的信息用于本声明第一条列明的用途；**

**在获得终端用户的同意前，除非法律法规另有规定，不应收集终端用户的个人信息；**

**已向终端用户提供易于操作且满足法律法规要求的用户权利实现机制，并告知终端用户如何查阅、复制、修改、删除个人信息，撤回同意，以及限制个人信息处理、转移个人信息、获取个人信息副本和注销账号。**

# 三、如何共享、转让、公开披露第三方开发者和/或终端用户的个人信息 [#三如何共享转让公开披露第三方开发者和或终端用户的个人信息]

### 1. 共享 [#1-共享]

一般情况下，我们不会与我们的关联公司、合作伙伴及第三方共享第三方开发者和/或终端用户的必要的个人信息，除非为实现本声明第一条中所提及目的的需要。

如存在分享的行为，我们会要求关联公司、合作伙伴及第三方提供数据安全能力和信息安全资质（如等级保护测评、信息安全管理体系等）证明。在个人敏感信息的处理上，我们会要求第三方采用数据脱敏加密技术，从而更好地保护个人信息。如果第三方开发者和/或终端用户对第三方处理个人信息有异议或发现这些第三方存在风险时，请按照本声明第九条所述方式联系我们。

我们的关联公司、合作伙伴及第三方如要改变个人信息的处理目的，我们会再次征求第三方开发者和/或终端用户的同意。

### 2. 转让 [#2-转让]

我们不会将第三方开发者和/或终端用户的个人信息转让给任何公司、组织和个人，但以下情况除外：
2.1 事先获得第三方开发者和/或终端用户明确的同意或授权；
2.2 在涉及合并、收购、资产转让或类似的交易时，如涉及到个人信息转让，我们会要求新的持有第三方开发者和/或终端用户个人信息的公司、组织继续受本隐私声明的约束，否则，我们将要求该公司、组织重新向第三方开发者和/或终端用户征求授权同意。

### 3. 公开披露 [#3-公开披露]

我们不会公开披露第三方开发者和/或终端用户的个人信息，除非：

* 3.1 获得第三方开发者和/或终端用户的明确同意后；
* 3.2 在法律法规、法律程序、诉讼或政府主管部门强制要求的情况下。

### 4. 共享、转让、公开披露个人信息时事先征得授权同意的例外 [#4-共享转让公开披露个人信息时事先征得授权同意的例外]

请理解，在以下情形中，根据法律法规及国家标准，我们共享、转让、公开披露第三方开发者和/或终端用户的个人信息，无需事先征得第三方开发者和/或终端用户的授权同意：

* 4.1 与个人信息控制者履行法律法规规定的义务相关的；
* 4.2 与国家安全、国防安全有关的；
* 4.3 与公共安全、公共卫生、重大公共利益直接相关的；
* 4.4 与刑事侦查、起诉、审判和判决执行等直接相关的；
* 4.5 出于维护第三方开发者和/或终端用户或其他个人的生命、财产等重大合法权益但又很难得到本人同意的；
* 4.6 第三方开发者和/或终端用户自行向社会公众公开的个人信息；
* 4.7 从合法公开披露的信息中收集个人信息的，如合法的新闻报道、政府信息公开等渠道。

请知悉，\*\*如我们收集的信息无法单独或结合其他信息识别到第三方开发者和/或终端用户的个人身份，其不属于法律意义上的个人信息，\*\*此类处理后数据的共享、转让、公开披露，无需另行向第三方开发者和/或终端用户通知并征得同意。

# 四、如何存储第三方开发者和/或终端用户的个人信息 [#四如何存储第三方开发者和或终端用户的个人信息]

### 1. 存储方式和期限 [#1-存储方式和期限]

我们会通过安全的方式存储第三方开发者和/或终端用户的信息，包括本地存储、数据库和服务器日志。
一般情况下，我们只会在为实现本声明所述目的所必需的最短时间内或适用的法律法规规定或个人信息主体另行授权同意的条件/范围内存储第三方开发者和/或终端用户的个人信息。

* 法律法规另有规定，或第三方开发者和/或终端用户另行授权同意的情形下，我们可能会延长个人信息存储期限。

### 2. 存储地域 [#2-存储地域]

**我们会按照法律法规规定，将境内收集的个人信息存储于中国境内。**
如七牛因提供服务需要跨境传输或存储个人信息的，我们会向第三方开发者和/或终端用户告知个人信息出境的目的、接收方、安全保证措施和安全风险，&#x2A;*并征得第三方开发者和/或终端用户的同意。**

**若第三方开发者使用七牛的产品或服务，应用于中华人民共和国大陆以外的地区，需向中华人民共和国境外提供个人信息的，第三方开发者应当遵守《中华人民共和国个人信息保护法》关于个人信息跨境传输的有关规定，并符合当地有关数据跨境传输转移的法律法规和监管要求。**

# 五、如何保护第三方开发者和/或终端用户的个人信息安全 [#五如何保护第三方开发者和或终端用户的个人信息安全]

### 1. 安全保护措施 [#1-安全保护措施]

我们已使用符合业界标准的安全防护措施保护第三方开发者和/或终端用户提供的个人信息，防止数据遭到未经授权访问、公开披露、使用、修改、损毁、泄漏或丢失。
&#x2A;*我们采用业界领先的技术保护措施。我们使用的技术手段包括但不限于防火墙、加密（例如 SSL）、去标识化或匿名化处理、访问控制措施等。此外，我们还会不断加强将 SDK 集成到第三方上的安全能力。**
我们建立了专门保障个人信息安全的管理制度、流程和组织。我们也会审查该管理制度、流程和组织，以防未经授权的人员擅自访问、使用或披露用户的信息。

### 2. 安全事件处置措施 [#2-安全事件处置措施]

若发生个人信息泄露、损毁、丢失等安全事件，我们会启动应急预案，阻止安全事件扩大。安全事件发生后，我们会及时以推送通知、邮件等形式向第三方开发者和/或终端用户告知安全事件的基本情况、我们即将或已经采取的处置措施和补救措施，以及我们对第三方开发者和/或终端用户的应对建议。

# 六、第三方开发者和/或终端用户如何管理其个人信息 [#六第三方开发者和或终端用户如何管理其个人信息]

我们非常重视第三方开发者和/或终端用户对个人信息的管理，并尽全力提供对个人信息的查询、访问、修改、删除、投诉举报以及设置隐私功能等的相关权利，以使第三方开发者和/或终端用户有能力保障自身的隐私和信息安全。

### 1. 针对第三方开发者 [#1-针对第三方开发者]

鉴于第三方开发者直接负有响应终端用户个人信息请求的义务，第三方开发者应：

根据其使用的开发者平台功能设置, 为终端用户提供并明确其查阅、复制、修改、删除个人信息、撤回同意、转移个人信息、限制个人信息处理、获取个人信息副本和注销账号的方式。

当在使用七牛SDK产品的过程中, 如果终端用户提出管理其个人信息的请求, 并且第三方开发者已确定该等请求涉及到了七牛SDK产品处理的个人信息、需要我们协助处理时, 您应当及时通过本声明第九条所述方式联系我们, 并附上必要的终端用户请求的书面证明材料。我们将及时核验相关材料, 并按照相关法律法规, 以及本声明等法律文本中明确的规则, 为终端用户行使权利的请求提供相应的支持与配合。

### 2. 针对第三方终端用户 [#2-针对第三方终端用户]

由于第三方终端用户不是我们的直接用户，我们建议：

* 2.1 为保障终端用户的权利实现，我们已要求第三方开发者承诺提供便于操作的用户权利实现方式。如终端用户需要查阅、复制、修改、删除其相关的个人信息、撤回同意、限制个人信息处理、获取个人信息副本和注销账号，可要求第三方开发者提供上述权利实现方式。&#x2A;*<u>请终端用户注意，我们难以控制第三方开发者的行为，如果第三方开发者未按照承诺提供，终端用户可通过本声明第九条中的方式与我们取得联系，我们将尽力协调、支持并保障终端用户的权利的实现；</u>**
* 2.2 为了更好保障终端用户的相关账号安全和个人信息安全，当终端用户直接向我们主张个人信息主体权利时，应提供必要的证明文件，我们还会对终端用户进行身份验证。我们会向第三方开发者核实终端用户身份以保障终端用户第三方账号安全的情况下，响应终端用户的相关请求；
* 2.3 当终端用户直接向我们主张个人信息主体权利时，根据第三方开发者的隐私政策或个人信息保护声明，我们还可能将与终端用户个人信息相关的请求直接发送给该第三方开发者，要求其处理和/或寻求帮助。

### 3. 响应第三方开发者和/或终端用户的合理请求 [#3-响应第三方开发者和或终端用户的合理请求]

我们会响应第三方开发者和/或终端用户上述的合理请求，对多次重复、超出合理限度的请求，我们将视情况收取一定成本费用，对无端重复、需要过多技术手段（例如，需要开发新系统或从根本上改变现行惯例）、给他人合法权益带来风险或者非常不切实际（例如，涉及备份磁盘上存放的信息）的请求，我们可能会予以拒绝。
在以下情形中，我们可能无法响应第三方开发者和/或终端用户的请求：

* 3.1 与我们履行法律法规规定的义务相关的；
* 3.2 与国家安全、国防安全直接相关的；
* 3.3 与公共安公共卫生、重大公共利益直接相关的；
* 3.4 与犯罪侦查、起诉、审判和执行判决等直接相关的；
* 3.5 我们有充分证据表明第三方开发者和/或终端用户存在主观恶意或滥用权利的；
* 3.6 出于维护第三方开发者和/或终端用户或其他个人的生命、财产等重大合法权益但又很难得到本人同意的；
* 3.7 响应第三方开发者和/或终端用户的请求将导致第三方开发者或其他个人、组织的合法权益受到严重损害的；
* 3.8 涉及商业秘密的。

**如第三方开发者和/或终端用户的对上述权利实现存在疑问，可以根据本声明第九条所述方式与我们联系。**

# 七、如何处理儿童个人信息 [#七如何处理儿童个人信息]

请第三方开发者确保是18周岁（含）以上人士。请第三方开发者理解并知悉，如果第三方是针对不满 14 周岁儿童用户的\*\*（第三方开发者知悉用户群体中有不满十四周岁未成年人的也属于此种情形\*\*），请第三方开发者务必制定专门的个人信息处理规定，并确保第三方终端用户（儿童）的父母或其他监护人已经阅读并同意了第三方的隐私政策以及本文，并且经其单独同意后提供儿童个人信息给我们，以实现第三方在隐私政策中所述的相关功能。

如果第三方开发者的第三方是针对儿童并为儿童用户设计和开发的，请第三方开发者务必指定专门的个人信息处理规定，并务必确保该第三方终端用户（儿童）的父母或其他监护人已经阅读并同意了第三方的隐私政策/个人信息保护声明以及本声明，并且经其单独同意提供儿童个人信息给我们以实现第三方的相关功能。

如果我们在不知情的情况下收集了儿童的个人信息，我们将及时对其进行删除，除非法律法规要求我们保留此类资料。如果第三方开发者和/或终端用户（儿童）的父母或其他监护人认为我们错误或意外地向儿童收集了信息，请按本声明第九条所述方式及时联系我们。如果经我们发现第三方开发者未获得儿童的父母或其他监护人同意向我们提供儿童个人信息的，我们将尽快删除该儿童的个人信息并确保不对其进一步处理。如果未成年人的监护人对所监护未成年人的个人信息处理行为有相关疑问时、或希望查询、复制、变更、撤回同意或删除相应未成年人的个人信息时, 可以联系第三方开发者, 或通过本声明第九条的联系方式与我们联系。

**但请注意，若终端用户和/或终端用户（儿童）的父母或其他监护人要求我们删除特定儿童个人信息，可能导致该终端用户（儿童）无法继续使用我们的产品和服务或产品和服务中的某些具体业务功能。**

# 八、如何变更与更新本声明 [#八如何变更与更新本声明]

为给第三方开发者提供更好的服务以及随着本平台产品和/或服务的不断发展与变化，我们可能会适时对本声明进行修订。

当本声明的条款发生变更时，我们会在版本更新时以弹窗、红点提示、网站公告等方式进行提示，并说明生效日期。此外，如果更新后的本声明对第三方终端用户的权利有所影响，还需要请第三方开发者适时更新第三方的隐私政策。

* 对于重大变更，我们还会提供更为显著的通知（包括对于某些服务，我们会通过电子邮件或站内信形式或公告形式发送通知，说明本声明的具体变更内容）。因此，请随时查看和了解本声明内容。如果第三方开发者和/或终端用户不同意接受本声明，请停止集成七牛 SDK。

本声明是七牛各 SDK 开发者平台服务协议的重要组成部分。我们还会将本声明的旧版本存档，供第三方开发者和/或终端用户查阅。

# 九、如何联系我们 [#九如何联系我们]

如第三方开发者和/或终端用户对本声明或个人信息相关事宜有疑问，可以通过以下方式与我们取得联系：

* [提交工单](https://support.qiniu.com/tickets/new)
* 通过七牛客服电话 400-101-8589转1
* 发送邮件至 [bd@qiniu.com](mailto:bd@qiniu.com)
* 邮寄信件至：中国上海市浦东新区浦东软件园Q座七牛云客服中心（收）邮编：201203

为保障我们高效处理您的问题并及时向您反馈，我们可能需要您提交身份证明、有效联系方式和书面请求及相关证据，我们将在验证请求人身份后尽快审核所涉问题，并于十五个工作日内予以回复。

# 十、其它 [#十其它]

**《七牛云隐私政策》是七牛统一适用的一般性隐私条款，其中所规定的用户权利及信息安全保障措施均适用于第三方开发者和/或终端用户。如《七牛云隐私政策》与本声明存在不一致或矛盾之处，请以本声明为准。**

我们请第三方开发者特别注意：当第三方开发者进行个人信息的处理活动，如果符合以下任何一项条件，请第三方开发者注意同时遵守《欧盟通用数据保护条例》（General Data Protection Regulation，以下简称 “GDPR”）：

* 第三方开发者在欧盟经济区域（“EEA”），无论该处理活动是否在欧盟进行；
* 向在 EEA 的个人提供商品或服务（不论是否有偿），或者监视其在 EEA 内的行为；
* 不在 EEA 内，但根据国际公法适用欧盟成员国法律（例如 EEA 成员国的使馆或领事馆）。

如果第三方开发者和/或终端用户来自EEA，我们收集和使用上述个人信息的法律依据将取决于相关个人信息以及我们收集信息的具体背景。
对于 EEA 中的第三方开发者和/或终端用户，有权根据适用的数据保护法律向主管数据保护机构投诉或向具有管辖权的法院提起诉讼。
如果第三方开发者和/或终端用户对我们收集和使用个人信息的法律依据有疑问或需要进一步信息的，请根据本声明第九条所述方式与我们联系。

2026 年 01 月 19 日更新并生效。

《七牛 SDK 隐私声明》历史版本：
[《七牛 SDK 隐私声明》(2022 年 5 月 6 日版)](/products/mikustream/2-privacy-policy)
[《七牛 SDK 隐私声明》(2022 年 7 月 20 日版)](https://developer.qiniu.com//mikustream/service_agreement/12979/miku-sdk-privacy-policy)


# 校园开发者成长计划常见问题 (/products/mkt/manual/12265-campus-developers-growth-plan-application-and-common-problems)



最近更新时间: 2022-09-27 15:56:30

# 「七牛校园开发者成长计划」活动规则： [#七牛校园开发者成长计划活动规则]

## 活动对象： [#活动对象]

完成七牛注册及学生认证，历史上未有消费的用户。

## 活动说明： [#活动说明]

1、本次活动区域为中国大陆地区，完成学生认证即可领用专属订单抵用券，抵用券将由系统自动发放至认证账户，用户可在商城页面下单使用。

2、本活动可免费领取的产品额度以页面展示为准。

3、如您在活动或使用过程中有任何疑问，请点击此处[提交工单](https://support.qiniu.com/tickets/new/?ref=developer.qiniu.com)或发送邮件至 \[[marketing@qiniu.com](mailto:marketing@qiniu.com)]。

4、为保证活动的公平公正，七牛云有权对恶意刷抢活动资源，利用系统漏洞购买规定数量以外的商品，长期资源闲置，利用资源从事违法违规行为的用户收回云资源。

5、所有参加本活动的用户，均视为认可并同意遵守《七牛云用户协议》。

*活动最终解释权在法律允许范围内归七牛云所有 。*


# 推广奖励规则 (/products/mkt/manual/7261-cps-promotion-rules)



最近更新时间: 2026-05-08 17:04:48

**使用专属推广链接推荐好友成功上云，即可获得关联期内好友所有购买的订单返佣，推广者基础返佣比例为 25%，叠加当前推广等级，最高可享 35% 现金奖励！**

![CPS推广奖励规则插图.png](/docs-assets/products/mkt/manual/7261-cps-promotion-rules/FpkOFlaW4Gg8WxHbKnFgGN3_9J-R-13d6dc6b78da.webp)

**推广等级共分为 3 个阶梯，不同的等级对应不同权益，推广等级越高返佣比例越高、佣金上限越高。 [点击查看推广等级说明>](/products/mkt/manual/7564-the-new-officer-promotion-class-rules)**<br /><br />

# 一、推广资格界定 [#一推广资格界定]

**1、注册七牛云账号并完成实名认证的个人用户。**

**2、企业用户及渠道代理商不能成为推广者。**

**3、七牛云内部员工不能成为推广者。**

**4、海外用户暂不参与新推官活动。**<br /><br />

# 二、好友关联判断 [#二好友关联判断]

**1、建立关联**

被邀请人通过专属推广链接注册 / 登录就会与推广者建立有效关联。在关联有效期内，被邀请人使用现金部分购买的所有订单产品，推广者均可获得 25% \~ 35% 的返佣奖励（[好友下单前请确定是否已经建立关联](https://portal.qiniu.com/cps/customer)）。

* **全新用户**
  * 用户定义：从未注册过七牛云的用户，通过推广者推荐注册的新用户
  * 关联机制：推广者与新客户建立30天有效关联，保护期内不允许关联其他推广者。30天关联结束后，如被邀请人未出现现金付费行为则流转为沉默客户。
* **沉默用户**
  * 用户定义：已注册七牛云但从未有过现金付费行为的用户，通过推广者推荐链接登录的老用户
  * 关联机制：推广者与被激活的沉默客户建立30天有效关联，关联期间 1 年内不允许客户与其他新推官建立关联，以最近建立关联的新推官为有效关联。

**2、关联失败**

\<1>、付费老用户（销售团队直接服务）

\<2>、渠道商 / 代理商用户（合作伙伴团队直接对接）

\<3>、同人风控拦截（同手机号、注册邮箱、身份证、登录 IP）

\<4>、已被其他推广者关联的全新用户（关联保护期为 30 天）

\<5>、关联用户通过“无痕浏览”模式下的浏览器注册，会导致系统无法获得用户绑定信息，导致关联失败<br /><br />

# 三、返佣计算规则 [#三返佣计算规则]

**1、推广佣金计算**

推广奖励佣金 = （被邀请人实付订单金额 - 退款订单金额） × 推广者等级对应的返佣比例

**2、推广返佣范围**

被邀请人在 30 天关联期间内产生的所有有效订单，均可根据推广者当前对应的返佣比例进行返佣奖励。

**3、单笔佣金上限**

被邀请人单笔订单返佣封顶为 5000 元。

举例：被邀请人在与推广者有效关联期间购买单笔订单金额为9万元，根据单笔订单佣金上限5000元的要求，所以该推广者最多在该笔订单中获得返佣金额为5000元。

**4、有效客户定义**

需同时满足以下两点：
1.完成个人 / 企业实名认证，订单现金实付金额 ＞0元 的用户。
2.无任何违法违规行为的用户<br /><br />

# 四、推广佣金结算 [#四推广佣金结算]

**1、结算时间**

推广佣金暂不支持后台自主提现，每月25日前七牛云财务系统会向您的银行卡汇入结算佣金，具体到账时间以银行为准。（推广者及时在系统上如实填写个人银行卡信息，避免延误结算）

**2、打款要求**

当月最低打款要求未结算佣金累计 ≥100元。如推广者多笔佣金合计未满足每月最低打款要求，会累计到下个月直至满足最低打款要求后安排统一打款。

**3、结算周期**

佣金结算周期为5期，每期打款比例为返佣金额的20%。

举例：推广者在某月推广了一笔订单，返佣金额为450元并分5期结算，每期结算金额为90元，第一期佣金结算金额为90元，不满足最低打款要求，则累计到与第二期应发佣金一并结算，所以第二期打款金额为180元。第三期结算金额仍为90元，依然不满足最低打款要求并累计到第四期一并结算。剩于第五期的90元佣金需要满足当月最低打款要求后完成打款。

**4、佣金计算**

佣金计算：单笔订单实时计算返佣金额并分为5期打款。

订单退款：如有订单退款行为，系统会实时扣除该笔订单所奖励的佣金。如该笔订单佣金已完成结算，则会在下一期结算金额中扣除。以此类推。

# 5、重要风控事项说明 [#5重要风控事项说明]

禁止链接劫持、强制捆绑、违反法律法规等的非正当方式推广。如推广者推广的客户涉及黑产及违规操作，推广者不会获得相应黑产订单产生的佣金。

新推官应在七牛云推广许可范围内，使用正当的手段方式进行推广，不应进行任何欺骗或虚假性质的推广行为，包括但不限于：
1、与其他新推官、或被推广客户相互串通，弄虚作假，恶意刷单，骗取返佣奖励；新推官如使用上述非正当方式开展推广活动，七牛云有权判定该等推广方式所带来的推广结果无效，并扣除佣金；
2、虚假、或夸大陈述七牛云活动的推广政策及优惠（如在其他平台以低于官网活动价形式进行推广售卖）；
3、采取诱导用户访问其网站、并通过放置网页插件、可执行代码等方式，强制与用户建立推广关系的；
4、其他侵犯被推广用户知情权、选择权的不正当推广行为；
5、其他七牛云判定推广手段属于不正当推广行为的；

注意：若发现虚假推广行为，将对月结佣金进行冻结扣除并终止推广合作。若您发现其他新推官采用不正当手段进行推广，支持提供证据进行举报。举报接收邮箱：[zhongbowen@qiniu.com](mailto:zhongbowen@qiniu.com)。

<br />

<br />


# 新推官申请及常见问题 (/products/mkt/manual/7562-push-the-new-officer-common-problems)



最近更新时间: 2021-12-01 10:53:02

# 1、关于七牛云新推官项目？ [#1关于七牛云新推官项目]

做为国内知名的云计算及数据服务提供商，七牛云一直致力于以数据科技全面驱动数字化未来，赋能各行各业全面进入数据时代。新推官项目是七牛云生态合作伙伴计划之一，现只对七牛云实名认证的个人用户开放推广奖励。加入新推官分享专属推广链接带动身边的好友一起上云，在新推官中有多种推广素材，可以助力推广者高效快速的完成推广并获得奖励。随着有效推广人数的增加，对应推广等级的返佣比例和返佣金额也会提高。如推广中遇到问题可加入七牛云新推官交流群获得帮助与支持（QQ 群号：1106335666），快来帮助身边的开发者小伙伴和中小企业上云吧！<br /><br />

# 2、如何加入七牛云新推官？ [#2如何加入七牛云新推官]

**只需要四步就可以完成推广并获得返佣：**

**1.1、【加入】新推官**

[进入活动页面](https://www.qiniu.com/cps)， 点击 “加入新推官” 按钮，确认推广协议后，成为新推官。

**1.2、【分享】专属链接**

您可以将自己的专属推广链接分享到个人博客、技术论坛、技术网站等页面，引导客户访问并完成注册 / 登录。

**1.3、【关联】并支付订单**

引导客户完成注册 / 登录，实现 30 天有效关联，并在关联期间购买订单。

**1.4、【返利】获得奖励**

推广者在系统内填写好银行卡信息，七牛云会按月发放佣金奖励，打款至推广者的银行账号。<br /><br />

# 3、我是推广小白，如何达成有效推广？ [#3我是推广小白如何达成有效推广]

**1.1、找到需要推荐的客户活动范围，如线上群聊、IT论坛、技术网站、技术博客；**

**1.2、通过包装推广素材和相关权益、撰写技术文章吸引客户点击注册 / 登录推广链接；**

**1.3、持续分享、或利用自身技术优势与潜在客户建立推广关系，建立有效关联后，客户在关联期间所产生的订单即获返佣奖励；**<br /><br />

# 4、哪些人无法申请加入新推官？ [#4哪些人无法申请加入新推官]

**4.1、七牛云合作伙伴、渠道商；**

**4.2、七牛云内部员工；**

**4.3、企业认证的七牛云用户；**<br /><br />


# 推广等级规则 (/products/mkt/manual/7564-the-new-officer-promotion-class-rules)



最近更新时间: 2021-12-01 10:41:28

# 一、推广等级说明 [#一推广等级说明]

**推广等级共分为 3 档，分别为青铜、白银、黄金，等级越高返佣比例越高，佣金上限越高。新加入的推广者默认为青铜等级。**

![CPS规则插图.png](/docs-assets/products/mkt/manual/7564-the-new-officer-promotion-class-rules/FtjQbZ6eSAvOphKLDENe3FEXl7U3-eec662663666.webp)

<br />

<br />

# 二、有效客户定义 [#二有效客户定义]

**1、被邀请人完成个人 / 企业实名认证；**

**2、订单现金实付金额 ＞0元 的用户；**<br /><br />

# 三、推广等级判定 [#三推广等级判定]

**1、等级计算**

核算推广者近 3 个月的推广情况，根据推广者邀请的有效客户数来计算本月等级。（推广等级 = 近3个月累计邀请有效客户数 - 近3个月累计退款客户数）

举例：截止9月某白银推广者近3个月累计有效推广人数为105人，但近3个月共有9位被邀请人发起退款行为。则10月做等级调整时该推广者等级仍为白银等级。

**2、等级更新**

等级按月更新，每月1-3日确认推广者本月等级。

**3、跨级限制**

青铜等级的推广者次月最高升级为白银，不得升级为黄金；升级黄金等级前，原等级不得低于白银。
举例：某推广者初始等级为青铜，当月有效推广客户数为145人，次月做等级调整时，该用户等级为白银，因升级黄金等级前该用户等级不得低于白银，不允许推广者跨级。<br /><br />


# 关联客户规则 (/products/mkt/manual/7565-the-new-officer-associated-customer-rules)



最近更新时间: 2026-05-06 15:01:12

# 一、关联客户规则 [#一关联客户规则]

**1、建立关联**

1.1、新用户通过访问推广者的专属链接，并完成注册，将与推广者建立起30天的关联期。关联期间，被关联客户完成首单，推广者即可获得首单奖励。

关联期间，被关联客户不会与其他推广者建立关联，即使访问其他推广者的链接，关联关系也不会改变。这里，新用户是指通过访问推广者的专属链接，并完成注册的用户。

1.2、七牛已注册用户，访问推广者的专属链接。将与推广者建立起30天的关联。关联期间，被关联客户完成首单，推广者即可获得首单奖励。

关联期间允许客户与其他推广者建立关联，后建立关联的推广者将覆盖先关联的推广者。老用户是指访问推广者的专属链接之前已经在七牛云注册的用户。

关联的用户账号主体如果已经有代理商、销售团队直接服务的无法建立关联。

**2、解除关联**

建立关联的30天后，将自动解除关联关系。解除关联后，客户支付完成的首单将与原推广者无关，将不会计入原推广者的奖励。

**3、同人风控**

七牛云将比对被关联客户与已注册用户的信息是否一致，包括但不限于：手机号、邮箱、身份信息、注册ip等，如发现一致，即视为被关联客户在七牛拥有多个同人账号，不再视为新客户，并取消该首单奖励。

**4、查看关联客户**

您可以在这个页面查看 立即前往 CPS关联客户和推广情况。

如果关联客户中存在命中同人风控的账号，那么结算前七牛云将剔除这部分账号的首单奖励，剩余奖励照常发放。因此关联客户的数据可能会更新，请您以结算前的数据为准。


# 服务端接口文档 (/products/qnvs/api/12452-qnvs_api_server)



最近更新时间: 2023-06-13 17:37:40

# API 说明 [#api-说明]

## API 服务域名 [#api-服务域名]

```
https://ums-api.qiniu.com/
```

## 请求鉴权 [#请求鉴权]

API 服务采用Qiniu Auth 的方式进行鉴权。

每一个请求均需在 HTTP 请求头部增加一个 Authorization 字段，其值为符合管理凭证的字符串，形式如下：

```
Authorization: <QiniuToken>
```

## 生成管理凭证 [#生成管理凭证]

可以参考如下代码生成管理凭证。

```
// golang

// 构造待签名的 Data
// 1. 添加 Path
data = "<Method> <Path>"

// 2. 添加 Query，前提: Query 存在且不为空
if "<RawQuery>" != "" {
        data += "?<RawQuery>"
}

// 3. 添加 Host
data += "\nHost: <Host>"

// 4. 添加 Content-Type，前提: Content-Type 存在且不为空
if "<Content-Type>" != "" {
        data += "\nContent-Type: <Content-Type>"
}

// 5. 添加回车
data += "\n\n"

// 6. 添加 Body，前提: Content-Length 存在且 Body 不为空，同时 Content-Type 存在且不为空或 "application/octet-stream"
bodyOK := "<Content-Length>" != "" && "<Body>" != ""
contentTypeOK := "<Content-Type>" != "" && "<Content-Type>" != "application/octet-stream"
if bodyOK && contentTypeOK {
        data += "<Body>"
}

// 计算 HMAC-SHA1 签名，并对签名结果做 URL 安全的 Base64 编码
sign = hmac_sha1(data, "Your_Secret_Key")
encodedSign = urlsafe_base64_encode(sign)

// 将 Qiniu 标识与 AccessKey、encodedSign 拼接得到管理凭证
<QiniuToken> = "Qiniu " + "Your_Access_Key" + ":" + encodedSign

```

## 请求返回 [#请求返回]

号码认证服务的API，统一使用如下形式的返回结果。

```
{
    "request_id": "Yl0BACAisJ3-qlkX",
    "code": 200,
    "message": "success",
    "data": {}
}
```

\| 参数   | 类型    | 说明   |
\--------| -------------| ------------------ | -------
request\_id | string | 请求ID
code  | int |  200：请求成功；其他：请求失败。
message | string | 当请求失败时，返回失败描述信息。
data | object | 当请求成功时，返回业务数据。具体看每个接口的解析。

# 一键认证 [#一键认证]

## 请求方法 [#请求方法]

```
POST:           /v1/verification/login
Content-Type:   application/json
认证方式:        Qiniu-Auth
```

## 请求参数 [#请求参数]

```
{
    "out_id": "req-1",
    "app_id":"h40ndbd35",
    "token": "STsid0000001683366126670vx3grYley91DoSwwa0f5LxRxBWhnWacJ",
    "client_ip": "1.1.1.1",
    "encrypt_type": 0,
    "timestamp": 1683360751,
    "sign": "be9def62498a5025d44180b7a81d8236e400a52813af8ed06900b1b9d1dff2f6"
}
```

### 参数解析 [#参数解析]

| 参数            | 类型      | 是否必选 | 说明                                                          |
| ------------- | ------- | ---- | ----------------------------------------------------------- |
| out\_id       | string  | 可选   | 请求方生成的流水号。                                                  |
| app\_id       | string  | 必选   | 号码认证服务的应用ID                                                 |
| token         | string  | 必选   | 客户端APP，通过号码认证服务SDK，获取到的一键登录 Token。                          |
| client\_ip    | string  | 可选   | 客户端IP地址，可选。                                                 |
| encrypt\_type | integer | 必选   | 返回手机号码的加密方式：0，aes加密；1，rsa 加密。当使用 RSA 加密时，在申请应用时，需要配置RSA 公钥。 |
| timestamp     | integer | 必选   | 请求的时间戳，秒级时间戳                                                |
| sign          | string  | 必选   | 请求的签名                                                       |

### sign 签算 [#sign-签算]

sign 字段是对请求其余字段的签名。

签算内容生成：请求参数，除 sign 字段外，所有字段，按字段名升序排列，生成url query 形式的字符串。无值的字段，不能省略。

使用hmacSHA256 算法 ，使用应用的appKey，对待签算内容，进行签算。

代码示例：

```
// 所有可选字段都有的签算内容生成
data := "app_id=app_1&client_ip=1.1.1.1&encrypt_type=0&out_id=req-1&timestamp=0&token=xxxxxx"
sign := hmacSHA256(data, appKey)


// client_ip 不填的签算内容生成
data =: "app_id=app_1&client_ip=&encrypt_type=0&out_id=&timestamp=0&token=xxxxxx"
sign := hmacSHA256(data, appKey)

```

签算算法，参考后面的【签算与加密】部分。

## 返回结果 [#返回结果]

```
{
    "request_id": "Yl0BACAisJ3-qlkX",
    "code": 200,
    "message": "success",
    "data": {
        "out_id": "req-1",
        "msg_id": "msg-1",
        "timestamp": 123456,
        "mobile": "ABABCDCD"
    }
}
```

### data 部分说明 [#data-部分说明]

| 参数        | 类型      | 是否必选 | 说明          |
| --------- | ------- | ---- | ----------- |
| out\_id   | string  | 可选   | 请求方生成的流水号。  |
| msg\_id   | string  | 必选   | 七牛生成的消息流水号。 |
| timestamp | integer | 必选   | 服务端应答时间戳。   |
| mobile    | string  | 必选   | 手机号码密文。     |

### 手机号码解密 [#手机号码解密]

手机号码返回的是密文。根据请求的 encrypt\_type 选择解密算法。

* encrypt\_type 为0，使用 AES 解密。
* encrypt\_type 为1，使用RSA 解密。

解密算法，参考【签算与加密】部分。

# 本机号码验证 [#本机号码验证]

## 请求方法 [#请求方法-1]

```
POST:           /v1/verification/check
Content-Type:   application/json
认证方式:        Qiniu-Auth
```

## 请求参数 [#请求参数-1]

```
{
    "out_id": "req-1",
    "app_id":"h40ndbd35",
    "token": "STsid0000001683366126670vx3grYley91DoSwwa0f5LxRxBWhnWacJ",
    "mobile": "13800000000",
    "timestamp": 1683360751,
    "sign": "be9def62498a5025d44180b7a81d8236e400a52813af8ed06900b1b9d1dff2f6"
}
```

### 参数解析 [#参数解析-1]

| 参数        | 类型      | 是否必选 | 说明                                   |
| --------- | ------- | ---- | ------------------------------------ |
| out\_id   | string  | 可选   | 请求方生成的流水号。                           |
| app\_id   | string  | 必选   | 号码认证服务的应用ID                          |
| token     | string  | 必选   | 客户端APP，通过号码认证服务SDK，获取到的本机号码验证 Token。 |
| mobile    | string  | 必选   | 手机号码                                 |
| timestamp | integer | 必选   | 请求的时间戳，秒级时间戳                         |
| sign      | string  | 必选   | 请求的签名                                |

### sign 签算 [#sign-签算-1]

sign 字段是对请求其余字段的签名。

签算内容生成：请求参数，除 sign 字段外，所有字段，按字段名升序排列，生成url query 形式的字符串。无值的字段，不能省略。

使用hmacSHA256 算法 ，使用应用的appKey，对待签算内容，进行签算。

代码示例：

```
// 所有可选字段都有的签算内容生成
data := "app_id=app_1&mobile=13800000000&out_id=req-1&timestamp=0&token=xxxxxx"
sign := hmacSHA256(data, appKey)


// out_id 不填的签算内容生成
data =: "app_id=app_1&mobile=13800000000&out_id=&timestamp=0&token=xxxxxx"
sign := hmacSHA256(data, appKey)

```

签算算法，参考后面的【签算与加密】部分。

## 返回结果 [#返回结果-1]

```

{
    "request_id": "AjYAAJAQ7fDXulkX",
    "code": 0,
    "message": "success",
    "data": {
          "out_id": "req-1"
        "msg_id": "msg_1",
        "timestamp": 0,
        "is_verify": false,
        "operator": 0
    }
}
```

### data 部分说明 [#data-部分说明-1]

| 参数         | 类型      | 是否必选 | 说明                      |
| ---------- | ------- | ---- | ----------------------- |
| out\_id    | string  | 可选   | 请求方生成的流水号。              |
| msg\_id    | string  | 必选   | 七牛生成的消息流水号。             |
| timestamp  | integer | 必选   | 服务端应答时间戳。               |
| is\_verify | boolean | 必选   | true 是本机号码，false，不是本机号码 |
| operator   | integer | 可选   | 运营商。0 未知；1 移动；2 联通；3 电信 |

# 签算与加密 [#签算与加密]

## hmacSHA256签算 [#hmacsha256签算]

请求的数据，使用应用的appKey，对请求数据进行签算。

对签算结果，进行hex 编码后，转成大写。

### go代码示例 [#go代码示例]

```
func hmacSHA256(message string, key string) string {
   mac := hmac.New(sha256.New, []byte(key))
   mac.Write([]byte(message))
   sign := mac.Sum(nil)
   return strings.ToUpper(hex.EncodeToString(sign))
}
```

### 签算测试用例 [#签算测试用例]

```
// 待签算内容(UTF-8 编码)
message := "hello world, 你好中国"
// appKey
appKey := "1234554321"

// 签算
sign := hmacSHA256(message, appKey)

assert.Equal("617098ED069332F668C47083F5983DD754DFDF94209CCBDFAE5689CD40984907", sign)

```

## AES 解密 [#aes-解密]

当加密类型使用 AES 时，使用AES CBC算法进行解密。

### 秘钥生成 [#秘钥生成]

使用 appKey，生成秘钥与初始化向量

* 对appKey 进行 md5，得到hash 值是一个长度为 16 字节的byte 数组。
* 对 hash 进行hex 编码，并转成大写。得到一个 32 字节长度的字符串。
* 字符串的前16位字符串为秘钥，后16位字符为初始化向量解密。

### 执行解密 [#执行解密]

使用生成的秘钥与初始化向量进行AES CBC 解密。

### go代码示例 [#go代码示例-1]

```
// 使用appKey，分离出 key，iv
func splitAppKey(appKey string) ([]byte, []byte) {
	hash := md5.Sum([]byte(appKey))
	hashString := strings.ToUpper(hex.EncodeToString(hash[:]))

	return []byte(hashString[:16]), []byte(hashString[16:])
}

// 使用appKey，进行AES 解密
func Decrypt(data string, appKey string) (string, error) {
  // 1，对待解密内容，进行 hex 解码，得到原始密文。
	source, err := hex.DecodeString(data)
	if err != nil {
		return "", err
	}

  // 2，使用appKey，分离出 key，iv
	key, iv := splitAppKey(appKey)

	// 3，使用 key，iv 进行解密
	block, err := aes.NewCipher(key)
	if err != nil {
		return "", err
	}
	ecb := cipher.NewCBCDecrypter(block, iv)
	decrypted := make([]byte, len(source))
	ecb.CryptBlocks(decrypted, source)

  // 4，去掉填充数据
  result := UnPadding(decrypted)
	return string(result), nil
}

// 删除解密后数据的填充部分
func UnPadding(data []byte) []byte {
	padding := data[len(data)-1]
	return data[:(len(data) - int(padding))]
}

```

### 解密测试用例 [#解密测试用例]

这里提供解密测试用例，供对比测试。

```
密文：2253F7EA8DFB2D36439F6739CDBD7364
appKey：1234554321
解密后内容：13812341234
```

# 错误码 [#错误码]

| Code  | 说明                         |
| ----- | -------------------------- |
| 200   | 成功                         |
| 400   | 参数错误                       |
| 401   | 鉴权错误                       |
| 500   | 服务器内部错误                    |
| 30001 | APP 状态不可用                  |
| 30002 | 请求的加密算法是 RSA，但是应用未配置RSA 公钥 |
| 30003 | 请求运营商服务发生异常。               |
| 30004 | 运营商返回错误。                   |


# 安卓端接入指南 (/products/qnvs/development_guidelines/12453-anzhuoduan-access-guide)



最近更新时间: 2023-12-18 17:17:50

# 安卓快速集成文档 [#安卓快速集成文档]

## 体验demo [#体验demo]

下载[app文件](https://github.com/pili-engineering/QAuth_Android/blob/main/app-debug.apk)

## 快速跑通demo [#快速跑通demo]

* 申请七牛一键登录appID
* 修改build.gradle文件下的包名、签名文件、appID、appKey信息
* 运行demo工程

## 本地集成 [#本地集成]

### 导入sdk [#导入sdk]

下载sdk:[QAuth-sdk-x.x.x.aar](https://github.com/pili-engineering/QAuth_Android/tree/main/sdk-aar),导入你的安卓工程

### 权限配置 [#权限配置]

必要权限：

```xml

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"/>
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/>
```

| 权限名称                   | 权限说明           | 使用说明                     |
| ---------------------- | -------------- | ------------------------ |
| INTERNET               | 允许应用程序联网       | 用于访问网关和认证服务器             |
| ACCESS\_WIFI\_STATE    | 允许访问WiFi网络状态信息 | 允许程序访问WiFi网络状态信息         |
| ACCESS\_NETWORK\_STATE | 允许访问网络状态       | 区分移动网络或WiFi网络            |
| CHANGE\_NETWORK\_STATE | 允许改变网络连接状态     | 设备在WiFi跟数据双开时，强行切换使用数据网络 |
| CHANGE\_WIFI\_STATE    | 允许改变WiFi网络连接状态 | 设备在WiFi跟数据双开时，强行切换使用     |

### 配置对http协议的支持 [#配置对http协议的支持]

两种方式（任选其一）：
方式一：在application标签中配置usesCleartextTraffic，示例如下

```xml

<application
    android:name=".view.MyApplication"
    ***
    android:usesCleartextTraffic="true"
    ></application>
```

方式二：将域名10010.com设置为白名单，示例如下

```xml
<application
    android:name=".view.MyApplication"
    ***
    android:networkSecurityConfig="@xml/network_security_config"
    ></application>
```

network\_security\_config.xml文件：

```xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">10010.com</domain>
    </domain-config>
</network-security-config>
```

## 一键登录api [#一键登录api]

### 初始化 [#初始化]

调用SDK其他流程方法前，请确保已调用过初始化，否则会返回未初始化。建议在application.onCeate()中初始化。

示例代码

```java
QAuth.init(this, "your appID", "your appKey")
```

方法原型

```java
/**
 * @param context applicationContext
 * @param appID   七牛一键登录appID
 * @param appKey  七牛一键登录appKey
 */
public static void init(Context context, String appID, String appKey)
```

### 预取号 [#预取号]

获取取号临时凭证；建议在调用拉起授权页前2到3秒调用，可以缩短拉起授权页耗时；如果启动app就需要展示授权页，中间没有2到3秒的间隔，不建议调用，起不到缩短时间的效果。
示例代码

```java
QAuth.preMobile(new QCallback<Void>() {
    @Override
    public void onError(int code, @NonNull String msg) {}

    @Override
    public void onSuccess(@Nullable Void data) {}
});
```

### 拉起授权页&获取token [#拉起授权页获取token]

* 拉起授权页方法将会调起运营商授权页面。已登录状态请勿调用 。
* 每次调用拉起授权页方法前均需先调用授权页配置方法，否则授权页可能会展示异常。
* 必须保证上一次拉起的授权页已经销毁再调用，否则SDK会返回请求频繁。

示例代码

```java
QAuth.openLoginAuth(true, this, new QCallback<String>() {
    @Override
    public void onError(int code, @NonNull String msg) {}
    @Override
    public void onSuccess(@Nullable String data) {}
});
```

方法原型

```java
/**
 * 拉起授权页&获取token
 *
 * @param isDestroyWhenCallback 点击授权页一键登录按钮有回调时是否自动销毁授权页：true：自动销毁,false:不自动销毁，开发者需主动调用销毁授权页方法进行授权页销毁操作
 * @param activity              当前activity
 * @param callback              操作回调
 */
public static void openLoginAuth(Boolean isDestroyWhenCallback, Activity activity, QCallback<String> callback)
```

当callback回调成功会获取到置换手机号所需的token。请参考「服务端」文档来实现获取手机号码的步骤

### 其他api [#其他api]

#### 关闭授权页面 [#关闭授权页面]

```java
QAuth.closeAuthActivity()
```

方法原型

```java
public static void closeAuthActivity()
```

#### 设置协议勾选状态 [#设置协议勾选状态]

需要在授权页activity创建后并且未销毁的情况下调用。

示例代码

```java
QAuth.setPrivacyCheckBoxValue(false)
```

方法原型

```java
public static void setPrivacyCheckBoxValue(boolean state)
```

#### 清理预取号缓存 [#清理预取号缓存]

示例代码

```java
QAuth.clearScripCache(this)
```

方法原型

```java
/**
 * @param context 安卓上下文
 */
public static void clearScripCache(Context context)
```

#### 获取运营商类型 [#获取运营商类型]

示例代码

```kotlin
String operatorType = QAuth.getOperatorType(this)
```

方法原型

```java
/**
 * @param context
 * @return 四种情况：CMCC（移动）；CUCC（联通）；CTCC（电信）； Unknown_Operator（无SIM卡或非三网运营商）
 */
public static String getOperatorType(Context context)
```

#### 设置预取号超时时间 [#设置预取号超时时间]

不建议设置小于4的值，否则可能会导致超时的概率增加。
示例代码

```java
QAuth.setTimeOutForPreLogin(3)
```

方法原型

```java
/**
 * @param timeSecond 秒
 */
public static void setTimeOutForPreLogin(int timeSecond)
```

## 授权页界面配置 [#授权页界面配置]

### 设计规范 [#设计规范]

<img src="/docs-assets/products/qnvs/development_guidelines/12453-anzhuoduan-access-guide/Fq244_6opceLsC1y_nbgyZhfkn9Y-88832e053d18.webp" width="256" height="512" />

<img src="/docs-assets/products/qnvs/development_guidelines/12453-anzhuoduan-access-guide/FlC91DWnuCBhHCsnwxItdRa5A9ib-e7434dbd4484.webp" width="256" height="512" />

<img src="/docs-assets/products/qnvs/development_guidelines/12453-anzhuoduan-access-guide/Fp2OzSxAVW2Tc2IQfeHzxM_-VGLk-93ac3579e588.webp" width="256" height="512" />

<img src="/docs-assets/products/qnvs/development_guidelines/12453-anzhuoduan-access-guide/FkT6qWhEriEMlRvyZwWmlEQqqNf6-f6655a67a2a4.webp" width="512" height="255" />

**注意：开发者不得将授权页面的登录按钮、隐私栏、号码栏内容隐藏、覆盖，对于接入七牛一键登录SDK并上线的应用，我方和运营商会对授权页面做审查，如果有出现未按要求设计授权页面，我方有权将应用的一键登录功能下线。
登录按钮ID：qn\_btn\_one\_key\_login
隐私栏ID：qn\_ll\_privacy、qn\_checkbox\_privacy\_status、qn\_tv\_privacy\_text
号码栏ID：qn\_tv\_per\_code**

### 自定义修改授权页布局修改 [#自定义修改授权页布局修改]

步骤一 、拷贝[qlogin\_activity\_quick\_login.xml](https://github.com/pili-engineering/QAuth_Android/blob/main/app/src/main/res/layout/qlogin_activity_quick_login.xml)并重命名至你的项目res->layout下
按需修改样式
步骤二 、按需设置配置项目

```java
QUIConfig uiConfig = new QUIConfig();

//配置登录页面UI
LoginPage loginPage = new LoginPage();
//授权页面布局文件
loginPage.customLayoutID = R.layout.custom_activity_quick_login;
//提示同意隐私协议的弹窗
loginPage.privacyAlertDialogBuilder = new CustomPrivacyDialogBuilder();
//入场动画
loginPage.actInAnimalResName = "login_demo_bottom_in_anim";
//出场动画
loginPage.actOutAnimalResName = "login_demo_bottom_out_anim";
//状态栏
StatusBarConfig statusBarConfig = new StatusBarConfig();
//状态栏文字模式 白色/黑色
statusBarConfig.isLightColor = true;
//状态栏颜色
statusBarConfig.statusBarColor = Color.parseColor("#FFF15959");
loginPage.statusBarConfig = statusBarConfig;
//自定义勾选隐私协议提示
loginPage.checkTipText = "请勾选隐私协议";
 //使用代码方式配置协议-（也可以在xml配置-代码配置优先级高于xml
loginPage.privacyTextTip = "同意 %s 和 %s 并授权获取本机号码"；
LoginPage loginPage = new LoginPage();
loginPage.privacyList = new ArrayList<>();
loginPage.privacyList.add(new Privacy(
        "《七牛云服务用户协议》",
        Color.parseColor("#FF6200EE"),
        "https://www.qiniu.com/privacy-right"
));
loginPage.privacyList.add(new Privacy(
        "《七牛云服务用户协议》",
        Color.parseColor("#FF6200EE"),
        "https://www.qiniu.com/privacy-right"
));
//设置跳转隐私协议拦截
loginPage.privacyClickListener = (context, url, privacyTittle) -> {
    //返回是否拦截跳转
    return false;
};

//设置登录页面
uiConfig.loginPage = loginPage;

//隐私协议页配置
PrivacyPage privacyPage = new PrivacyPage();
//状态栏
privacyPage.statusBarConfig = statusBarConfig;
//横竖屏
privacyPage.isVerticalActivity = true;
//自定义布局文件
privacyPage.customLayoutID = R.layout.custom_activity_privacy;

//设置协议页面
uiConfig.privacyPage = privacyPage;

QAuth.setUIConfig(uiConfig);
```

### 自定义隐私协议 [#自定义隐私协议]

xml中静态设置如下（也可以在代码中动态设置）

```
<com.qiniu.qlogin_core.view.PrivacyTextView
    android:gravity="center"
    android:id="@+id/qn_tv_privacy_text"
    android:layout_height="wrap_content"
    android:layout_marginStart="5dp"
    android:layout_width="wrap_content"
    android:textColor="#222222"
    android:textSize="11sp"
    app:innerPrivacyColor="#FFF15959"
    app:privacy_color1="@color/purple_500"
    app:privacy_color2="@color/teal_700"
    app:privacy_text1="《七牛云服务用户协议》"
    app:privacy_text2="《隐私权政策》"
    app:privacy_tip="同意 %s %s 和 %s 并授权获取本机号码"
    app:privacy_url1="https://www.qiniu.com/privacy-right"
    app:privacy_url2="https://www.qiniu.com/user-agreement" />
```

配置内置协议的属性和自定义协议的属性，最多支持配置4个自定义协议

| 属性                | 格式     | 描述                         |
| :---------------- | ------ | -------------------------- |
| privacy\_tip      | string | 显示文本，协议名字用%s代替（预留内置一个协议占位） |
| innerPrivacyColor | color  | 内置协议的颜色                    |
| privacy\_text1    | string | 自定义协议1名称                   |
| privacy\_color1   | color  | 自定义协议1颜色                   |
| privacy\_url1     | string | 定义协议1跳转路径                  |
| privacy\_text...  |        |                            |

### 混淆 [#混淆]

aar中自带混淆文件无需配置

### 资源压缩过滤 [#资源压缩过滤]

如果使用AndResGuard资源压缩，需添加过滤，参考demo示例：

```
"R.anim.umcsdk*",
"R.drawable.umcsdk*",
"R.layout.layout_shanyan*",
"R.id.shanyan_view*",
```

如果使用系统shrinkResources true，需要在raw/keep里面配置资源过滤keep.xml：

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools" tools:keep="R.anim.umcsdk*,
    R.drawable.umcsdk*,
    R.layout.layout_shanyan*,
    R.id.shanyan_view*" />
```

## 错误码 [#错误码]

sdk错误码

| **返回码**  | **返回码描述**                              |
| :------- | :------------------------------------- |
| 10001001 | 运营商通道关闭                                |
| 10001002 | 运营商信息获取失败                              |
| 10001003 | 一键登录获取token失败                          |
| 10001007 | 网络请求失败                                 |
| 10001011 | 点击返回，用户取消免密登录                          |
| 10001014 | 未知错误                                   |
| 10001016 | APPID为空                                |
| 10001018 | 无网络（缺少时间参数）                            |
| 10001021 | 运营商信息获取失败（accessToken失效）               |
| 10001023 | 预初始化失败                                 |
| 10001025 | 非联通号段（目前联通号段 46001 46006 46009）针对联通定制版 |
| 10001031 | 请求频繁                                   |
| 10001032 | 账户禁用                                   |
| 20010001 | 用户模块错误码                                |
| 20010002 | SSO 鉴权失败，无效的token                      |
| 20010003 | 获取用户信息失败                               |
| 20010004 | Token 已经过期                             |
| 20020001 | 应用名已经存在                                |
| 20020002 | 应用的包名已经存在                              |
| 20020003 | 应用的bundle 已经存在                         |
| 20020004 | 当前状态无法编辑                               |
| 20020005 | 平台不能修改                                 |
| 20030001 | APP 状态不可用                              |
| 20030002 | 未配置RSA 公钥                              |
| 20030003 | 请求外部系统发生异常                             |
| 20030004 | 外部系统返回失败状态                             |

移动

| 返回码    | 返回码描述                                 |
| ------ | ------------------------------------- |
| 103000 | 成功                                    |
| 102507 | 登录超时（授权页点登录按钮时）                       |
| 103101 | 请求异常                                  |
| 103102 | 包签名错误（社区填写的appid和对应的包名包签名必须一致）        |
| 103111 | 错误的运营商请求（可能是用户正在使用代理或者运营商判断失败导致）      |
| 103119 | appid不存在                              |
| 103211 | 其他错误，联系技术支撑解决问题                       |
| 103412 | 无效的请求（1.加密方式错误；2.非json格式；3.空请求等）      |
| 103414 | 参数校验异常                                |
| 103511 | 服务器ip白名单校验失败                          |
| 103811 | token为空                               |
| 103902 | scrip失效（短时间内重复登录）                     |
| 103911 | token请求过于频繁，10分钟内获取token且未使用的数量不超过30个 |
| 104201 | token已失效或不存在（重复校验或失效）                 |
| 105001 | 联通取号失败                                |
| 105002 | 移动取号失败                                |
| 105003 | 电信取号失败                                |
| 105012 | 不支持电信取号                               |
| 105013 | 不支持联通取号                               |
| 105018 | token权限不足（使用了本机号码校验的token获取号码）        |
| 105019 | 应用未授权（未在开发者社区勾选能力）                    |
| 105021 | 当天已达取号限额                              |
| 105302 | appid不在白名单                            |
| 105312 | 余量不足（体验版到期或套餐用完）                      |
| 105313 | 非法请求                                  |
| 200005 | 用户未授权（READ\_PHONE\_STATE）             |
| 200010 | 无法识别sim卡或没有sim卡（android）              |
| 200015 | 短信验证码格式错误                             |
| 200020 | 用户取消登录                                |
| 200021 | 数据解析异常                                |
| 200022 | 无网络                                   |
| 200023 | 请求超时                                  |
| 200024 | 数据网络切换失败                              |
| 200025 | 未知错误一般出现在线程捕获异常，请配合异常打印分析             |
| 200026 | 输入参数错误                                |
| 200027 | 未开启数据网络或网络不稳定                         |
| 200028 | 网络异常                                  |
| 200038 | 异网取号网络请求失败                            |
| 200039 | 异网取号网关取号失败                            |
| 200040 | UI资源加载异常                              |
| 200048 | 用户未安装sim卡                             |
| 200050 | EOF异常                                 |
| 200060 | 切换账号（未使用SDK短验时返回）                     |
| 200072 | CA根证书校验失败                             |
| 200080 | 本机号码校验仅支持移动手机号                        |
| 200082 | 服务器繁忙                                 |
| 200087 | 授权页成功调起                               |

联通

| **状态码（status）** |       **信息（msg）**       |                                                                                       **示例说明**                                                                                       |
| :-------------: | :---------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|      101001     |       授权码不能为空使用SDK      |                                                                                    调用置换接口时没有填入授权码                                                                                    |
|      101002     |     认证的手机号不能为空使用SDK     |                                                                                  认证置换时没有填入需要认证的手机号码                                                                                  |
|      101003     |         UiConfig        |                                                                                  不能为空调用openActivity                                                                                  |
|      101004     |  ApiKey 或PublicKey 不能为空 |                                                                            未进行初始化，调用SDKManager.init()进行初始化                                                                           |
|      101005     |            超时           |                                                                                      超过了接入方设置的时间                                                                                     |
|      101006     |           公钥出错          |                                                                                公钥错误，请核对配置的公钥是否与申请的公钥一致                                                                               |
|      101007     |          用户取消登录         |                                                                                  免密登录时，进入授权页执行了返回操作                                                                                  |
|      102001     |         选择流量通道失败        |                                               <p>取号功能必须使用流量访问，在wifi 和流量同时开启的情况下，</p><p>sdk 会选择使用流量进行访问，此返回码代表切换失败！（受不</p><p>同机型的影响）</p>                                              |
|      201001     |        操作频繁请稍后再试        |                                                                                 超出10 分钟之内只能访问30 次的限制                                                                                 |
|      302001     |         SDK 解密异常        |                                                                           服务端返回数据时sdk 会进行解密操作，如果解密出错则出现此错误                                                                           |
|      302002     |        网络访问异常sdk        |                                                                                        网络请求异常                                                                                        |
|      302003     |        服务端数据格式出错        |                                                                                      服务端返回数据格式错误                                                                                     |
|      10000      |           请求超时          |                                                                     移动网络复杂，超时时间设置过短时，容易发生超时错误。 建议超时时间设置的长一点，3秒以上。                                                                    |
|      10001      |   获取token失败，请先调用预取号接口   |                                                                                                                                                                                      |
|    ~~10002~~    |       ~~服务响应解析异常~~      |                                                                                 ~~取号服务端返回的数据无法正常解析~~                                                                                 |
|      10003      |        无法切换至数据网络        |                                                                        wifi和蜂窝数据网络都开启的情况下， 无法强制取号请求从蜂窝数据网络发出。                                                                        |
|      10004      |         数据网络未开启         |                                                                                    检测到蜂窝数据网络没有开启。                                                                                    |
|    ~~10005~~    |        ~~网络判断异常~~       |                                                                              ~~在进行网络开通情况判断和切换过程中捕获的异常~~                                                                              |
|      10007      |          预取号过期          |                                                                                       标准UI版本使用                                                                                       |
|    ~~10010~~    | ~~Http状态码是200，302之外的值~~ |                                                                           ~~取号接口只处理200和302状态码，其他都作为失败处理。~~                                                                           |
|      10011      |       Https通讯抛出异常       |                                                                           取号接口用到的HttpsURLConnection通信抛出的异常                                                                           |
|    ~~10012~~    |     ~~200 但body为空~~     |                                                                                                                                                                                      |
|    ~~10013~~    |        ~~跳转地址错误~~       |                                                                                      ~~基本不会发生~~                                                                                      |
|      10021      |          初始化失败          |                                                                                                                                                                                      |
|    ~~10022~~    |       ~~网络请求响应为空~~      |                                                                                                                                                                                      |
|      10024      |        Http通讯抛出异常       |                                                                            取号接口用到的HttpURLConnection通信抛出的异常                                                                           |
|      10025      |      ios sdk用到的部分异常     |                                                                                                                                                                                      |
|      10026      |   ios sdk用到的socket部分错误  |                                                                                                                                                                                      |
|       100       |          应用未授权          |                                                                                                                                                                                      |
|       101       |          应用秘钥错误         |                                                            该应用秘钥即为client\_secret。<br />1. 核对**应用秘钥**是否正确<br />2. 联系客服详细处理                                                            |
|       102       |           应用无效          |                                                                       1. client\_id字段未传<br />2. client\_id字段值错误                                                                      |
|     ~~103~~     |      ~~应用未授权该IP访问~~     |                                                                                                                                                                                      |
|       104       |         应用访问次数不足        |                                                                                                                                                                                      |
|       105       |         应用包名不正确         |                                                                             注册应用时填写的包名与实际包名不符，核对包名报备是否正确                                                                             |
|       106       |          应用状态非法         |                                                                                       应用处于非正常状态                                                                                      |
|       107       |          商户状态非法         |                                                                                       商户处于非正常状态                                                                                      |
|       108       |        商户请求次数超限额        |                                                                                                                                                                                      |
|       200       |        tokenId无效        |                                                                                                                                                                                      |
|       201       |         token已失效        | 登录接口token无效标识。<br />token即预取号获得的accessCode值，默认有效期**30min**且**单次有效**。<br />可能原因如下：<br />1. 已过有效期；<br />2. 已被消费；<br />3. 使用不存在的token；<br />4. 应用标识与token不匹配。例：用应用标识A获取token，而用应用标识B去消费 |
|       202       |      token未授权该应用访问      |                                                                                                                                                                                      |
|       203       |     登录鉴权级别不满足接口鉴权要求     |                                                                                                                                                                                      |
|       300       |          接口未开放          |                                                                                                                                                                                      |
|       301       |        应用未授权访问该接口       |                                                                             client\_id无访问相关接口权限，联系客服详细处理                                                                             |
|       302       |       IP 未授权码访问该接口      |                                                                              核对client\_id所配**公网IP**是否正确                                                                              |
|       303       |       应用访问接口次数超日限额      |                                                                                                                                                                                      |
|       400       |          请求参数为空         |                                                                                                                                                                                      |
|       401       |         请求参数不完整         |                                                                         核对必填参数：<br />1. 是否传值<br />2. 字段名是否正确                                                                         |
|       402       |          请求参数非法         |                                                               1. timeStamp间隔时间太久<br />2. 其他参数传了不可识别的值：请检查请求参数是否与接口文档相符                                                               |
|       600       |           请求非法          |                                                                                                                                                                                      |
|       1000      |          请求解析错误         |                                                                             服务端无法解析请求参数，请检查请求参数是否与接口文档相符                                                                             |
|       1001      |          请求已失效          |                                                                         请求时间戳与中国标准时间间隔太久。<br />处理建议：请使用中国标准时间                                                                        |
|       1002      |           验签失败          |                                                             1. 核对sign生成规则<br />2. 核对调用生成sign的method\<br>3. 核对**公私钥**是否匹配                                                             |
|       1003      |          授权码已过期         | 认证接口token失效标识。<br />token即预取号获得的accessCode值，默认有效期**30min**且**单次有效**。<br />可能原因如下：<br />1. 已过有效期；<br />2. 已被消费；<br />3. 使用不存在的token；<br />4. 应用标识与token不匹配。例：用应用标识A获取token，而用应用标识B去消费 |
|       1004      |         加密方式不支持         |                                                                                                                                                                                      |
|       1005      |         RSA加密错误         |                                                                                                                                                                                      |
|       1010      |         服务间访问失败         |                                                                                                                                                                                      |
|       1011      |         服务间访问错误         |                                                                               系统内部访问，未得到正确结果，联系客服详细处理。                                                                               |
|     ~~2004~~    |        ~~用户不存在~~        |                                                                                                                                                                                      |
|     ~~3002~~    |        ~~跳转异网取号~~       |                                                                                                                                                                                      |
|     ~~3003~~    |   ~~本网执行取号失败,不需要重定向~~   |                                                                                                                                                                                      |
|     ~~3004~~    |       ~~NET取号失败~~       |                                                                                                                                                                                      |
|     ~~3005~~    |    ~~上网方式为WIFI，无法取号~~   |                                                                                                                                                                                      |
|     ~~3006~~    |    ~~urlencode编码失败~~    |                                                                                                                                                                                      |
|     ~~3007~~    |       ~~请求认证接口异常~~      |                                                                                                                                                                                      |
|     ~~3009~~    |        ~~非联通号码~~        |                                                                                                                                                                                      |
|       3010      |          网关取号错误         |                                                                                                                                                                                      |
|       3011      |         源IP鉴权失败         |                                                                 1. 当前非联通数据网络<br />2. APN为3gwap，目前仅支持3gnet\<br>3. 物联网卡                                                                |
|       3012      |          网关取号失败         |                                                                                    服务内部错误，联系客服详细处理                                                                                   |
|       3013      |         电信网关取号失败        |                                                                                                                                                                                      |
|       3014      |         电信网关取号错误        |                                                                                                                                                                                      |
|       3015      |        回调消息缓存已失效        |                                                                                                                                                                                      |
|       3016      |         移动网关取号失败        |                                                                                                                                                                                      |
|       3017      |         移动网关取号错误        |                                                                                                                                                                                      |
|       3018      |         生成授权码失败         |                                                                                                                                                                                      |
|       3032      |         APPID不存在        |                                                                                                                                                                                      |
|       3050      |         取号网关内部错误        |                                                                                                                                                                                      |
|       3051      |         公网IP校验错误        |                                                                 1. 当前非联通数据网络<br />2. APN为3gwap，目前仅支持3gnet\<br>3. 物联网卡                                                                |
|       3052      |       公网IP无法找到对应省份      |                                                                                                                                                                                      |
|     ~~3053~~    |    ~~公网IP省份编码与输入不符~~    |                                                                                                                                                                                      |
|       3054      |         私网IP校验错误        |                                                                                                                                                                                      |
|       3055      |        私网IP查找号码失败       |                                                                                                                                                                                      |
|       3056      |         省份暂不支持取号        |                                                                                                                                                                                      |
|       3057      |       网关鉴权码查找号码失败       |                                                                                                                                                                                      |
|       3058      |        网关鉴权码格式错误        |                                                                                                                                                                                      |
|       3059      |         网关鉴权码已失效        |                                                                                                                                                                                      |
|       3060      |         网关账号认证失败        |                                                                                                                                                                                      |
|       3061      |         网关取号配额不足        |                                                                                                                                                                                      |
|       3062      |        IP未授权访问网关        |                                                                                                                                                                                      |
|       3063      |        网关并发连接数受限        |                                                                                                                                                                                      |
|       3064      |         访问网关参数非法        |                                                                                                                                                                                      |
|       3065      |        未授权访问该网关能力       |                                                                                                                                                                                      |
|       3066      |        网关服务暂时不可用        |                                                                                                                                                                                      |

电信

|   错误码  |                      含义                      |
| :----: | :------------------------------------------: |
|    0   |                     请求成功                     |
|   -64  |           permission-denied(无权限访问)           |
|   -65  | API-request-rates-Exceed-Limitations(调用接口超限) |
| -10001 |                     取号失败                     |
| -10002 |                     参数错误                     |
| -10003 |                     解密失败                     |
| -10004 |                     ip受限                     |
| -10005 |                  异网取号回调参数异常                  |
| -10006 |                Mdn取号失败，且属于电信网络               |
| -10007 |                   重定向到异网取号                   |
| -10008 |                   超过预设取号阈值                   |
| -10009 |                     时间戳过期                    |
| -20005 |              sign-invalid(签名错误）              |
| -20006 |                     应用不存在                    |
| -20007 |                    公钥数据不存在                   |
| -20100 |                    内部解析错误                    |
| -20102 |                   加密参数解析失败                   |
| -30001 |                     时间戳非法                    |
| -30003 |          topClass失效，请查看5.3+5.4常见问题。          |
|  51002 |                     参数为空                     |
|  51114 |                   无法获取手机号数据                  |
|  80000 |                     请求超时                     |
|  80001 |                    请求网络异常                    |
|  80002 |                     响应码错误                    |
|  80003 |                     无网络连接                    |
|  80004 |                    移动网络未开启                   |
|  80005 |                  Socket超时异常                  |
|  80006 |                    域名解析异常                    |
|  80007 |                     IO异常                     |
|  80008 |               No route to host               |
|  80009 | nodename nor servname provided, or not known |
|  80010 |         Socket closed by remote peer         |
|  80100 |                    登录结果为空                    |
|  80101 |                    登录结果异常                    |
|  80102 |                     预登录异常                    |
|  80103 |                    SDK未初始化                   |
|  80104 |                   未调用预登录接口                   |
|  80105 |                   加载nib文件异常                  |
|  80200 |                    用户关闭界面                    |
|  80201 |                    其他登录方式                    |
|  80800 |                   WIFI切换异常                   |
|  80801 |                   WIFI切换超时                   |


# 号码认证业务流程 (/products/qnvs/development_guidelines/12478-a-login-key-business-processes)



最近更新时间: 2023-06-13 17:38:00

# 总体流程 [#总体流程]

您需要在APP中集成七牛的号码认证SDK，并在服务端完成API对接。全流程主要分为以下几个步骤：

* 初始化；
* 预取号；
* 拉取授权页；
* 一键登录；

![一键登录流程-对外.png](/docs-assets/products/qnvs/development_guidelines/12478-a-login-key-business-processes/FphI-spvQdnUfrnJoJ8rvPOjRDnP-4028de70a544.webp)

# SDK初始化 [#sdk初始化]

* 用户打开APP时，应用客户端启动SDK初始化程序。
* SDK 向七牛验证服务，验证应用信息。
* SDK 获取SIM卡中的运营商标示，并根据标示预备展示该运营商授权页。
* 本地初始化完成后SDK将会于运营商建立互通并建立验证通道。

# 预取号（加快授权页拉取） [#预取号加快授权页拉取]

* 应用客户端在SDK初始化成功后，判断用户未登录的情况下。可以在APP后台无感执行预取号方法（已登录的用户不必执行此步骤）。
* SDK 通过SIM卡访问运营商蜂窝移动网，与运营商建立数据交换并获取临时令牌（用于后面步骤中快速拉取授权页）。
* 成功获取到临时令牌；三大运营商临时令牌有效期如下：移动：48小时；联通：1小时；电信：1小时。

# 拉取授权页（唤起免密登录页） [#拉取授权页唤起免密登录页]

* 由用户触发或者APP启动时自动触发的方式执行拉取授权页方法
* 运营商根据来自SIM卡的访问请求识别该数据流量对应的手机号码掩码；运营商加密返回，用于后续请求验证结果使用。
* 终端应用程序获取返回密文并展示运营商授权页，用于用户授权登录注册使用。

# 一键登录（用户触发） [#一键登录用户触发]

* 由用户触发点击一键登录
* 用户发起一键登录授权请求后，SDK后台向运营商发起token请求
* 运营商收到token请求后进行校验，并返回token。
* SDK 返回token 到App客户端

# 置换号码（返回请求结果） [#置换号码返回请求结果]

* App客户端收到token后传递给App服务端，进行登录校验。
* App服务端将token请求至七牛服务器，以请求手机号码。七牛服务器，再将token传递给运营商请求手机号码。
* 七牛服务器，加密手机号码，返回给应用服务器。
* 应用服务器收到解密手机号，根据手机号码执行登录，并返回登录结果给应用客户端。
* 应用客户端展示登录结果。


# iOS使用指南 (/products/qnvs/development_guidelines/12489-ios-guidelines)



最近更新时间: 2023-06-13 17:38:13

# 快速跑通demo [#快速跑通demo]

* clone 七牛号码验证服务 [demo工程](https://github.com/pili-engineering/QAuth_iOS)
* 申请七牛一键登录appID
* 修改demo buildID, AppDelegate 中使用您申请的 appID、appKey
* 运行demo工程

# 本地集成 [#本地集成]

## 导入sdk [#导入sdk]

下载sdk:[framworks](https://github.com/pili-engineering/QAuth_iOS/tree/main/QAuth_iOS/frameworks),导入你的 iOS 工程

其他依赖： QNAuthSDK 内部依赖 CocoaSecurity 加解密
pod 'CocoaSecurity'

# 一键登录api [#一键登录api]

## 初始化 [#初始化]

调用SDK其他流程方法前，请确保已调用过初始化，否则会返回未初始化。建议在application.onCeate() 中初始化。

示例代码

```objective-c
[QNAuthSDKManager initWithAppId:APPID appKey:APPKEY complete:^(QNCompleteResult * _Nonnull completeResult) {
 }];
```

方法原型

```objective-c
/// 初始化
/// @param appId            七牛后台申请的appId
/// @param complete         预初始化回调block（⚠️在子线程中回调）
+ (void)initWithAppId:(NSString *)appId appKey:(NSString *)appKey
             complete:(nullable QNComplete)complete
```

## 预取号 [#预取号]

* **不建议 频繁的多次调用和在拉起授权页后调用**
* **预取号方法回调中处理UI操作需手动切换到主线程**
* **建议在执行一键登录的方法前，提前一段时间调用此方法**（比如调一键登录的 vc 的viewdidload 中，或者 rootVC 的 viewdidload 中，或者 app 启动后，此调用将有助于提高闪验拉起授权页的速度和流畅度）

方法原型

```java
/// 预取号
///此调用将有助于提高七牛拉起授权页的速度和成功率
///建议在一键登录前提前调用此方法，比如调一键登录的vc的viewdidload中
///不建议在拉起授权页后调用
///⚠️‼️以 if (completeResult.error == nil) 为判断成功的依据，而非返回码
/// @param complete         回调block（⚠️在子线程中回调）
+ (void)preGetPhonenumber:(nullable QNComplete)complete
```

当callback回调成功会获取到置换手机号所需的token。请参考「服务端」文档来实现获取手机号码的步骤

**接口作用**

**电信、联通、移动预取号** :初始化成功后，如果当前为电信/联通/移动，将调用预取号，可以提前获知当前用户的手机网络环境是否符合一键登录的使用条件，成功后将得到用于一键登录使用的临时凭证，默认的凭证有效期60min(三大运营商一致)。

## 其他 api [#其他-api]

### 清理预取号缓存 [#清理预取号缓存]

方法原型

```java
/// 清除预取号缓存
+ (void)clearScripCache;
```

### 获取运营商类型 [#获取运营商类型]

方法原型

```java
/// 获取当前流量卡运营商，结果仅供参考（CTCC：电信、CMCC：移动、CUCC：联通、UNKNOW：未知）
+ (NSString *)getOperatorType;
```

### 设置预取号超时时间 [#设置预取号超时时间]

方法原型

```objective-c
///**
// 设置初始化超时 单位:s
// 大于0有效
// 建议4s左右，默认4s
// */
//+ (void)setInitTimeOut:(NSTimeInterval)initTimeOut;

/// 设置预取号超时 单位:s（大于0有效；建议4s左右，默认4s）
/// @param preGetPhoneTimeOut 预取号超时时间
+ (void)setPreGetPhonenumberTimeOut:(NSTimeInterval)preGetPhoneTimeOut;
```

### 拉起授权页 [#拉起授权页]

**在预取号成功后调用**，预取号失败不建议调用。调用拉起授权页方法后将会调起运营商授权页面。该方法会拉起登录界面，&#x2A;*已登录状态请勿调用 。**

```objective-c
/**
 一键登录 区分拉起授权页之前和之后的回调

 @param qnUIConfigure 闪验授权页参数配置
 @param openLoginAuthListener 拉起授权页监听：拉起授权页面成功或失败的回调，拉起成功或失败均触发。当拉起失败时，oneKeyLoginListener不会触发。此回调的内部触发时机是viewDidAppear

 @param oneKeyLoginListener 一键登录监听：拉起授权页成功后的后续操作回调，包括点击SDK内置的(非外部自定义)取消登录按钮，以及点击本机号码一键登录的回调。点击授权页自定义按钮不触发此回调

 * 回调中如需UI操作，建议自行切到主线程
 */
+(void)quickAuthLoginWithConfigure:(QNUIConfigure *)clUIConfigure
             openLoginAuthListener:(QNComplete)openLoginAuthListener
               oneKeyLoginListener:(QNComplete)oneKeyLoginListener;
```

### 关闭授权页面 [#关闭授权页面]

```objective-c
/// 关闭授权页
///注：若授权页未拉起或已经提前关闭，此方法调用无效果，complete不触发。内部实现为调用系统方法dismissViewcontroller:Complete
/// @param flag             dismissViewcontroller`Animated, default is YES.
/// @param completion       dismissViewcontroller`completion（⚠️在子线程中回调）
+ (void)finishAuthControllerAnimated:(BOOL)flag
                          Completion:(void(^_Nullable)(void))completion;
```

# 授权页界面配置，自定义参考 demo ,参考演示有如下： [#授权页界面配置自定义参考-demo-参考演示有如下]

![image\_0.jpeg](/docs-assets/products/qnvs/development_guidelines/12489-ios-guidelines/FjPKuEJUGbDTHjGZxfNct0huBmYn-73973d8b1a61.webp)

![image\_1.PNG](/docs-assets/products/qnvs/development_guidelines/12489-ios-guidelines/Fnnl35wJeKER3gLXgoodjPD5V7jO-00b927d195cc.webp)

![image\_2.PNG](/docs-assets/products/qnvs/development_guidelines/12489-ios-guidelines/Fv6FXmjMpaOGQz2FVWcILfRfP1rr-2b7c310e0d43.webp)

![image\_3.PNG](/docs-assets/products/qnvs/development_guidelines/12489-ios-guidelines/FsU_zbzfuwMmbbCVq2zbDGg0S1_O-20bf2d071f81.webp)

![image\_4.PNG](/docs-assets/products/qnvs/development_guidelines/12489-ios-guidelines/FtMazODmNwSbDDXv1eJ-b5ve5Ssa-99a4d99d1d7a.webp)

![image\_5.PNG](/docs-assets/products/qnvs/development_guidelines/12489-ios-guidelines/FnLfy1Kcu3YKDVFKBs87bsSg8NoE-6882a5a4abd3.webp)

# 错误码 [#错误码]

| sdk 错误码 | 返回码描述                     |
| ------- | ------------------------- |
| 1000    | 一键登录成功，解析result，可得到网络请求参数 |
| 1011    | 用户取消免密登录（点击返回按钮）          |
| 1001    | SDK初始化失败                  |
| 1023    | 预取号/取号失败                  |
| 1003    | 拉起授权页失败/一键登录失败/获取token失败  |
| 1008    | 未开启移动网络                   |
| 1032    | 账户禁用                      |
| 2000    | 本机校验：获取token成功            |
| 2001    | 本机校验：手机号码为空               |
| 2003    | 本机校验：联通获取token失败          |
| 2004    | 本机校验：电信获取token失败          |
| 2005    | 本机校验：移动获取token失败          |
| 2009    | 本机校验：非三大运营商               |
| 2023    | 本机校验：未开启移动网络              |
| 其他      | 其他错误                      |

移动

| 返回码    | 返回码描述                                 |
| ------ | ------------------------------------- |
| 103000 | 成功                                    |
| 102507 | 登录超时（授权页点登录按钮时）                       |
| 103101 | 请求异常                                  |
| 103102 | 包签名错误（社区填写的appid和对应的包名包签名必须一致）        |
| 103111 | 错误的运营商请求（可能是用户正在使用代理或者运营商判断失败导致）      |
| 103119 | appid不存在                              |
| 103211 | 其他错误，联系技术支撑解决问题                       |
| 103412 | 无效的请求（1.加密方式错误；2.非json格式；3.空请求等）      |
| 103414 | 参数校验异常                                |
| 103511 | 服务器ip白名单校验失败                          |
| 103811 | token为空                               |
| 103902 | scrip失效（短时间内重复登录）                     |
| 103911 | token请求过于频繁，10分钟内获取token且未使用的数量不超过30个 |
| 104201 | token已失效或不存在（重复校验或失效）                 |
| 105001 | 联通取号失败                                |
| 105002 | 移动取号失败                                |
| 105003 | 电信取号失败                                |
| 105012 | 不支持电信取号                               |
| 105013 | 不支持联通取号                               |
| 105018 | token权限不足（使用了本机号码校验的token获取号码）        |
| 105019 | 应用未授权（未在开发者社区勾选能力）                    |
| 105021 | 当天已达取号限额                              |
| 105302 | appid不在白名单                            |
| 105312 | 余量不足（体验版到期或套餐用完）                      |
| 105313 | 非法请求                                  |
| 200005 | 用户未授权（READ\_PHONE\_STATE）             |
| 200010 | 无法识别sim卡或没有sim卡（android）              |
| 200015 | 短信验证码格式错误                             |
| 200020 | 用户取消登录                                |
| 200021 | 数据解析异常                                |
| 200022 | 无网络                                   |
| 200023 | 请求超时                                  |
| 200024 | 数据网络切换失败                              |
| 200025 | 未知错误一般出现在线程捕获异常，请配合异常打印分析             |
| 200026 | 输入参数错误                                |
| 200027 | 未开启数据网络或网络不稳定                         |
| 200028 | 网络异常                                  |
| 200038 | 异网取号网络请求失败                            |
| 200039 | 异网取号网关取号失败                            |
| 200040 | UI资源加载异常                              |
| 200048 | 用户未安装sim卡                             |
| 200050 | EOF异常                                 |
| 200060 | 切换账号（未使用SDK短验时返回）                     |
| 200072 | CA根证书校验失败                             |
| 200080 | 本机号码校验仅支持移动手机号                        |
| 200082 | 服务器繁忙                                 |
| 200087 | 授权页成功调起                               |

联通

| **状态码（status）** |       **信息（msg）**       |                                                                                       **示例说明**                                                                                       |
| :-------------: | :---------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|      101001     |       授权码不能为空使用SDK      |                                                                                    调用置换接口时没有填入授权码                                                                                    |
|      101002     |     认证的手机号不能为空使用SDK     |                                                                                  认证置换时没有填入需要认证的手机号码                                                                                  |
|      101003     |         UiConfig        |                                                                                  不能为空调用openActivity                                                                                  |
|      101004     |  ApiKey 或PublicKey 不能为空 |                                                                            未进行初始化，调用SDKManager.init()进行初始化                                                                           |
|      101005     |            超时           |                                                                                      超过了接入方设置的时间                                                                                     |
|      101006     |           公钥出错          |                                                                                公钥错误，请核对配置的公钥是否与申请的公钥一致                                                                               |
|      101007     |          用户取消登录         |                                                                                  免密登录时，进入授权页执行了返回操作                                                                                  |
|      102001     |         选择流量通道失败        |                                               <p>取号功能必须使用流量访问，在wifi 和流量同时开启的情况下，</p><p>sdk 会选择使用流量进行访问，此返回码代表切换失败！（受不</p><p>同机型的影响）</p>                                              |
|      201001     |        操作频繁请稍后再试        |                                                                                 超出10 分钟之内只能访问30 次的限制                                                                                 |
|      302001     |         SDK 解密异常        |                                                                           服务端返回数据时sdk 会进行解密操作，如果解密出错则出现此错误                                                                           |
|      302002     |        网络访问异常sdk        |                                                                                        网络请求异常                                                                                        |
|      302003     |        服务端数据格式出错        |                                                                                      服务端返回数据格式错误                                                                                     |
|      10000      |           请求超时          |                                                                     移动网络复杂，超时时间设置过短时，容易发生超时错误。 建议超时时间设置的长一点，3秒以上。                                                                    |
|      10001      |   获取token失败，请先调用预取号接口   |                                                                                                                                                                                      |
|    ~~10002~~    |       ~~服务响应解析异常~~      |                                                                                 ~~取号服务端返回的数据无法正常解析~~                                                                                 |
|      10003      |        无法切换至数据网络        |                                                                        wifi和蜂窝数据网络都开启的情况下， 无法强制取号请求从蜂窝数据网络发出。                                                                        |
|      10004      |         数据网络未开启         |                                                                                    检测到蜂窝数据网络没有开启。                                                                                    |
|    ~~10005~~    |        ~~网络判断异常~~       |                                                                              ~~在进行网络开通情况判断和切换过程中捕获的异常~~                                                                              |
|      10007      |          预取号过期          |                                                                                       标准UI版本使用                                                                                       |
|    ~~10010~~    | ~~Http状态码是200，302之外的值~~ |                                                                           ~~取号接口只处理200和302状态码，其他都作为失败处理。~~                                                                           |
|      10011      |       Https通讯抛出异常       |                                                                           取号接口用到的HttpsURLConnection通信抛出的异常                                                                           |
|    ~~10012~~    |     ~~200 但body为空~~     |                                                                                                                                                                                      |
|    ~~10013~~    |        ~~跳转地址错误~~       |                                                                                      ~~基本不会发生~~                                                                                      |
|      10021      |          初始化失败          |                                                                                                                                                                                      |
|    ~~10022~~    |       ~~网络请求响应为空~~      |                                                                                                                                                                                      |
|      10024      |        Http通讯抛出异常       |                                                                            取号接口用到的HttpURLConnection通信抛出的异常                                                                           |
|      10025      |      ios sdk用到的部分异常     |                                                                                                                                                                                      |
|      10026      |   ios sdk用到的socket部分错误  |                                                                                                                                                                                      |
|       100       |          应用未授权          |                                                                                                                                                                                      |
|       101       |          应用秘钥错误         |                                                            该应用秘钥即为client\_secret。<br />1. 核对**应用秘钥**是否正确<br />2. 联系客服详细处理                                                            |
|       102       |           应用无效          |                                                                       1. client\_id字段未传<br />2. client\_id字段值错误                                                                      |
|     ~~103~~     |      ~~应用未授权该IP访问~~     |                                                                                                                                                                                      |
|       104       |         应用访问次数不足        |                                                                                                                                                                                      |
|       105       |         应用包名不正确         |                                                                             注册应用时填写的包名与实际包名不符，核对包名报备是否正确                                                                             |
|       106       |          应用状态非法         |                                                                                       应用处于非正常状态                                                                                      |
|       107       |          商户状态非法         |                                                                                       商户处于非正常状态                                                                                      |
|       108       |        商户请求次数超限额        |                                                                                                                                                                                      |
|       200       |        tokenId无效        |                                                                                                                                                                                      |
|       201       |         token已失效        | 登录接口token无效标识。<br />token即预取号获得的accessCode值，默认有效期**30min**且**单次有效**。<br />可能原因如下：<br />1. 已过有效期；<br />2. 已被消费；<br />3. 使用不存在的token；<br />4. 应用标识与token不匹配。例：用应用标识A获取token，而用应用标识B去消费 |
|       202       |      token未授权该应用访问      |                                                                                                                                                                                      |
|       203       |     登录鉴权级别不满足接口鉴权要求     |                                                                                                                                                                                      |
|       300       |          接口未开放          |                                                                                                                                                                                      |
|       301       |        应用未授权访问该接口       |                                                                             client\_id无访问相关接口权限，联系客服详细处理                                                                             |
|       302       |       IP 未授权码访问该接口      |                                                                              核对client\_id所配**公网IP**是否正确                                                                              |
|       303       |       应用访问接口次数超日限额      |                                                                                                                                                                                      |
|       400       |          请求参数为空         |                                                                                                                                                                                      |
|       401       |         请求参数不完整         |                                                                         核对必填参数：<br />1. 是否传值<br />2. 字段名是否正确                                                                         |
|       402       |          请求参数非法         |                                                               1. timeStamp间隔时间太久<br />2. 其他参数传了不可识别的值：请检查请求参数是否与接口文档相符                                                               |
|       600       |           请求非法          |                                                                                                                                                                                      |
|       1000      |          请求解析错误         |                                                                             服务端无法解析请求参数，请检查请求参数是否与接口文档相符                                                                             |
|       1001      |          请求已失效          |                                                                         请求时间戳与中国标准时间间隔太久。<br />处理建议：请使用中国标准时间                                                                        |
|       1002      |           验签失败          |                                                             1. 核对sign生成规则<br />2. 核对调用生成sign的method\<br>3. 核对**公私钥**是否匹配                                                             |
|       1003      |          授权码已过期         | 认证接口token失效标识。<br />token即预取号获得的accessCode值，默认有效期**30min**且**单次有效**。<br />可能原因如下：<br />1. 已过有效期；<br />2. 已被消费；<br />3. 使用不存在的token；<br />4. 应用标识与token不匹配。例：用应用标识A获取token，而用应用标识B去消费 |
|       1004      |         加密方式不支持         |                                                                                                                                                                                      |
|       1005      |         RSA加密错误         |                                                                                                                                                                                      |
|       1010      |         服务间访问失败         |                                                                                                                                                                                      |
|       1011      |         服务间访问错误         |                                                                               系统内部访问，未得到正确结果，联系客服详细处理。                                                                               |
|     ~~2004~~    |        ~~用户不存在~~        |                                                                                                                                                                                      |
|     ~~3002~~    |        ~~跳转异网取号~~       |                                                                                                                                                                                      |
|     ~~3003~~    |   ~~本网执行取号失败,不需要重定向~~   |                                                                                                                                                                                      |
|     ~~3004~~    |       ~~NET取号失败~~       |                                                                                                                                                                                      |
|     ~~3005~~    |    ~~上网方式为WIFI，无法取号~~   |                                                                                                                                                                                      |
|     ~~3006~~    |    ~~urlencode编码失败~~    |                                                                                                                                                                                      |
|     ~~3007~~    |       ~~请求认证接口异常~~      |                                                                                                                                                                                      |
|     ~~3009~~    |        ~~非联通号码~~        |                                                                                                                                                                                      |
|       3010      |          网关取号错误         |                                                                                                                                                                                      |
|       3011      |         源IP鉴权失败         |                                                                 1. 当前非联通数据网络<br />2. APN为3gwap，目前仅支持3gnet\<br>3. 物联网卡                                                                |
|       3012      |          网关取号失败         |                                                                                    服务内部错误，联系客服详细处理                                                                                   |
|       3013      |         电信网关取号失败        |                                                                                                                                                                                      |
|       3014      |         电信网关取号错误        |                                                                                                                                                                                      |
|       3015      |        回调消息缓存已失效        |                                                                                                                                                                                      |
|       3016      |         移动网关取号失败        |                                                                                                                                                                                      |
|       3017      |         移动网关取号错误        |                                                                                                                                                                                      |
|       3018      |         生成授权码失败         |                                                                                                                                                                                      |
|       3032      |         APPID不存在        |                                                                                                                                                                                      |
|       3050      |         取号网关内部错误        |                                                                                                                                                                                      |
|       3051      |         公网IP校验错误        |                                                                 1. 当前非联通数据网络<br />2. APN为3gwap，目前仅支持3gnet\<br>3. 物联网卡                                                                |
|       3052      |       公网IP无法找到对应省份      |                                                                                                                                                                                      |
|     ~~3053~~    |    ~~公网IP省份编码与输入不符~~    |                                                                                                                                                                                      |
|       3054      |         私网IP校验错误        |                                                                                                                                                                                      |
|       3055      |        私网IP查找号码失败       |                                                                                                                                                                                      |
|       3056      |         省份暂不支持取号        |                                                                                                                                                                                      |
|       3057      |       网关鉴权码查找号码失败       |                                                                                                                                                                                      |
|       3058      |        网关鉴权码格式错误        |                                                                                                                                                                                      |
|       3059      |         网关鉴权码已失效        |                                                                                                                                                                                      |
|       3060      |         网关账号认证失败        |                                                                                                                                                                                      |
|       3061      |         网关取号配额不足        |                                                                                                                                                                                      |
|       3062      |        IP未授权访问网关        |                                                                                                                                                                                      |
|       3063      |        网关并发连接数受限        |                                                                                                                                                                                      |
|       3064      |         访问网关参数非法        |                                                                                                                                                                                      |
|       3065      |        未授权访问该网关能力       |                                                                                                                                                                                      |
|       3066      |        网关服务暂时不可用        |                                                                                                                                                                                      |

电信

|   错误码  |                      含义                      |
| :----: | :------------------------------------------: |
|    0   |                     请求成功                     |
|   -64  |           permission-denied(无权限访问)           |
|   -65  | API-request-rates-Exceed-Limitations(调用接口超限) |
| -10001 |                     取号失败                     |
| -10002 |                     参数错误                     |
| -10003 |                     解密失败                     |
| -10004 |                     ip受限                     |
| -10005 |                  异网取号回调参数异常                  |
| -10006 |                Mdn取号失败，且属于电信网络               |
| -10007 |                   重定向到异网取号                   |
| -10008 |                   超过预设取号阈值                   |
| -10009 |                     时间戳过期                    |
| -20005 |              sign-invalid(签名错误）              |
| -20006 |                     应用不存在                    |
| -20007 |                    公钥数据不存在                   |
| -20100 |                    内部解析错误                    |
| -20102 |                   加密参数解析失败                   |
| -30001 |                     时间戳非法                    |
| -30003 |          topClass失效，请查看5.3+5.4常见问题。          |
|  51002 |                     参数为空                     |
|  51114 |                   无法获取手机号数据                  |
|  80000 |                     请求超时                     |
|  80001 |                    请求网络异常                    |
|  80002 |                     响应码错误                    |
|  80003 |                     无网络连接                    |
|  80004 |                    移动网络未开启                   |
|  80005 |                  Socket超时异常                  |
|  80006 |                    域名解析异常                    |
|  80007 |                     IO异常                     |
|  80008 |               No route to host               |
|  80009 | nodename nor servname provided, or not known |
|  80010 |         Socket closed by remote peer         |
|  80100 |                    登录结果为空                    |
|  80101 |                    登录结果异常                    |
|  80102 |                     预登录异常                    |
|  80103 |                    SDK未初始化                   |
|  80104 |                   未调用预登录接口                   |
|  80105 |                   加载nib文件异常                  |
|  80200 |                    用户关闭界面                    |
|  80201 |                    其他登录方式                    |
|  80800 |                   WIFI切换异常                   |
|  80801 |                   WIFI切换超时                   |


# 控制台使用流程 (/products/qnvs/development_guidelines/12490-the-console-using-the-process)



最近更新时间: 2023-06-13 17:39:08

# 总体流程 [#总体流程]

开通七牛云号码认证服务需要执行以下步骤：

* 开通服务
* 创建应用申请
* 概览分析

## 开通服务 [#开通服务]

您需要一个七牛云账号才能使用号码认证服务：

1. 如果还没有账号注册七牛云账号，并按照要求完成\[实名认证]。([https://developer.qiniu.com/af/manual/4057/the-identity-authentication)。](https://developer.qiniu.com/af/manual/4057/the-identity-authentication\)。)
2. 如果您已有实名认证的七牛云账号，请直接进行下一步操作。

访问号码认证控制台，如果是首次使用号码认证服务，需要进行服务开通操作，开通好后即可进入一键认证 dashboard 界面。

![image.png](/docs-assets/products/qnvs/development_guidelines/12490-the-console-using-the-process/FjsEQEeczhH1eLZoCOwEwX-WKoG0-3a0266177c29.webp)

## 创建申请 [#创建申请]

使用该服务前需要进行应用报备，开通服务后进入一键认证服务页面：

![image.png](/docs-assets/products/qnvs/development_guidelines/12490-the-console-using-the-process/FiEeQSyYZIQ2ZbQDPxnOZ2eVkOXW-df7f341878cd.webp)

在应用申请页面点击创建按钮，根据提示依次输入应用信息后，点击提交申请按钮完成：

![image.png](/docs-assets/products/qnvs/development_guidelines/12490-the-console-using-the-process/FsnYmdwJp4xbv385aU_QQcpvId7M-63f55a2087a4.webp)

## 概览分析 [#概览分析]

进入概览分析页面，可以查看本账号下已申请通过的应用的使用情况：

![image.png](/docs-assets/products/qnvs/development_guidelines/12490-the-console-using-the-process/Fl3CZQ3bRCuKRbi_ae9vgkqam69f-00aaf2d4ba83.webp)


# 用户服务协议 (/products/qnvs/development_guidelines/12512-user-agreement)



最近更新时间: 2023-08-07 14:19:02

本协议是上海七牛信息技术有限公司（以下称“七牛云”）与用户（以下称“您”）就您使用七牛云所提供的一键认证SDK服务等相关事宜所签订的具有法律效力的合约。您通过打印件加盖公章并寄回、或在七牛云官方网站相关版面确认，即表示您与七牛云已达成约定，同意接受本协议所列全部条款内容。在签订本协议之前，请您仔细阅读本协议所列全部条款内容。如您对本协议的条款内容有疑问，请联系七牛云商务部门垂询，七牛云将为您解释各项条款内容。如果您不同意本协议的任一条款内容，或者无法准确理解七牛云对相关条款的解释，请勿进行后续操作。您进行后续操作或点击确认即视为您知晓并无条件接受本协议全部条款的约束。

1、术语与定义
1.1 服务：指本协议下七牛云为付费用户提供的七牛一键认证 SDK 服务，未付费用户使用服务不在此服务范围。
1.2 七牛一键认证 SDK： 指本协议下七牛云为您提供的包含一键登录和本机认证服务。一键登录功能支持自动获取手机号码，用户一键通过验证，无需号码手动输入和短信验证。本机认证功能在用户输入手机号码后，自动校验与当前本机卡号的一致性，无需发送短信验证码。

2、服务内容
2.1 七牛云为您提供的可供选购的 SDK。
2.2 七牛云将根据您的选购授权您使用七牛一键认证 SDK 软件，并为您开通所有功能。
2.3 七牛云为您提供的软件使用授权服务均为非独占、无转让许可、非排他之授权。

3、指标项
3.1 服务可用性
七牛云授权用户使用七牛一键认证 SDK 软件，授权版本为用户选购的版本，用户将包名提供给七牛云，七牛云为用户开放对应版本的所有功能。
3.2 故障恢复能力
3.2.1 七牛一键认证 SDK 以在线自助工单系统、客服电话报障方式为用户提供全天候的技术支持服务，如您有任何故障报修需要，均可通过上述方式联系七牛云。
3.2.2 您正常使用 SDK 服务过程中发生的问题、BUG，七牛云将采取优先排期解决的响应机制。
3.2.3 如您需增加新功能或进行版本升级，可通过 3.2.1 条的所列方式联系七牛云。
3.3 客服保证
七牛云将为您提供 7\*24 小时的客户服务，客服咨询电话：400-101-8589。

4、权利义务
4.1 您向七牛云付费成功后，七牛云将根据您的选购版本为您开通相应功能，您享有正常使用七牛一键认证 SDK 开放功能并获得技术支持的权利。
4.2 您可于付费后自行登录七牛云官网，申请发票并填写开票信息。
4.3 除非您与七牛云另行达成协议，您同意不将从七牛云获得的授权软件用于约定产品以外的其他任何产品。
4.4 除非您与七牛云另行达成协议，您确认不将从七牛云获得的 SDK 或其他任何形式的技术资料授权、转让、分享给任何未经七牛云书面同意的第三方。
4.5 您承诺不对授权软件进行任何反向工程、反编译、反汇编、破解，或实施其他行为以试图获得源代码。
4.6 您知晓并确认如您违反了上述第 4.3、4.4 或 4.5 条的约定，七牛云有权要求您承担相应的赔偿责任。

5、不可抗力与免责
5.1 不可抗力事件，是指不能预见、不能避免并不能克服的客观情况，其中包括但不限于，政府行为、自然力、火灾、爆炸、地理变化、风暴、洪水泛滥、地震、潮汐、闪电或战争。鉴于移动互联网所具有之特殊性质，不可抗力事件还应包括黑客攻击、计算机病毒侵入或发作、服务器硬件故障、电信部门技术调整导致之影响、因政府管制而造成网站的暂时性关闭等在内的任何影响网络正常经营之情形。
5.2 受不可抗力事件影响寻求免除本协议项下或本协议任何条款下履行责任的一方应在不可抗力事件发生之后尽快通知另一方，由双方协商相应解决方案。
5.3 您理解并同意，由于七牛云在提供服务过程中需要利用许多非七牛云所能控制的渠道和资源，且提供的服务依赖于互联网的安全稳定性、运营商数据库的真实准确性等因素，七牛云不能保证数据传输绝对实时到达或所提供验证结果的绝对准确性，出现以下情形导致七牛云提供服务瑕疵的，七牛云免责：
5.3.1 由于 iOS、Android 等移动平台的升级导致七牛云未及时进行版本的兼容而引起的；
5.3.2 由于市场上新机型的投放导致的七牛云未及时进行版本的兼容而引起的；
5.3.3 用户的应用程序或数据信息受到黑客攻击而引起的；
5.3.4 用户维护不当或保密不当致使数据、口令、密码等丢失或泄漏所引起的；
5.3.5 用户自行升级操作系统所引起的；
5.3.6 用户的应用程序或安装活动所引起的；
5.3.7 用户的疏忽或由用户授权的操作所引起的；
5.3.8 用户网络速度及互联网稳定性原因引起的；
5.3.9 用户验证的是虚拟卡号引起的；
5.3.10 运营商数据误差，出现串号等情形；
5.3.11 不可抗力以及意外事件引起的；
5.3.12 其他非七牛云原因所造成的不可用。

6、保密条款
6.1 保密信息指由一方向另一方披露的所有技术及非技术信息，包括但不限于： 产品资料，产品计划，价格，财务及营销规划，业务战略，客户信息，客户数据，研发，软件硬件，API 应用数据接口，技术说明，设计，特殊公式，特殊算法等。
6.2 七牛云与您均知晓并确认，对因您选购七牛一键认证 SDK 服务产生的含技术资料在内的任何保密信息均仅用于为履行本协议的目的，任何一方均不以任何付费或免费的方式向第三方进行授权、转让或分享该等信息，除非应司法部门或国家政府部门的要求需进行披露。
6.3 您同意尽最大的努力保护上述保密信息等不被披露。一旦发现有上述保密信息泄露事件，应及时通知七牛云并采取一切合理措施避免或者减轻损害后果的产生。 未经对方同意进行披露的情形下，泄露方应承担由此给保密材料所有方造成的全部损失。

7、争议解决
7.1 本协议的订立、执行和解释及争议的解决均应适用中国法律并受中国法院管辖。
7.2 如双方就本协议内容或其执行发生任何争议，双方应尽量友好协商解决；协商不成时，任何一方均可向上海市浦东新区人民法院提起诉讼。

8、其他
8.1 您知晓七牛云有权随时对协议内容进行修改。如您不同意七牛云对本协议相关内容所做的修改，您有权停止使用七牛一键认证 SDK 服务。 如您继续使用七牛一键认证 SDK 服务，即视为您接受七牛云对本协议相关内容所做的修改。
8.2 如本协议项下七牛一键认证 SDK 服务协议及服务内容等发生变更，七牛云将通过包括但不限于网页公告、站内信、电子邮件、手机短信等方式进行通知；该通知于发送之日视为已送达收件人。
8.3 本协议构成双方对本协议之约定事项及其他有关事宜的完整协议，除本协议规定的之外，未赋予本协议各方其他权利。
8.4 如本协议中的任何协议无论因何种原因完全或部分无效或不具有执行力，本协议的其余部分仍应有效并且有约束力。


# 用户隐私政策 (/products/qnvs/development_guidelines/12514-privacy-right)



最近更新时间: 2023-11-10 21:09:59

引言
上海七牛信息技术有限公司（以下称“七牛”或称“我们”）作为一家专注互联网综合数据服务的公司，一直以来都非常重视数据服务中的个人信息和隐私数据保护。七牛深知个人信息对您的重要性，并会尽全力保护您的个人信息安全可靠。《七牛云一键认证用户隐私政策》（以下简称“本政策”）适用于我们为您提供产品或服务过程中对于您提供的个人信息的处理和保护。
鉴于我们与您是直接合同关系（即您已在七牛平台上（以下简称“本平台”）注册了合法有效的七牛账号且集成了七牛SDK），这不同于我们与您的终端用户的间接关系。故七牛会要求您通过隐私政策或服务协议等适当的方式确保您知悉且同意我们获取和使用您的用户相关信息，以便让七牛可以获取和使用实现相关服务功能所必要的合理信息。
我们希望通过本隐私政策帮助您了解七牛提供服务过程中是如何收集、使用、共享、转让、公开披露、保护您的用户信息，同时向您披露我们收集和使用用户信息的目的、方式、范围，为您提供访问、更新、删除用户信息的方法。&#x2A;*因此，请您仔细阅读并充分理解本隐私政策。作为我们的客户，您利用我们的产品或服务为您的终端用户再行提供服务而收集的信息部分，您应当根据适用的法律法规另行与您的终端用户约定隐私政策，七牛对此不承担任何责任。**
本政策帮助您了解以下内容：
一、我们如何收集和使用您或您的终端用户信息
二、我们如何使用Cookie等同类技术
三、终端用户的授权与同意
四、我们如何共享、转让、公开披露您或您的终端用户信息
五、我们如何存储您或您的终端用户的个人信息
六、我们如何保护您或您终端用户信息
七、您的权利
八、我们如何处理未成年人的个人信息
九、我们如何更新与修改本政策
十、如何联系我们
附录：关键词定义

一、我们如何收集和使用您或您的终端用户信息
我们会遵循正当、合法、必要的原则，出于本政策所述的以下目的，并通常会在征得您同意的情况下收集和使用您在使用本平台过程中主动提供的、因您使用本平台而产生的以及我们从第三方获取的您或您的终端用户信息。
无论基于上述何种场景收集和使用您或您的终端用户信息，我们通常只会在征得您同意的情况下进行，除非在某些情况下，基于法律义务或者可能需要保护您或其他人的重要利益向您或您的终端用户收集信息。

当我们要将信息用于本政策未载明的其他用途时，会事先征求您的同意。
当我们要将基于特定目的收集而来的信息用于其他目的时，会事先征求您的同意。

我们承诺，绝不收集或者要求您提供包括但不限于个人种族、政治倾向、宗教、信仰、个人基因数据或生物特征数据、性取向等个人敏感信息。

(一) 您作为七牛开发者客户（或潜在开发者客户）的个人信息
为实现本平台的基本业务功能，我们可能需要收集、使用您的相关个人信息。以下将详细说明我们的基本业务功能以及为实现该功能所需的个人信息类型，若您拒绝提供，则无法使用本平台的相关产品或服务。

1. 注册、登录
   当您注册七牛账户时，您需要向我们提供您的手机号码，以便我们与您沟通产品使用与费用支付情况。
2. 日志信息
   为保障您的账户安全与系统运行安全，更准确地预防钓鱼网站欺诈，当您在访问和浏览七牛网站时，我们会自动收集您使用七牛产品或服务的详细情况，并作为网络日志进行保存，以判断您的账户风险，保障七牛为您正常提供服务，统计流量，排查异常信息以及检测、预防和调查欺诈、滥用或安全事件。
3. 创建应用
   需要提供您的产品信息，包括但不限于应用名称、包名等；如果包含Android服务，需要提供您的应用签名。

(二) 您的终端用户信息

1. 为实现本平台的基本业务功能，我们可能需要收集、使用您终端用户的相关个人信息。
   以下将详细列出我们的基本业务功能及为实现该功能所必需的信息类型，这些个人信息的收集、使用仅会在您确认已获得了终端用户同意的前提下进行：
   （1）七牛一键认证SDK整合了三大运营商的号码认证能力，为APP开发者提供了一键登录及快速验证用户输入的手机号码和本机流量卡号一致性的服务,使用当前服务这一过程中收集和使用的信息名称、目的以及范围如下：

![image.png](/docs-assets/products/qnvs/development_guidelines/12514-privacy-right/FlIBlZIqVqGGIBcQ6yWN2m_TVOXB-ac337c6709f6.webp)

2. 一键认证SDK认证服务集成第三方SDK信息及说明
   为了更好的实现认证服务，我们集成了合作方的服务能力，该服务会另有单独的协议、相关业务规则等（以下统称为“单独协议”）。单独协议也是不可分割的组成部分，您同样应当遵守。您对以下单独协议、相关业务规则的接受，即视为您对本协议全部的接受。
   ![企业微信截图\_d9119e80-7c2d-4193-a2b5-af963783ffb6.png](/docs-assets/products/qnvs/development_guidelines/12514-privacy-right/Fp3Rq2xmYn8v0yrR1d7PyBENN8Bp-315b68008729.webp)

提请您注意并知悉，七牛SDK为实现上述业务功能，收集您终端用户“设备信息”、“网络信息”或“位置信息”的前提是，终端用户授权同意开启“读写SD卡权限”、“网络访问权限”、“设备信息权限”或“位置权限”。如果您的终端用户不想被收集上述信息，可以通过关闭“读写SD卡权限”、“网络访问权限”、“设备信息权限”或“位置权限”实现。
请您理解，由于商业策略的变化，本平台上的产品或服务的功能也可能进行更迭和发展。
(三) 我们从第三方获取的您的个人信息

1. 我们可能会在您的授权同意范围内从第三方（我们的合作方）处收集并使用您的个人信息。我们保证严格依照与第三方签订的合同以及相关法律规定处理您的个人信息，同时请您详细阅读该第三方的隐私政策及用户协议。如您拒绝第三方在提供服务时收集、使用或者传递您的个人信息，将可能导致您无法使用七牛相应的服务。
2. 我们可能通过网页等公开途径获得、适当使用有关您的公开信息，或者从第三方提供商处获取有关您企业已经对外公示的经营性信息，以帮助我们更好地了解我们的客户群，例如您的行业、您企业的规模和您企业的网站URL。
   (四) 征得授权同意的例外
   请您理解，在下列情形中，根据法律法规及相关国家标准，我们收集和使用您或您终端用户的个人信息无需征得您或您的终端用户的授权同意：
   A.与公共安全、公共卫生、重大公共利益直接相关的；
   B.出于维护您或其他个人的生命、财产等重大合法权益但又很难得到本人同意的；
   C.所收集的您或您的终端用户的个人信息是您自行向社会公众公开的；
   D.从合法公开披露的信息中收集的您或您的终端用户的个人信息的，如合法的新闻报道、政府信息公开等渠道；
   E.根据您的要求签订或履行合同所必需的；
   F.用于维护软件及相关服务的安全稳定运行所必需的，例如发现、处置软件及相关服务的故障；
   G.法律法规规定的其他情形。
   特别提示您注意，如信息无法单独或结合其他信息识别到您或您终端用户的个人身份，其不属于法律意义上您或您终端用户的个人信息；当您或您终端用户的相关信息可以单独或结合其他信息识别到您或您终端用户的个人身份时，或者我们将无法与任何特定个人信息建立联系的数据与其他您或您终端用户的个人信息结合使用时，这些信息在结合使用期间，将作为您或您终端用户的个人信息按照本政策处理与保护。

二、我们如何使用Cookie等同类技术
为确保网站正常运转，我们会在您的计算机或移动设备上存储名为Cookie 的小数据文件。Cookie 通常包含标识符、站点名称以及一些号码和字符。借助于Cookie，网站能够存储您的偏好或所选择的商品或者服务等数据。
我们不会将Cookie用于本政策所述目的之外的任何用途。您可根据自己的偏好管理或删除Cookie。您可以清除计算机上保存的所有Cookie，大部分网络浏览器都设有阻止Cookie的功能。但如果您这么做，则需要在每一次访问我们的网站时亲自更改用户设置，且您可能因为该等修改，无法登录或使用依赖于Cookie的七牛提供的服务或功能。除Cookie 外，我们向您发送的电子邮件可能含有链接至我们网站内容的点击URL。如果您点击该链接，我们则会跟踪此次点击，帮助我们了解您的产品或服务偏好并改善客户服务。

三、终端用户的授权与同意
您作为我们的业务合作伙伴十分清楚，为给您或您的终端用户提供您所选择的七牛服务，我们会以去标识化或匿名化方式收集、存储、加工来自于您的应用程序的终端用户的个人信息。因此，您接受本政策并把我们的SDK、API或其他统计分析工具、开发者工具集成到您的产品中，则表示您确认并保证：

1. 您已经告知终端用户并且获得终端用户充分、必要且明确的授权、同意和许可，为提供服务之目的允许我们收集和使用其信息；
2. 除非适用法律另有规定，您已经告知终端用户并且获得终端用户充分必要的授权、同意和许可，允许我们对已收集的个人信息进行去标识化处理，允许我们在符合相关法律法规的前提下可将收集、处理的信息用于本政策第一条列明的服务用途；
3. 您已经遵守并将持续遵守适用的法律、法规和监管要求，包括但不限于制定和公布有关个人信息保护和隐私保护的相关政策；
4. 您已经向终端用户提供易于操作的用户权利实现机制，说明用户如何以及何时可以行使选择权、如何访问、更正其个人信息、行使删除权、更改其授权同意的范围等操作。
   5.您已经向终端用户进行披露和说明，允许我们对已收集的数据进行的去标识化和聚合性的处理后，并构建七牛数据库，用以提供数据服务，但您同时应向终端用户提供易于操作的选择机制，说明用户如何以及何时可以行使选择权，并说明行使选择权后如何以及何时可以修改或撤回该选择，使得用户可以选择同意或不同意为商业目的而收集和使用其个人信息的去标识化数据。

如因您违反上述承诺导致您的终端用户对我们主张任何形式的索赔或权利要求，或导致我们被卷入到法律或行政程序，您将负责全面解决，并赔偿我们因此可能遭受的任何形式的损失。

四、我们如何共享、转让、公开披露您的终端用户的个人信息
(一) 共享
我们不会与七牛以外的任何公司、组织和个人共享您的用户信息，但以下情况除外：

1. 在获得您的明确同意后，我们会与其他方共享。
2. 我们可能会根据法律法规的规定，或按照政府主管部门的强制性要求，对外共享您的个人信息。
3. 与授权伙伴共享。我们可能聘请受信赖的第三方供应商、顾问或其他服务商（简称“合作伙伴”）为我们提供必要的维护、支持和服务，以提供更好的客户服务和优化用户体验。目前，我们的授权合作伙伴包含三大运营商（电信、联通、移动）、广告主、广告联盟、媒体或者其他经营者。我们会将数据平台处理、加工后的去标识数据用于商业化使用。在对数据进行处理、加工过程中，我们会严格遵守法律法规的要求，采取相应的安全保护措施来保护您的用户信息。我们仅会出于合法、正当、必要、特定、明确的目的共享信息，并且只会共享提供服务所必要的信息。
   对获得个人信息主体的授权同意后我们与之共享的个人信息的公司、组织和个人，我们会与其签署严格的保密协定，要求他们按照我们的说明、本隐私政策列明的目的或用途，以及保密和安全措施来处理共享信息。

(二) 转让
我们不会将您或您的终端用户的信息转让给任何公司、组织和个人，但以下情况除外：

1. 获得您的明确同意后；
2. 在涉及合并、收购或破产清算时，如涉及到个人信息转让，我们会要求新的持有您个人信息的公司、组织继续受本声明的约束。如果本声明中约定的个人信息的收集、处理方式发生任何改变，该公司、组织将重新向您征求授权同意。

(三) 公开披露
我们仅会在以下情况公开披露您的用户信息：
1.获得您的明确同意后；
2.基于法律法规、法律程序、诉讼或政府主管部门强制性要求的情况下，我们可能会公开披露；
3.在紧急情况下，经合理判断是为了保护我们、我们的代理人、客户、终端用户和其他人的合法权益和安全的；
4.我们为维护自己或其他用户的合法权益而向用户提起诉讼或者仲裁的。

（四）共享、转让、公开披露信息时事先征得授权同意的例外
请您理解，根据法律法规，以下情形中，我们共享、转让、公开披露您的信息无需征得您的授权同意：
1、出于维护您或其他个人的生命、财产等重大合法权益但又很难得到本人同意的；
2、您自行向社会公众公开的信息；
3、从合法公开披露的信息中收集的，如合法的新闻报道、政府信息公开等渠道；
4、为订立、履行个人作为一方当事人的合同所必需，或者按照依法制定的劳动规章制度和依法签订的集体合同实施人力资源管理所必需；
5、为履行法定职责或者法定义务所必需；
6、为公共利益实施新闻报道、舆论监督等行为，在合理的范围内处理个人信息；
7、法律法规规定的其他情形。

五、我们如何存储您的终端用户信息
(一) 存储地点
原则上，我们仅收集在中华人民共和国境内产生的个人信息，并且将收集到的个人信息存储在中华人民共和国境内。若您使用我们的产品或服务，应用于中华人民共和国大陆以外的地区，您应当遵守《中华人民共和国个人信息保护法》关于个人信息跨境传输的有关规定，并符合当地有关数据跨境传输转移的法律法规和监管要求。
本服务在除中国外的任何其他国家/地区不可用。
(二) 存储期限
我们仅出于本政策所述目的和法律法规规定的最短期限存储您或最终用户的个人信息，在超出存储期限后，我们会对您的个人信息进行删除或匿名化处理。但是为了遵守相应的法律法规，出于诉讼抗辩、维护公共利益、保护个人财产安全或合法权利的目的以及您和您的用户另行授权同意的情形下，我们可能会延长您或您的最终用户的个人信息存储期限。

六、我们如何保护您的用户信息

1. 在互联网上没有任何传输方法，或电子存储方法是百分之百安全的，尽管我们已经尽到合理努力，但仍有可能被盗、非法拥有或者滥用而给您和您的用户带来人身、财产和声誉等方面损失的危险。您已了解上述风险并自愿承担。我们已使用符合业界标准的安全防护措施保护您提供的信息，防止数据遭到未经授权访问、泄露、滥用、篡改、损坏或丢失。我们会采取一切合理可行的措施，保护您或您的终端用户数据安全。例如，在您的浏览器与“服务”之间交换数据时受 SSL 加密保护；我们同时对qiniu.com 网站提供 https 安全浏览方式；我们会使用加密技术确保数据的保密性；我们会使用受信赖的保护机制防止数据遭到恶意攻击；我们会部署访问控制机制，确保只有授权人员才可访问个人信息；以及我们会定期举办安全和隐私保护培训课程，加强员工对于保护个人信息重要性的认识。
2. 我们已经取得了以下认证：《ISO 27001信息安全管理体系认证》、《ISO9001质量管理体系认证证书》等。
3. 我们会采取一切合理可行的措施，确保未收集无关的个人信息。我们只会在达成本隐私政策所述目的所需的期限内保留您或您的终端用户的信息，除非需要延长保留期或受到法律的允许。
4. 互联网并非绝对安全的环境，而且电子邮件、即时通讯、及与其他用户的交流方式并未加密，我们强烈建议您不要通过此类方式发送个人信息。请使用复杂密码并定期修改密码，协助我们保证您的账号安全。
5. 互联网环境并非百分之百安全，我们将尽力确保或担保您发送给我们的任何信息的安全性。尽管我们已经尽到必要且合理的努力，但仍有可能被盗、被非法拥占有或者滥用而给您和您的用户带来人身、财产和声誉等方面损失的危险。您已了解上述风险并自愿承担。
6. 若我们采取必要合理的安全保护措施后，仍不幸发生个人信息安全事件的，我们将按照法律法规的要求，及时向您告知：安全事件的基本情况和可能的影响、我们已采取或将要采取的处置措施、您可自主防范和降低风险的建议、对您的补救措施等。我们将及时将事件相关情况以邮件、推送通知等方式告知您，难以逐一告知个人信息主体时，我们会采取合理、有效的方式发布公告。
7. 同时，我们还将按照监管部门要求，主动上报个人信息安全事件的处置情况。

七、您的权利
我们非常重视您或您的终端用户对个人信息的管理，并尽全力保护您对个人信息的查询、访问、修改、删除、投诉举报以及设置隐私功能的相关权利，以保障您或您的终端用户的隐私和信息安全。
(一) 针对七牛的直接用户

1. 查询、更改您的个人信息
   您有权访问您的个人信息，法律法规规定的例外情况除外。如果您想行使数据访问权，譬如您希望访问或编辑您的账户中的企业/个人资料信息和支付信息、更改您的密码、添加安全信息等，您可以通过访问账户设置执行此类操作。
   在访问相关信息时，我们可能会要求您进行身份验证，以保障账户安全。
   请您理解，由于技术所限、基于法律法规要求，您的某些请求可能无法进行响应。基于法律法规要求、保障信息安全等正当事由，您的部分信息可能无法访问。我们将努力使您能够访问、更正和补充您的信息，但是也请您理解，在您执行某项操作时，我们可能会要求您提供足够的信息使我们能够验证您的身份，以确保请求人是所请求信息主体本人或合法授权人。对于您补充提供的信息，我们将按照本隐私政策列明的目的、方式、保密和安全措施进行处理。
2. 删除信息
   在以下任一情形中，您可以通过发送电子邮件至[bd@qiniu.com](mailto:bd@qiniu.com)联系客服，请求删除您提供的个人信息：
   1\)我们违反法律法规规定，收集、使用个人信息的；
   2\)我们违反了与您的约定，收集、使用个人信息的；
   3\)我们违反法律法规规定或违反与您的约定向第三方共享、转让个人信息，我们将立即停止共享、转让的行为，并通知第三方及时删除；
   4\)我们违反法律法规规定或与您的约定，公开披露个人信息，我们将立即停止公开披露的行为，并发布通知要求相关接收方删除相应的信息；
   5）我们的处理目的已实现、无法实现或者为实现处理目的不再必要；
   6）我们停止提供产品或者服务，或者我们的保存期限已届满；
   7）您撤回同意，不再允许我们处理您的个人信息。

在删除相关信息时，我们可能会要求您进行身份验证，以保障账户安全。以上删除请求一旦被响应，除法律法规另有规定要求保留的信息外，您的个人信息将被删除。

当您从我们的服务中删除信息后，因为适用的法律法规和安全技术，我们可能不会立即从备份系统中删除相应的信息，我们将安全存储您的信息直到备份可以清除或实现匿名化，在此期间我们将采取必要的安全保护措施保护您信息的安全。
3\. 改变您授权同意的范围
每个业务功能往往需要收集一些基本的个人信息才能得以运营，对于您个人信息的收集和使用，您可以发送电子邮件至[bd@qiniu.com](mailto:bd@qiniu.com).联系我们要求撤回同意。
当您撤回同意后，我们后续将不再收集和使用您相应的个人信息，但请您理解，当您撤回同意或授权后，我们无法继续为您提供撤回同意或授权所对应的特定功能或服务。您撤回同意的决定，不会影响此前基于您的授权而开展的个人信息处理。
4\. 注销账户
您随时可以注销此前注册的账户，您可以通过发送电子邮件至[bd@qiniu.com](mailto:bd@qiniu.com)联系客服。您应该知道，注销您的七牛账户将导致您永久失去对账户和账户中数据的访问权。我们将在验证您的身份并与您协商处理完您账户中的资产后，为您提供账户注销服务。为了向您提供更加便捷的注销方式，我们后续会不断优化我们的产品，并且通过页面公告向您告知。在注销七牛账户后，我们将停止为您提供产品或服务，并依据您的要求，尽快删除您的个人信息或将其作匿名化处理，法律法规另有规定的除外。
5\. 获得个人信息副本
您有权获取您的个人信息副本，您可以随时发送电子邮件至[bd@qiniu.com](mailto:bd@qiniu.com)联系客服。在技术可行的前提下，例如数据接口匹配，我们还可按您的要求，直接将您的个人信息副本传输给您指定的第三方。
6\. 拒绝定向推送
您可以按照这些电子邮件中的取消订阅/退出说明选择不接收来自七牛的促销电子邮件。您也可以通过发送电子邮件至[bd@qiniu.com](mailto:bd@qiniu.com)联系客服来选择退出。请注意，即使您选择退出促销通信，我们仍可能向您发送与我们的服务条款或隐私通知更新、安全警报以及与您访问或使用我们的产品和服务有关的其他通知等相关的非促销信息。
7\. 响应您的上述请求
为保障安全，我们可能会要求先验证您的身份，再处理您的请求。您可能需要提供书面请求，或以其他方式证明您的身份。对于您提出的本节项下的所有请求，我们原则上将于收到您的请求并在验证您用户身份后的15日内进行反馈。

(二) 如果您是使用七牛产品或服务的应用程序的终端用户，而不是七牛的直接客户，我们建议您：

1. 及时提供您合法途径获得的您独立的权利要求证明文件，我们可能会要求您进行身份验证，在向您的应用程序提供商核实并且需要保障客户账户安全的情况下，我们会响应您的相关请求；或
2. 根据应用程序提供商的隐私政策，请将与您个人信息相关的请求直接发送给相关应用程序提供商处理和寻求帮助。

(三) 对于您或您的终端用户的上述的合理请求，我们原则上不收取费用。对于那些无端重复、需要过多技术手段（例如，需要开发新系统或从根本上改变现行惯例）、给他人合法权益带来风险或者非常不切实际（例如，涉及备份磁带上存放的信息）的请求，我们可能会予以拒绝。
在以下情形中，我们将无法响应您或您的终端用户的请求：
（1）与我们履行法律法规规定的义务相关的；
（2）与公共安全、公共卫生、重大公共利益直接相关的；
（3）我们有充分证据表明您存在主观恶意或滥用权利的；
（4）出于维护您或其他个人的生命、财产等重大合法权益但又很难得到本人同意的；
（5）响应您的请求将导致您或其他个人、组织的合法权益受到严重损害的；
（6）涉及商业秘密的；
（7）法律法规规定的其他情形。

(四) 如您或您的终端用户对上述权利实现存在疑问，可以根据本政策第十条所述方式中的相关联系方式与我们取得联系。

八、我们如何处理未成年人的个人信息
我们原则上不接受未成年人注册登记成为我们的用户，并且我们原则上不接受您提供14周岁以下终端用户的个人信息，请您注意并谨慎提供。尽管各地法律和习俗对未成年人的定义不同，但我们将不满 14 周岁的任何人均视为未成年人。如果我们在不知情的情况下向不满 14 周岁的未成年人收集了个人信息，我们将及时删除相关资料，除非法律要求我们保留此类资料。
如果您认为我们错误或意外地向不满14周岁的未成年人收集了信息，请及时联系我们。
如果您的应用是针对不满14周岁的未成年人而设计和开发的，请您制定专门的个人信息处理规则，请务必确保您的终端用户为监护人，已经阅读并同意应用程序的隐私政策，授权同意提供未成年人个人信息给我们以实现应用的相关功能。您还需要严格遵守《中华人民共和国个人信息保护法》、《儿童个人信息网络保护规定》及其他有关未成年人个人信息保护的相关法律法规、政策、标准和指南的要求。

对于经父母或监护人同意而处理未成年人个人信息的情况，我们只会在得到法律法规允许、父母或监护人明确同意或者保护未成年人所必要的情况下处理此信息，否则我们会设法尽快删除相关数据。

鉴于现有技术和业务模式的限制，我们很难主动识别未成年人的个人信息，如果您发现我们在不知情的情况下或在未事先获得可证实的父母或监护人同意的情况下处理了未成年人的个人信息，您可以及时联系我们，我们将在发现后设法及时删除，如果我们自己发现前述情形的，我们也会及时删除，法律法规要求我们保留的除外。

九、我们如何更新与修改本政策
为了给您提供更好的服务，本平台及相关服务将不时更新与变化，我们会适时对本政策进行修订，这些修订构成本政策的一部分并具有等同于本政策的效力，未经您明确同意，我们不会削减您或您的终端用户按照本隐私政策所应享有的权利。
本政策更新后，我们会在官方网站上发出更新版本，并在更新后的条款生效前通过适当的方式提醒您更新的内容，以便您及时了解本政策的最新版本。
对于重大变更，我们还会提供更为显著的通知（包括对于某些服务，我们会通过电子邮件或站内信形式或公告形式发送通知，说明隐私政策的具体变更内容）。因此，请随时查看和了解您应遵守的隐私政策。如果您不同意接受本隐私政策，请停止访问和使用我们的服务。
本政策所指的重大变更包括但不限于：

1. 我们的服务模式发生重大变化。如处理个人信息的目的、处理的个人信息类型、个人信息的使用方式等；
2. 个人信息共享、转让或公开披露的主要对象发生变化；
3. 您参与个人信息处理方面的权利及其行使方式发生重大变化；
4. 我们负责处理个人信息安全的责任部门、联络方式及投诉渠道发生变化时；
   除此之外，我们还会将本政策的旧版本存档，供您查阅。
   本政策未明确授予的权利由七牛及其关联公司保留。

十、如何联系我们
如您对本政策有任何疑问、意见、建议或需要申诉，您可以通过如下方式与我们取得联系：

1. 提交工单；
2. 拨打我们的客服热线400-101-8589；
3. 发送邮件至[legal@qiniu.com](mailto:legal@qiniu.com)；
4. 信件寄至：中国上海市浦东新区浦东软件园Q座七牛云客服中心（收）邮编：201203.
   为保障我们高效处理您的问题并及时向您反馈，我们可能需要您提交身份证明、有效联系方式和书面请求及相关证据，我们将在验证请求人身份后尽快审核所涉问题，并于十五个工作日内予以回复。

附录：关键词定义
本政策中使用的特定词语，具有如下含义：

1. 我们或七牛：指上海七牛信息技术有限公司
2. 关联公司：是指与上海七牛信息技术有限公司合并报表范围内的下属公司或其他关联企业。上述公司中任何一方现在或将来控制、受控制或与其处于共同控制下。
3. 控制：是指直接或间接地拥有影响所提及公司管理的能力，无论是通过所有权、有投票权的股份、合同或其他被依法认定的方式。
4. 您：指使用我们的产品或服务的注册用户以及收费服务的购买方。
5. 您的终端用户：指七牛平台产品或服务的应用程序的终端用户。
6. 七牛或本平台：指七牛平台。
7. 个人信息：指以电子或者其他方式记录的能够单独或者与其他信息结合识别特定自然人身份或者反映特定自然人活动情况的各种信息。个人信息包括个人基本信息、个人身份信息、个人生物识别信息、网络身份标识信息、个人健康生理信息、个人教育工作信息、个人财产信息、个人通信信息、联系人信息、个人上网记录、个人常用设备信息、个人位置信息等。为免疑义，个人信息包括但不限于个人敏感信息。
8. 个人信息主体：指个人信息所标识的自然人。
9. 个人敏感信息：指一旦泄露、非法提供或滥用可能危害人身和财产安全，极易导致个人名誉、身心健康受到损害或歧视性待遇等的个人信息。个人敏感信息包括个人财产信息、个人健康生理信息、个人生物识别信息、个人身份信息、网络身份标识信息等。
10. 设备信息：设备标识符（IMEI、Android ID、MAC、OAID等相关信息）、应用信息（应用崩溃信息、通知开关状态、软件列表等相关信息）、设备参数及系统信息（设备类型、设备型号、操作系统及硬件相关信息）
11. 网络信息：IP地址，WiFi信息，基站信息等相关信息。
12. 去标识化：指通过对个人信息的技术处理，使其在不借助额外信息的情况下，无法识别个人信息主体的过程。
13. 匿名化：指通过对个人信息的技术处理，使得个人信息主体无法被识别，且处理后的信息不能被复原的过程。
14. 中国或中国境内：指中华人民共和国大陆地区，仅为本政策之目的，不包含香港特别行政区、澳门特别行政区和台湾地区。


# 资源池、地域和可用区 (/products/qvm/0-region-zone)



最近更新时间: 2026-05-06 15:55:40

<a id="region" />

# **什么是资源池、地域和可用区？** [#什么是资源池地域和可用区]

资源池包含了不同的地域和可用区。
地域和可用区指的云主机QVM 所在数据中心的位置，您可以在特定的区域、可用区创建资源。

**资源池：** 不同的资源池提供了不同的产品服务，七牛云有两大资源池，资源池一和资源池三的产品与服务&#x2A;*完全隔离，互不相通。**
&#x2A;*地域：** 从地理位置和网络时延维度划分，&#x2A;*同一个资源池的同一地域内网互通。**
&#x2A;*可用区：** 可用区是指在同一地域内，电力和网络互相独立的物理区域。**同一地域内的可用区与可用区之间内网互通**，可用区之间能做到故障容错。例如：当你的应用需要较高的容灾能力时，QVM 实例最好部署在同一地域的不同可用区内；当你的应用在实例之间需要较低的网络延迟时，QVM 实例最好部署在同一可用区内。

> 注意：
>
> 1. 实例创建成功后不能更换资源池、地域和可用区。
> 2. 不同资源池资源完全隔离，如上海1和上海3是两个地域。

# **资源池、地域、可用区关联图** [#资源池地域可用区关联图]

资源池一和资源池三的产品与服务&#x2A;*完全隔离，互不相通。**，以上海、杭州为例，关联关系如下图：

![](/docs-assets/products/qvm/%281-product-introduction%29/0-region-zone/FieTFORcqz5B4a0Ua_IcH9wffkJk-162df300103d.webp)

# **资源池和服务** [#资源池和服务]

| 产品与服务           | 资源池一 | 资源池三 |
| --------------- | ---- | ---- |
| 云主机             | ✔    | ✔    |
| 云硬盘             | ✔    | ✔    |
| 镜像服务            | ✔    | ✔    |
| 弹性公网IP          | ✔    | ✔    |
| 负载均衡            | ✔    | ✖    |
| 弹性伸缩            | ✔    | ✖    |
| NAT网关           | ✔    | ✖    |
| VPN网关           | ✔    | ✖    |
| 共享带宽            | ✔    | ✖    |
| 云企业网            | ✔    | ✖    |
| IPv6网关          | ✔    | ✖    |
| 云数据库 MySQL      | ✔    | ✖    |
| 云数据库 SQL Server | ✔    | ✖    |
| 云数据库 PostgreSQL | ✔    | ✖    |
| 云数据库 PolarDB    | ✔    | ✖    |
| 云数据库 Redis      | ✔    | ✖    |
| 云数据库 MongoDB    | ✔    | ✖    |
| Web应用防火墙        | ✔    | ✖    |
| BGP 高防 IP       | ✔    | ✖    |

# **资源池一地域** [#资源池一地域]

| 大区   | 地域    | Region ID      |
| ---- | ----- | -------------- |
| 华北   | 青岛1   | cn-qingdao     |
| 华北   | 北京1   | cn-beijing     |
| 华北   | 张家口1  | cn-zhangjiakou |
| 华北   | 呼和浩特1 | cn-huhehaote   |
| 华北   | 乌兰察布1 | cn-wulanchabu  |
| 华东   | 杭州1   | cn-hangzhou    |
| 华东   | 上海1   | cn-shanghai    |
| 华南   | 深圳1   | cn-shenzhen    |
| 西北   | 成都1   | cn-chengdu     |
| 香港   | 香港1   | cn-hongkong    |
| 亚太东南 | 新加坡1  | ap-southeast-1 |
| 亚太东南 | 吉隆坡1  | ap-southeast-3 |
| 亚太东南 | 雅加达1  | ap-southeast-5 |
| 亚太东南 | 东京1   |                |
| 亚太南部 | 东京1   | ap-northeast-1 |
| 中东东部 | 迪拜1   | me-east-1      |
| 美国东部 | 弗吉尼亚1 | us-east-1      |
| 美国西部 | 硅谷1   | us-west-1      |
| 欧洲中部 | 法兰克福1 | eu-central-1   |

# **资源池三地域** [#资源池三地域]

| 大区 | 地域  | Region ID        |
| -- | --- | ---------------- |
| 华北 | 北京3 | grand-cn-north-4 |
| 华东 | 上海3 | grand-cn-east-3  |
| 华南 | 广州3 | grand-cn-south-1 |


# 产品介绍 (/products/qvm/1-qvm-overview)



最近更新时间: 2026-08-27 14:30:58

<a id="step01" />

# **什么是云主机 QVM** [#什么是云主机-qvm]

七牛云主机（Qiniu Virtual Machine，QVM）是七牛面向用户提供的可弹性伸缩的计算服务，帮助你在短时间内快速启动任意数量的云主机并即时部署应用程序。

通过 QVM 云主机服务，你只需要根据业务发展需要创建相应规模的虚拟机实例、云硬盘和网络服务，再也无需提前采购相关资源，缩短了业务部署上线的周期，同时大大降低了企业的运维成本。在使用过程中，随着访问量和负载等需求变化，你可以随时地调整 CPU、内存、硬盘、网络、安全等等。

<br />

<a id="step02" />

# **基本功能** [#基本功能]

* **实例管理：** 实例经过启动或创建进入运行中的状态，运行中的实例执行重启关机等操作切换到其他状态。通过管理控制台可以轻松便捷的管理实例。在 QVM 中，实例包括按量计费和包年包月两种计费模式

* **镜像配置：** 镜像是实例运行环境的模板，一般包括操作系统和预装的软件。镜像和云主机实例可以互相转换。通过实例可以创建自定义镜像，自定义镜像保证减少重复劳动。用户在创建云主机时需要为云主机选择一个镜像，用户可以选择七牛 QVM 云平台默认提供的公共镜像，或者选择自定义镜像快照。公共镜像为用户提供了标准操作系统和必要的基础软件设施；自定义镜像为用户自定义的软件和数据环境，方便反复多次使用。

* **规格配置：** 你在创建云主机的时候需要为云主机选择特定的规格配置，这里主要包括 CPU 核数和内存大小；CPU 核数决定了云主机计算能力的强弱，内存大小决定了云主机暂存程序和数据的多少。QVM 云主机为你提供了多种规格的 CPU 核数和内存大小，方便你根据实际的业务需要进行选择。

* **云硬盘配置：** 云硬盘是云主机存储数据和程序的载体，创建云主机会默认提供一个系统盘用于存放操作系统必要的数据。你如需更多的存储空间，可以通过为云主机添加云磁盘的方式扩展，挂载的云磁盘可以在云主机详情中的磁盘选项中查看。

* **网络配置：** QVM 云平台默认为你提供一个专业网络，提供更安全稳定的独享网络。相同网络下的云主机可以通过内网地址相互访问。

<br />

<a id="step05" />

# 产品定价和地域 [#产品定价和地域]

云主机 QVM 支持预付费和后付费等多种计费模式。关于计费方式的说明及计费项信息，请参见[计费说明](/products/qvm/0-qvm-billing-contrast)。
云主机 QVM 按照不同的规格类型分为不同的规格族，关于规格族信息，请参见[实例规格族](/products/qvm/cloud-server/instances/0-qvm-instance-family)。
云主机 QVM 不同的区域提供的实例以及产品资源也不同，关于地域与资源的关系，请参见[地域与可用区](/products/qvm/0-region-zone)。

# **相关概念** [#相关概念]

使用云主机时，你通常会看到以下一些概念：

* **[实例](/products/qvm/cloud-server/instances/1-qvm-instance-overview)：** 云上的虚拟计算环境

* **[实例规格](/products/qvm/cloud-server/instances/0-qvm-instance-family)：** 实例的不同配置，包括 vCPU 核数、内存、网络性能等。实例规格决定了 QVM 实例的计算和存储能力。

* **[镜像](/products/qvm/cloud-server/images/0-qvm-mirror-overview)：** 创建云主机的基础操作系统模版，包含服务器的预配置环境（操作系统和其他已安装的软件）

* **[快照](/products/qvm/snapshot)：** 是指某一个时间点上一个块存储的数据备份。

* **[云硬盘](/products/qvm/cloud-server/cloud-disk/1-qvm-storage-overview#step01)：** 云主机可挂载并可用作持久化存储的块设备

* **[专有网络](/products/qvm/network/qvm-vpc)：** 自定义的虚拟网络空间，与其他资源逻辑隔离。

* **IP 地址：** 包括用于内网通信的私有 IP，以及用于访问 Internet 的公网 IP。

* **[弹性公网 IP](/products/qvm/0-region-zone)：** 可以与实例反复绑定或解绑的静态公网IP地址。

* **[安全组](/products/qvm/cloud-server/security-groups/0-summary-of-the-security-group)：** 由同一地域内具有相同保护需求并相互信任的实例组成，是一种虚拟防火墙，用于设置不同实例的网络访问控制。

* **登录方式：** 安全性高的[ SSH 密钥对登录](/products/qvm/cloud-server/instances/qvm-linux-login)和普通密码的[密码登录](/products/qvm/cloud-server/instances/qvm-linux-login)。

* **[地域与可用区](/products/qvm/0-region-zone)：** QVM 服务部署的数据中心

* **[云主机管理控制台](https://portal.qiniu.com/qvm/vm/instance)：** 是指 QVM 的 Web 操作界面

<br />

<a id="step06" />

# **相关服务** [#相关服务]

* 你可以对多台云主机 QVM 进行流量分发的负载均衡服务。更多信息，请参考[负载均衡产品文档](/products/qvm/section-ie86go/5-slb-introduction)。

* 你可以在云上部署关系数据库，也可以使用七牛云云数据库。更多信息，请参考[云数据库 MySQL](/products/qvm/cloud-database/cloud-database-rds/cloud-database-rds/mysql/1-mysql-introduction)。

* 你可以在云上部署 Redis 数据库，也可以使用七牛云云数据库 Redis。更多信息，请参考[云数据库 Redis](/products/qvm/cloud-database/cloud-database-rds/redis/0-qvm-redis-introduction)。


# 产品优势 (/products/qvm/2-qvm-features)



最近更新时间: 2021-03-15 11:07:11

# **高可用性** [#高可用性]

相较于普通的 IDC 机房以及服务器厂商，QVM 会使用更严格的 IDC 标准、服务器准入标准以及运维标准，以保证云计算整个基础框架的高可用性、数据的可靠性以及云服务器的高可用性。

在此基础之上，QVM 所提供的每个地域都存在多可用区。当你需要更高的可用性时，可以利用 QVM 的多可用区搭建自己的主备服务或者双活服务。对于面向金融领域的两地三中心的解决方案，你也可以通过多地域和多可用区搭建出更高的可用性服务，其中包括容灾、备份等服务。

此外，QVM 为你提供了如下三项支持：

* 提升可用性的产品和服务，包括云服务器、负载均衡、多备份数据库服务等。
* 行业合作伙伴以及生态合作伙伴，帮助你完成更高、更稳定的架构，并且保证服务的永续性。
* 多种多样的培训服务，让你从业务端到底层的基础服务端，在整条链路上实现高可用。

<br />

# **安全性** [#安全性]

选择了云计算，最关心的问题就是云计算的安全与稳定。QVM 提供专有网络。

* 在专有网络之上，可以产生更多的业务可能性。你只需进行简单配置，就可在自己的业务环境下，与全球所有机房进行串接，从而提高了业务的灵活性、稳定性以及业务的可发展性。

* 对于原来拥有自建的 IDC 机房，也不会产生问题。QVM 专有网络可以拉专线到原有的 IDC 机房，形成混合云的架构。QVM 可以提非常多的网络产品，形成强大的网络功能，让你的业务更加灵活。

* QVM 专有网络更加稳定和安全。

\*\*稳定性：\*\*业务搭建在专有网络上，而网络的基础设施将会不停进化，使你每天都拥有更新的网络架构以及更新的网络功能，使得你的业务永远保持在一个稳定的状态。专有网络允许你自由地分割、配置和管理自己的网络。

\*\*安全性：\*\*面对互联网上不断的攻击流量，专有网络天然就具备流量隔离以及攻击隔离的功能。业务搭建在专有网络上后，专有网络会为业务筑起第一道防线。

总之，专有网络提供了稳定、安全、快速交付、自主可控的网络环境。对于传统行业以及未接触到云计算的行业和企业而言，借助专有网络混合云的能力和混合云的架构，你们将享受云计算所带来的技术红利。

<br />

# **弹性** [#弹性]

云计算最大的优势就在于弹性。QVM 能够保证大部分企业在云上所构建的业务都能够承受巨大的业务量压力。

**计算弹性**

* 纵向的弹性，即单个服务器的配置变更。传统 IDC 模式下，很难做到对单个服务器进行变更配置。而对于 QVM，当你购买了云服务器或者存储的容量后，可以根据业务量的增长或者减少自由变更自己的配置。关于纵向弹性的具体应用，详情请参考[升降配](xxxx)。

* 横向的弹性。对于游戏应用或直播平台出现的高峰期，若在传统的 IDC 模式下，你根本无法立即准备资源；而云计算却可以使用弹性的方式帮助你度过这样的高峰。当业务高峰消失时，你可以将多余的资源释放掉，以减少业务成本的开支。

**存储弹性**

当存储量增多时，对于传统的 IDC 方案，你只能不断去增加服务器，而这样扩展的服务器数量是有限的。在云计算模式下，将为你提供海量的存储，当你需要时可以直接购买，为存储提供最大保障。关于存储弹性的具体应用，详情请参考[磁盘扩容](/products/qvm/cloud-server/cloud-disk/0-qvm-disk#6)。

**网络弹性**

云上的网络也具有非常大的灵活性。只要你购买了专有网络，那么所有的网络配置与线下 IDC 机房配置可以是完全相同的，并且可以拥有更多的可能性。可以实现各个机房之间的互联互通，各个机房之间的安全域隔离，对于专有网络内所有的网络配置和规划都会非常灵活。关于网络弹性的具体应用，详情请参考[专有网络](/products/qvm/network/0-qvm-netsec-overview#2)。

总之，对于 QVM 的弹性而言，是计算的弹性、存储的弹性、网络的弹性以及你对于业务架构重新规划的弹性。你可以使用任意方式去组合自己的业务，QVM 都能够满足你的需求。


# 应用场景 (/products/qvm/3-qvm-scenarios)



最近更新时间: 2021-03-15 11:07:11

云服务器 QVM  应用非常广泛，既可以作为简单的 Web 服务器单独使用，也可以与其他七牛云产品（如 Kodo、CDN 等）搭配提供强大的多媒体解决方案。以下是云服务器 QVM 的典型应用场景。

<br />

<a id="step01" />

## **企业官网、简单的 Web 应用** [#企业官网简单的-web-应用]

云服务器 QVM 与对象存储搭配，对象存储承载静态图片、视频或者下载包，进而降低存储费用。同时配合内容分发网络CDN和负载均衡SLB，可大幅减少用户访问等待时间、降低网络带宽费用以及提高可用性。

<br />

<a id="step02" />

## **多媒体、大流量的 app 或网站** [#多媒体大流量的-app-或网站]

云服务器 QVM 与对象存储 Kodo 搭配，将 Kodo 作为静态图片、视频、下载包的存储，以降低存储费用，同时配合 CDN 和负载均衡 ，可大幅减少用户访问等待时间、降低带宽费用、提高可用性。

<br />

<a id="step03" />

## **数据库** [#数据库]

支持对 I/O 要求较高的数据库。使用较高配置的 I/O 优化型云服务器 QVM，同时采用 SSD 云盘，可实现支持高 I/O 并发和更高的数据可靠性。也可以采用多台稍微低配的 I/O 优化型 QVM 服务器，搭配负载均衡，实现高可用架构。

<br />

<a id="step04" />

## **访问量波动大的 app 或网站** [#访问量波动大的-app-或网站]

某些应用，如抢红包应用、优惠券发放应用、电商网站和票务网站，访问量可能会在短时间内产生巨大的波动。您可以配合使用弹性伸缩，自动化实现在请求高峰来临前增加 QVM 实例，并在进入请求低谷时减少 QVM 实例。满足访问量达到峰值时对资源的要求，同时降低了成本。如果搭配负载均衡SLB，您还可以实现高可用应用架构。


# 配额管理 (/products/qvm/4-quota-management)



最近更新时间: 2026-05-06 16:07:55

七牛云为个人认证和企业认证用户提供不同的资源配额，当配额不足时，需提升资源配额才能成功购买。

您可以通过联系您的商务经理或[提交工单](https://support.qiniu.com/tickets/new/form?category=%E5%85%B6%E4%BB%96%E7%B1%BB%E5%92%A8%E8%AF%A2\&space=%E4%BA%91%E4%B8%BB%E6%9C%BA)提升配额。

# 企业认证配额 [#企业认证配额]

![](/docs-assets/products/qvm/%281-product-introduction%29/4-quota-management/FiT0C81yL1q7ELRfZ4O1lZAFE9Ny-64b3761dec05.webp)

配额详情信息如上图所示，其中，关键资源配额如下：

| 付费类型 | 资源     | 配额    |
| ---- | ------ | ----- |
| 按量付费 | 主机数    | 10个   |
| 按量付费 | CPU(核) | 40    |
| 按量付费 | 内存(GB) | 32    |
| 按量付费 | IP 个数  | 10 个  |
| 按量付费 | IP 带宽  | 200M  |
| 包年包月 | 主机数    | 100 个 |
| 包年包月 | IP 个数  | 40    |

# 个人认证配额 [#个人认证配额]

![](/docs-assets/products/qvm/%281-product-introduction%29/4-quota-management/Fi9Y9qMCFSwZmU6XuaxnKWTlYXjD-525f843c5649.webp)

配额详情信息如上图所示，其中，关键资源配额如下：

| 付费类型 | 资源     | 配额   |
| ---- | ------ | ---- |
| 按量付费 | 主机数    | 5个   |
| 按量付费 | CPU(核) | 20   |
| 按量付费 | 内存(GB) | 20   |
| 按量付费 | IP 个数  | 5 个  |
| 按量付费 | IP 带宽  | 50M  |
| 包年包月 | 主机数    | 50 个 |
| 包年包月 | IP 个数  | 20   |


# 云主机 (/products/qvm/0-qvm-instance-faq)



最近更新时间: 2026-05-07 15:19:37

instance faq


# 云主机迁移 FAQ (/products/qvm/1-cloud-host-migration-faq)



最近更新时间: 2021-04-07 15:49:16

# QSMC是否支持断点续传？ [#qsmc是否支持断点续传]

支持。数据传输中断后，重新运行客户端并重新启动迁移任务即可继续迁移。

# 迁移中断或提示失败时，如何处理？ [#迁移中断或提示失败时如何处理]

迁移任务中断或失败时，处理方式如下：

* 当 QSMC 客户端程序异常退出或者迁移进度卡顿时，可以尝试重新运行SMC客户端并重启迁移任务以恢复迁移。
* 如果迁移任务状态为出错，您可以在 QSMC 控制台查看迁移任务的日志文件，定位错误原因。
* 如还有问题，请提交工单。

# 中转实例的规格有哪些？ [#中转实例的规格有哪些]

QSMC会按下列顺序，根据库存情况，依次选择符合条件的突发型t5、突发型t6 实例规格来创建中转实例。

* 1 vCPU 2 GiB
* 1 vCPU 4 GiB
* 2 vCPU 2 GiB
* 2 vCPU 4 GiB
* 2 vCPU 8 GiB
  如果以上实例规格均库存不足时，系统会选择其他性能和价格兼顾的实例规格。

# 关于中转实例，我需要注意什么？ [#关于中转实例我需要注意什么]

有关中转实例的注意事项如下：

* QSMC自动创建、启动、停止和释放中转实例No\_Delete\_SMC\_Transition\_Instance。为保证顺利完成迁移任务，请勿干预中转实例的运行状态。
* 中转实例的默认安全组在入方向开放了8080和8703端口，这是中转实例的迁移服务端口，请勿修改或删除该安全组配置。
* 迁移任务完成后，中转实例会被自动释放，如果迁移失败，需要手动释放实例。

# 误释放了中转实例怎么办？ [#误释放了中转实例怎么办]

如果误清理了中转资源，您可以删除当前的迁移任务，重新为迁移源新建并启动迁移任务。

# 我的待迁移服务器需要在出方向访问哪些公网地址和端口？ [#我的待迁移服务器需要在出方向访问哪些公网地址和端口]

确认源服务器能访问以下服务地址和端口。

* 服务器迁移中心SMC：[https://smc.aliyuncs.com443端口。](https://smc.aliyuncs.com443端口。)

* 中转实例：公网IP地址8080和8703端口。当您使用内网传输的网络模式时，需访问私有IP地址。

* 如何安装Rsync？
  请您根据源服务器的操作系统选择相应的命令安装Rsync。

* CentOS：运行yum -y install rsync。

* Ubuntu：运行apt-get -y install rsync。

* Debian：运行apt-get -y install rsync。

* SUSE：运行zypper install rsync。
  其他发行平台系统：参见发行版官网的安装文档。

# 我想要重新导入迁移源，怎么办？ [#我想要重新导入迁移源怎么办]

您需要先删除迁移源后，再重新运行客户端导入迁移源。若迁移源已和迁移任务关联，请先删除与之关联的迁移任务，再删除迁移源。

# 迁移任务多久过期？过期后会怎样？ [#迁移任务多久过期过期后会怎样]

通过 QSMC 控制台创建迁移任务时，由于控制台不提供过期时间的设置方式，因此任务的默认有效期为30天


# 计费说明 (/products/qvm/0-qvm-billing-contrast)



最近更新时间: 2022-07-01 09:12:09

# **计费模式** [#计费模式]

| 计费模式      | 释义                                                                                                         |
| --------- | ---------------------------------------------------------------------------------------------------------- |
| 预付费（包年包月） | 即先付费再使用，按月计费。计费周期以一个整点为一个结算周期（均以 UTC+8 时间为准），计费周期从创建开始付费，到释放结束付费，整点结算完进入新的结算周期。                            |
| 后付费（按量付费） | 即先使用再付费，按小时计费。按量付费ECS资源每一个小时整点结算一次费用（以UTC+8时间为准），不足一小时按照一小时计费，结算完毕后进入新的结算周期。若在一个结算周期内调整了实例配置，将会按费用最高的配置计费。 |

# **按量付费云主机停机不收费模式** [#按量付费云主机停机不收费模式]

## 1.前提条件 [#1前提条件]

（1）网络类型为专有网络。
（2）计费方式为按量付费。
（3）实例规格族不包含本地存储，例如大数据型、本地SSD型等。
（4）实例规格族不包含持久内存，例如re6p、re6p-redis。

## 2.支持停机不收费的 QVM 资源 [#2支持停机不收费的-qvm-资源]

计算资源（vCPU和内存）

## 3.触发效果 [#3触发效果]

触发节省停机效果后，计算资源（vCPU和内存）被回收，不再产生费用，但存在以下风险。
（1）由于计算资源（vCPU和内存）被回收，再次启动实例时可能因为库存不足导致启动失败。您可以稍后尝试再次启动，或者尝试变配换用其它实例规格。
（2）有些场景下可能需要短时间内再次启动实例，建议您不启用停机不收费模式，保证可以成功启动实例并投入生产使用。例如：

* 更换系统盘
* 使用快照回滚云盘
* 重新初始化系统盘

# **资源升级询价规则** [#资源升级询价规则]

## 1. 按量资源 [#1-按量资源]

按量资源的升级价格和购买新配置的价格一致，不计算差价，只返回指定配置的价格。

## 2. 包年包月资源 [#2-包年包月资源]

包年包月资源的升级价格 = 剩余时间新配置B的购买价格 - 剩余时间旧配置A的购买价格 = (新配置B的折扣月价 - 旧配置A的折扣月价) \* (剩余月数 + 剩余天数/30)，0 \<= 剩余天数 \< 30

上述公式的折扣月价计算逻辑如下表所示。

| 剩余时长的月数(30天/月) | 单月价格                      |
| -------------- | ------------------------- |
| 12月及以上         | n/12的年购买价格/n, 其中n/12取整数部分 |
| 12月以下          | 月价                        |

<br />

**注: 重置系统盘时的扩容也属于升级。**

# **查看价格** [#查看价格]

云主机服务各项产品价格明细，可直接点击下方按钮进入**价格计算器**查看。

<div>
  <a type="button" class="btn btn-primary" href="https://www.qiniu.com/calculator_qvm">
    查看云主机价格明细
  </a>

  <br />
</div>

# **计费项总览** [#计费项总览]

| 资源类型         | 计费模式                | 类别                                             | 描述                                                                                                                                                                                                                                        |
| ------------ | ------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 实例           | 包年包月（预付费）；按量付费（后付费） | X86 实例集群；GPU 实例集群                              | 费用：实例规格 vCPU 和内存                                                                                                                                                                                                                          |
| 镜像           | 包年包月（预付费）；按量付费（后付费） | 公共镜像；私有镜像；自定义镜像                                | 公共镜像：Windows Server 港澳台 / 海外镜像收费，其他类型镜像及地域免费；私有镜像和自定义镜像：按照该地域的快照规格收费，参考 [快照收费标准](/products/qvm/cloud-server/snapshots/0-the-snapshot-charge-standard)。                                                                                    |
| 块存储          | 包年包月（预付费）；按量付费（后付费） | 高效云盘；SSD 云盘；ESSD 云盘；本地盘                        | 云盘：收取云盘容量费用，可以用作系统盘和数据盘；本地盘：此处本地盘指与特定实例规格绑定的本地盘，不支持单独购买，且费用计入实例规格；；说明：单独购买磁盘只支持按量付费模式                                                                                                                                                     |
| 快照           | 按量付费（后付费）           | 无                                              | 收取快照容量/时长费用，参考 [快照收费标准](/products/qvm/cloud-server/snapshots/0-the-snapshot-charge-standard)。                                                                                                                                             |
| 弹性公网 IP      | 包年包月（预付费）           | 按固定带宽计费                                        | EIP 实例的费用：带宽单价（元/月） x 购买时长                                                                                                                                                                                                                |
| 弹性公网 IP      | 按量付费（后付费)           | 按固定带宽计费                                        | EIP 实例的费用： 带宽/流量费 + 配置费；带宽/流量费: 根据 EIP 带宽/流量计费；配置费：按小时计费                                                                                                                                                                                  |
| 弹性公网 IP      | 按量付费（后付费)           | 按使用流量计费                                        | EIP 实例的费用： 带宽/流量费 + 配置费；带宽/流量费: 根据 EIP 带宽/流量计费；配置费：按小时计费                                                                                                                                                                                  |
| NAT 网关       | 按量付费（后付费）           | 小型；中型；大型；超大型                                   | 费用 = NAT 网关实例费 + 弹性公网 IP 费                                                                                                                                                                                                                |
| VPN 网关       | 包年包月（预付费）           | 只开启 IPsec-VPN 功能；                              | VPN网关费用 =（IPsec-VPN 实例费+带宽费）x 购买时长                                                                                                                                                                                                        |
| VPN 网关       | 包年包月（预付费）           | 只开启 SSL-VPN 功能；                                | VPN网关费用 =（SSL-VPN 实例费 + 带宽费 + SSL 规格费）x 购买时长                                                                                                                                                                                              |
| VPN 网关       | 包年包月（预付费）           | 同时开启 IPsec-VPN 和 SSL-VPN 功能；                   | VPN网关费用 =（IPsec-VPN 实例费+ SSL-VPN 实例费 + 带宽费+ SSL 规格费）x 购买时长                                                                                                                                                                                |
| 共享带宽         | 包年包月（预付费）；按量付费（后付费） | 按固定带宽计费                                        | 费用 = 按带宽计费 x 时长                                                                                                                                                                                                                           |
| 云企业网         | 包年包月（预付费）           | 带宽包费用；；说明：跨地域才需带宽包                             | 费用 = 带宽包大小（元/月）x 购买时长                                                                                                                                                                                                                     |
| 负载均衡         | 包年包月（预付费）；按量付费（后付费） | 规格费用                                           | 费用 = 所选规格费单价（元/月）x 购买时长                                                                                                                                                                                                                   |
| 弹性伸缩         | 免费                  | 免费                                             | 开通弹性伸缩服务免费，弹性伸缩下的实例收费                                                                                                                                                                                                                     |
| RDS 云数据库     | 包年包月（预付费）；按量付费（后付费） | 实例                                             | RDS 实例规格的费用。计费方式为包年包月或按量付费。                                                                                                                                                                                                               |
| RDS 云数据库     | 包年包月（预付费）；按量付费（后付费） | 存储空间                                           | RDS 实例存储空间的费用。计费方式为包年包月或按量付费，与实例的计费方式一致                                                                                                                                                                                                   |
| RDS 云数据库     | 按量付费（后付费）           | 只读实例（可选）                                       | RDS 只读实例规格的费用。按量付费，费用取决于扣费时的只读实例规格                                                                                                                                                                                                        |
| RDS 云数据库     | 按量付费（后付费）           | 备份空间（可选）；；说明：超出免费备份空间的部分需按量付费。                 | 备份文件占用空间的费用；；备份空间的免费额度 = 50% \* 实例购买的存储空间。                                                                                                                                                                                                |
| RDS 云数据库     | 按量付费（后付费）           | 公网流量（可选）                                       | 申请外网地址后并使用外网地址连接 RDS，会产生外网流量。                                                                                                                                                                                                             |
| MongoDB 云数据库 | 包年包月（预付费）；按量付费（后付费） | 副本集实例                                          | 规格费用：根据实例规格和购买时长产生费用；磁盘空间费用：MongoDB 实例存储空间的费用。计费方式为包年包月或按量付费，与实例的计费方式一致                                                                                                                                                                   |
| MongoDB 云数据库 | 包年包月（预付费）；按量付费（后付费） | 分片集群实例                                         | 集群版本组成 = mongos + shard + configserver；；集群版本费用 = mongos 规格费用 + shard（规格和磁盘空间费用） + configserve（规格和磁盘空间费用）；；说明：；1. shard 和 configserver 组件磁盘空间按量付费价格 0.0047 元 / G；2. shard 组件磁盘空间为 10 - 2000 G,步长 10 G 递增。；3. configserver 组件配置为 20 G，不可修改。 |
| MongoDB 云数据库 | 包年包月（预付费）；按量付费（后付费） | 备份                                             | 根据备份存储量收取备份费用，并提供一定免费额度（云盘实例：备份存储使用量超过实例存储空间的200%时开始按量计费。本地盘实例：备份存储使用量超过实例存储空间的50%时开始按量计费。）；；说明：；国内：物理备份（本地盘）按量付费 ¥0.024/GB/天；快照（云盘）按量付费￥0.006/GB/天；香港及海外：物理备份（本地盘）按量付费 ¥0.0288/GB/天；快照（云盘）按量付费￥0.0072/GB/天                               |
| BGP 高防 IP    | 包年包月（预付费）           | 保底防护带宽                                         | 根据带宽规格和购买时长产生费用                                                                                                                                                                                                                           |
| BGP 高防 IP    | 按量付费（后付费）           | 弹性防护带宽                                         | 弹性防护免费开启，未发生弹性防护不收费。发生弹性防护后，取当天弹性防护峰值按区间单独按天结算。                                                                                                                                                                                           |
| BGP 高防 IP    | 按量付费（后付费）           | 转发规则数                                          | 默认免费为每个高防 IP 提供 60 个转发规则数                                                                                                                                                                                                                 |
| BGP 高防 IP    | 按量付费（后付费）           | 转发带宽；；说明：清洗后转发回源站的业务流量所用的带宽                    | 默认免费支持 100M 业务带宽                                                                                                                                                                                                                          |
| 新 BGP 高防 IP  | 包年包月（预付费）           | 保底防护带宽                                         | 根据带宽规格和购买时长产生费用                                                                                                                                                                                                                           |
| 新 BGP 高防 IP  | 按量付费（后付费）           | 弹性防护带宽                                         | 弹性防护免费开启，未发生弹性防护不收费。发生弹性防护后，取当天弹性防护峰值按区间单独按天结算                                                                                                                                                                                            |
| 新 BGP 高防 IP  | 包年包月（预付费）           | 防护域名数；；说明：实例支持添加的 HTTP/HTTPS 域名数量              | 默认 50 个，增加数量计费参考如下：；；标准功能套餐：每 10 个域名 285 元/月；增强功能套餐：每 10 个域名 475 元/月                                                                                                                                                                      |
| 新 BGP 高防 IP  | 包年包月（预付费）           | 防护端口数；；说明：实例支持添加的 TCP/UDP 端口数量                 | 默认 50 个，增加数量计费每 10 个端口：475 元 / 月                                                                                                                                                                                                          |
| 新 BGP 高防 IP  | 包年包月（预付费）           | 业务带宽；；说明：实例支持处理的无攻击情况下最大业务流量                   | 默认 100 Mb，增加每 1 Mb ：95 元 / 月                                                                                                                                                                                                              |
| 新 BGP 高防 IP  | 包年包月（预付费）           | 业务 QPS；；说明：实例支持处理的无攻击情况下最大HTTP/HTTPS 业务的并发请求速率 | 默认 3,000 QPS，增加每 100 QPS ：950 元 / 月                                                                                                                                                                                                       |
| Nas 文件存储     | 按量付费（后付费）           | 性能型；容量型                                        | 每小时实际存储空间的最大值（峰值）；；费用 = 每小时文件系统最大存储空间（峰值）x 每小时单价                                                                                                                                                                                          |
| 私网连接         | 按量付费（后付费）           | 按实例和流量收费                                       | 实例费：终端节点所包含的1个可用区为1个计费实例。；；流量处理费：进出终端节点网卡的双向流量。                                                                                                                                                                                           |

## 按量使用 IP 配置费用 [#按量使用-ip-配置费用]

请以控制台创建弹性公网 IP 时显示价格为准。


# 退款说明 (/products/qvm/1-five-days-have-no-reason-to-refund)



最近更新时间: 2022-02-22 16:11:27

七牛云支持三种退订类型：**五天无理由退订、未生效续费订单退订、非五天无理由退订**。

# 退款限制 [#退款限制]

1. 退款只退还实付金额，已使用的代金券不退还；
2. 每个用户限最多退款 1 次，且仅可退 1 个资源；
3. 转后付费的订单不支持退款；
4. 规则中说明“不支持5天无理由退款”，则无法申请 5 天无理由退款。

# 退订资金流向 [#退订资金流向]

退订款项会退回至您的七牛云账户余额。

# 订单退款产品 [#订单退款产品]

1. 仅限**新购包年包月产品**云主机、弹性公网 IP、关系型数据库 RDS及其他预付费云产品；
2. 活动优惠券购买的主机、云数据库 Redis 不支持退款；
3. BGP 高防 IP 、云防火墙不支持退款。

# 退款方式 [#退款方式]

退款需要您[提交工单](https://support.qiniu.com/tickets/new/form?category=%E5%85%B6%E4%BB%96%E7%B1%BB%E5%92%A8%E8%AF%A2\&space=%E4%BA%91%E4%B8%BB%E6%9C%BA)，工单中写明以下信息：

> 订单号：
> 资源id：
> 退款类型：
> 退款金额：
> 退款原因：

其中，您可以登录您的七牛账号查询订单号，控制台页面右上角 → 费用 → 订单列表，选择需要退款的订单后双击复制订单号即可。

# 退款金额公式 [#退款金额公式]

**以下五天无理由退订类型退款金额公式：**
对于云服务器（包月）这款商品，

> 退款金额 = 订单实付金额 － 已消费金额
> 使用时长不足30天时：已消费金额 =【包月天价（月价/30 换算成天价）x 实际消费时长】\*1.5
> 使用时长大于等于30天时：已消费金额 =包月天价（月价/30 换算成天价）x 实际消费时长

其他云商品，

> 退款金额 = 订单实付金额 － 已消费金额
> 已消费金额 =包月天价（月价/30 换算成天价）x 实际消费时长

说明：

1. 实际消费时长已使用部分精确到天，不满一天按天计算。
2. 按照退款金额计算公式得出的退款金额如小于 0，则不予退款。

**以下未生效续费订单退订和非五天无理由退订类型退款金额公式：**

> 退款金额 = 订单实付金额 － 已消费金额 － 退订手续费
> 已消费金额 = 包月天价（月价 / 30 换算成天价）x 实际消费时长

说明：

1. 实际消费时长已使用部分精确到天，不满一天按天计算。
2. 退订手续费 =  资源池一为 5% 手续费，资源池二为 10% 手续费。即分别为，订单实付金额 x 5%（资源池一）；订单实付金额 x 10%（资源池二）。
3. 按照退款金额计算公式得出的退款金额如小于 0，则不予退款。
4. 未生效续费订单退订分别收取 5%（资源池一）、10%（资源池二）手续费，已消费金额为计为 0 。


# 欠费/冻结说明 (/products/qvm/2-disable-delete-resources-following-the-account-is-frozen)



最近更新时间: 2021-11-17 19:50:02

如果由于账户欠费，或风控审核导致账户进入停用或冻结状态，账号所属资源将受到一定限制，具体说明如下：
**资源池一**

| 计费方式 | 到期/欠费说明                                                                                | 续费/充值说明 |
| ---- | -------------------------------------------------------------------------------------- | ------- |
| 包年包月 | 云主机类资源(包括但不限于云主机、弹性公网IP、云数据库RDS、Redis、MongoDB、负载均衡、网络安全产品等)到期前 7 天、3 天、1 天均会收到短信和邮件提醒。 |         |

1. 当以上资源实例到期/或账户冻结后，将立即进入停止状态。在此状态下，资源实例不能正常提供服务。
2. 以上资源实例到期停机 7 天后，系统将自动释放（实例资源到期 15 天后自动释放，其他 7 天）。在实例释放前一天会发送短信/邮件提醒，实例被释放后相关配置和数据将被永久删除，不可恢复。

\| 在主机未到期前内或在未释放资源的情况下均可以进行续费。如开启自动续费，资源到期前 3 天内每天会执行两次自动续费任务。 |
\| 按量付费 | 当云主机类资源(包括但不限于云主机、弹性公网IP、云数据库RDS、Redis、MongoDB、负载均衡、网络安全产品等)发生欠费（存在已出账单无法进行扣款)，资源所属账户会收到短信和邮件提醒。

1. 账户欠费后，会在欠费 1 天后解绑弹性公网IP，云主机实例停机，此时资源无法继续对外进行服务。
2. 如果进入暂停服务状态达到7天仍未缴清账单/解冻账号，上述资源实例会被自动释放。在实例释放前一天会发送短信/邮件提醒，实例被释放后相关配置和数据将被永久删除，不可恢复。

备注：该操作不区分个人与企业账户， | 按量计费实例发生欠费/账户冻结后对账户进行充值即可。
在欠费/账户冻结后进行充值，您停用的资源将被恢复服务。
欠费/账户冻结后7天内，在未释放资源的情况下向账户充值，系统会立即自动进行未支付账单的支付；支付成功后，资源实例会立即恢复服务。
恢复服务后需要将实例开机、弹性公网 IP 绑定相应资源。 |

**资源池二**

| 计费方式                    | 宽限期                   | 冻结保护期                 | 续费说明                                                                                                                                                                                                                                      |
| ----------------------- | --------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img width="100" />包年包月 | <img width="50" /> 1天 | <img width="100" />7天 | 包周期资源续费：在续费时因余额不足出现续费不成功或未续费，七牛云不会立即停止您的服务，资源进入宽限期（资源可用）。<br />若您在宽限期内对资源续费，包周期资源在宽限期内产生的相关费用将在您续费时一并收取（抵扣续费周期时长）。<br />宽限期到期，若您仍未对资源进行续费，则资源进入冻结保护期，保护期内资源不可用。若您在保护期内对资源续费，资源在宽限期和保护期内产生的相关费用将在您续费时一并收取（抵扣续费周期时长）；若保护期到期您仍未续费，相应的资源将被释放。 |
| <img width="100" />按量付费 | <img width="50" /> 0天 | <img width="100" />7天 | 客户账号因按需资源自动扣费导致欠费后，客户账号将变成欠费状态。<br />欠费后，按需资源立即停止服务，资源进入冻结保护期，保护期到期，若您仍未支付账户欠款，相应的云服务资源将被释放。                                                                                                                                              |


# 注册与购买 (/products/qvm/0-qvm-linux-quickstart)



最近更新时间: 2026-08-18 12:03:17

<a id="prepare" />

# **准备工作** [#准备工作]

在使用云服务器 QVM 前，您需要完成本文中的准备工作。

* [注册七牛云账号](https://portal.qiniu.com/signup)，并完成实名认证。
* 如果要购买按量付费实例，账户余额不能少于 100 元人民币。
* 如果要创建专有网络（VPC）类型的 QVM 实例，需要在目标地域创建一个专有网络和交换机。
* 安全组是一种虚拟防火墙，每个实例必须属于至少一个安全组。系统提供一个默认安全组，您也可以在目标地域创建一个安全组并添加能满足您业务需求的安全组规则。

# **购买** [#购买]

根据业务需求，参考[ QVM 选型](/products/qvm/11-selection-of-the-enterprise)确定好您的架构和实例配置后，可通过[云主机价格计算器](https://www.qiniu.com/calculator_qvm?entry=product-qvm)估算成本，然后在[七牛云主机控制台](https://portal.qiniu.com/qvm/vm/instance/create)直接创建购买。
总共分为以下四个步骤：

# **1.基本选项** [#1基本选项]

1. 付费类型：按量付费，包年包月，不同付费方式的区别，请参考[计费说明](/products/qvm/0-qvm-billing-contrast)。
2. 地域与可用区：靠近你客户的地域可降低访问延迟，提高下载速度。说明：实例创建完成后，不可更改地域和可用区。如何选择地域和可用区，请参考地域和可用区。
3. 实例规格：可供选择的实例规格由你所选择的地域决定。不同实例规格的适用场景，[请参考实例规格族。](/products/qvm/cloud-server/instances/0-qvm-instance-family)
4. 实例镜像：你可以选择公共镜像和自定义镜像，如果你要使用 SSH 密钥对，必须选择 Linux 系统。
5. 块存储包含系统盘和数据盘。
   1. **系统盘**：购买后直接使用。默认容量为 40GB， 容量区间为20\~500GB。
   2. **数据盘**：如购买数据盘，必需格式化后使用。

# **2.网络安全** [#2网络安全]

1. 网络类型：提供默认专有网络和默认交换机。也可以创建专有网络后选择。
2. 选择安全组：如果你自己没有创建安全组，可以使用默认安全组。默认安全组的规则，请参考[安全组默认规则。](/products/qvm/cloud-server/security-groups/0-summary-of-the-security-group)
3. 公网访问：实例必须绑定弹性公网 IP 方可正常连接公网。弹性网络 IP 可随实例购买时直接购买，也可以实例购买后在购买弹性网络 IP 绑定到实例上。

# **3.系统选项** [#3系统选项]

1. 实例名称：名称为 2-128 个字符，以大小字母或中文开头，可包含数字，"\_"或"-"
2. 登录设置：可选择新密码自动生成，该密码如果忘记可直接在实例更多操作 -> 重置密码，重置密码**需手动重启实例**后生效。
   * Linux 系统：可以选择密码或 SSH 密钥对作为登录凭证；
   * Windows 系统：只能使用密码作为登录凭证。
3. 到期自动续费：包年包月主机默认自动续费时长和您购买时相同，您可随时关闭或修改此功能。

# **4.确认订单** [#4确认订单]

最后确认订单信息，如无疑后点击提交订单支付即可。

# **实例更多操作** [#实例更多操作]

1. 连接实例
   1. [连接登录 Linux 类型实例](/products/qvm/cloud-server/instances/qvm-linux-login)
   2. [连接登录 Windos 类型实例](/products/qvm/cloud-server/instances/4307-qvm-Windows-login)
2. [数据盘格式化指引](/products/qvm/cloud-server/cloud-disk/format-cloud-disk/0-formatting-data-plate)


# 统一告警服务 (/products/qvm/0-cloud-monitor)



最近更新时间: 2022-04-27 20:52:20

# 服务简介 [#服务简介]

统一告警服务是一项针对七牛云主机（QVM）资源和互联网应用进行监控的服务。统一告警服务可用于收集获取七牛云主机（QVM）资源的监控指标，探测互联网服务可用性，以及针对指标设置警报。

七牛统一告警服务为用户提供开箱即用的企业级开放型一站式监控解决方案。涵盖 IT 设施基础监控，外网网络质量拨测监控，基于事件、自定义指标、日志的业务监控。为您全方位提供更高效、更全面、更省钱的监控服务。
通过提供Dashboard，帮助您快速构建自定义业务监控大盘。使用统一告警服务，不但可以帮助您提升您的系统服务可用时长，还可以降低企业IT运维监控成本。

七牛统一告警服务可用于收集获取七牛云主机（QVM）资源的监控指标或用户自定义的监控指标，探测服务可用性，以及针对指标设置警报。使您全面了解资源使用情况、业务的运行状况和健康度，并及时收到异常报警做出反应，保证应用程序顺畅运行。

# 主要功能 [#主要功能]

* **Dashboard**：统一告警服务的 Dashboard 功能为您提供自定义查看监控数据的功能。您可以在一张监控大盘中跨产品、跨实例查看监控数据，将相同业务的不同产品实例集中展现。
* **应用分组**：提供跨云产品、跨地域的云产品资源分组管理功能，支持您从业务角度集中管理业务线涉及到的服务器、数据库、负载均衡、存储等资源。从而按业务线来管理报警规则、查看监控数据，可以迅速提升运维效率
* **主机监控**：统一告警服务主机监控服务通过在服务器上安装插件，为您提供CPU、内存、磁盘、网络等三十余种监控项，并对所有监控项提供报警功能，可以选择在实例、应用分组、全部资源三个角度设置报警规则。从业务角度的不同角度出发使用报警功能，满足服务器的基本监控运运维需求。目前支持Linux操作系统和Windows操作系统。
* **自定义监控**：您可以针对自己关心的业务指标进行自定义监控，将采集到监控数据上报至统一告警服务，由统一告警服务来进行数据的处理，并根据处理结果进行报警。
* **站点监控**：为您提供互联网网络探测的监控服务，主要用于通过遍布全国的互联网终端节点，发送模拟真实用户访问的探测请求，监控全国各省市运营商网络终端用户到您服务站点的访问情况。
* **云服务监控**：为您提供查询购买的云服务实例各项性能指标情况，帮助您分析使用情况、统计业务趋势，及时发现以及诊断系统的相关问题。
* **日志监控**：提供对日志数据实时分析，监控图表可视化展示和报警服务。您只需要开通日志服务，将本地日志通过日志服务进行收集，即可解决企业的监控运维与运营诉求。此外，还可完美结合统一告警服务的主机监控、云服务监控、站点监控、应用分组、Dashboard、报警服务，形成完整的监控闭环。
* **事件监控**：提供事件类型数据的上报、查询、报警功能，方便您将业务中的各类异常事件或重要变更事件收集上报到统一告警服务，并在异常发生时接收报警。
* **报警服务**：统一告警服务为您提供监控数据的报警功能。您可以通过设置报警规则来定义报警系统如何检查监控数据，并在监控数据满足报警条件时发送报警通知。您对重要监控指标设置报警规则后，便可在第一时间得知指标数据发生异常，迅速处理故障。

# 产品优势 [#产品优势]

* **数据可视化**：统一告警服务通过 Dashboard 为您提供丰富的图表展现形式，并支持全屏展示和数据自动刷新。满足各种场景下的监控数据可视化需求。
* **监控数据处理**：统一告警服务支持您通过 Dashboard 对监控数据进行时间维度和空间维度的聚合处理。
* **灵活报警**：统一告警服务还为您提供了监控项的报警服务。您在为监控项设置好合理的报警规则和通知方式后，一旦发生异常便会立刻为您发出报警通知，让您及时知晓服务异常并处理异常，从而提高用户产品的可用性。

# 应用场景 [#应用场景]

* **系统监控**：通过监控 ECS 的 CPU 使用率、内存使用率、公网流出流速（带宽）等基础指标，确保实例的正常使用，避免因为对资源的过度使用造成用户业务无法正常运转。
* **及时处理异常场景**：统一告警服务会根据您设置的报警规则，在监控数据达到报警阈值时发送报警信息，让您及时获取异常通知，查询异常原因。
* **及时扩容场景**：对带宽、连接数、磁盘使用率等监控项设置报警规则后，可以让您方便的了解云服务现状，在业务量变大后及时收到报警通知进行服务扩容。
* **站点监控**：站点监控服务目前提供 HTTP(HTTPS)、ICMP、TCP、UDP、DNS、SMTP、POP3、FTP 8 种协议的监控设置，可探测您站点的可用性、响应时间、丢包率，让您全面了解站点的可用性并在异常时及时处理。


# RocketMQ名词解释 (/products/qvm/6123-rocketmq-nouns-explain)



最近更新时间: 2026-08-18 12:07:16

**Topic**
消息主题，一级消息类型，通过 Topic 对消息进行分类。
**Message**
消息，消息队列中信息传递的载体。
**Message ID**
消息的全局唯一标识，由消息队列 RocketMQ 系统自动生成，唯一标识某条消息。
**Message Key**
消息的业务标识，由消息生产者（Producer）设置，唯一标识某个业务逻辑。
**Tag**
消息标签，二级消息类型，用来进一步区分某个 Topic 下的消息分类。详情请参见 Topic 与 Tag 最佳实践。
**Producer**
消息生产者，也称为消息发布者，负责生产并发送消息。
**Producer 实例**
Producer 的一个对象实例，不同的 Producer 实例可以运行在不同进程内或者不同机器上。Producer 实例线程安全，可在同一进程内多线程之间共享。
**Consumer**
消息消费者，也称为消息订阅者，负责接收并消费消息。
**Consumer 实例**
Consumer 的一个对象实例，不同的 Consumer 实例可以运行在不同进程内或者不同机器上。一个 Consumer 实例内配置线程池消费消息。
**Group**
一类 Producer 或 Consumer，这类 Producer 或 Consumer 通常生产或消费同一类消息，且消息发布或订阅的逻辑一致。
**Group ID**
Group 的标识。
**队列**
每个 Topic 下会由一到多个队列来存储消息。每个 Topic 对应队列数与消息类型以及实例所处地域（Region）相关。
**Exactly-Once 投递语义**
Exactly-Once 投递语义是指发送到消息系统的消息只能被 Consumer 处理且仅处理一次，即使 Consumer 重试消息发送导致某消息重复投递，该消息在 Consumer 也只被消费一次。详情请参见 [Exactly-Once 投递语义](/products/qvm/6134-exactly-once-delivery-semantics)。
**集群消费**
一个 Group ID 所标识的所有 Consumer 平均分摊消费消息。例如某个 Topic 有 9 条消息，一个 Group ID 有 3 个 Consumer 实例，那么在集群消费模式下每个实例平均分摊，只消费其中的 3 条消息。详情请参见[集群消费和广播消费](/products/qvm/6135-cluster-consumption-and-radio)。
**广播消费**
一个 Group ID 所标识的所有 Consumer 都会各自消费某条消息一次。例如某个 Topic 有 9 条消息，一个 Group ID 有 3 个 Consumer 实例，那么在广播消费模式下每个实例都会各自消费 9 条消息。详情请参见[集群消费和广播消费](/products/qvm/6135-cluster-consumption-and-radio)。
**定时消息**
Producer 将消息发送到消息队列 RocketMQ 服务端，但并不期望这条消息立马投递，而是推迟到在当前时间点之后的某一个时间投递到 Consumer 进行消费，该消息即定时消息。详情请参见[定时/延时消息](/products/qvm/6129-timing-and-delay-news)。
**延时消息**
Producer 将消息发送到消息队列 RocketMQ 服务端，但并不期望这条消息立马投递，而是延迟一定时间后才投递到 Consumer 进行消费，该消息即延时消息。详情请参见[定时/延时消息](/products/qvm/6129-timing-and-delay-news)。
**事务消息**
消息队列 RocketMQ 提供类似 X/Open XA 的分布事务功能，通过消息队列 RocketMQ 的事务消息能达到分布式事务的最终一致。详情请参见[事务消息](/products/qvm/6131-transaction-message)。
**顺序消息**
消息队列 RocketMQ 提供的一种按照顺序进行发布和消费的消息类型，分为全局顺序消息和分区顺序消息。详情请参见[顺序消息](/products/qvm/6130-the-order-message)。
**全局顺序消息**
对于指定的一个 Topic，所有消息按照严格的先入先出（FIFO）的顺序进行发布和消费。详情请参见[顺序消息](/products/qvm/6130-the-order-message)息。
**分区顺序消息**
对于指定的一个 Topic，所有消息根据 Sharding Key 进行区块分区。同一个分区内的消息按照严格的 FIFO 顺序进行发布和消费。Sharding Key 是顺序消息中用来区分不同分区的关键字段，和普通消息的 Message Key 是完全不同的概念。详情请参见[顺序消息](/products/qvm/6130-the-order-message)。
**消息堆积**
Producer 已经将消息发送到消息队列 RocketMQ 的服务端，但由于 Consumer 消费能力有限，未能在短时间内将所有消息正确消费掉，此时在消息队列 RocketMQ 的服务端保存着未被消费的消息，该状态即消息堆积。
**消息过滤**
Consumer 可以根据消息标签（Tag）对消息进行过滤，确保 Consumer 最终只接收被过滤后的消息类型。消息过滤在消息队列 RocketMQ 的服务端完成。详情请参见[消息过滤](/products/qvm/6133-the-message-filter)。
**消息轨迹**
在一条消息从 Producer 发出到 Consumer 消费处理过程中，由各个相关节点的时间、地点等数据汇聚而成的完整链路信息。通过消息轨迹，您能清晰定位消息从 Producer 发出，经由消息队列 RocketMQ 服务端，投递给 Consumer 的完整链路，方便定位排查问题。详情请参见[消息轨迹](/products/qvm/6156-query-message-trajectory)。
**重置消费位点**
以时间轴为坐标，在消息持久化存储的时间范围内（默认 3 天），重新设置 Consumer 对已订阅的 Topic 的消费进度，设置完成后 Consumer 将接收设定时间点之后由 Producer 发送到消息队列 RocketMQ 服务端的消息。详情请参见[重置消费位点](/products/qvm/6158-reset-the-consumer-site)。
**死信队列**
死信队列用于处理无法被正常消费的消息。当一条消息初次消费失败，消息队列 RocketMQ 会自动进行消息重试；达到最大重试次数后，若消费依然失败，则表明 Consumer 在正常情况下无法正确地消费该消息。此时，消息队列 RocketMQ 不会立刻将消息丢弃，而是将这条消息发送到该 Consumer 对应的特殊队列中。
消息队列 RocketMQ 将这种正常情况下无法被消费的消息称为死信消息（Dead-Letter Message），将存储死信消息的特殊队列称为死信队列（Dead-Letter Queue）。
详情请参见[死信队列](/products/qvm/6159-dead-letter-queue)。


# 使用场景 (/products/qvm/6124-rocketmq-usage-scenarios)



最近更新时间: 2026-08-18 12:08:58

本文为您介绍消息队列 RocketMQ 的使用场景，以便您更好地判断如何在业务中使用消息队列 RocketMQ。
例如，针对一家互联网电商企业，其业务涉及广泛，如注册、订单、库存、物流等；同时，也会涉及许多业务峰值时刻，如秒杀活动、周年庆、定期特惠等。这些活动都对分布性系统中的各项微服务应用的处理性能带来很大的挑战。
消息队列 RocketMQ 作为分布式系统中的重要组件，可用于应对这些挑战，例如解决应用的异步解耦。
下文先以用户注册为场景说明消息队列 RocketMQ 如何实现以下功能：

* 异步解耦
* 分布式事务的数据一致性
* 消息的顺序首发
  最后，再以电商的秒杀场景和价格同步场景分别说明消息队列 RocketMQ 所实现的削峰填谷和大规模机器的缓存同步。

# 传统处理 [#传统处理]

最常见的一个场景是用户注册后，需要发送注册邮件和短信通知，以告知用户注册成功。传统的做法有以下两种：

* 串行方式
  串行方式下的注册流程如下图所示。
  ![](/docs-assets/products/qvm/%284-development-guidelines%29/6124-rocketmq-usage-scenarios/FsnsFP_8Jj1MwYOvla-U0Uva0R5D-2d299dc3fd30.webp)
  数据流动如下所述：
  i. 用户在注册页面填写账号和密码并提交注册信息，这些注册信息首先会被写入注册系统成功。
  ii. 注册信息写入注册系统成功后，再发送请求至邮件通知系统。邮件通知系统收到请求后向用户发送邮件通知。
  iii. 邮件通知系统接收注册系统请求后再向下游的短信通知系统发送请求。短信通知系统收到请求后向用户发送短信通知。
  以上三个任务全部完成后，才返回注册结果到客户端，用户才能使用账号登录。
  假设每个任务耗时分别为 50 ms，则用户需要在注册页面等待总共需要 150 ms 才能登录。
* 并行方式
  并行方式下的注册流程如下图所示。
  ![](/docs-assets/products/qvm/%284-development-guidelines%29/6124-rocketmq-usage-scenarios/Fgbo8Av6rWIsQaLMNXO82Y4Jdm5S-774566274940.webp)
  数据流动如下所述：
  i. 用户在注册页面填写账号和密码并提交注册信息，这些注册信息首先会被写入注册系统成功。
  ii. 注册信息写入注册系统成功后，再同时发送请求至邮件和短信通知系统。邮件和短信通知系统收到请求后分别向用户发送邮件和短信通知。

以上三个任务全部完成后，才返回注册结果到客户端，用户才能使用账号登录。
假设每个任务耗时分别为 50 ms，其中，邮件和短信通知并行完成，则用户需要在注册页面等待总共需要 100 ms 才能登录。
以下就注册场景中使用了消息队列 RocketMQ 的效果进行说明。

# 异步解耦 [#异步解耦]

对于用户来说，注册功能实际只需要注册系统存储用户的账户信息后，该用户便可以登录，后续的注册短信和邮件不是即时需要关注的步骤。
对于注册系统而言，发送注册成功的短信和邮件通知并不一定要绑定在一起同步完成，所以实际当数据写入注册系统后，注册系统就可以把其他的操作放入对应的消息队列 RocketMQ 中然后马上返回用户结果，由消息队列 RocketMQ 异步地进行这些操作。
![](/docs-assets/products/qvm/%284-development-guidelines%29/6124-rocketmq-usage-scenarios/FiXP77dRlW8FvqbNP8VsDNK0O-gU-2a7a841d9ce4.webp)
数据流动如下所述：

1. 用户在注册页面填写账号和密码并提交注册信息，这些注册信息首先会被写入注册系统成功。
2. 注册信息写入注册系统成功后，再发送消息至消息队列 RocketMQ。消息队列 RocketMQ 会马上返回响应给注册系统，注册完成。用户可立即登录。
3. 下游的邮件和短信通知系统订阅消息队列 RocketMQ 的此类注册请求消息，即可向用户发送邮件和短信通知，完成所有的注册流程。

用户只需在注册页面等待注册数据写入注册系统和消息队列 RocketMQ 的时间，即等待 55 ms 即可登录。

异步解耦是消息队列 RocketMQ 的主要特点，主要目的是减少请求响应时间和解耦。主要的使用场景就是将比较耗时而且不需要即时（同步）返回结果的操作作为消息放入消息队列。同时，由于使用了消息队列 RocketMQ，只要保证消息格式不变，消息的发送方和接收方并不需要彼此联系，也不需要受对方的影响，即解耦和。

# 分布式事务的数据一致性 [#分布式事务的数据一致性]

注册系统注册的流程中，用户入口在网页注册系统，通知系统在邮件系统，两个系统之间的数据需要保持最终一致。

## 普通消息处理 [#普通消息处理]

如上所述，注册系统和邮件通知系统之间通过消息队列进行异步处理。注册系统将注册信息写入注册系统之后，发送一条注册成功的消息到消息队列 RocketMQ，邮件通知系统订阅消息队列 RocketMQ 的注册消息，做相应的业务处理，发送注册成功或者失败的邮件。具体流程如下图所示。
![](/docs-assets/products/qvm/%284-development-guidelines%29/6124-rocketmq-usage-scenarios/FhSC2LkekA2GjmIADs8X4H6ZlFR3-dc85a6fbd10f.webp)
流程说明如下：
注册系统发起注册。
注册系统向消息队列 RocketMQ 发送注册消息成功与否的消息。
2.1 消息发送成功，进入 3。
2.2 消息发送失败，导致邮件通知系统未收到消息队列 RocketMQ 发送的注册成功与否的消息，而无法发送邮件，最终邮件通知系统和注册系统之间的状态数据不一致。
邮件通知系统收到消息队列 RocketMQ 的注册成功消息。
邮件通知系统发送注册成功邮件给用户。
在这样的情况下，虽然实现了系统间的解藕，上游系统不需要关心下游系统的业务处理结果；但是数据一致性不好处理，如何保证邮件通知系统状态与注册系统状态的最终一致。

## 事务消息处理 [#事务消息处理]

此时，需要有利用消息队列 RocketMQ 所提供的事务消息来实现系统间的状态数据一致性。具体流程如下图所示。
![](/docs-assets/products/qvm/%284-development-guidelines%29/6124-rocketmq-usage-scenarios/Fi-DJ0b66G5y8jOb-otHaNCNfZbO-e26d19aeefc9.webp)
流程说明如下：
注册系统向消息队列 RocketMQ 发送半事务消息。
1.1 半事务消息发送成功，进入 2。
1.2 半事务消息发送失败，注册系统不进行注册，流程结束。（最终注册系统与邮件通知系统数据一致）
注册系统开始注册。
2.1 注册成功，进入 3.1。
2.2 注册失败，进行 3.2。
注册系统向消息队列 RocketMQ 发送半消息状态。
3.1 提交半事务消息，产生注册成功消息，进入 4。
3.2 回滚半事务消息，未产生注册成功消息，流程结束。（最终注册系统与邮件通知系统数据一致）
邮件通知系统接收消息队列 RocketMQ 的注册成功消息。
邮件通知系统发送注册成功邮件。（最终注册系统与邮件通知系统数据一致）
分布式事务消息的更多详细内容请参见[事务消息](/products/qvm/6131-transaction-message)。

# 消息的顺序收发 [#消息的顺序收发]

消息队列 RocketMQ 顺序消息分为两种情况：

* 全局顺序：对于指定的一个 Topic，所有消息将按照严格的先入先出（FIFO）的顺序，进行顺序发布和顺序消费；
* 分区顺序：对于指定的一个 Topic，所有消息根据 Sharding Key 进行区块分区，同一个分区内的消息将按照严格的 FIFO 的顺序，进行顺发布和顺序消费，可以保证一个消息被一个进程消费。
  在注册场景中，可使用用户 ID 作为 Sharding Key 来进行分区，同一个分区下的新建、更新或删除注册信息的消息必须按照 FIFO 的顺序发布和消费。
  顺序消息的详细内容请参见[顺序消息](/products/qvm/6130-the-order-message)。

# 削峰填谷 [#削峰填谷]

流量削锋也是消息队列 RocketMQ 的常用场景，一般在秒杀或团队抢购活动中使用广泛。
在秒杀或团队抢购活动中，由于用户请求量较大，导致流量暴增，秒杀的应用在处理如此大量的访问流量后，下游的通知系统无法承载海量的调用量，甚至会导致系统崩溃等问题而发生漏通知的情况。为解决这些问题，可在应用和下游通知系统之间加入消息队列 RocketMQ，如下图所示。
![](/docs-assets/products/qvm/%284-development-guidelines%29/6124-rocketmq-usage-scenarios/FncSUvYOVAKSDYI3MAHgEyt5LseT-63089654846b.webp)
秒杀处理流程如下所述：
1、用户发起海量秒杀请求到秒杀业务处理系统。
2、秒杀处理系统按照秒杀处理逻辑将满足秒杀条件的请求发送至消息队列 RocketMQ。
3、下游的通知系统订阅消息队列 RocketMQ 的秒杀相关消息，再将秒杀成功的消息发送到相应用户。
4、用户收到秒杀成功的通知。


# 使用限制 (/products/qvm/6125-rocketmq-use-restrictions)



最近更新时间: 2021-03-15 17:22:09

消息队列 RocketMQ 对某些具体指标进行了约束和规范，您在使用消息队列 RocketMQ 时注意不要超过相应的限制值，以免程序出现异常。
具体的限制项和限制值请参见下表。

| 限制项               | 限制值                           | 说明                                                              |
| ----------------- | ----------------------------- | --------------------------------------------------------------- |
| 单个地域（Region）内的实例数 | 8 个                           | 无                                                               |
| Topic 名称长度        | 64 个字符                        | Topic 名称长度不得超过该限制，否则会导致无法发送或者订阅。                                |
| 消息大小              | 普通和顺序消息：4 MB 事务和定时/延时消息：64 KB | 消息大小不得超过其类型所对应的限制，否则消息会被丢弃。                                     |
| 消息保存时间            | 3 天                           | 消息最多保留 3 天，超过时间将自动滚动删除。                                         |
| 消费位点重置            | 3 天                           | 支持重置消费 3 天之内任何时间点的消息。                                           |
| 单实例的消息收发 TPS      | 5000 条/秒                      | 无                                                               |
| 定时/延时消息的延时时长      | 40 天                          | msg.setStartDeliverTime 参数（单位：毫秒）可设置 40 天内的任何时刻，超过 40 天消息发送将失败。 |


# 快速入门 (/products/qvm/6136-rocketmq-quick-start)



最近更新时间: 2021-03-15 17:23:31

如果您使用的是阿里云主账号，则可以通过本文来体验从开通服务、创建资源、到使用 SDK 收发消息的完整流程，快速上手消息队列 RocketMQ。
无论您使用的是消息队列 RocketMQ 支持的何种协议、何种语言，前三个步骤都一致，只是在控制台上具体填写的信息会略有不同，请以控制台说明为准。但在调用 SDK 时，不同协议和语言的示例代码有所不同，本文以 TCP 协议下的 Java SDK 为例进行说明。

# 步骤一：创建资源 [#步骤一创建资源]

在使用消息队列 RocketMQ 时，请注意以下网络访问限制：

* Topic 和 Group ID 需创建在同一个地域（Region）下的同一个实例中才能互通。例如，当某 Topic 创建在华东1（杭州）下的实例 A 中，那么该 Topic 只能被在华东1（杭州）下的实例 A 中创建的 Group ID 对应的生产端和消费端访问。
* 如果只是测试，或者需要在本地（非七牛云 ECS 服务器）使用消息队列 RocketMQ 的服务，请将 Topic 和 Group ID 都创建在公网地域下的实例中。生产端和消费端可以部署在本地或者部署在任意地域的 ECS 上，前提是本地服务器或者相应的 ECS 需要能够访问公网。

## 创建实例 [#创建实例]

实例是用于消息队列 RocketMQ 服务的虚拟机资源，会存储消息主题（Topic）和客户端 ID（Group ID）信息。
登录消息队列 RocketMQ 控制台。在页面顶部导航栏，选择地域，如公网地域。
在左侧导航栏，单击实例管理。
在实例管理页面右上角，单击创建实例按钮。
在创建实例对话框，选择实例类型，并输入实例名和描述，然后单击确认。
&#x2A;*注意：当您删除某实例时，该实例中的所有 Topic 和 Group ID 也会在 10 分钟内被清理；若单独删除 Topic 或 Group ID，则不会对其他资源造成影响。**

## 创建 Topic [#创建-topic]

Topic 是消息队列 RocketMQ 里对消息的一级归类，比如可以创建 Topic\_Trade 这一 Topic 来识别交易类消息，消息生产者将消息发送到 Topic\_Trade，而消息消费者则通过订阅该 Topic 来获取和消费消息。
在控制台左侧导航栏，单击 Topic 管理。
在 Topic 管理页面上方选择刚创建的实例，单击创建 Topic 按钮。
在创建 Topic 对话框中的 Topic 一栏，输入 Topic 名称，选择该 Topic 对应的消息类型，输入该 Topic 的备注内容，然后单击确定。
消息类型的更多信息，请参见消息类型。
&#x2A;*注意：**

* Topic 不能跨实例使用，比如在实例 A 中创建的 Topic A 不能在实例 B 中使用。
* Topic 名称必须在同一实例中是唯一的。
* 您可创建不同的 Topic 来发送不同类型的消息，例如用 Topic A 发送普通消息，Topic B 发送事务消息，Topic C 发送定时/延时消息。
  您创建的 Topic 将出现在 Topic 列表中。

## 创建 Group ID [#创建-group-id]

创建完实例和 Topic 后，您需要为消息的消费者（或生产者）创建客户端 ID ，即 Group ID 作为标识。
&#x2A;*说明：消费者必须有对应的 Group ID，生产者不做强制要求。**
在控制台左侧导航栏，单击 Group 管理。
在 Group 管理页面上方选择刚创建的实例，然后选择 TCP 协议 > 创建 Group ID。本文以 TCP 协议为例。
说明：TCP 和 HTTP 协议下的 Group ID 不可以共用，因此需分别创建。
在创建 Group ID 对话框中，输入 Group ID 和描述，然后单击确认。
&#x2A;*注意：**

* Group ID 必须在同一实例中是唯一的。
* Group ID 和 Topic 的关系是 N：N，即一个消费者可以订阅多个 Topic，同一个 Topic 也可以被多个消费者订阅；一个生产者可以向多个 Topic 发送消息，同一个 Topic 也可以接收来自多个生产者的消息。

## 创建消息队列 AccessKey [#创建消息队列-accesskey]

消息队列 AccessKey 用于收发消息时进行账户鉴权。
在调用 SDK 发送和订阅消息的时候，除了需要指定创建的 Topic 和 Group ID 以外，还需输入您在 消息队列 控制台创建的身份验证信息，即 AccessKey。AccessKey 的信息包含 AccessKeyId 和 AcessKeySecret。

# 步骤二：获取接入点 [#步骤二获取接入点]

在控制台创建好资源后，您需通过控制台获取实例的接入点。在收发消息时，您需要为生产端和消费端配置该接入点，以此接入某个具体实例或地域的服务。
在控制台左侧导航栏，单击实例管理。
在实例管理页面上方选择刚创建的实例。
在默认显示的实例信息页签的获取接入点信息区域，您可以分别看到新创建实例的 TCP 协议接入点。
完成以上准备工作后，您就可以运行示例代码，用消息队列 RocketMQ 进行消息发送和订阅了。

# 步骤三：发送消息 [#步骤三发送消息]

您可以通过调用 SDK 发送消息。

下文以调用 Java SDK 为例进行说明。

1. 通过以下任一方式引入依赖：

* Maven 方式引入依赖：

```
<dependency>
  <groupId>com.aliyun.openservices</groupId>
  <artifactId>ons-client</artifactId>
  <version>"XXX"</version>
  //设置为 Java SDK 的最新版本号
</dependency>
```

Java SDK 的最新版本号，请参见 Java SDK 版本说明。

* 下载依赖 JAR 包：
  Java SDK 最新版本的下载链接，请参见 Java SDK 版本说明。

2. 根据以下说明设置相关参数，运行示例代码：

```
public class ProducerTest {
    public static void main(String[] args) {
        Properties properties = new Properties();
        // 您在控制台创建的 Group ID
        properties.put(PropertyKeyConst.GROUP_ID, "XXX");
        // 鉴权用 AccessKeyId，在消息队列管理控制台创建
        properties.put(PropertyKeyConst.AccessKey,"XXX");
        // 鉴权用 AccessKeySecret，在消息队列管理控制台创建
        properties.put(PropertyKeyConst.SecretKey, "XXX");
        // 设置 TCP 接入域名，进入控制台的实例管理页面，在页面上方选择实例后，在实例信息中的“获取接入点信息”区域查看
        properties.put(PropertyKeyConst.NAMESRV_ADDR,"XXX");
        Producer producer = ONSFactory.createProducer(properties);
        // 在发送消息前，必须调用 start 方法来启动 Producer，只需调用一次即可
        producer.start();
        //循环发送消息
        while(true){
            Message msg = new Message( //
                // 在控制台创建的 Topic，即该消息所属的 Topic 名称
                "TopicTestMQ",
                // Message Tag,
                // 可理解为 Gmail 中的标签，对消息进行再归类，方便 Consumer 指定过滤条件在消息队列 RocketMQ 服务器过滤
                "TagA",
                // Message Body
                // 任何二进制形式的数据，消息队列 RocketMQ 不做任何干预，
                // 需要 Producer 与 Consumer 协商好一致的序列化和反序列化方式
                "Hello MQ".getBytes());
            // 设置代表消息的业务关键属性，请尽可能全局唯一，以方便您在无法正常收到消息情况下，可通过控制台查询消息并补发
            // 注意：不设置也不会影响消息正常收发
            msg.setKey("ORDERID_100");
            // 发送消息，只要不抛异常就是成功
            // 打印 Message ID，以便用于消息发送状态查询
            SendResult sendResult = producer.send(msg);
            System.out.println("Send Message success. Message ID is: " + sendResult.getMessageId());
        }
        // 在应用退出前，可以销毁 Producer 对象
        // 注意：如果不销毁也没有问题
        producer.shutdown();
    }
}
```

## 查看消息是否发送成功 [#查看消息是否发送成功]

消息发送后，您可以在控制台查看消息发送状态，步骤如下：

1. 在控制台左侧导航栏，选择消息查询 > 按 Message ID 查询。
2. 在搜索框中输入发送消息后返回的 Message ID，单击搜索查询消息发送状态。
   储存时间表示消息队列 RocketMQ 服务端存储这条消息的时间。如果查询到此消息，表示消息已经成功发送到服务端。
   &#x2A;*注意：此步骤演示的是第一次使用消息队列 RocketMQ 的场景，此时消费者从未启动过，所以消息状态显示暂无消费数据。要启动消费者并进行消息订阅请继续下一步操作订阅消息。更多消息状态请参见消息查询和查询消息轨迹。**

# 步骤四：调用 SDK 订阅消息 [#步骤四调用-sdk-订阅消息]

消息发送成功后，需要启动消费者来订阅消息。下文以调用 TCP Java SDK 为例说明如何订阅消息。

## 调用 TCP Java SDK 订阅消息 [#调用-tcp-java-sdk-订阅消息]

您可以运行以下示例代码来启动消费者，并测试订阅消息的功能。请按照说明正确设置相关参数。

```
public class ConsumerTest {
    public static void main(String[] args) {
        Properties properties = new Properties();
        // 您在控制台创建的 Group ID
        properties.put(PropertyKeyConst.GROUP_ID, "XXX");
        // 鉴权用 AccessKeyId，在消息队列管理控制台创建
        properties.put(PropertyKeyConst.AccessKey, "XXX");
        // 鉴权用 AccessKeySecret，在消息队列管理控制台创建
        properties.put(PropertyKeyConst.SecretKey, "XXX");
        // 设置 TCP 接入域名，进入控制台的实例管理页面，在页面上方选择实例后，在实例信息中的“获取接入点信息”区域查看
        properties.put(PropertyKeyConst.NAMESRV_ADDR,"XXX");
        Consumer consumer = ONSFactory.createConsumer(properties);
        consumer.subscribe("TopicTestMQ", "*", new MessageListener() {
            public Action consume(Message message, ConsumeContext context) {
                System.out.println("Receive: " + message);
                return Action.CommitMessage;
            }
        });
        consumer.start();
        System.out.println("Consumer Started");
    }
}
```

## 查看消息订阅是否成功 [#查看消息订阅是否成功]

完成上述步骤后，您可以在控制台查看消费者是否启动成功，即消息订阅是否成功。

1. 在控制台左侧导航栏，单击 Group 管理。
2. 找到要查看的 Group ID，单击该 Group ID 所在行操作列的订阅关系。
   如果是否在线显示为是，且订阅关系一致，则说明订阅成功。否则说明订阅失败。


# 控制台使用指南 (/products/qvm/6154-the-console-using-guide)



最近更新时间: 2021-03-15 17:26:01

控制台使用指南


# 什么是消息队列 RocketMQ？ (/products/qvm/6212-what-is-the-message-queue-rocketmq)



最近更新时间: 2026-08-18 12:10:27

消息队列 RocketMQ 是基于高可用分布式集群技术的云正式商用的专业消息中间件，既可为分布式应用系统提供异步解耦和削峰填谷的能力，同时也具备互联网应用所需的海量消息堆积、高吞吐、可靠重试等特性。

# 核心概念 [#核心概念]

* Topic：消息主题，一级消息类型，生产者向其发送消息。
* 生产者：也称为消息发布者，负责生产并发送消息至 Topic。
* 消费者：也称为消息订阅者，负责从 Topic 接收并消费消息。
* 消息：生产者向 Topic 发送并最终传送给消费者的数据和（可选）属性的组合。
* 消息属性：生产者可以为消息定义的属性，包含 Message Key 和 Tag。
* Group：一类生产者或消费者，这类生产者或消费者通常生产或消费同一类消息，且消息发布或订阅的逻辑一致。

消息队列 RocketMQ 涉及的概念的详细解释，请参见[RocketMQ名词解释](/products/qvm/6123-rocketmq-nouns-explain)。

# 消息收发模型 [#消息收发模型]

消息队列 RocketMQ 支持发布/订阅模型，消息生产者应用创建 Topic 并将消息发送到 Topic。消费者应用创建对 Topic 的订阅以便从其接收消息。通信可以是一对多（扇出）、多对一（扇入）和多对多。
具体通信如下图所示。
![](/docs-assets/products/qvm/%284-development-guidelines%29/6212-what-is-the-message-queue-rocketmq/Ft2s2t-iCjk8GE4ZYWSyV8qzW5RG-c2aa4019b63e.webp)
消息收发模型

* 生产者集群: 用来表示发送消息应用，一个生产者集群下包含多个生产者实例，可以是多台机器，也可以是一台机器的多个进程，或者一个进程的多个生产者对象。
  一个生产者集群可以发送多个 Topic 消息。发送分布式事物消息时，如果生产者中途意外宕机，Broker 会主动回调生产者集群的任意一台机器来确认事务状态。
* 消费者集群：用来表示消费消息应用，一个消费者集群下包含多个消费者实例，可以是多台机器，也可以是多个进程，或者是一个进程的多个消费者对象。
  一个消费者集群下的多个消费者以均摊方式消费消息。如果设置的是广播方式，那么这个消费者集群下的每个实例都消费全量数据。
  一个消费者集群对应一个 Group ID，一个 Group ID 可以订阅多个 Topic，如图中的 Group 2 所示。Group 和 Topic 的订阅关系可以通过直接在程序中设置即可。

# 产品功能 [#产品功能]

消息队列 RocketMQ 在多个地域（Region）提供了高可用消息云服务。单个地域内采用多机房部署，可用性极高，即使整个机房都不可用，仍然可以为应用提供消息发布服务。
消息队列 RocketMQ 提供 TCP 协议的多语言接入方式，方便不同编程语言开发的应用快速接入消息队列 RocketMQ 消息云服务。您可以将应用部署在七牛云 ECS、企业自建云，或者嵌入到移动端、物联网设备中与消息队列 RocketMQ 建立连接进行消息收发；同时，本地开发者也可以通过公网接入消息队列 RocketMQ 服务进行消息收发。

## TCP接入 [#tcp接入]

提供专业、可靠、稳定的 TCP 协议的 SDK 接入服务。支持的语言包括 Java、C/C++ 以及 .NET。

## Web 控制台 [#web-控制台]

支持 Topic 管理、Group 管理、消息查询、消息轨迹展示和查询以及资源报表。

## 消息类型 [#消息类型]

* [普通消息](/products/qvm/6128-ordinary-message)：消息队列 RocketMQ 中无特性的消息，区别于有特性的定时/延时消息、顺序消息和事务消息。
* [事务消息](/products/qvm/6131-transaction-message)：实现类似 X/Open XA 的分布事务功能，以达到事务最终一致性状态。
* [定时/延时消息](/products/qvm/6129-timing-and-delay-news)：允许消息生产者对指定消息进行定时（延时）投递，最长支持 40 天。
* [顺序消息](/products/qvm/6130-the-order-message)：允许消息消费者按照消息发送的顺序对消息进行消费。

## 特色功能 [#特色功能]

* [消息查询](/products/qvm/6155-information-query)：消息队列 RocketMQ 提供了三种消息查询的方式，分别是按 Message ID、Message Key 以及 Topic 查询。
* [消息轨迹](/products/qvm/6156-query-message-trajectory)：通过消息轨迹，能清晰定位消息从生产者发出，经由消息队列 RocketMQ 服务端，投递给消息消费者的完整链路，方便定位排查问题。
* [集群消费和广播消费](/products/qvm/6135-cluster-consumption-and-radio)：当使用集群消费模式时，消息队列 RocketMQ 认为任意一条消息只需要被消费者集群内的任意一个消费者处理即可；当使用广播消费模式时，消息队列 RocketMQ 会将每条消息推送给消费者集群内所有注册过的消费者，保证消息至少被每台机器消费一次。
* [重置消费位点](/products/qvm/6158-reset-the-consumer-site)：根据时间或位点重置消费进度，允许用户进行消息回溯或者丢弃堆积消息。
* [死信队列](/products/qvm/6159-dead-letter-queue)：将无法正常消费的消息储存到特殊的死信队列供后续处理。
* [资源报表](/products/qvm/6162-resources-report)：消息生产和消费数据的统计功能。通过该功能，您可查询在一段时间范围内发送至某 Topic 的消息总量或者 TPS（消息生产数据），也可查询在一个时间段内某 Topic 投递给某 Group ID 的消息总量或 TPS（消息消费数据）。

## 应用场景 [#应用场景]

* **削峰填谷**：诸如秒杀、抢红包、企业开门红等大型活动时皆会带来较高的流量脉冲，或因没做相应的保护而导致系统超负荷甚至崩溃，或因限制太过导致请求大量失败而影响用户体验，消息队列 RocketMQ 可提供削峰填谷的服务来解决该问题。
* **异步解耦**：对于交易系统而言每笔交易订单数据的产生会引起几百个下游业务系统的关注，包括物流、购物车、积分、流计算分析等等，整体业务系统庞大而且复杂，消息队列 RocketMQ 可实现异步通信和应用解耦，确保主站业务的连续性。
* **顺序收发**：细数日常中需要保证顺序的应用场景非常多，比如证券交易过程时间优先原则，交易系统中的订单创建、支付、退款等流程，航班中的旅客登机消息处理等等。与先进先出（First In First Out，缩写 FIFO）原理类似，消息队列 RocketMQ 提供的顺序消息即保证消息 FIFO。
* **分布式事务一致性**：交易系统、支付红包等场景需要确保数据的最终一致性，大量引入消息队列 RocketMQ 的分布式事务，既可以实现系统之间的解耦，又可以保证最终的数据一致性。
* **大数据分析**：数据在“流动”中产生价值，传统数据分析大多是基于批量计算模型，而无法做到实时的数据分析，利用七牛云消息队列 RocketMQ 与流式计算引擎相结合，可以很方便的实现将业务数据进行实时分析。


# 产品架构 (/products/qvm/6214-product-architecture1)



最近更新时间: 2021-03-15 17:22:09

本文介绍消息队列 RocketMQ 的系统部署架构，方便您更好地理解消息队列 RocketMQ 的高可用性。
消息队列 RocketMQ 在任何一个环境都是可扩展的，生产者必须是一个集群，消息服务器必须是一个集群，消费者也同样。集群级别的高可用，是消息队列 RocketMQ 跟其他的消息服务器的主要区别，消息生产者发送一条消息到消息服务器，消息服务器会随机的选择一个消费者，只要这个消费者消费成功就认为是成功了。
&#x2A;*注意：文中所提及的消息队列 RocketMQ 的服务端或者服务器包含 Name Server、Broker 等。服务端不等同于 Broker。**

# 系统部署架构 [#系统部署架构]

系统部署架构如下图所示。
![](/docs-assets/products/qvm/%284-development-guidelines%29/6214-product-architecture1/Fik8Scl05LRt_cOhov1eYnPRB0eA-801c9a50313c.webp)
图中所涉及到的概念如下所述：

* Name Server: 是一个几乎无状态节点，可集群部署，在消息队列 RocketMQ 中提供命名服务，更新和发现 Broker 服务。
* Broker：消息中转角色，负责存储消息，转发消息。分为 Master Broker 和 Slave Broker，一个 Master Broker 可以对应多个 Slave Broker，但是一个 Slave Broker 只能对应一个 Master Broker。Broker 启动后需要完成一次将自己注册至 Name Server 的操作；随后每隔 30s 定期向 Name Server 上报 Topic 路由信息。
* 生产者：与 Name Server 集群中的其中一个节点（随机）建立长链接（Keep-alive），定期从 Name Server 读取 Topic 路由信息，并向提供 Topic 服务的 Master Broker 建立长链接，且定时向 Master Broker 发送心跳。
* 消费者：与 Name Server 集群中的其中一个节点（随机）建立长连接，定期从 Name Server 拉取 Topic 路由信息，并向提供 Topic 服务的 Master Broker、Slave Broker 建立长连接，且定时向 Master Broker、Slave Broker 发送心跳。Consumer 既可以从 Master Broker 订阅消息，也可以从 Slave Broker 订阅消息，订阅规则由 Broker 配置决定。


# Go SDK (/products/qvm/0-stack-go)



最近更新时间: 2024-03-11 11:06:40

<a id="intro" />

# 简介 [#简介]

使用此 SDK 用于管理七牛云主机实例，主要有如下功能：

### 通用类接口： [#通用类接口]

* 获取地域列表

### 资源管理： [#资源管理]

* 实例（主机）管理：列表，详情，创建，删除，续费，开机，关机，重启，规格列表，查询可用资源
* 磁盘管理：列表，详情，创建，删除，挂载，卸载
* 镜像类管理：列表，创建，详情，删除
* 秘钥对管理：列表，详情，导入，删除，绑定，解绑
* 安全组管理：列表，详情，创建，绑定，解绑，入网规则管理，出网规则管理
* VPC 管理：列表，详情，创建，删除
* VSwitch 管理： 列表，详情，创建，删除
* EIP 管理： 列表，详情，创建，续费，删除，绑定，解绑，变配

### BGP 高防类 [#bgp-高防类]

* 资源管理： 修改实例名称，修改弹性防护带宽
* 端口配置管理： 获取四层规则列表，创建四层规则，修改四层规则，删除四层规则，修改四层健康检查，修改会话保持配置

### 订单类 [#订单类]

* 支付订单
* 取消订单
* 未支付订单列表

> 说明：
> SDK名称：云主机 Golang SDK
> 开发者：上海七牛信息技术有限公司
> 云主机 Golang SDK 合规使用说明请参考[七牛 SDK 合规使用说明](/products/qvm/0-stack-go)；隐私政策说明请参考[七牛 SDK 隐私策略](/products/qvm/0-stack-go)

<a id="install" />

# 安装 stack-go SDK v0.0.4 [#安装-stack-go-sdk-v004]

```
go get github.com/qiniu/stack-go
```

# 示例 [#示例]

```go
import (
  "github.com/qiniu/stack-go"
  "github.com/qiniu/stack-go/components/auth"
  "github.com/qiniu/stack-go/components/log"
)

func main() {
  s := stack.New(log.NewSimpleLog(), "https://api-qvm.qiniu.com", auth.NewCredential("xxx", "xxx"))

  resp, _ := s.ECS().ListInstances(&ecs.ListInstancesParams{...})

  ...
}
```

<a id="opensource" />

# 开源 [#开源]

* [Go SDK 项目地址](https://github.com/qiniu/stack-go)
* [Go SDK 发布地址](https://github.com/qiniu/stack-go/releases)

<a id="related-resources" />

# 相关资源 [#相关资源]

如果您有任何关于我们文档或产品的建议和想法，欢迎您通过以下方式与我们互动讨论：

* [技术论坛](http://segmentfault.com/qiniu) - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
* [提交工单](https://support.qiniu.com/tickets/new) - 如果您的问题不适合在论坛讨论或希望及时解决，您也可以提交一个工单，我们的技术支持人员会第一时间回复您
* [博客](http://blog.qiniu.com) - 这里会持续更新发布市场活动和技术分享文章
* [微博](http://weibo.com/qiniutek)
* [常见问题](https://support.qiniu.com/question)

<a id="contribute-code" />

# 贡献代码 [#贡献代码]

1. Fork
2. 创建您的特性分支 git checkout -b my-new-feature
3. 提交您的改动 git commit -am 'Added some feature'
4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature
5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

<a id="license" />

# 许可证 [#许可证]

基于 Apache 2.0 license. 协议发布:

* [www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)


# 云服务器服务（QVM）服务条款 (/products/qvm/0-qvm-the-terms-of-service)



最近更新时间: 2021-03-15 11:31:15

本服务条款是七牛信息技术有限公司(以下简称“七牛云”)与您就七牛云服务器服务(Qiniu Virtual Machine，简称QVM）的相关事项所订立的有效合约。您通过盖章、网络页面点击确认或以其他方式选择接受本服务条款，包括但不限于未点击确认本服务条款而事实上使用了七牛云QVM服务，即表示您与七牛云已达成协议并同意接受本服务条款的全部约定内容。如若双方盖章文本与网络页面点击确认或以其他方式选择接受之服务条款文本，存有不一致之处，以双方盖章文本为准。

关于本服务条款，提示您特别关注限制、免责条款，七牛云对您违规、违约行为的认定处理条款，以及管辖法院的选择条款等。限制、免责条款可能以加粗或加下划线形式提示您注意。在接受本服务条款之前，请您仔细阅读本服务条款的全部内容。如果您对本服务条款的条款有疑问的，请通过七牛云相关业务部门进行询问，七牛云将向您解释条款内容。如果您不同意本服务条款的任意内容，或者无法准确理解七牛云对条款的解释，请不要进行后续操作。

# 1. 服务内容 [#1-服务内容]

1.1. 本条款中“服务”指：七牛云向您提供 [www.qiniu.com](http://www.qiniu.com) 网站上所展示的云服务器服务以及相关的技术及网络支持服务。

1.2. 七牛云提供的服务必须符合本服务条款的约定。

# 2. 服务费用 [#2-服务费用]

2.1. 服务费用将在您订购页面予以列明公示，您可自行选择具体服务类型并按列明的价格予以支付。

2.2. 您可选择预付费或后付费：

2.2.1. 预付费

2.1.1.1. 在您付费之后，七牛云才开始为您提供服务。您未在下单后7天内付费的，本服务条款以及与您就服务所达成的一切行为失效。

2.1.1.2. 服务期满双方愿意继续合作的，您至少应在服务期满前7天内支付续费款项，以使服务得以继续进行。如续费时七牛云对产品体系、名称或价格进行调整的，双方同意按照届时有效的新的产品体系、名称或价格履行。

2.2.2. 后付费。您先使用后付费。具体扣费规则请查看 [https://www.qiniu.com/calculator\_qvm](https://www.qiniu.com/calculator_qvm) 上的页面公告且以页面公布的后付费服务当时有效的计费模式、标准为准。

2.3. 七牛云保留在您未按照约定支付全部费用之前不向您提供服务和/或技术支持，或者终止服务和/或技术支持的权利。同时，七牛云保留对后付费服务中的欠费行为追究法律责任的权利。

2.4. 您完全理解七牛云价格体系中所有的赠送服务项目或活动均为七牛云在正常服务价格之外的一次性特别优惠，优惠内容不包括赠送服务项目的修改、更新及维护费用，并且赠送服务项目不可折价冲抵服务价格。

# 3. 权利义务 [#3-权利义务]

3.1. 您的权利、义务

3.1.1. 您同意遵守本服务条款以及服务展示页面的相关管理规范及流程。您了解上述协议及规范等的内容可能会不时变更。如本服务条款的任何内容发生变动，七牛云应通过提前30天在 [https://portal.qiniu.com/qvm](https://portal.qiniu.com/qvm) 的适当版面公告向您提示修改内容。如您不同意七牛云对本服务条款相关条款所做的修改，您有权停止使用七牛云的服务，此等情况下，七牛云应与您进行服务费结算（如有），并且您应将业务数据迁出。如您继续使用七牛云服务，则视为您接受七牛云对本服务条款相关条款所做的修改。

3.1.2. 您应按照七牛云的页面提示及本服务条款的约定支付相应服务费用。

3.1.3. 您承诺：

3.1.3.1. 如果您利用七牛云提供的服务进行经营或非经营的活动需要获得国家有关部门的许可或批准的，应获得该有关的许可或批准。包括但不限于以下内容：
3.1.3.1.1． 如果您在云服务器服务上开办了多个网站，须保证所开办的全部网站均获得国家有关部门的许可或批准；
3.1.3.1.2． 如您网站提供非经营性互联网信息服务的，必须办理非经营性网站备案，并保证所提交的所有备案信息真实有效，在备案信息发生变化时及时在备案系统中提交更新信息；
3.1.3.1.3． 如您网站提供经营性互联网信息服务的，还应自行在当地通信管理部门取得经营性网站许可证；
3.1.3.1.4． 如您如提供BBS等电子公告服务的，也需根据相关法规政策要求备案或获得相应批准；
3.1.3.1.5． 如您经营互联网游戏网站的，您应依法获得网络文化经营许可证；
3.1.3.1.6． 如您经营互联网视频网站的，您应依法获得信息网络传播视听节目许可证；
3.1.3.1.7． 若您从事新闻、出版、教育、医疗保健、药品和医疗器械等互联网信息服务，依照法律、行政法规以及国家有关规定须经有关主管部门审核同意，在申请经营许可或者履行备案手续前，应当依法经有关主管部门审核同意。
您理解并认可，以上列举并不能穷尽您进行经营或非经营活动需要获得国家有关部门的许可或批准的全部类型，您应获得有关的许可或批准，并应符合国家及地方不时颁布相关法律法规之要求。

3.1.3.2. 除七牛云明示许可外，不得修改、翻译、改编、出租、转许可、在信息网络上传播或转让七牛云提供的服务或软件，也不得逆向工程、反编译或试图以其他方式发现七牛云提供的服务或软件的源代码；

3.1.3.3. 若七牛云的服务涉及第三方软件之许可使用的，您同意遵守相关的许可协议的约束；

3.1.3.4. 不散布电子邮件广告、垃圾邮件（SPAM）：不利用七牛云提供的服务散发大量不受欢迎的或者未经请求的电子邮件、电子广告或包含反动、色情等有害信息的电子邮件；

3.1.3.5. 不得将七牛云所提供的云服务器用作虚拟服务器、或用作磁盘空间出租，或用作非法代理服务器（Proxy）或邮件服务器（根据七牛云《云平台安全规则》，未经报备许可云服务器不得用于连接SMTP服务发送邮件，七牛云默认将禁止云服务器用于SMTP服务）；

3.1.3.6. 不利用七牛云提供的资源和服务上传（Upload）、下载（download）、储存、发布如下信息或者内容，不为他人发布该等信息提供任何便利（包括但不限于设置URL、BANNER链接等）:
3.1.3.6.1. 违反国家规定的政治宣传和/或新闻信息；
3.1.3.6.2. 涉及国家秘密和/或安全的信息；
3.1.3.6.3. 封建迷信和/或淫秽、色情、下流的信息或教唆犯罪的信息；
3.1.3.6.4. 博彩有奖、赌博游戏、“私服”、“外挂”等非法互联网出版活动；
3.1.3.6.5. 违反国家民族和宗教政策的信息；
3.1.3.6.6. 妨碍互联网运行安全的信息；
3.1.3.6.7. 侵害他人合法权益的信息和/或其他有损于社会秩序、社会治安、公共道德的信息或内容；
3.1.3.6.8. 其他违反法律法规、部门规章或国家政策的内容。

3.1.3.7. 不应大量占用，亦不得导致如程序或进程等大量占用七牛云云计算资源（如云服务器、网络带宽、存储空间等）所组成的平台（以下简称“云平台”）中服务器内存、CPU或者网络带宽资源（比如但不限于互联网挖矿等行为），并给七牛云云平台或者七牛云的其他用户的网络、服务器（包括但不限于本地及外地和国际的网络、服务器等）、产品/应用等带来严重的、不合理的负荷，影响七牛云与国际互联网或者七牛云与特定网络、服务器及七牛云内部正常通畅的联系，或者导致七牛云云平台产品与服务或者七牛云的其他用户的服务器宕机、死机或者用户基于云平台的产品/应用不可访问等；

3.1.3.8. 不进行任何破坏或试图破坏网络安全的行为（包括但不限于钓鱼，黑客，网络诈骗，网站或空间中含有或涉嫌散播：病毒、木马、恶意代码，及通过虚拟服务器对其他网站、服务器进行涉嫌攻击行为如扫描、嗅探、ARP欺骗、DOS等）；

3.1.3.9. 不进行任何改变或试图改变七牛云提供的系统配置或破坏系统安全的行为；

3.1.3.10. 不利用本服务从事DDoS防护、DNS防护等防护售卖业务；

3.1.3.11. 不利用七牛云的服务提供任何不经网络审查或依靠技术手段成为境内获取境外非法信息的途径；

3.1.3.12. 不从事其他违法、违规或违反七牛云服务条款的行为。

3.1.3.13. 如七牛云发现您违反上述条款的约定，有权根据情况采取相应的处理措施，包括但不限于立即终止服务、中止服务或删除相应信息等。如果第三方机构或个人对您提出质疑或投诉，七牛云将通知您，您有责任在规定时间内进行说明并出具证明材料，如您未能提供相反证据或您逾期未能反馈的，七牛云将采取包括但不限于立即终止服务、中止服务或删除相应信息等处理措施。因您未及时更新联系方式或联系方式不正确而致使未能联系到您的，亦视为您逾期未能反馈。

3.1.4. 您不应在七牛云服务或平台之上安装、使用盗版软件；您对自己行为（如自行安装的软件和进行的操作）所引起的结果承担全部责任。

3.1.5. 您对自己存放在七牛云云平台上的数据以及进入和管理七牛云云平台上各类产品与服务的口令、密码的完整性和保密性负责。因您维护不当或保密不当致使上述数据、口令、密码等丢失或泄漏所引起的一切损失和后果均由您自行承担。

3.1.6. 您应向七牛云提交执行本服务条款的联系人和管理用户网络及云平台上各类产品与服务的人员名单和联系方式并提供必要的协助。如以上人员发生变动，您应自行将变动后的信息进行在线更新并及时通知七牛云。因您提供的人员的信息不真实、不准确、不完整，以及因以上人员的行为或不作为而产生的结果，均由您负责。

3.1.7. 您对您存放在七牛云云平台上的数据内容负责，如因上传、发布的公开信息违反法律法规、部门规章或国家政策，由此造成的全部结果及责任由您自行承担。七牛云对此予以监督、通过七牛绿网功能向您提示不合规或疑似不合规内容，并郑重提示您谨慎判断数据内容的合法性。您开通QVM即将默认开通七牛绿网功能，如不需七牛绿网服务，您可按七牛云官网相关服务说明予以关闭此功能，您一旦在管理控制台执行关闭七牛绿网功能的操作，则您已购和将新购的任何QVM都将不再默认开通并享有七牛绿网服务。

3.1.8. 您须依照《互联网信息服务管理办法》、《互联网电子公告服务管理规定》等法律法规的规定保留自己网站的访问日志记录，包括发布的信息内容及其发布时间、互联网地址（IP）、域名等，国家有关机关依法查询时应配合提供。您自行承担未按规定保留相关记录而引起的全部法律责任。

3.1.9. 您了解七牛云无法保证其所提供的服务毫无瑕疵（如七牛云安全产品并不能保证您的硬件或软件的绝对安全），但七牛云承诺不断提升服务质量及服务水平。所以您同意：即使七牛云提供的服务存在瑕疵，但上述瑕疵是当时行业技术水平所无法避免的，其将不被视为七牛云违约。您同意和七牛云一同合作解决上述瑕疵问题。

3.1.10. 为了数据的安全，您应负责您数据的备份工作。

3.2. 七牛云的权利、义务

3.2.1. 七牛云应按照服务条款约定提供服务。

3.2.2. 七牛云为付费用户提供7×24售后电话咨询服务和在线工单服务系统，解答客户在使用中的问题。

3.2.3. 若服务涉及云服务器的，七牛云仅负责操作系统以下的底层部分及七牛云提供的软件的运营维护，即云服务器服务的相关技术架构及操作系统等。操作系统之上部分（如您在系统上安装的应用程序）由您自行负责。此外，您自行升级操作系统可能会造成宕机等不良影响，请自行把握风险并谨慎操作。

3.2.4. 七牛云将消除您非人为操作所出现的故障，但因您原因和/或不可抗力以及非七牛云控制范围之内的事项除外。

3.2.5. 您理解并认可，七牛云在必要时将会对您使用的云服务器服务进行机房迁移。七牛云进行上述操作前将提前7个自然日通知您，由于进行上述操作可能需要修改您相关域名的DNS，因此您需在接到七牛云通知后按照七牛云要求的时间将DNS修改到七牛云指定IP上，否则因此造成网站应用无法访问的，由您自行负责。

3.2.6. 七牛云的云服务器服务为您提供镜像分享的功能。您可以通过云服务器的镜像分享功能向他人提供您的镜像，也可以获取他人已提供的镜像并安装于自己的云服务器之上。在此种情况下，七牛云仅是镜像分享的平台，并不是镜像本身的提供者，请您在提供、使用他人镜像时，谨慎判断镜像以及其中的数据是否适合公开，以及相关的安全性和适用性等情况，如因分享的镜像出现任何纠纷，将由镜像提供者和镜像使用者双方解决，七牛云不对双方之间的达成的或涉及的法定和/或契约责任承担任何责任。

# 4. 用户业务数据 [#4-用户业务数据]

4.1 七牛云理解并认可，您通过七牛云提供的服务，加工、存储、上传、下载、分发以及通过其他方式处理的数据，均为您的用户业务数据，您完全拥有您的用户业务数据。

4.2 就用户业务数据，七牛云除执行您的服务要求外，不进行任何未获授权的使用及披露；但以下情形除外：
4.2.1 在国家有关机关依法查询或调阅用户业务数据时，七牛云具有按照相关法律法规或政策文件要求提供配合，并向第三方或者行政、司法等机构披露的义务；
4.2.2 您和七牛云另行协商一致。

4.3 您可自行对您的用户业务数据进行删除、更改等操作。如您自行释放服务或删除数据的，七牛云将删除您的数据，按照您的指令不再保留该等数据。就数据的删除、更改等操作，您应谨慎操作。

4.4. 当服务期届满、服务提前终止（包括但不限于双方协商一致提前终止，其他原因导致的提前终止等）或您发生欠费时，除法律法规明确约定、主管部门要求或双方另有约定外，七牛云仅在一定的缓冲期（以您所订购的服务适用的产品文档、服务说明等所载明的时限为准）内继续存储您的用户业务数据（如有），缓冲期届满七牛云将删除所有用户业务数据，包括所有缓存或者备份的副本，不再保留您的任何用户业务数据。

4.5. 用户业务数据一经删除，即不可恢复；您应自行承担数据因此被删除所引发的后果和责任，您理解并同意，七牛云没有继续保留、导出或者返还用户业务数据的义务。

4.6. 根据您与七牛云协商一致，七牛云在您选定的数据中心存储用户业务数据。七牛云恪守对用户的安全承诺，根据适用的法律保护用户存储在七牛云数据中心的数据。

# 5. 知识产权 [#5-知识产权]

5.1. 您应保证提交七牛云的素材、对七牛云服务的使用及使用七牛云服务所产生的成果未侵犯任何第三方的合法权益。如有第三方基于侵犯版权、侵犯第三人之权益或违反中国法律法规或其他适用的法律等原因而向七牛云提起索赔、诉讼或可能向其提起诉讼,则您应赔偿七牛云因此承担的费用或损失，并使七牛云完全免责。

5.2. 如果第三方机构或个人对您使用七牛云服务所涉及的相关素材的知识产权归属提出质疑或投诉，您有责任出具相关知识产权证明材料，并配合七牛云相关投诉处理工作。

5.3. 您承认七牛云向您提供的任何资料、技术或技术支持、软件、服务等的知识产权均属于七牛云或第三方所有。除七牛云或第三方明示同意外，您无权复制、传播、转让、许可或提供他人使用上述资源，否则应承担相应的责任。

# 6. 保密条款 [#6-保密条款]

6.1. 保密资料指由一方向另一方披露的所有技术及非技术信息(包括但不限于产品资料，产品计划，价格，财务及营销规划，业务战略，客户信息，客户数据，研发资料，软件硬件，API应用数据接口，技术说明，设计，特殊公式，特殊算法等)。

6.2. 本服务条款任何一方同意对获悉的对方之上述保密资料予以保密，并严格限制接触上述保密资料的员工遵守本条之保密义务。除非国家机关依法强制要求或上述保密资料已经进入公有领域外，接受保密资料的一方不得对外披露。

6.3. 本服务条款双方明确认可保密资料是双方的重点保密信息并是各自的重要资产，本服务条款双方同意尽最大的努力保护上述保密资料等不被披露。一旦发现有上述保密资料泄露事件，双方应合作采取一切合理措施避免或者减轻损害后果的产生。

6.4. 本条款不因本服务条款的终止而失效。

# 7. 期限与终止 [#7-期限与终止]

7.1. 服务期限自您创建任一云服务器服务成功之日起计算，而非以您获得云服务器服务的管理员身份（包括获取了管理员登录号和密码）为依据。具体服务期限将根据您实际使用情况计算。云服务器服务创建成功后，您需进行网站开通前准备的（如办理网站经营许可证/网站备案手续等），准备期间包含在服务期限内。

7.2. 发生下列情形，服务期限提前终止：
7.2.1. 双方协商一致提前终止的；
7.2.2. 您严重违反本服务条款（包括但不限于a.您未按照协议约定履行付款义务，及/或b.您严重违反法律规定等），七牛云有权提前终止服务，并不退还您已经支付的费用；
7.2.3. 您理解并充分认可，虽然七牛云已经建立（并将根据技术的发展不断完善）必要的技术措施来防御包括计算机病毒、网络入侵和攻击破坏（包括但不限于DDOS）等危害网络安全的事项或行为（以下统称该等行为），但鉴于网络安全技术的局限性、相对性以及该等行为的不可预见性，因此如因您遭遇该等行为而给七牛云或者七牛云的其他的网络或服务器（包括但不限于本地及外地和国际的网络、服务器等）带来危害，或影响七牛云与国际互联网或者七牛云与特定网络、服务器及七牛云内部的通畅联系，七牛云可决定暂停或终止服务，如果终止服务的，将按照实际提供服务月份计算（不足一个月的按一个月计）服务费用，将剩余款项（如有）返还。
7.2.4. 七牛云可提前30天在 [https://portal.qiniu.com/qvm](https://portal.qiniu.com/qvm) 上通告或给您发网站内通知或书面通知的方式终止本服务条款。届时七牛云应将您已支付但未消费的款项退还至您的七牛云账户。

# 8. 违约责任 [#8-违约责任]

8.1. 本服务条款任何一方违约均须依法承担违约责任。

8.2. 您理解，鉴于计算机、互联网的特殊性，下述情况不属于七牛云违约：
8.2.1. 七牛云在进行服务器配置、维护时，需要短时间中断服务；
8.2.2. 由于Internet上的通路阻塞造成您网站访问速度下降。

8.3. 如因七牛云原因，造成您连续72小时不能正常使用服务的，您可以终止服务，但非七牛云控制之内的原因引起的除外。

8.4. 在任何情况下，七牛云均不对任何间接性、后果性、惩戒性、偶然性、特殊性的损害，包括您使用七牛云服务而遭受的利润损失承担责任（即使您已被告知该等损失的可能性）。

8.5. 在任何情况下，七牛云对本服务条款所承担的违约赔偿责任总额不超过违约服务对应之服务费总额。

# 9. 不可抗力 [#9-不可抗力]

9.1. 因不可抗力或者其他意外事件，使得本服务条款的履行不可能、不必要或者无意义的，遭受不可抗力、意外事件的一方不承担责任。

9.2. 不可抗力、意外事件是指不能预见、不能克服并不能避免且对一方或双方当事人造成重大影响的客观事件，包括但不限于自然灾害如洪水、地震、瘟疫流行等以及社会事件如战争、动乱、政府行为、电信主干线路中断、黑客、网路堵塞、电信部门技术调整和政府管制等。

# 10. 法律适用及争议解决 [#10-法律适用及争议解决]

10.1. 本服务条款受中华人民共和国法律管辖。

10.2. 在执行本服务条款过程中如发生纠纷，双方应及时协商解决。协商不成时，任何一方可直接向杭州市西湖区人民法院提起诉讼。

# 11. 附则 [#11-附则]

11.1. 七牛云在 [https://portal.qiniu.com/qvm](https://portal.qiniu.com/qvm) 相关页面上的服务说明、价格说明和您确认同意的订购页面是本服务条款不可分割的一部分。如果 [https://portal.qiniu.com/qvm](https://portal.qiniu.com/qvm) 相关页面上的服务说明、价格说明和您确认同意的订购页面与本服务条款有不一致之处，以本服务条款为准。

11.2. 七牛云有权以提前30天在官网上公布、或给您发网站内通知或书面通知的方式将本服务条款的权利义务全部或者部分转移给七牛云的关联公司。

11.3. 如果任何条款在性质上或其他方面理应地在此协议终止时继续存在，那么应视为继续存在的条款，这些条款包括但不局限于保证条款、保密条款、知识产权条款、法律适用及争议解决条款。


# API 概述 (/products/qvm/0-openapi-overview)



最近更新时间: 2022-02-18 15:43:35

本文适用基于 API URL 发起 HTTP/HTTPS 请求的用户。

发起 API 请求的 URL 由不同参数拼凑而成，有固定的 请求结构。URL 中包含 公共参数、您的 签名 和某个 API 的具体参数。

每篇 API 文档均给出了 URL 请求示例供您参考，但是为了方便显示，我们并没有编码这些 URL 示例，您需要在发起请求前自行编码。

我们根据您的签名验证了请求后，会 返回结果 给您。接口调用成功会显示返回参数，调用失败则显示相应报错，您可以根据公共错误码和具体 API 错误码分析排查。

# API 请求凭证 [#api-请求凭证]

> 详见 [《管理凭证》](/products/kodo/development-guidelines/security/access-token)

# API 请求域名 [#api-请求域名]

> [https://api-qvm.qiniu.com](https://api-qvm.qiniu.com)

# API 请求示例 [#api-请求示例]

```
POST /v1/vm/instance HTTP/1.1
Host: api-qvm.qiniu.com
X-Qiniu-Regionid: cn-beijing
Content-Type: application/json
Authorization: Qiniu <AccessToken>

{
  ...
}
```

# API 通用返回结果 [#api-通用返回结果]

返回结果由 JSON 格式组成。

为了便于查看和美观，API 文档返回示例均有换行和缩进等处理，实际返回结果无换行和缩进处理。

## 正常返回示例 [#正常返回示例]

接口调用成功后会返回接口返回参数和请求 ID，我们称这样的返回为正常返回。HTTP 状态码为 2xx。

```json
{
    "request_id": "4C467B38-3910-447D-87BC-AC049166F216", /* 请求 ID */
    "data": {} /* 返回结果数据 */
}
```

## 异常返回示例 [#异常返回示例]

接口调用出错后，会返回错误码、错误信息和请求 ID，我们称这样的返回为异常返回。HTTP 状态码为 4xx 或者 5xx。

您可以根据接口的错误提示进行排查错误。当您无法排查错误时，可以 提交工单 联系我们，并在工单中注明 RequestId。

```json
{
    "request_id": "540CFF28-407A-40B5-B6A5-74Bxxxxxxxxx", /* 请求 ID */
    "code": 400, /* 错误码 */
    "error_message": "invalid instance_type" /* 错误信息 */
}
```


# 常用公共参数信息 (/products/qvm/1-common-params)



最近更新时间: 2022-02-18 15:43:35

# 付费参数 [#付费参数]

\| 名称 | 类型 | 描述 |
\| ----- | ----- | ----- | ----- | ----- |
\| cost\_charge\_type | string | 付费类型，PrePaid: 预付费, PostPaid: 后付费 |
\| cost\_charge\_mode | string | 计费方式，不同产品的计费方式有不同，具体如下:<br />PayByBandwidth: 按照弹性 IP 带宽计费<br />PayByTraffic: 按照弹性 IP 流量计费<br />PayByDisk: 按磁盘使用计费<br />PayByInstance: 按主机规格使用计费<br />PayBySlbSpec: 按 SLB 实例规格计费<br />PayByRedis: 按 Redis 实例规格计费<br />PayByMongo: 按 Mongo 实例规格计费<br />PayByVRouterInterface: 按 VRouterInterface 实例规格计费<br />PayBy95: 按增强型95计费<br />PayByRds: 按 RDS 实例规格计费<br />PayByVpn: 按 vpn 规格计费<br />PayByNATGatewaySpec: 按高速通道规格计费<br />PayByNewBgpIp: 安全产品新 BGP\<br>PayByBgpIp: 安全产品高防<br />PayByWaf: 安全产品 WAF\<br>PayByPolarDB: 按 PolarDB 节点规格计费 |
\| cost\_period\_unit | int | 付费周期，取值: Hour, Day, Month, Year, 预付费只能取 Month, Year, 后付费只能取 Hour (常用), Day |
\| cost\_period | string | 付费周期长度 |


# 云主机和对象存储内网互通实践 (/products/qvm/0-qvm-kodo)



最近更新时间: 2023-03-30 11:21:06

七牛云主机 QVM 和七牛对象存储 KODO 可以使用**加速域名**来高速互通，避免绕行公网带来的网络质量不稳定问题，也可以免去数据在传输过程中被窃取的风险。

<br />

### **Region 和 Endpoint 对照表** [#region-和-endpoint-对照表]

目前支持**杭州1地域**的云主机可以访问**同区域**的对象存储服务，可以使用如下的加速访问域名：

| 云主机地域 | 对象存储地域 | 协议    | 对象存储内网访问加速域名                                                                                                                                                     | 专线带宽上限 |
| ----- | ------ | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| 杭州1   | 华东     | HTTP  | 上传：[http://free-qvm-z0-xs.qiniup.com](http://free-qvm-z0-xs.qiniup.com)<br />下载：[http://free-qvm-nbxs-gate-io.qiniu.com](http://free-qvm-nbxs-gate-io.qiniu.com) | 2 Gbps |
| 杭州1   | 华东     | HTTPS | 上传：[https://free-qvm-z0-xs.qiniup.com](https://free-qvm-z0-xs.qiniup.com)<br />下载：[https://qvm.qbox.me](https://qvm.qbox.me)                                     | 2 Gbps |
| 北京1   | 华北     | HTTP  | 暂不支持                                                                                                                                                             | 暂不支持   |
| 北京1   | 华北     | HTTPS | 暂不支持                                                                                                                                                             | 暂不支持   |
| 深圳1   | 华南     | HTTP  | 暂不支持                                                                                                                                                             | 暂不支持   |
| 深圳1   | 华南     | HTTPS | 暂不支持                                                                                                                                                             | 暂不支持   |

### **七牛云主机 QVM 通过 S3 接口访问七牛对象存储** [#七牛云主机-qvm-通过-s3-接口访问七牛对象存储]

* 杭州 1 区域域名： qvm-s3v2.qiniucs.com

# **操作步骤** [#操作步骤]

## 准备 [#准备]

我们以杭州 1举例介绍如何上传下载文件，在执行操作前，你需要准备：

* **云主机：** 准备一台资源池一杭州 1 的主机。如果你还没有对应的主机，请参考文档[创建实例](/products/qvm/0-qvm-linux-quickstart#2)前往创建主机

* **存储空间(Bucket)：** 创建华东的存储空间。您可以查考文档[创建空间](/products/kodo/0-console-quickstart#1)

* **AK/SK：** 你可以在七牛云控制台的[密钥管理](https://portal.qiniu.com/user/key)页面查看你的密钥

* **绑定域名**：准备一个 ICP 备案的域名，本文以`p68d9xi47.qiniuts.com`示例。

<br />

## 上传文件 [#上传文件]

通过七牛云[命令行工具(qshell)](/products/kodo/0-qshell#7)的`fput`命令执行上传操作：

```
# HTTP协议
/qshell-linux-x64 fput qvm-test qvm.txt qvm.txt -u http://free-qvm-z0-xs.qiniup.com

# HTTPS协议
/qshell-linux-x64 fput qvm-test qvm.txt qvm.txt -u https://free-qvm-z0-xs.qiniup.com
```

参数解析：

* `qvm-test`：存储空间名
* `http(s)://free-qvm-z0-xs.qiniup.com`：杭州 1 对应的专线上传域名

上传完成后，您可以[登录控制台](https://portal.qiniu.com/bucket)查看文件是否上传成功。您也可以通过云主机监控数据查看内网带宽。

<br />

## 下载文件 [#下载文件]

您需要将为空间绑定域名`p68d9xi47.qiniuts.com` ，然后将域名**CNAME** 到`free-qvm-nbxs-gate-io.qiniu.com `，关于如何 CNAME 请参考文档[如何配置域名的 CNAME](/faq/cdn/domain-name-configuration-problem/1322-how-to-configure-cname-domain-name)，再通过以下命令下载文件：

```
# HTTP协议
curl http://p68d9xi47.qiniuts.com/qvm.txt  -o t.txt

# HTTPS协议
curl https://p68d9xi47.qiniuts.com/qvm.txt -o t.txt
```

或者通过以下命令下载文件：

```
# HTTP协议
curl -H "Host: p68d9xi47.qiniuts.com" http://free-qvm-nbxs-gate-io.qiniu.com/qvm.txt  -o t.txt

# HTTPS协议
curl -H "Host: p68d9xi47.qiniuts.com" https://qvm.qbox.me/qvm.txt -o t.txt
```

参数解析：

* `p68d9xi47.qiniuts.com`：空间绑定域名，私有空间资源访问 [下载凭证](/products/kodo/development-guidelines/security/0-download-token) 使用该 Host
* `t.txt`：本地保存文件名


# 使用迁移工具迁移服务器至QVM (/products/qvm/1-server-migration-qiniu)



最近更新时间: 2021-03-15 10:51:08

<a id="step01" />

# **迁移工具** [#迁移工具]

迁云工具能将计算机磁盘中的操作系统、应用程序以及应用数据等迁移到虚拟环境或是虚拟磁盘分区。支持在线迁移物理机服务器、虚拟机、以及其他云平台的云主机至 QVM 管理控制台，实现统一部署资源的目的。

迁云工具支持迁移下列 64 位的 Windows 和 Linux 操作系统，包括：

| 操作系统    | 具体版本                                                                                                                                                                         |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Windows | <br />-  Windows Server 2003  <br />-  Windows Server 2008  <br />-  Windows Server 2012  <br />-  Windows Server 2016                                                       |
| Linux   | <br />-  CentOS 5/6/7  <br />-  Ubuntu 10/12/14/16  <br />-  Debian 7/8/9  <br />-  Red Hat 5/6/7 <br />-  SUSE 11.4/12.1/12.2  <br />-  OpenSUSE 13.1  <br />-  Gentoo 13.0 |

迁云工具是免费工具，不收取额外的费用。但是，在迁云过程中会涉及少量费用：

（1）迁云过程中，会创建快照以生成自定义镜像，该快照会按照实际占用容量收取少部分费用。

（2）迁云过程中，系统默认在你的账户下创建一个云主机实例做中转站，该中转实例产生的资源耗费默认付费模式为按量付费。

**迁云注意事项：**

* 执行迁移任务时，可以通过加大可用带宽来提高迁移速度。

* 迁云工具当前版本暂不支持迁移增量数据。对于源服务器上需要保持数据完整的业务，你可以选择一个业务空闲时段，暂时停止这些业务，再迁移数据。

* 为避免迁云失败，请勿停止、重启或者释放中转实例。迁云完成后，该中转实例会自动释放。但迁云失败后，中转实例会保留在控制台，此时，需要你前往控制台手动[删除实例](/products/qvm/cloud-server/instances/1-qvm-instance-overview#5)，以免造成不必要的扣费。

* 每成功迁云一次，配置文件 client\_data 会自动记录迁云成功后在 QVM 控制台创建的 QVM 实例的相关数据。再次迁云时，你需要使用初始下载的客户端配置文件。为避免迁云失败，尽量不修改配置文件 client\_data。

<a id="step011" />

**迁移云工具下载：**

* [Linux 64bits](http://p70nwjoid.bkt.clouddn.com/go2qvm_client1.5.1.5_linux_x86_64.zip)

* [Linux 32bits](http://p70nwjoid.bkt.clouddn.com/go2qvm_client1.5.1.5_linux_i386.zip)

* [Windows 64bits](http://p70nwjoid.bkt.clouddn.com/go2qvm_client1.5.1.5_windows_x86_64.zip)

* [Windows 32bits](http://p70nwjoid.bkt.clouddn.com/go2qvm_client1.5.1.5_windows_i386.zip)

迁云工具压缩包，解压后包含的文件列表如下：

* Windows 服务器

* Rsync 文件夹：迁云所需要依赖的应用，除筛选机制文件 Rsync\etc\rsync\_excludes\_win.txt 外，其余文件请勿手动修改。

* client\_data：迁云过程中的数据文件

* config.json：源服务器信息配置文件

* qvm\_client.exe：迁云工具主程序

* Linux 服务器

* client\_check：辅助程序

* client\_data：迁云过程中的数据文件

* config.json：源服务器信息配置文件

* rsync\_excludes\_linux.txt：筛选机制文件，设置不迁云的路径

* qvm\_client：迁云工具主程序

<br />

<a id="step02" />

# **Linux云主机迁移至QVM** [#linux云主机迁移至qvm]

迁云前期准备：

* 迁云之前，你需要确保待迁云的源服务器能够访问公网，便于传输数据至 QVM

* 确保系统本地时间与实际时间一致，否则日志文件会提示 TimeStamp 异常

* 确保待迁移的源服务器的安全组的出方向设置为全部允许

* 确保系统已关闭 SELinux。你可以运行`setenforce 0`临时关闭 SELinux

* 你需要以 root 身份运行迁云工具

* 如果你的源服务器系统是 CentOS 5 或者 Debian 7 等内核版本比较低并且自带 GRUB 程序版本低于 1.99 时。你可以预先[安装 1.9 以上版本的系统引导程序 GRUB](/products/qvm/1-server-migration-qiniu)

* 确保你已经安装了 Rsync 库：

* CentOS：运行`yum install rsync –y`

* Ubuntu：运行`apt-get install rsync –y`

* Debian：运行`apt-get install rsync –y`

* 其他发行版：参考发行版官网安装相关的文档

<br />

<a id="step021" />

### **示例一: 迁移一台无数据盘的 Linux 服务器** [#示例一-迁移一台无数据盘的-linux-服务器]

例如服务器配置信息为：

* 操作系统: Ubuntu 14.04 x86\_64

* 系统盘：20 GB

* 系统架构：64 位

迁云目标为：

* 目标地域：QVM 华北 2 地域 (cn-beijing)

* 镜像名称：TEST\_MIRROR\_Migration\_01

* 系统盘设置：40 GB

操作步骤：

\*\*1. \*\*登录待迁云的服务器、虚拟机或者云主机

\*\*2. \*\*将下载的迁云工具压缩包解压到指定的目录

\*\*3. \*\*在控制台[创建 	PublicKey/SecretKey](https://portal.qiniu.com/qvm/system/keys)，用于输出到配置文件 config.json 里，对应的配置信息如下：

```
{
    "public_key": "PublicKey",
    "secret_key": "SecretKey",
    "region_id": "cn-beijing",
    "image_name": "TEST_MIRROR_Migration_01",
    "system_disk_size": 40,
    "platform": "Ubuntu",
    "architecture": "x86_64",
    "data_disks": [],
    "bandwidth_limit": 0
}
```

参数说明：

| 参数名                 | 类型     | 是否必填 | 说明                                                                                                                                                                         |
| ------------------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PublicKey/SecretKey | string | 是    | 访问云主机 QVM 密钥对，你可以创建多对访问密钥，且可随时启用、禁用或着删除已经生成的访问密钥对                                                                                                                          |
| region\_id          | string | 是    | 你的服务器迁移入目标地域 ID，如 cn-beijing。关于目标地域 ID 的详细信息请参考文档[地域和可用区](/products/qvm/0-region-zone)                                                                                     |
| image\_name         | string | 是    | 为你的服务器镜像设定一个镜像名称，该名称不能与同一地域下现有镜像名重复。<br />-  长度为 \[2, 128] 个英文或中文字符，必须以大小字母或中文开头，可包含数字、点号`.`、下划线`_`或短横线`-` <br />-  镜像名称会显示在 QVM 控制台  <br />-  不能以 http\:// 和 https\:// 开头 |
| system\_disk\_size  | int    | 是    | 为系统盘指定大小，单位为 GB。取值范围；\[40, 500]。该参数取值需要大于源服务器系统盘实际占用大小，若源系统盘大小为 500 GB，实际占用 100 GB，那该参数取值只要大于 100 GB 即可                                                                    |
| platform            | string | 否    | 源服务器的操作系统。取值可以是：CentOS、Ubuntu、SUSE、OpenSUSE、Debian、RedHat 等。取值必须区分大小写，并保持空格一致。                                                                                             |
| architecture        | string | 否    | 系统架构。取值：<br />-  i386：32 位系统架构 <br />-  x86\_64：64 位系统架构                                                                                                                   |
| data\_disks         | array  | 否    | 数据盘列表，最多支持 16 块数据盘。该参数可以置为缩容数据盘的预期数值，单位为 GB，该值不能小于数据盘实际使用空间大小。                                                                                                             |
| bandwidth\_limit    | int    | 否    | 数据传输的带宽上限限制，单位为 KB/s。默认值：0                                                                                                                                                 |

\*\*6. \*\*运行`chmod +x ./qvm_client`

\*\*7. \*\*运行`./qvm_client`

\*\*8. \*\*当出现`Goto Qvm Finished!`提示时，前往 QVM 控制台镜像详情页查看结果；当出现`Goto Qvm Not Finished!`提示时，检查日志文件[排查故障](/products/qvm/1-cloud-host-migration-faq)。修复问题后，重新运行迁云工具，重新运行迁云工具即可恢复迁云工作，迁云工具会从上一次执行的进度中继续迁云，无需重头开始；当出现如下信息时：

![下载最新](/docs-assets/products/qvm/%287-best-practices%29/1-server-migration-qiniu/FjGtkIOlN3gHwVesB4zQsFHARgUC-bb28c5cdb583.webp)

请前往下载中心[下载最新版本工具 >>](#step011)

<br />

<a id="step022" />

### **示例二: 迁移一台带数据盘的 Linux 服务器** [#示例二-迁移一台带数据盘的-linux-服务器]

如果你的 Linux 服务器在示例一的基础上加入了 3 块数据盘，源目录和数据盘大小分别为：

* /mnt/disk1：100 GB

* /mnt/disk2：150 GB

* /mnt/disk3：200 GB

那么你可以根据如下信息配置 config.json 文件：

```
{
    "public_key": "PublicKey",
    "secret_key": "SecretKey",
    "region_id": "cn-beijing",
    "image_name": "TEST_MIRROR_Migration_01",
    "system_disk_size": 40,
    "platform": "Ubuntu",
    "architecture": "x86_64",
    "data_disks":  [ {
            "data_disk_index": 1,
            "data_disk_size": 100,
            "src_path": "/mnt/disk1"
        }, {
            "data_disk_index": 2,
            "data_disk_size": 150,
            "src_path": "/mnt/disk2"
        }, {
            "data_disk_index": 3,
            "data_disk_size": 200,
            "src_path": "/mnt/disk3"
        }
    ],
    "bandwidth_limit": 0
}
```

参数说明：

| 参数名                 | 类型     | 是否必填 | 说明                                                                                                                                                                                                                                                                                                                                         |
| ------------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| PublicKey/SecretKey | string | 是    | 访问云主机 QVM 密钥对，你可以创建多对访问密钥，且可随时启用、禁用或着删除已经生成的访问密钥对                                                                                                                                                                                                                                                                                          |
| region\_id          | string | 是    | 你的服务器迁移入目标地域 ID，如 cn-beijing。关于目标地域 ID 的详细信息请参考文档[地域和可用区](/products/qvm/0-region-zone)                                                                                                                                                                                                                                                     |
| image\_name         | string | 是    | 为你的服务器镜像设定一个镜像名称，该名称不能与同一地域下现有镜像名重复。<br />-  长度为 \[2, 128] 个英文或中文字符，必须以大小字母或中文开头，可包含数字、点号`.`、下划线`_`或短横线`-` <br />-  镜像名称会显示在 QVM 控制台  <br />-  不能以 http\:// 和 https\:// 开头                                                                                                                                                                 |
| system\_disk\_size  | int    | 是    | 为系统盘指定大小，单位为 GB。取值范围：\[40, 500]。该参数取值需要大于源服务器系统盘实际占用大小，若源系统盘大小为 500 GB，实际占用 100 GB，那该参数取值只要大于 100 GB 即可                                                                                                                                                                                                                                    |
| platform            | string | 否    | 源服务器的操作系统。取值可以是：CentOS、Ubuntu、SUSE、OpenSUSE、Debian、RedHat 等。取值必须区分大小写，并保持空格一致。                                                                                                                                                                                                                                                             |
| architecture        | string | 否    | 系统架构。取值：<br />-  i386：32 位系统架构 <br />-  x86\_64：64 位系统架构                                                                                                                                                                                                                                                                                   |
| data\_disks         | array  | 否    | 数据盘列表，最多支持 16 块数据盘。该参数可以置为缩容数据盘的预期数值，单位为 GB，该值不能小于数据盘实际使用空间大小。                                                                                                                                                                                                                                                                             |
| data\_disk\_index   | int    | 是    | 数据盘序号。取值范围：\[1, 16]，初始值：1                                                                                                                                                                                                                                                                                                                  |
| data\_disk\_size    | int    | 是    | 数据盘大小。单位为 GB。取值范围：\[20, 32768]，该参数取值需要大于源服务器数据盘实际占用大小，例如，源数据盘大小为 500 GB，实际占用 100 GB，那该参数取值只要大于 100 GB 即可。                                                                                                                                                                                                                                  |
| src\_path           | string | 是    | 数据盘源目录。Linux 指定目录，例如，/mnt/disk1、/mnt/disk2 或者 /mnt/disk3。\*\*注意：\*\*不能配置为根目录或者系统目录，例如，/bin、/boot、/dev、/etc、/lib、/lib64、/sbin、/usr 和 /var。迁移带数据盘的 Linux 服务器后，启动实例时默认不挂载数据盘。你可以在启动 QVM 实例后运行`ls /dev/vd`命令查看数据盘设备，根据实际需要手动挂载，并编辑`/etc/fstab`配置开机自动挂载。更多详情，请参考[Linux 格式化和挂载数据盘](/products/qvm/0-qvm-linux-quickstart#linux-mount-format-disk) |
| bandwidth\_limit    | int    | 否    | 数据传输的带宽上限限制，单位为 KB/s。默认值：0                                                                                                                                                                                                                                                                                                                 |

<br />

<a id="step03" />

# **Windows云主机/物理机迁移至QVM** [#windows云主机物理机迁移至qvm]

迁云前期准备：

* 迁云之前，你需要确保待迁云的源服务器能够访问公网，便于传输数据至 QVM

* 确保系统本地时间与实际时间一致，否则日志文件会提示 TimeStamp 异常

* 确保待迁移的源服务器的安全组的出方向设置为全部允许

<br />

<a id="step031" />

### **示例一: 迁移一台无数据盘的 Windows 服务器** [#示例一-迁移一台无数据盘的-windows-服务器]

例如服务器配置信息为：

* 操作系统: Windows Server 2012R2 Standard 64bit

* 系统盘：40 GB

* 系统架构：64 位

迁云目标为：

* 目标地域：QVM 华北 2 地域 (cn-beijing)

* 镜像名称：TEST\_MIRROR\_Migration\_02

* 系统盘设置：50 GB

操作步骤：

\*\*1. \*\*登录待迁云的服务器、虚拟机或者云主机

\*\*2. \*\*将下载的迁云工具压缩包解压到指定的目录

\*\*3. \*\*在控制台[创建 	PublicKey/SecretKey](https://portal.qiniu.com/qvm/system/keys)，用于输出到配置文件 config.json 里，对应的配置信息如下：

```
{
    "public_key": "PublicKey",
    "secret_key": "SecretKey",
    "region_id": "cn-beijing",
    "image_name": "TEST_MIRROR_Migration_02",
    "system_disk_size": 40,
    "platform": "Windows Server 2012",
    "architecture": "x86_64",
    "data_disks": [],
    "bandwidth_limit": 0
}
```

参数说明：

| 参数名                 | 类型     | 是否必填 | 说明                                                                                                                                                                         |
| ------------------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PublicKey/SecretKey | string | 是    | 访问云主机 QVM 密钥对，你可以创建多对访问密钥，且可随时启用、禁用或着删除已经生成的访问密钥对                                                                                                                          |
| region\_id          | string | 是    | 你的服务器迁移入目标地域 ID，如 cn-beijing。关于目标地域 ID 的详细信息请参考文档[地域和可用区](/products/qvm/0-region-zone)                                                                                     |
| image\_name         | string | 是    | 为你的服务器镜像设定一个镜像名称，该名称不能与同一地域下现有镜像名重复。<br />-  长度为 \[2, 128] 个英文或中文字符，必须以大小字母或中文开头，可包含数字、点号`.`、下划线`_`或短横线`-` <br />-  镜像名称会显示在 QVM 控制台  <br />-  不能以 http\:// 和 https\:// 开头 |
| system\_disk\_size  | int    | 是    | 为系统盘指定大小，单位为 GB。取值范围：\[40, 500]。该参数取值需要大于源服务器系统盘实际占用大小，若源系统盘大小为 500 GB，实际占用 100 GB，那该参数取值只要大于 100 GB 即可                                                                    |
| platform            | string | 否    | 源服务器的操作系统。可以是：Windows Server 2003、Windows Server 2008、Windows Server 2012、Windows Server 2016 等。取值必须区分大小写，并保持空格一致。                                                         |
| architecture        | string | 否    | 系统架构。取值：<br />-  i386：32 位系统架构 <br />-  x86\_64：64 位系统架构                                                                                                                   |
| data\_disks         | array  | 否    | 数据盘列表，最多支持 16 块数据盘。该参数可以置为缩容数据盘的预期数值，单位为 GB，该值不能小于数据盘实际使用空间大小。                                                                                                             |
| bandwidth\_limit    | int    | 否    | 数据传输的带宽上限限制，单位为 KB/s。默认值：0                                                                                                                                                 |

**6. **右击 qvm\_client.exe，选择**以管理员身份运行**

\*\*7. \*\*当出现`Goto Qvm Finished!`提示时，前往 QVM 控制台镜像详情页查看结果；当出现`Goto Qvm Not Finished!`提示时，检查日志文件[排查故障](/products/qvm/1-cloud-host-migration-faq)。修复问题后，重新运行迁云工具，重新运行迁云工具即可恢复迁云工作，迁云工具会从上一次执行的进度中继续迁云，无需重头开始。当出现如下信息时：

![下载最新](/docs-assets/products/qvm/%287-best-practices%29/1-server-migration-qiniu/FjGtkIOlN3gHwVesB4zQsFHARgUC-bb28c5cdb583.webp)

请前往下载中心[下载最新版本工具 >>](#step011)

<br />

<a id="step032" />

### **示例二: 迁移一台带数据盘的 Windows 服务器** [#示例二-迁移一台带数据盘的-windows-服务器]

如果你的 Windows 服务器在示例一的基础上加入了 3 块数据盘，源目录和数据盘大小分别为：

* D：100 GB
* E：150 GB
* F：200 GB

那么你可以根据如下信息配置 config.json 文件：

```
{
    "public_key": "PublicKey",
    "secret_key": "SecretKey",
    "region_id": "cn-beijing",
    "image_name": "TEST_MIRROR_Migration_02",
    "system_disk_size": 40,
    "platform": "Windows Server 2012",
    "architecture": "x86_64",
    "data_disks":  [ {
            "data_disk_index": 1,
            "data_disk_size": 100,
            "src_path": "D:"
        }, {
            "data_disk_index": 2,
            "data_disk_size": 150,
            "src_path": "E:"
        }, {
            "data_disk_index": 3,
            "data_disk_size": 200,
            "src_path": "F:"
        }
    ],
    "bandwidth_limit": 0
}
```

参数说明：

| 参数名                 | 类型     | 是否必填 | 说明                                                                                                                                                                         |
| ------------------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PublicKey/SecretKey | string | 是    | 访问云主机 QVM 密钥对，你可以创建多对访问密钥，且可随时启用、禁用或着删除已经生成的访问密钥对                                                                                                                          |
| region\_id          | string | 是    | 你的服务器迁移入目标地域 ID，如 cn-beijing。关于目标地域 ID 的详细信息请参考文档[地域和可用区](/products/qvm/0-region-zone)                                                                                     |
| image\_name         | string | 是    | 为你的服务器镜像设定一个镜像名称，该名称不能与同一地域下现有镜像名重复。<br />-  长度为 \[2, 128] 个英文或中文字符，必须以大小字母或中文开头，可包含数字、点号`.`、下划线`_`或短横线`-` <br />-  镜像名称会显示在 QVM 控制台  <br />-  不能以 http\:// 和 https\:// 开头 |
| system\_disk\_size  | int    | 是    | 为系统盘指定大小，单位为 GB。取值范围： \[40, 500]。该参数取值需要大于源服务器系统盘实际占用大小，若源系统盘大小为 500 GB，实际占用 100 GB，那该参数取值只要大于 100 GB 即可                                                                   |
| platform            | string | 否    | 源服务器的操作系统。可以是：Windows Server 2003、Windows Server 2008、Windows Server 2012、Windows Server 2016 等。取值必须区分大小写，并保持空格一致。                                                         |
| architecture        | string | 否    | 系统架构。取值：<br />-  i386：32 位系统架构 <br />-  x86\_64：64 位系统架构                                                                                                                   |
| data\_disks         | array  | 否    | 数据盘列表，最多支持 16 块数据盘。该参数可以置为缩容数据盘的预期数值，单位为 GB，该值不能小于数据盘实际使用空间大小。                                                                                                             |
| data\_disk\_index   | int    | 是    | 数据盘序号。取值范围：\[1, 16]，初始值：1                                                                                                                                                  |
| data\_disk\_size    | int    | 是    | 数据盘大小。单位为 GB。取值范围：\[20, 32768]，该参数取值需要大于源服务器数据盘实际占用大小，若源数据盘大小为 500 GB，实际占用 100 GB，那该参数取值只要大于 100 GB 即可。                                                                    |
| src\_path           | string | 是    | 数据盘源目录。Windows 指定盘符，例如，D、E、F                                                                                                                                               |
| bandwidth\_limit    | int    | 否    | 数据传输的带宽上限限制，单位为 KB/s。默认值：0                                                                                                                                                 |


# 阿里云镜像共享到七牛云创建主机实例 (/products/qvm/10-sharedmirror)



最近更新时间: 2022-03-03 17:45:44

# 阿里云侧操作 [#阿里云侧操作]

* 登录阿里云 ECS 管理控制台。
* 在左侧导航栏，选择实例与镜像 > 镜像。
* 在顶部菜单栏左上角处，选择地域。
* 在自定义镜像页签，选中待共享的自定义镜像。在操作栏，单击共享镜像。
* 在共享镜像对话框中，输入待共享用户的账号 ID（联系七牛云技术支持获取）并选中提示信息，然后单击共享镜像。

提示：阿里云账号 ID 的获取方式为：将鼠标移至控制台右上角的用户头像，在弹出的用户信息框中，如果标识了账号为主账号，则显示的账号 ID 即为阿里云账号 ID。

![image.png](/docs-assets/products/qvm/%287-best-practices%29/10-sharedmirror/FsVuXIM3sl45PbNq3MO5Z1OPu1tM-c9605e5ee5ba.webp)

# 七牛云侧操作 [#七牛云侧操作]

* 联系七牛云技术支持将共享过来的镜像复制（复制镜像将在指定地域生成快照，会产生额外费用，请知悉）
* 登录七牛云 QVM 管理控制台。
* 在左侧导航栏，选择云主机 > 镜像。
* 选中共享的镜像，点击操作栏的「创建实例」

![image.png](/docs-assets/products/qvm/%287-best-practices%29/10-sharedmirror/Fo3Kdy9y9CArwpHhs0nIk7fZNC3J-84b4e600d088.webp)

# 异常情况排查： [#异常情况排查]

1、创建云主机实例无法选中共享的私有镜像

1. 确保云主机实例地域是否和镜像地域相同
2. 检查是否是镜像缺少 cloudinit 标记

* 登录源服务器
* 运行以下命令检查是否已安装 cloudinit.

```text
which cloud-init
```

无路径输出信息表示未安装，您需要安装阿里云版cloud-init.

* 在服务器中安装 cloud-init 参考文档 [https://help.aliyun.com/document\_detail/57803.html](https://help.aliyun.com/document_detail/57803.html)
* 如还有问题，请[提交工单](https://support.qiniu.com/tickets/category)联系七牛云技术支持


# 部署高可用计算集群实践 (/products/qvm/11-deployment-practice-of-high-availability-clusters)



最近更新时间: 2022-02-17 16:41:57

# 前提条件 [#前提条件]

如果需要为伸缩组关联负载均衡 SLB 实例，请确保满足以下条件：

* 您持有一个或多个处于运行中状态的 SLB 实例。
* SLB实例和伸缩组必须位于同一地域。
* SLB实例至少配置一个监听。具体操作，请参见监听概述。
* SLB实例必须开启健康检查。具体操作，请参见配置健康检查。
* SLB实例和伸缩组的网络类型：
* SLB实例和伸缩组必须是同一专有网络。

如果需要为伸缩组关联 RDS 实例，请确保满足以下条件：

* 您持有一个或多个处于运行中状态的 RDS 实例。
* RDS 实例和伸缩组必须位于同一地域。

# 业务场景 [#业务场景]

某在线广告提供商应用机器学习精准投放广告，在业务高峰期会临时需要大量计算资源，成本较高，也可能存在 QVM 实例库存不足、手动创建 QVM 实例操作仓促、QVM 实例临时停止服务等问题，存在一定的业务受损风险。

假设您的应用面向以下场景，也可以采用类似解决方案：

* 分布式大数据计算。
* 人工智能训练。

# 解决方案 [#解决方案]

弹性伸缩可以快速交付一个计算集群，同时利用均衡分布策略自动将计算节点分散在多个可用区，并实时检测 QVM 实例的运行状况，确保计算集群的高可用性。

方案如下：

* 通过弹性伸缩将计算节点分散在多个可用区，同时指定多种实例规格。
  ![截屏2022-02-17 下午4.14.51.png](/docs-assets/products/qvm/%287-best-practices%29/11-deployment-practice-of-high-availability-clusters/Fmg_7neBYE7NCxjkhci_oBj4slGh-375864859e60.webp)

# 业务收益 [#业务收益]

利用弹性伸缩部署高可用计算集群，您可以获得以下收益：

* 零运维成本
  您只需提前配置扩缩容策略。负载增加时，伸缩组自动创建 QVM 实例，并将 QVM 实例添加到 RDS 实例的白名单；负载降低时，伸缩组自动将 QVM 实例从 RDS 实例的白名单中移除，然后释放 QVM 实例。整个过程自动触发和完成，无需人工干预。
* 超高性价比
  弹性伸缩支持使用突发性能型实例，性价比高。
* 天然高可用
  均衡分布策略实现自动分散部署计算节点，避免因单可用区中库存不足等原因导致服务不可用，而且默认开启的健康检查功能可以确保伸缩组内 QVM 实例都处于可用状态

# 操作步骤 [#操作步骤]

请根据您的业务架构评估业务模块，为需要部署高可用集群的业务模块创建伸缩组，并为伸缩配置选择应用实例的自定义镜像，确保自动创建出的 QVM 实例符合应用的要求。

1.登录 QVM 控制台。

2.在侧边栏选择弹性伸缩。

3.创建一个伸缩组。

* 组内最小实例数设置为100。
* 选择多个可用区下的虚拟交换机。
* 多区扩缩容策略设置为均衡分布策略。
* 绑定当前业务模块所使用的 RDS 实例。

4.在伸缩组管理页面，找到新创建的伸缩组，打开伸缩组详情页面。

* 创建一个伸缩配置。
* 镜像设置为您的自定义镜像。
* 请根据需要配置其它信息

5.启用伸缩配置和伸缩组。

# 执行结果 [#执行结果]

启用伸缩组后，伸缩组自动在所选可用区中均衡部署满100台 QVM 实例，单可用区中因库存不足等原因引发问题时，对整个应用的影响有限。伸缩组自动移除进入不健康状态的 QVM 实例并创建新的 QVM 实例。保证集群高可用性的同时，也降低了成本。


# 设置高防根据域名回源到不同的业务服务器 (/products/qvm/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source)



最近更新时间: 2021-03-15 10:51:08

### 目前高防暂时不支持直接按域名回源到不同业务服务器，可以通过负载均衡来设置转发规则 [#目前高防暂时不支持直接按域名回源到不同业务服务器可以通过负载均衡来设置转发规则]

* **高防** 先回源到 **负载均衡**
* **负载均衡** 按域名回源到不同的业务服务器

#### 配置流程图示： [#配置流程图示]

* 创建负载均衡
  * 注意事项：
    * 负载均衡和业务云主机要在相同的区域
    * 负载均衡和业务云主机要在相同的专有网络内

![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/Fi4CceK5wW-2cRBR-mATEBYrPcj3-280ec5565b34.webp)
![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/FuM2-lET87lQ9D8YKagcL1FgoZki-ce53cdd3939f.webp)

* 负载均衡添加虚拟服务器组

![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/FmW8tTInI-j4o8I7vVwPywmwQ3eA-bbd800222583.webp)
![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/FhkK4lvv-acf4aJvi5qjI8GBkAhz-cf8513487b70.webp)
![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/FgrOujrrCk4iPag8ARnH_4fWPnqa-a3b20cc8db67.webp)
![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/Fkq4NSWV4HIJV6DyYDt-H88_A9ND-db3c590306e4.webp)

* 负载均衡创建监听器

![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/Fq7nj0pCeQeEvdnBeEublgnHLEYe-7cce33156f85.webp)
![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/FmZVBtWMCmxj9DtHBeahv_ovb4JH-c0eff22260ab.webp)

* 负载均衡监听器设置转发规则

![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/Fg_eAxXmmiBJ9fH7_5oydyKczOlw-cc2f0b7ca875.webp)
![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/FvVe3RRDEWaEh6OodzJdZ8OQJ23t-2b4d7495071e.webp)
![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/FiaPUZPC1Ronaer7-V91cp41OSHm-73434e50b27f.webp)
![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/Fgx9nhg6-_bShzQ6Oiai5uQnny7i-48aefb6031de.webp)

* 更改高防回源ip ，更改回源到 负载均衡 ip

![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/FugmKPXUamA5qI29pLzw4MGihtfP-56708e0ff1c3.webp)
![](/docs-assets/products/qvm/%287-best-practices%29/2-how-to-make-the-defense-support-according-to-the-domain-name-back-to-the-source/FvH74ACth1IoRVn4KQ51bdkf_lMJ-82f52fc75649.webp)


# 通过用 iptables 做 NAT 代理上网 (/products/qvm/3-by-using-iptables-do-nat-the-web-site)



最近更新时间: 2022-03-03 10:47:17

### 同一个vpc 内的两台主机（一台有公网ip ，一台无 公网ip ）想要通过用 iptables 做NAT代理上网 [#同一个vpc-内的两台主机一台有公网ip-一台无-公网ip-想要通过用-iptables-做nat代理上网]

* 内网主机： A eth0: 192.168.2.209
* 外网主机： B eth0: 192.168.2.208 外网地址：47.101.128.169

### 设置步骤 [#设置步骤]

* 在 B 主机上做转发：
  * 1、sed -i 's/net.ipv4.ip\_forward = 0/net.ipv4.ip\_forward = 1/g' /etc/sysctl.conf // 开启转发
  * 2、sysctl --p // 让转发生效
  * 3、iptables -t nat -I POSTROUTING -s 192.168.0.0/16 -j SNAT --to-source 192.168.2.208 // 192.168.0.0/16 为 vpc 内网网段、192.168.2.208 为 B 主机内网 ip
  * 4、service iptables save
  * 5、/etc/init.d/iptables restart // 是转发规则生效
  * 6、iptables -t -L -n nat //查看转发规则

* 在七牛控制台添加路由转发

* 测试是否是可以访问外网

![](/docs-assets/products/qvm/%287-best-practices%29/3-by-using-iptables-do-nat-the-web-site/FhSrUAIDG2W_7hclqPmlQPDXgb81-06080a82c214.webp)


# QVM安全组实践（一） (/products/qvm/4-qvm-security-group-practice-a)



最近更新时间: 2021-03-15 10:51:08

本文介绍配置安全组的入方向规则的最佳实践。您可以通过配置安全组规则，允许或禁止安全组内的QVM实例对公网或私网的访问。

# 安全组实践建议 [#安全组实践建议]

您在云端安全组提供类似虚拟防火墙功能，用于设置单台或多台QVM实例的网络访问控制，是重要的安全隔离手段。创建QVM实例时，您必须选择一个安全组。您还可以添加安全组规则，对某个安全组下的所有QVM实例的出方向和入方向进行网络控制。

在使用安全组前，您应先了解以下实践建议：

* 最重要的规则：安全组应作为白名单使用。
* 开放应用出入规则时应遵循最小授权原则。例如，您可以选择开放具体的端口，如80端口。
* 不应使用一个安全组管理所有应用，因为不同的分层一定有不同的需求。
* 对于分布式应用来说，不同的应用类型应该使用不同的安全组，例如，您应对Web层、Service层、Database层、Cache层使用不同的安全组，暴露不同的出入规则和权限。
* 避免为每台实例单独设置一个安全组，控制管理成本。
* 优先考虑专有网络VPC。
* 不需要公网访问的资源不应提供公网IP。
* 尽可能保持单个安全组的规则简洁。因为一台实例最多可以加入五个安全组，一个安全组最多可以包括200条安全组规则，所以一台QVM实例可能同时应用数百条安全组规则。您可以聚合所有分配的安全规则以判断是否允许流入或流出，但是，如果单个安全组规则很复杂，就会增加管理的复杂度。
* 七牛云的控制台提供了克隆安全组和安全组规则的功能。如果您想要修改线上的安全组和规则，您应先克隆一个安全组，再在克隆的安全组上进行调试，避免直接影响线上应用。

**说明** 调整线上的安全组的出入规则是比较危险的动作。如果您无法确定，不应随意更新安全组出入规则的设置。

# 避免设置0.0.0.0/0授权对象 [#避免设置00000授权对象]

允许全部入网访问是经常犯的错误。使用0.0.0.0/0意味着所有的端口都对外暴露了访问权限。这是非常不安全的。正确的做法是，先拒绝所有的端口对外开放。安全组应该是白名单访问。例如，如果您需要暴露Web服务，默认情况下可以只开放80、8080和443之类的常用TCP端口，其它的端口都应关闭。

\{ "IpProtocol" : "tcp", "FromPort" : "80", "ToPort" : "80", "SourceCidrIp" : "0.0.0.0/0", "Policy": "accept"} ,\{ "IpProtocol" : "tcp", "FromPort" : "8080", "ToPort" : "8080", "SourceCidrIp" : "0.0.0.0/0", "Policy": "accept"} ,\{ "IpProtocol" : "tcp", "FromPort" : "443", "ToPort" : "443", "SourceCidrIp" : "0.0.0.0/0", "Policy": "accept"} ,

# 关闭不需要的入网规则 [#关闭不需要的入网规则]

如果您当前使用的入规则已经包含了0.0.0.0/0，您需要重新审视自己的应用需要对外暴露的端口和服务。如果确定不想让某些端口直接对外提供服务，您可以加一条拒绝的规则。例如，如果您的服务器上安装了MySQL数据库服务，默认情况下您不应该将3306端口暴露到公网，此时，您可以添加一条拒绝规则，如下所示，并将其优先级设为100，即优先级最低。

\{ "IpProtocol" : "tcp", "FromPort" : "3306", "ToPort" : "3306", "SourceCidrIp" : "0.0.0.0/0", "Policy": "drop", Priority: 100} ,

上面的调整会导致所有的端口都不能访问3306端口，极有可能会阻止您正常的业务需求。此时，您可以通过授权另外一个安全组的资源进行入规则访问。

# 以安全组为授权对象添加规则 [#以安全组为授权对象添加规则]

不同的安全组按照最小原则开放相应的出入规则。对于不同的应用分层应该使用不同的安全组，不同的安全组应有相应的出入规则。

例如，如果是分布式应用，您会区分不同的安全组，但是，不同的安全组可能网络不通，此时您不应该直接授权IP或者CIDR网段，而是直接授权另外一个安全组ID的所有的资源都可以直接访问。例如，您的应用对Web、Database分别创建了不同的安全组：sg-
web和sg-database。在sg-database中，您可以添加如下规则，授权所有的sg-web安全组的资源访问您的3306端口。

\{ "IpProtocol" : "tcp", "FromPort" : "3306", "ToPort" : "3306", "SourceGroupId" : "sg-web", "Policy": "accept", Priority: 2} ,

# 以IP地址段为授权对象添加规则 [#以ip地址段为授权对象添加规则]

经典网络中，因为网段不太可控，建议您使用安全组ID来授信入网规则。

VPC网络中，您可以自己通过不同的VSwitch设置不同的IP域，规划IP地址。所以，在VPC网络中，您可以默认拒绝所有的访问，再授信自己的专有网络的网段访问，直接授信可以相信的CIDR网段。

\{ "IpProtocol" : "icmp", "FromPort" : "-1", "ToPort" : "-1", "SourceCidrIp" : "10.0.0.0/24", Priority: 2} ,\{ "IpProtocol" : "tcp", "FromPort" : "0", "ToPort" : "65535", "SourceCidrIp" : "10.0.0.0/24", Priority: 2} ,\{ "IpProtocol" : "udp", "FromPort" : "0", "ToPort" : "65535", "SourceCidrIp" : "10.0.0.0/24", Priority: 2} ,

# 变更安全组规则步骤 [#变更安全组规则步骤]

变更安全组规则可能会影响您的实例间的网络通信。为了保证必要的网络通信不受影响，您应先尝试以下方法放行必要的实例，再执行安全组策略收紧变更。

**说明** 执行收紧变更后，应观察一段时间，确认业务应用无异常后再执行其它必要的变更。

* 新建一个安全组，将需要互通访问的实例加入这个安全组，再执行变更操作。
* 如果授权类型为安全组访问，则将需要互通访问的对端实例所绑定的安全组ID添加为授权对象。
* 如果授权类型为地址段访问，则将需要互通访问的对端实例内网IP添加为授权对象。


# QVM实例数据传输的实现方式 (/products/qvm/5-the-realization-of-the-data-transmission-way-qvm-instance)



最近更新时间: 2021-03-15 10:51:08

本文首先简单介绍文件传输的基本原理，然后详细介绍类Unix/Linux、Windows平台上常用的文件传输方式，并针对它们各自的特点进行比较，让您对文件传输方式有比较详尽地了解，从而能够根据不同的需要选择合适的文件传输方式。

# 文件传输原理 [#文件传输原理]

文件传输是信息传输的一种形式，它是在数据源和数据宿之间传送文件数据的过程，也称文件数据通信。操作系统把文件数据提取到内存中做暂存，再复制到目的地，加密就是在文件外加了一个壳，文件本身还是一个整体，复制只是把这个整体转移到其它地方，不需要解密，只有打开压缩包时才需解密。一个大文件作为一个数据整体，是不可能瞬间从一台主机转移到其它的主机，传输是一个持续的过程，但不是把文件分割了，因此，如果在传输的过程中意外中断，目标路径中是不会有传输的文件，另外，如果传输的是多个文件，那么，这些文件是按顺序分别传输，如果中间中断，则正在传输的文件会传输失败，但是，之前已经传完的文件传输成功（如果传输的是文件压缩包，那么，不管里面有几个文件，它本身被视为一个文件）。

通常我们看到的NC、FTP、SCP、NFS等等，都是可以用来传输文件数据的工具，下面我们将详细介绍主要文件传输工具的特点以及用法。

# NETCAT [#netcat]

在网络工具中有“瑞士军刀”的美誉，它功能强大，作为网络工具的同时，它传输文件的能力也不容小觑。

常用参数说明如下表所示。

| 参数          | 说明                             |
| ----------- | ------------------------------ |
| -g \<网关>    | 设置路由器跃程通信网关，最多可设置8个            |
| -G \<指向器数目> | 设置来源路由指向器，其数值为4的倍数             |
| -i \<延迟秒数>  | 设置时间间隔，以便传送信息及扫描通信端口           |
| -l          | 使用监听模式，管控传入的资料                 |
| -o \<输出文件>  | 指定文件名称，把往来传输的数据以16进制字码倾倒成该文件保存 |
| -p \<通信端口>  | 设置本地主机使用的通信端口                  |
| -r          | 指定本地与远端主机的通信端口                 |
| -u          | 使用UDP传输协议                      |
| -v          | 显示指令执行过程                       |
| -w \<超时秒数>  | 设置等待连线的时间                      |
| -z          | 使用0输入/输出模式，只在扫描通信端口时使用         |
| -n          | 直接使用IP地址，而不通过域名服务器             |

# 用法举例 [#用法举例]

* 端口扫描21\~24（以IP192.168.2.34为例）。

  nc -v -w 2 192.168.2.34 -z 21-24

返回示例：

nc: connect to 192.168.2.34 port 21 (tcp) failed: Connection refusedConnection to 192.168.2.34 22 port \[tcp/ssh] succeeded!nc: connect to 192.168.2.34 port 23 (tcp) failed: Connection refusednc: connect to 192.168.2.34 port 24 (tcp) failed: Connection refused

* 从192.168.2.33拷贝文件到192.168.2.34。
  * 在192.168.2.34上：`nc-l 1234 > test.txt`
  * 在192.168.2.33上：`nc192.168.2.34 < test.txt`
* 用nc命令操作memcached。
  * 存储数据：`printf “set key 0 10 6rnresultrn” \|nc 192.168.2.34 11211`
  * 获取数据：`printf “get keyrn” \|nc 192.168.2.34 11211`
  * 删除数据：`printf “delete keyrn” \|nc 192.168.2.34 11211`
  * 查看状态：`printf “statsrn” \|nc 192.168.2.34 11211`
  * 模拟top命令查看状态：`watch “echo stats” \|nc 192.168.2.34 11211`
  * 清空缓存：

    printf “flush\_allrn” |nc 192.168.2.34 11211       #谨慎操作，清空了缓存就没了

# SCP安全拷贝 [#scp安全拷贝]

SCP（ Secure
Copy）命令的用法和RCP命令格式非常类似，区别就是SCP提供更安全保障，SCP在需要进行验证时会要求您输入密码或口令，一般推荐使用SCP命令，因为它比RCP更安全。SCP命令使用SSH来传输数据，并使用与SSH相同的认证模式，提供同样的安全保障，SSH是目前较可靠得，为远程登录会话和其他网络服务提供安全性的协议，利用SSH协议可以有效防止远程管理过程中的信息泄露问题。SCP是基于SSH的应用，所以进行数据传输的机器上必须支持SSH服务。

SCP的特点如下：

SCP类似于RCP，它能够保留一个特定文件系统上的文件属性，能够保留文件属性或者需要递归的拷贝子目录。

SCP具备更好的文件传输保密性。与此同时，付出的代价就是文件传输时需要输入密码而且涉及到SSH的一些配置问题，这些都影响其使用的方便性，对于有特定需求的用户，是比较合适的传输工具。

SCP的常用示例如下：

1. 使用SCP命令，需要输入密码，如果不想每次都输入，可以通过配置SSH，这样在两台机器间拷贝文件时不需要每次都输入用户名和密码。

生成RSA类型的密钥：
!\[返回示例]\([http://qey2kbifv.hn-](http://qey2kbifv.hn-)
bkt.clouddn.com/2020-08-13/WVEgDbsQdFmTAqYac7yn.png)

上述命令生成RSA类型的密钥。在提示密钥的保存路径和密码时，可以直接回车使用默认路径和空密码。这样，生成的公共密钥保存在/.ssh/id\_rsa.pub，私有密钥保存在
/.ssh/id\_rsa。然后把这个密钥对中的公共密钥的内容复制到要访问的机器上的/.ssh/authorized\_keys文件中。这样，下次再访问那台机器时，就不用输入密码了。

2. 在两台Linux主机间复制文件。

命令基本格式：

```
scp [可选参数] file_source file_target
```

* 从本地复制到远程（如下四种方式）：

```
scp local_file remote_username@remote_ip:remote_folder
scp local_file remote_username@remote_ip:remote_file
scp local_file remote_ip:remote_folder
scp local_file remote_ip:remote_file
```

> **说明** 第1、2个指定了用户名，命令执行后需要再输入密码，第1个仅指定了远程的目录，文件名字不变，第2个指定了文件名。
>
> 第3、4个没有指定用户名，命令执行后需要输入用户名和密码，第3个仅指定了远程的目录，文件名字不变，第4个指定了文件名。

* 从远程复制到本地：

```
scp root@www.cumt.edu.cn:/home/root/others/music /home/space/music/i.mp3
scp -r www.cumt.edu.cn:/home/root/others/ /home/space/music/
```

**说明** 从远程复制到本地，只要将从本地复制到远程的命令的后2个参数调换顺序即可。

# Rsync [#rsync]

Rsync是linux/Unix文件同步和传送工具。用于替代RCP的一个工具，rsync可以通过rsh或ssh使用，也能以daemon模式去运行，在以daemon方式运行时rsync
server会开一个873端口，等待客户端去连接。连接时rsync
server会检查口令是否相符，若通过口令查核，则可以通过进行文件传输，第一次连通完成时，会把整份文件传输一次，以后则就只需进行增量备份。

Rsync的安装方式如下：

**说明** 可以使用每个发行版本自带的安装包管理器安装。

```
sudo apt-get  install  rsync      #在debian、ubuntu 等在线安装方法；
slackpkg  install  rsync          #Slackware 软件包在线安装；
yum install rsync                 #Fedora、Redhat 等系统安装方法；
```

源码编译安装：

```
wget http://rsync.samba.org/ftp/rsync/src/rsync-3.0.9.tar.gz
tar xf rsync-3.0.9.tar.gz
cd rsync-3.0.9
./configure && make && make install
```

| 参数介绍如下表所示：  参数 | 说明                                               |
| -------------- | ------------------------------------------------ |
| -v             | 详细模式输出                                           |
| -a             | 归档模式，表示以递归的方式传输文件，并保持所有文件属性不变，相当于使用了组合参数-rlptgoD |
| -r             | 对子目录以递归模式处理                                      |
| -l             | 保留软链接                                            |
| -p             | 保持文件权限                                           |
| -t             | 保持文件时间信息                                         |
| -g             | 保持文件属组信息                                         |
| -o             | 保持文件属主信息                                         |
| -D             | 保持设备文件信息                                         |
| -H             | 保留硬链结                                            |
| -S             | 对稀疏文件进行特殊处理以节省DST的空间                             |
| -z             | 对备份的文件在传输时进行压缩处理                                 |

rsync有以下六种不同的工作模式：

* 拷贝本地文件，将/home/coremail目录下的文件拷贝到/cmbak目录下。

  rsync -avSH /home/coremail/ /cmbak/

* 拷贝本地机器的内容到远程机器。

  rsync -av /home/coremail/ 192.168.11.12:/home/coremail/

* 拷贝远程机器的内容到本地机器。

  rsync -av 192.168.11.11:/home/coremail/ /home/coremail/

* 拷贝远程rsync服务器（daemon形式运行rsync）的文件到本地机。

  rsync -av root\@172.16.78.192::www /databack

* 拷贝本地机器文件到远程rsync服务器（daemon形式运行rsync）中。当DST路径信息包含`::`分隔符时启动该模式。

  rsync -av /databack root\@172.16.78.192::www

* 显示远程机器的文件列表。这类似于rsync传输，不过只要在命令中省略掉本地机器信息即可。

  rsync -v rsync://192.168.11.11/data

rsync配置文件说明如下：

```
cat/etc/rsyncd.conf              #内容如下
port = 873                       #端口号
uid = nobody                     #指定当模块传输文件的守护进程UID
gid = nobody                     #指定当模块传输文件的守护进程GID
use chroot = no                  #使用chroot到文件系统中的目录中
max connections = 10             #最大并发连接数
strict modes = yes               #指定是否检查口令文件的权限
pid file = /usr/local/rsyncd/rsyncd.pid       #指定PID文件
lock file = /usr/local/rsyncd/rsyncd.lock     #指定支持max connection的锁文件，默认为/var/run/rsyncd.lock
motd file = /usr/local/rsyncd/rsyncd.motd     #定义服务器信息的，自己写 rsyncd.motd 文件内容
log file = /usr/local/rsyncd/rsync.log        #rsync 服务器的日志
log format = %t %a %m %f %b
syslog facility = local3
timeout = 300
[conf]                                   #自定义模块
path = /usr/local/nginx/conf             #用来指定要备份的目录
comment = Nginx conf
ignore errors                            #可以忽略一些IO错误
read only = no                           #设置no，客户端可以上传文件，yes是只读
write only = no                          #no为客户端可以下载，yes不能下载
hosts allow = 192.168.2.0/24             #可以连接的IP
hosts deny = *                           #禁止连接的IP
list = false                             #客户请求时，使用模块列表
uid = root
gid = root
auth users = backup                      #连接用户名，和linux系统用户名无关系
secrets file = /etc/rsyncd.pass          #验证密码文件
```


# 高可用架构部署方案 (/products/qvm/6-a-high-availability-architecture-deployment-scheme)



最近更新时间: 2021-03-15 10:51:08

高可用架构提供业务分发、弹性扩展、多可用区部署等功能。相较于使用单台QVM实例部署数据库与应用，高可用架构只需简单部署，并且拥有更高的稳定性和可扩展性。

# 高可用架构特点 [#高可用架构特点]

高可用架构具有如下特点：

* 使用多可用区高可用版的负载均衡SLB（Server Load Balancer）对多台云服务器QVM进行流量分发，可扩展应用系统对外服务能力、消除单点故障，提升应用系统的可用性。使用SLB自动跨可用区部署，可加强业务容灾能力。
* 通过自定义镜像，可以迅速复制出相同应用部署的云服务器QVM实例，之后将实例添加到SLB后端服务器组中，实现业务高可用。SLB可以同时配置四层和七层监听，及轮循、加权轮循、加权最小连接数等多种算法，合理分配后端QVM计算资源。
* 使用云数据库RDS（Relational Database Service），针对高并发场景进行特殊优化，同时引入线程池、并行复制、隐含主键等功能保证系统持续稳定和高吞吐。云数据库CloudDBA具有完备的性能监控数据，实时监控实例硬件使用指标、慢SQL，并给出各种优化建议，帮您快速定位并解决问题。

# 部署流程 [#部署流程]

假设您已拥有一台QVM实例，并且在该实例上部署了数据库与应用，您可以将单实例部署方式转变为单可用区或多可用区高可用架构。本教程指导您如何使用QVM、EIP、SLB和RDS产品来部署多可用区高可用架构。 ![](/docs-assets/products/qvm/%287-best-practices%29/6-a-high-availability-architecture-deployment-scheme/gEqyLWGVDn0ct7wkAhBS-7f0536002a15.webp)

1. 使用自定义镜像，部署多台相同配置的QVM实例。
2. 创建负载均衡SLB实例，将实例添加到SLB后端服务器组中，用于跨可用区挂载QVM实例，实现业务的高可用性。
3. 使用DTS将QVM实例上的自建数据库迁移至RDS实例，保障业务数据库不中断，自动备份保障数据不丢失。


# QVM实例搭建Windows系统AD域 (/products/qvm/7-qvm-instance-building-windows-active-directory)



最近更新时间: 2021-03-15 10:51:08

活动目录AD（Active Directory）是微软服务的核心组件。AD能实现高效管理，例如批量管理用户、部署应用和更新补丁等。许多微软组件（例如Exchange）和故障转移群集也需要AD域环境。本文以Windows Server 2012 R2 Datacenter操作系统为例，介绍如何搭建AD域。

# 前提条件 [#前提条件]

* 安装者必须拥有管理员权限。
* 安装分区必须为NTFS分区。
* 实例必须支持DNS服务。
* 实例必须支持TCP/IP协议，并且需要有固定私网IP地址。

  **说明** 建议使用固定IP地址，防止重启实例后IP地址发生变化。本文采用的是专有网络VPC，手动修改IP地址会导致IP失效。

# 背景信息 [#背景信息]

* 名词解释：
  * DC：Domain Controllers，域控制器
  * DN：Distinguished Name，识别名
  * OU：Organizational Unit，组织单位
  * CN：Canonical Name，正式名称
  * SID：Security Identifier，安全标识符
* 实例组网信息：
  * 网络类型：专有网络VPC
  * 交换机私网网段：192.168.100.0/24
  * 是否启用网关：是 ![VPC组网](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/6ZPf7NSV8qWhlyG9ICM1-e18c241ac1be.webp)
* 域名信息：
  * 域名：lyonz.com
  * DC：192.168.100.105
  * 需要加入域的客户端（Client）IP地址：192.168.100.106 ![域名信息](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/321kB58aQzZmPOiFcfMp-ff081cc8b332.webp)

# 注意事项 [#注意事项]

* 关于域控：
  * 如果您使用自定义镜像创建QVM实例部署域控制器，必须按照本文中的步骤修改SID。如果您使用公共镜像，已经默认修改了SID，无需手动修改。
  * 七牛云不推荐您使用已有的域控制器创建自定义镜像来部署新的域控。如果必须使用，请注意新建实例的主机名（hostname）和创建自定义镜像之前实例的主机名必须保持一致，否则可能会报错`服务器上的安全数据库没有此工作站信任关系`；您也可以在创建实例后修改成相同的主机名，解决此问题。
* 关于客户端：七牛云不推荐您使用已加入域的客户端实例来创建自定义镜像，否则新镜像创建的实例会报错`服务器上的安全数据库没有此工作站信任关系`。如果确实需要，建议您在创建新的自定义镜像前先退域。

# 操作步骤 [#操作步骤]

通过Windows Server 2012实例搭建AD域的步骤如下：

1. [步骤一：安装AD域控制器](#section-vdo-3hc-rfl)
2. [步骤二：修改客户端的SID](#section-xex-k3r-hup)
3. [步骤三：客户端加入AD域](#section-990-tcm-nuy)

# 步骤一：安装AD域控制器 [#步骤一安装ad域控制器]

1. 远程连接QVM实例。。

2. 打开服务器管理器，在QVM实例中添加角色和功能。

   ![添加角色和功能](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/u4wL0YUpz3tianQ6PMfO-ec9fa26b4636.webp)

   1. 选择安装类型。

      ![选择安装类型](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/tjB7UxefX1HcLVhQ2PJA-6ed640b7903e.webp)

   2. 选择要安装角色和功能的服务器。

      ![选择要安装角色和功能的服务器](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/pb36Dd9OsJ2iS7nxwAQP-4d4e44b9ab57.webp)

   3. 选择要安装在服务器上的角色。

      ![选择要安装在服务器上的角色](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/PuqQg02ev6cMAsWEGB4H-fac6e9544c12.webp)

3. 将此服务器提升为域服务器。

   ![将此服务器提升为域服务器](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/WQJpnkub8gCevs52zNTO-b4274751015e.webp)

   1. 部署配置。

      ![部署配置](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/ARNkQBwoGJycFsWlPmZ5-117c298a3fc5.webp)

   2. 配置域服务器参数。

      ![配置域服务器参数](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/H6r48cK5z1ajYkh27tBq-a232974cec5b.webp)

   3. 配置DNS选项。

      ![配置DNS选项](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/qu0cI5OsZ24V1jXPaK9G-a3e43be5ca21.webp)

   4. 配置NetBIOS域名。

      ![配置NetBIOS域名](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/zGV9h1kLAxbdPOX8rpFe-c6075bc9b968.webp)

   5. 检查并确认您的选择。

      ![检查并确认您的选择](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/iRorhuEKB9xDXfe43lLg-0cd4f84a94db.webp)

   6. 单击下一步。

   7. 单击安装，开始安装AD域服务器。

      ![开始安装AD域服务器](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/VX6gow8YBbL1hdsJc3vT-4ec1f03a5764.webp)

      安装完成，如下图所示。 ![安装完成，如下图所示](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/A58sNicwE9vhXQzjLCUG-02ee23e7c897.webp)

# 步骤二：修改客户端的SID [#步骤二修改客户端的sid]

1. 下载修改客户端SID的PowerShell脚本。

   * 下载地址：[AutoSysprep.ps1](http://docs-aliyun.cn-hangzhou.oss.aliyun-inc.com/assets/attach/40846/cn_zh/1542010494209/AutoSysprep.ps1)
   * 脚本来源：七牛云官方

2. 打开CMD，输入powershell切换至Windows PowerShell界面。

   **说明** 如果您的实例操作系统是64位，则不能使用32位的PowerShell（即Windows PowerShell (x86)），否则会报错。

3. 切换至脚本存储的路径，执行如下命令，查看脚本工具说明。

```
.\AutoSysprep.ps1 -help
```

4. 执行如下命令，服务器会重新初始化SID。

```
.\AutoSysprep.ps1 -ReserveHostname -ReserveNetwork -SkipRearm -PostAction "reboot"
```

初始化完成后，会重启实例，您需要注意以下事项。

* 实例IP地址会从DHCP变成固定IP地址。您可以重新改成DHCP，可以直接修改专有网络中QVM实例的私有IP，也可以通过更改QVM实例所属的交换机来更改QVM实例的私有IP。。 ![重新改成DHCP](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/7nGk0FHwgz4decoLZK8N-28f9cb003d9d.webp)
* 初始化SID后，云服务器防火墙的配置被修改成微软的默认配置，导致云服务器无法Ping通。您需要关闭防火墙来宾或公用网络，或者放行需要开放的端口。下图表示防火墙来宾或公用网络的状态是已连接。 ![来宾或公用网络](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/B8JzTqoZAXnumQ6OEGsd-7632dcc72996.webp)

5. 关闭来宾或公用网络防火墙。

![关闭来宾或公用网络防火墙](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/ZSlpzHrFxBMqXOb6cwaV-542098a69f75.webp)

关闭后，可以Ping通服务器。 ![PING通服务器示意图](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/pQ1wFXgcoahsiG9jH3lE-516c4613a458.webp)

# 步骤三：客户端加入AD域 [#步骤三客户端加入ad域]

您可以根据业务需求修改主机名和DNS指向DC的IP地址。

1. 修改DNS服务器地址。

   ![修改DNS服务器地址](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/nTIq34OZAo6bixcHraDR-e836cfe9edc0.webp)

2. 检查是否能Ping通DNS服务器IP地址。

   ![PING通DNS服务器的地址](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/RZcsICgEbqXGHDurAeVW-7e28ebc28d83.webp)

3. 修改主机名并加入AD域。

   ![修改主机名并加入AD域](/docs-assets/products/qvm/%287-best-practices%29/7-qvm-instance-building-windows-active-directory/OnfhzAUpCBDVisMv0IuT-e9b1a80bf9bc.webp)


# QVM安全组实践（二） (/products/qvm/8-qvm-security-group-practice-2)



最近更新时间: 2021-03-15 10:51:08

本文从授权和撤销安全组规则、加入和移出安全组讲解云服务器QVM的安全组最佳实践。

# 网络类型 [#网络类型]

七牛云的网络类型有专有网络VPC，对安全组支持不同的设置规则，您可以设置内网入方向和内网出方向的安全组规则。
台专有网络VPC类型的QVM实例只能加入本VPC的安全组。

# 安全组内网通讯的概念 [#安全组内网通讯的概念]

本文开始之前，您应知道以下几个安全组内网通讯的概念：

* 默认只有同一个安全组的QVM实例可以网络互通。即使是同一个账户下的QVM实例，如果分属不同安全组，内网网络也是不通的。
* 如果您有两台QVM实例，不在同一个安全组，您希望它们内网不互通，但实际上它们却内网互通，那么，您需要检查您的安全组内网规则设置。如果内网协议存在下面的协议，建议您重新设置。
  * 允许所有端口。
  * 授权对象为CIDR网段（SourceCidrIp）：0.0.0.0/0或者10.0.0.0/8的规则。
* 如果您想实现在不同安全组的资源之间的网络互通，您应使用安全组方式授权。对于内网访问，您应使用源安全组授权，而不是CIDR网段授权。

# 安全规则的属性 [#安全规则的属性]

安全规则主要是描述不同的访问权限，包括如下属性：

* Policy：授权策略，参数值可以是accept（接受）或drop（拒绝）。
* Priority：优先级，根据安全组规则的创建时间降序排序匹配。规则优先级可选范围为1-100，默认值为1，即最高优先级。数字越大，代表优先级越低。
* NicType：网络类型。如果只指定了SourceGroupId而没有指定SourceCidrIp，表示通过安全组方式授权，此时，NicType必须指定为intranet。
* 规则描述：
  * IpProtocol：IP协议，取值：tcp、udp、icmp、gre或all。all表示所有的协议。
  * PortRange：IP协议相关的端口号范围：
    * IpProtocol取值为tcp或udp时，端口号取值范围为1~~65535，格式必须是“起始端口号/终止端口号”，如“1/200”表示端口号范围为1~~200。如果输入值为“200/1”，接口调用将报错。
    * IpProtocol取值为icmp、gre或all时，端口号范围值为-1/-1，表示不限制端口。
  * 如果通过安全组授权，应指定SourceGroupId，即源安全组ID。此时，根据是否跨账号授权，您可以选择设置源安全组所属的账号SourceGroupOwnerAccount。
  * 如果通过CIDR授权，应指定SourceCidrIp，即源IP地址段，必须使用CIDR格式。

# 授权一条入网请求规则 [#授权一条入网请求规则]

在控制台或者通过API创建一个安全组时，入网方向默认deny all，即默认情况下您拒绝所有入网请求。这并不适用于所有的情况，所以您要适度地配置您的入网规则。

例如，如果您需要开启公网的80端口对外提供HTTP服务，因为是公网访问，您希望入网尽可能多访问，所以在IP网段上不应做限制，可以设置为0.0.0.0/0，具体设置可以参见以下描述，其中，括号外为控制台参数，括号内为OpenAPI参数，两者相同就不做区分。

* 网卡类型（NicType）：公网（internet）。如果是专有网络VPC类型的只需要填写intranet，通过EIP实现公网访问。
* 授权策略（Policy）：允许（accept）。
* 规则方向（NicType）：入网。
* 协议类型（IpProtocol）：TCP（tcp）。
* 端口范围（PortRange）：80/80。
* 授权对象（SourceCidrIp）：0.0.0.0/0。
* 优先级（Priority）：1。

# 禁止一个入网请求规则 [#禁止一个入网请求规则]

禁止一条规则时，您只需要配置一条拒绝策略，并设置较低的优先级即可。这样，当有需要时，您可以配置其它高优先级的规则覆盖这条规则。例如，您可以采用以下设置拒绝6379端口被访问。

* 网卡类型（NicType）：内网（intranet）。
* 授权策略（Policy）：拒绝（drop）。
* 规则方向（NicType）：入网。
* 协议类型（IpProtocol）：TCP（tcp）。
* 端口范围（PortRange）：6379/6379。
* 授权对象（SourceCidrIp）：0.0.0.0/0。
* 优先级（Priority）：100。

# 将需要互相通信的QVM实例加入同一个安全组 [#将需要互相通信的qvm实例加入同一个安全组]

一个QVM实例最多可以加入5个安全组，而同一安全组内的QVM实例之间是网络互通的。如果您在规划时已经有多个安全组，而且，直接设置多个安全规则过于复杂的话，您可以新建一个安全组，然后将需要内网通讯的QVM实例加入这个新的安全组。

这里也不建议您将所有的QVM实例都加入一个安全组，这将会使得您的安全组规则设置变成梦魇。对于一个中大型应用来说，每个服务器编组的角色不同，合理地规划每个服务器的入方向请求和出方向请求是非常有必要的。

在控制台上，您可以根据文档加入安全组
"您可以根据业务需要，将 QVM 实例加入一个或多个安全组。默认情况下，一个 QVM 实例可以加入五个安全组。")的描述将一台实例加入安全组。

# 将QVM实例移除安全组 [#将qvm实例移除安全组]

如果QVM实例加入不合适的安全组，将会暴露或者Block您的服务，这时您可以选择将QVM实例从这个安全组中移除。但是在移除安全组之前必须保证您的QVM实例已经加入其它安全组。

**说明** 将QVM实例从安全组移出，将会导致这台QVM实例和当前安全组内的网络不通，建议您在移出之前做好充分的测试。

合理的安全组名称和描述有助于您快速识别当前复杂的规则组合。您可以通过修改名称和描述来帮助自己识别安全组。

# 删除不需要的安全组 [#删除不需要的安全组]

安全组中的安全规则类似于一条条白名单和黑名单。所以，请不要保留不需要的安全组，以免因为错误加入某台QVM实例而造成不必要的麻烦。


# 私网传输迁移 (/products/qvm/9-the-private-network-transmission-migration)



最近更新时间: 2021-04-19 11:08:34

如果您能直接从自建机房IDC、虚拟机环境或者云主机访问阿里云某一地域下的专有网络VPC，建议您使用QSMC的私网传输迁移方案。通过QSMC的私网传输迁移，比公网更快速、更稳定，能提高迁移的效率。

# 前提条件 [#前提条件]

1. 已通过云企业网将本地数据中心和云上VPC打通。更多信息，请参见[连接本地IDC](/products/qvm/network/section-a8p7nr/6512-CEN-quick-start)。
2. 本地数据中心的防火墙已放行8703、8080端口，用于保证迁移源与中转实例数据传输畅通。

# 操作步骤 [#操作步骤]

创建迁移任务的过程中，需要注意将网络模式设置为私网传输，并配置已打通专线的VPC以及交换机。
![image.png](/docs-assets/products/qvm/%287-best-practices%29/9-the-private-network-transmission-migration/FlSnXsbP_hCxtcZpaMsvqHFAaxE0-df776edd0ead.webp)


# 快速入门 (/products/qvs/0-qvs-quick-start)



最近更新时间: 2026-08-18 11:54:25

本篇文档，阐述如何将摄像头,网络录像机,或者下级监控平台上云。

# **接入准备** [#接入准备]

**注册七牛开发者平台**
若尚无七牛开发者平台账号，需要先进行注册；访问[七牛官网](https://www.qiniu.com/)，点击右上角的[注册](https://portal.qiniu.com/signup)，进行七牛帐号注册。

**直播域名**
在qvs创建空间时，如果选择`静态地址`模式，则需准备好备案过的域名，详情请参见 [ICP 备案](/faq/cdn/6000-the-icp-registration-process)，如果选择`动态地址`模式，则不用域名即可快速体验本产品，两种模式的区别见下文。

**开通存储服务**
如果需要对实时视频流进行录制或者截图，用于点播回看等, 则需要先在七牛`云存储`服务中创建存储bucket,否则跳过本步骤。详情请参照[创建存储空间](/products/kodo/0-console-quickstart#step1)

# **使用流程** [#使用流程]

* [步骤一：创建空间](#步骤一)
* [步骤二：设备接入](#步骤二)
  * [RTMP主动推流接入](#方式1)
  * [GB/T 28181接入](#方式2)
  * [`主动拉流`(rtsp/hls/flv/rtmp主动拉流)接入](#方式3)
  * [ONVIF接入](#方式4)
* [步骤三：实时预览、云端录制回放、查看截图](#步骤三)

<a id="步骤一" />

## **步骤一：创建空间** [#步骤一创建空间]

**操作说明：**
1.登录[七牛开发者平台](https://sso.qiniu.com/?client_id=PIapUKqa3u6S24H868BelwrG0OFu8dS7AxVQ8oz8HznLXhgrl2BnjaO9cs9LzxK2\&redirect_url=https:%2F%2Fportal.qiniu.com%2Fapi%2Fgaea%2Fsso%2Fsignin%3Fredirect%3D%252Fcreate)。

2.选择**视频监控**产品，进入产品控制台，选择**空间管理**，[创建空间](/products/qvs/user-guide/0-namespace-management#1)，完成空间配置。注：创建空间时的模式选择, `动态地址和静态地址的区别`

| 模式     | 说明                                                                                                                                                                                                                                                                                                                                                                |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 静态地址   | 通过配置域名的方式接入, 默认情况下`地址是固定的`,[流地址格式](/products/qvs/flow-management/obtain-flow-address)\<br>1. `必须`为域名配置cname解析,[如何配置cname?](/products/qvs/6-configure-cname)\<br> 2.`如果`在`https`环境播放, 则`必须`配置https ssl证书。[如何配置https证书?](/products/qvs/user-guide/equipment-control/0-qvs-https-configuration)\<br>3.看不到域名配置管理入口或者流地址ip不固定? 因为新建空间时,`模式`选择了动态地址,重建一个新空间，选择`静态地址`即可。 |
| 动态地址   | 无需配置域名，流地址全部为IP形式，需通过API获取实时的流地址。<br />适用场景：<br />1.测试阶段，快速验证。<br /> 2.不想配置域名，能接受流地址通过API获取。<br /> 3. 只能用在http的播放环境。如果是`https`环境,必须新建空间,模式选择`静态地址` <br />**动态地址`不支持https`环境中播放, IP`不能`固定，必须通过[API](/products/qvs/flow-management/obtain-flow-address/1-dynamic-model)获取最新流地址**                                                                                    |

3.如果创建空间时，选择`静态地址`（直播域名）的接入模式，需要进入[域名管理](/products/qvs/user-guide/0-namespace-management#2)完成域名的解析配置。[如何CNAME解析配置](/products/qvs/6-configure-cname)。如果空间模式为`动态地址`可跳过此步。

4.如果需要对监控视频流进行录制或者截图，需要先创建 [录制模板](/products/qvs/user-guide/template-management/0-recording-the-template)、[截图模板](/products/qvs/user-guide/template-management/1-screenshot-of-the-template)，然后绑定到对应的空间或流。
![image.png](/docs-assets/products/qvs/%280-manual%29/0-qvs-quick-start/FvgnKtEf8VVduJNKMJGS16cV4gUp-70b2a9117729.webp)

<a id="步骤二" />

## **步骤二：设备接入** [#步骤二设备接入]

<a id="方式1" />

### **（1）RTMP接入** [#1rtmp接入]

**获取推拉流地址**

* 方式一：
  完成空间的配置后，进入流管理模块，进行[添加流](/products/qvs/flow-management/0-create-flow)操作，创建完成之后点击【实时预览】查询推拉流地址。
  ![](/docs-assets/products/qvs/%280-manual%29/0-qvs-quick-start/FmAdBVumd800h2FDTwBWhkvAAW5V-68ce9a449239.webp)

* 方式二：
  完成空间的配置后，可以通过portal中的**辅助工具**生成推流地址进行测试。
  ![](/docs-assets/products/qvs/%280-manual%29/0-qvs-quick-start/FjRLjw4zlR8hUV1l1Ii2NZyyFz0C-deb0b56b6ee1.webp)

**设备端配置**
设备端推流地址配置可参考[设备端配置说明](/products/qvs/2-rtmp-access-process)。

<a id="方式2" />

### **（2）GB/T 28181接入** [#2gbt-28181接入]

**创建设备**
完成空间配置后，进入设备管理模块，进行[添加设备](/products/qvs/user-guide/equipment-control#1)操作。
![image.png](/docs-assets/products/qvs/%280-manual%29/0-qvs-quick-start/FpjFdgquPEqIuBFf_WO4pl24tLWt-76cd08663269.webp)
**获取设备国标接入信息**
设备列表中检索出需要接入的设备，点击**查看**，获取设备国标接入信息。
![image.png](/docs-assets/products/qvs/%280-manual%29/0-qvs-quick-start/Fh7hIAMoA55qCjNjhrkAo4pUV_Sx-8a038389527c.webp)
![image.png](/docs-assets/products/qvs/%280-manual%29/0-qvs-quick-start/Fv3clFz4Yt_LmCs6DUomCkUb-b_D-04372890031c.webp)

**设备端配置**
设备端接入配置可参考[设备端配置说明](/products/qvs/0-gb-access-process)。

<a id="方式3" />

### **（3）主动拉流接入** [#3主动拉流接入]

1. 第一步
   ![image.png](/docs-assets/products/qvs/%280-manual%29/0-qvs-quick-start/FtVH7mlW3N0AuzkDPZcIhhogmBk-167f00ade14c.webp)
2. 第二步
   ![image.png](/docs-assets/products/qvs/%280-manual%29/0-qvs-quick-start/FmO1a4AAKl8yjf8x8NhhvjSEabJ8-818bb6ce5d54.webp)

<a id="方式4" />

### **（4）ONVIF接入** [#4onvif接入]

注意：`onvif接入要求设备有公网ip(内网设备可以使用内网映射工具，比如花生壳)`

1. 在摄像头web页面添加onvif用户名密码。
   ![用户名密码.png](/docs-assets/products/qvs/%280-manual%29/0-qvs-quick-start/FrfcPZfjIdgmer-mGIeI6d2Kqpsp-46955c9faea7.webp)
2. 在七牛控制台创建onvif设备。输入设备的`公网ip`和添加的onvif用户名密码。
   ![image.png](/docs-assets/products/qvs/%280-manual%29/0-qvs-quick-start/Frykq6F1SVtx6Zyr3T0CH0ekBdBh-b59c5143d3e3.webp)

<a id="步骤三" />

## **步骤三：实时预览、云端录制回放、查看截图** [#步骤三实时预览云端录制回放查看截图]

选择**视频流管理**，找到对应的流名，可以进行[实时预览](/products/qvs/user-guide/1-video-streaming-management#2)、查询流状态、[云端录制回放](/products/qvs/user-guide/1-video-streaming-management#3)、查询[视频截图](/products/qvs/user-guide/1-video-streaming-management#4)等操作。
![](/docs-assets/products/qvs/%280-manual%29/0-qvs-quick-start/Fj_GTzzP_Jb_KviEMBAU7AVDEmiM-ae0721f02aca.webp)


# API概述 (/products/qvs/0-summary-of-the-api)



最近更新时间: 2026-08-18 11:56:09

本文档介绍了视频监控服务的各类API，您可以分别查看各API的具体信息。

# **空间管理相关** [#空间管理相关]

| API                                                           | 说明                                  |
| ------------------------------------------------------------- | ----------------------------------- |
| [创建空间](/products/qvs/space-management/0-create-namespace)     | 用于创建新的业务空间                          |
| [删除空间](/products/qvs/space-management/1-delete-namespace)     | 用于删除业务空间                            |
| [更新空间](/products/qvs/space-management/2-update-namespace)     | 用户更新空间的配置信息操作                       |
| [查询空间信息](/products/qvs/space-management/3-query-namespace)    | 用户查询业务空间的详细信息                       |
| [获取空间列表](/products/qvs/space-management/4-list-namespace)     | 用户获取空间列表                            |
| [禁用空间](/products/qvs/space-management/5-disable-the-space)    | 禁用空间操作                              |
| [启用空间](/products/qvs/space-management/6-enable-the-space)     | 启用空间操作                              |
| [消息通知](/products/qvs/space-management/7-the-message-callback) | 直播流状态的实时变化、设备状态的实时变化，视频录制/截图成功的事件通知 |

# **域名管理相关** [#域名管理相关]

| API                                                                           | 说明                               |
| ----------------------------------------------------------------------------- | -------------------------------- |
| [创建域名](/products/qvs/domain-management/2-create-domain)                       | 用于在某空间下创建新的域名                    |
| [删除域名](/products/qvs/domain-management/3-delete-domain)                       | 用于删除空间下的域名                       |
| [更新域名](/products/qvs/domain-management/6-update-domain)                       | 更新域名,例如开启或关闭时间戳防盗链,添加或删除https证书等 |
| [查询域名](/products/qvs/domain-management/5-domain-information)                  | 查询域名信息                           |
| [获取域名列表](/products/qvs/domain-management/4-domain-name-list)                  | 获取某个空间下的域名列表                     |
| [获取https证书列表](/products/qvs/domain-management/1-to-obtain-a-list-certificate) | 获取https ssl证书列表                  |
| [配置域名戳防盗链](/products/qvs/domain-management/7-the-domain-name-configuration)   | 修改域名下的防盗链信息                      |

# **流管理相关** [#流管理相关]

| API                                                             | 说明          |
| --------------------------------------------------------------- | ----------- |
| [创建流](/products/qvs/flow-management/0-create-flow)              | 用于创建视频流     |
| [删除流](/products/qvs/flow-management/1-delete-flow)              | 用于删除已添加的视频流 |
| [更新流](/products/qvs/flow-management/7-update-the-flow)          | 用于更新流的配置新   |
| [查询流信息](/products/qvs/flow-management/2-query-information-flow) | 用于查询流的详细信息  |
| [获取流列表](/products/qvs/flow-management/3-query-list-flow)        | 用于获取流列表信息   |
| [获取流地址](/products/qvs/flow-management/obtain-flow-address)      | 用于获取推拉流地址信息 |
| [启用流](/products/qvs/flow-management/5-enable-the-flow)          | 启用流操作       |
| [禁用流](/products/qvs/flow-management/4-disable-the-flow)         | 禁用流操作       |
| [查询推流记录](/products/qvs/flow-management/6-query-flow-records)    | 用于查询流的推流记录  |

# **设备管理相关** [#设备管理相关]

| API                                                                                         | 说明              |
| ------------------------------------------------------------------------------------------- | --------------- |
| [创建设备](/products/qvs/equipment-management-related-interfaces/0-create-device)               | 用于创建设备          |
| [批量创建设备](/products/qvs/equipment-management-related-interfaces/10-batch-create-device)      | 用于批量创建设备        |
| [获取批次列表](/products/qvs/equipment-management-related-interfaces/12-get-batch-list)           | 用于查询批量创建设备的批次记录 |
| [获取批次设备信息](/products/qvs/equipment-management-related-interfaces/11-export-batch-equipment) | 用于查询批次下所有设备的信息  |
| [删除批次](/products/qvs/equipment-management-related-interfaces/13-batch-remove-devices)       | 用于删除批次下所有的设备    |
| [删除设备](/products/qvs/equipment-management-related-interfaces/1-delete-device)               | 用于删除设备          |
| [更新设备](/products/qvs/equipment-management-related-interfaces/2-update-the-device)           | 用于更新设备配置信息      |
| [查询设备信息](/products/qvs/equipment-management-related-interfaces/3-query-device-information)  | 用于查询设备信息        |
| [获取设备列表](/products/qvs/equipment-management-related-interfaces/4-query-device-list)         | 用于获取设备列表信息      |
| [获取通道列表](/products/qvs/equipment-management-related-interfaces/5-query-channel-list)        | 用于查询通道列表信息      |
| [删除通道](/products/qvs/equipment-management-related-interfaces/8-delete-the-channel)          | 用于删除网络录像机的指定通道  |
| [启动设备拉流](/products/qvs/equipment-management-related-interfaces/6-start-device)              | 用于启动国标设备拉流      |
| [停止设备拉流](/products/qvs/equipment-management-related-interfaces/7-stop-device)               | 用于结束国标设备拉流      |
| [语音对讲](/products/qvs/equipment-management-related-interfaces/9-voice-call)                  | 用于对设备发起语音对讲     |
| [获取设备地理位置](/products/qvs/equipment-management-related-interfaces/14-get-to-location)        | 用于获取设备地理位置信息    |

# **模板管理相关** [#模板管理相关]

| API                                                                | 说明                |
| ------------------------------------------------------------------ | ----------------- |
| [创建模板](/products/qvs/template-management/0-create-template)        | 用于创建录制、截图等模板      |
| [删除模板](/products/qvs/template-management/1-delete-template)        | 用户删除指定的模板         |
| [更新模板](/products/qvs/template-management/2-modify-the-template)    | 用于更新录制、截图等模板的配置信息 |
| [查询模板信息](/products/qvs/template-management/3-template-information) | 用于查询指定模板的配置信息     |
| [获取模板列表](/products/qvs/template-management/4-list-template)        | 用于获取模板列表信息        |

# **录制管理相关** [#录制管理相关]

| API                                                             | 说明                        |
| --------------------------------------------------------------- | ------------------------- |
| [启动按需录制](/products/qvs/recording/0-start-record-stream)         | 本接口用于对指定流启动按需录制           |
| [停止按需录制](/products/qvs/recording/1-stop-record-stream)          | 本接口用于对指定流停止按需录制           |
| [查询录制记录](/products/qvs/recording/2-query-recordhistories)       | 用于查询视频流的录制的记录             |
| [删除录制片段](/products/qvs/recording/3-delete-recorded-fragments)   | 用于删除通过qvs录制模板生成的视频文件      |
| [录制视频片段合并](/products/qvs/recording/9-record-video-clips)        | 该接口用于将多个录制文件合并成一个大的视频文件   |
| [录制回放](/products/qvs/recording/4-recording-playback)            | 本接口用于查询指定时间段的录像记录进行录像回放   |
| [按需截图](/products/qvs/recording/5-start-snapshot)                | 本接口用于对指定流立即截图一次，适用于按需截图场景 |
| [删除截图](/products/qvs/recording/8-deleted-screenshots)           | 用于删除通过qvs截图模板生成的截图文件      |
| [获取截图列表](/products/qvs/recording/6-list-stream-snapshots)       | 用于查询视频流截图的记录              |
| [获取直播封面截图](/products/qvs/recording/7-the-cover-for-screenshots) | 用于查询视频流的封面                |

# **本地录像管理相关** [#本地录像管理相关]

| API                                                                             | 说明                               |
| ------------------------------------------------------------------------------- | -------------------------------- |
| [本地录像回放控制](/products/qvs/local-video-playback/3-local-video-playback-control)   | 用于本地录像回放的控制，如快进、快退、慢放、拖动播放、暂停等操作 |
| [查询本地录像列表](/products/qvs/local-video-playback/0-query-local-video-list)         | 用于查询设备本地录像列表                     |
| [本地录像上传云端存储](/products/qvs/local-video-playback/1-uploaded-to-the-cloud)        | 用于将本地录像文件上传到云端并进行录制存储的操作         |
| [终止本地录像上传云端存储](/products/qvs/local-video-playback/2-stop-uploaded-to-the-cloud) | 用于终止本地录制文件上传云端录制的操作              |

# **PTZ相关** [#ptz相关]

| API                                                                    | 说明                         |
| ---------------------------------------------------------------------- | -------------------------- |
| [云台控制](/products/qvs/ptz-related-interface/0-ptz-control)              | 用于对摄像头进行 转动镜头，如水平、垂直、缩放等操作 |
| [变焦控制](/products/qvs/ptz-related-interface/2-zoom-control)             | 用于摄像头的变焦控制                 |
| [光圈控制](/products/qvs/ptz-related-interface/1-aperture-control)         | 用于摄像头的光圈控制                 |
| [预置位控制](/products/qvs/ptz-related-interface/3-set-the-preset-position) | 用于预置位的管理                   |
| [获取预置位列表](/products/qvs/ptz-related-interface/4-get-prepared-list)     | 用于摄像头端获取预置位列表信息            |

# **国标报警相关接口** [#国标报警相关接口]

| API                                                         | 说明             |
| ----------------------------------------------------------- | -------------- |
| [获取国标报警事件列表](/products/qvs/gb-alarm/0-gb-alarm-events-list) | 用于获取设备国标报警事件列表 |

# **数据统计相关** [#数据统计相关]

| API                                                           | 说明                      |
| ------------------------------------------------------------- | ----------------------- |
| [查询流量数据](/products/qvs/data/0-query-the-network-traffic-data) | 本接口用于查询用户或者空间下的流量数据     |
| [查询带宽数据](/products/qvs/data/1-query-data-bandwidth)           | 本接口用于查询用户或者空间下的带宽数据     |
| [查询国标接入设备数](/products/qvs/data/3-gb-devicecount)              | 本接口用于查询用户或者空间下接入的国标设备数量 |


# 播放端SDK (/products/qvs/0-play-the-sdk)



最近更新时间: 2026-05-06 16:00:17

\[小程序播放器]
[推荐小程序原生播放器](https://developers.weixin.qq.com/miniprogram/dev/component/live-player.html#%E7%A4%BA%E4%BE%8B%E4%BB%A3%E7%A0%81)    `仅支持视频编码h264`

\[web播放器]
推荐西瓜播放器 <br />[web http播放器](http://v3.h5player.bytedance.com/generate/) 适用于http地址 `限定hls和flv,支持视频编码h264和h265 `
[web https 播放器](https://v3.h5player.bytedance.com/generate/)适用于https地址               `限定hls和flv,支持视频编码h264和h265`

**webrtc 快直播低延迟专用播放器SDK：** `仅支持视频编码格式h264`
以下3种播放器SDK仅仅支持webrtc协议，如果是非webrtc协议请参考上面的SDK
[低延时 Web SDK](https://github.com/pili-engineering/QNRTPlayer-Web/tree/v1.2.6)
[低延时 Android SDK](https://github.com/pili-engineering/QNRTPlayer-Android/tree/v1.0.4)
[低延时 iOS SDK](https://github.com/pili-engineering/QNRTPlayer-iOS/tree/v1.0.6)
[webrtc接入最佳实践](/products/qvs/4-low-latency-will-broadcast-live-webrtc-access-process)

**七牛QVS控制台播放器展示**
其中播放器1，是采用hls播放拉流地址，延迟8s左右；播放器2，采用的是webrtc 低延迟播放拉流地址，延迟在500ms；客户可以根据自身场景选择不同的播放拉流协议。

<img src="/docs-assets/products/qvs/%282-sdk-downloads%29/0-play-the-sdk/Fk_5GqWShIoGyn1rXezTJDfAsCek-a51dc722972d.webp" width="450" height="300" alt="播放协议" align="center" />

**注意：各端 Gihub 地址下的 repo 中，有相应的 demo 文件，用户可以体验并参考使用。**


# 摄像头国标接入流程 (/products/qvs/0-gb-access-process)



最近更新时间: 2022-08-25 10:12:31

**本文简述了使用国标协议接入时配置流程，以及接入流程演示视频**。

# **国标接入配置示范** [#国标接入配置示范]

## **操作步骤：** [#操作步骤]

1.首先需要在七牛云视频监控产品portal上查询已经添加好的对应的配置信息，如尚未创建请参考[快速入门](/products/qvs/0-qvs-quick-start)。
2.登录到摄像头的配置页面，找到国标接入配置页面。
3.将对应信息配置到设备端配置、启用国标保存后，该设备将进行注册接入。
4.请确保视频编码格式为h264,码流控制/码率类型选择“可变码率”;音频编码格式为g711-alaw或者aac, 采样率 8000 。
5.平台`支持`h265接入和转发,但浏览器大都无法直接播放h265, 因此客户要自行集成[浏览器h265插件](https://github.com/numberwolf/h265web.js), `非浏览器`的h265播放，可以参考我们的[播放器sdk](/products/qvs/0-play-the-sdk)

<br />

## **海康设备国标接入配置示范** [#海康设备国标接入配置示范]

![](/docs-assets/products/qvs/%283-best-practices%29/0-gb-access-process/Furkm0igA4xP_kRx3CYPEcZl3mVn-b7e34430fa57.webp)
&#x2A;配置参数说明：*

| 参数        | 说明                                                         |
| --------- | ---------------------------------------------------------- |
| 平台接入方式    | 选择28181                                                    |
| 本地SIP端口   | 由于设备默认的本地Sip端口号5060,可能会被局域网屏蔽，建议修改为5061、5062等其他端口号         |
| 传输协议      | 选择UDP                                                      |
| 协议版本      | 选择“GB/T28181-2011 或 GB/T28181-2016”                        |
| SIP服务器ID  | 填入视频监控平台（QVS）提供的SIP服务器ID                                   |
| SIP服务器域   | SIP服务器ID的前10位                                              |
| SIP服务地址   | 填入视频监控平台（QVS）提供的SIP服务器IP                                   |
| SIP服务器端口  | 填入视频监控平台（QVS）提供的SIP服务器端口号                                  |
| SIP用户名    | 填入视频监控平台（QVS）中创建对应的设备时输入的用户名                               |
| SIP用户认证ID | 填入视频监控平台（QVS）中创建对应的设备时输入或自动生成的设备国标ID，网络摄像头的国标ID，11-13位为132 |
| 密码        | 填入视频监控平台（QVS）中创建对应的设备时输入的密码                                |
| 视频通道编码ID  | 填入视频监控平台（QVS）中创建对应的设备时输入的设备国标ID                            |

<br />

## **大华设备国标接入配置示范** [#大华设备国标接入配置示范]

![](/docs-assets/products/qvs/%283-best-practices%29/0-gb-access-process/Fh1UqngoGFfnoC9hoVAHGNdLEUwN-ce96e2dbeb68.webp)
&#x2A;配置参数说明：*

| 参数       | 说明                                                         |
| -------- | ---------------------------------------------------------- |
| SIP服务器编号 | 填入视频监控平台（QVS）提供的SIP服务器ID                                   |
| SIP域     | SIP服务器ID的前10位                                              |
| SIP服务IP  | 填入视频监控平台（QVS）提供的SIP服务器IP                                   |
| SIP服务器端口 | 填入视频监控平台（QVS）提供的SIP服务器端口号                                  |
| 设备编号     | 填入视频监控平台（QVS）中创建对应的设备时输入或自动生成的设备国标ID，网络摄像头的国标ID，11-13位为132 |
| 密码       | 填入视频监控平台（QVS）中创建对应的设备时输入的密码                                |
| 本地SIP端口  | 由于设备默认的本地Sip端口号5060,可能会被局域网屏蔽，建议修改为5061、5062等其他端口号         |
| 通道编号     | 填入视频监控平台（QVS）中创建对应的设备时输入的设备国标ID                            |

<br />

## **视频卡顿或拉流失败时，建议的参数配置** [#视频卡顿或拉流失败时建议的参数配置]

当同一个网络内接入的设备过多时或者摄像头所处的网络环境波动较大时，会由于网络带宽的限制导致视频卡顿，以海康设备为例，建议的参数配置

<br />

![ipc\_1.png](/docs-assets/products/qvs/%283-best-practices%29/0-gb-access-process/Fph6KNGklV5gwF5Qa6cOEX2Z6vpL-71e41c4dfe87.webp)

# **接入流程演示** [#接入流程演示]

<br />

<video id="video" preload="none" poster="https://dn-odum9helk.qbox.me/Fl4VrPs6534sJ669z2Up8ZVuDEZQ">
  <source id="mp4" src="https://dn-odum9helk.qbox.me/lqYSX9Bq9dC_tlxAR4y16n4x8_wS" type="video/mp4" />
</video>


# NVR设备国标接入流程 (/products/qvs/1-nvr-gb-access-process)



最近更新时间: 2026-08-18 12:01:03

**本文简述了使用国标协议接入NVR设备的配置流程，以及接入流程演示视频**。
NVR（网络视频存储）设备接入QVS过程与摄像头接入流程基本类似，都先要在QVS平台下已经创建好的国标类型的空间下先添加设备，此时设备类型需要选择为**平台**。然后在设备端进行国标注册操作，注册成功后，在QVS控制台中可以查看接入的NVR设备状态。

# **NVR设备接入配置示范** [#nvr设备接入配置示范]

## **操作步骤：** [#操作步骤]

1.首先需要在七牛云视频监控产品portal上查询已经添加好的对应的配置信息，如尚未创建请参考[快速入门](/products/qvs/0-qvs-quick-start)。
2.登录到NVR设备的配置页面中，找到国标接入配置页面。
3.将对应信息配置到NVR设备上、启用国标保存后，该设备将进行注册接入。
4.请确保nvr各个通道下,视频编码格式为h264,码流控制/码率类型选择“可变码率”;音频编码格式为g711-alaw或者aac, 采样率 8000。
5.平台`支持`h265接入和转发,但浏览器大都无法直接播放h265, 因此客户要自行集成[浏览器h265插件](https://github.com/numberwolf/h265web.js), `非浏览器`的h265播放，可以参考我们的[播放器sdk](/products/qvs/0-play-the-sdk)

## **海康设备国标接入配置示范** [#海康设备国标接入配置示范]

![](/docs-assets/products/qvs/%283-best-practices%29/1-nvr-gb-access-process/FtHAVF3IcsxMox-1tDtx9d6yp49q-2c5f86691034.webp)
&#x2A;配置参数说明：*

| 参数        | 说明                                                         |
| --------- | ---------------------------------------------------------- |
| 平台接入方式    | 选择28181                                                    |
| 本地SIP端口   | 由于设备默认的本地Sip端口号5060,可能会被局域网屏蔽，建议修改为5061、5062等其他端口号         |
| SIP服务器ID  | 填入视频监控平台（QVS）提供的SIP服务器ID                                   |
| SIP服务器域   | SIP服务器ID的前10位                                              |
| SIP服务地址   | 填入视频监控平台（QVS）提供的SIP服务器IP                                   |
| SIP服务器端口  | 填入视频监控平台（QVS）提供的SIP服务器端口号                                  |
| SIP用户认证ID | 填入视频监控平台（QVS）中创建对应的设备时输入或自动生成的设备国标ID，NVR设备的国标ID，11-13位为118 |
| 密码        | 填入视频监控平台（QVS）中创建对应的设备时输入的密码                                |

**海康NVR设备需要为该设备下，接入的摄像头对应通道分配视频通道编码ID（摄像头设备的国标ID）**
NVR设备下的视频通道编码，可自行分配，不重复即可，11-13位可填132；可参照下面的示例进行配置，示例如下：
D1:31011500991320000001
D2:31011500991320000002
D3:31011500991320000003
....按顺序排列填写即可（NVR接入了多少个摄像头填写多少个通道即可）
![](/docs-assets/products/qvs/%283-best-practices%29/1-nvr-gb-access-process/Fl0tQq_4nwq6UqNW3attGYSxr3-t-245cc661001f.webp)

## **大华设备国标接入配置示范** [#大华设备国标接入配置示范]

![](/docs-assets/products/qvs/%283-best-practices%29/1-nvr-gb-access-process/FkllVbXux5M0LlZ92y6duf2Npv6-c98b21980ca7.webp)
&#x2A;配置参数说明：*

| 参数       | 说明                                                         |
| -------- | ---------------------------------------------------------- |
| SIP服务器编号 | 填入视频监控平台（QVS）提供的SIP服务器ID                                   |
| SIP域     | SIP服务器ID的前10位                                              |
| SIP服务IP  | 填入视频监控平台（QVS）提供的SIP服务器IP                                   |
| SIP服务器端口 | 填入视频监控平台（QVS）提供的SIP服务器端口号                                  |
| 设备编号     | 填入视频监控平台（QVS）中创建对应的设备时输入或自动生成的设备国标ID，NVR设备的国标ID，11-13位为118 |
| 密码       | 填入视频监控平台（QVS）中创建对应的设备时输入的密码                                |
| 本地SIP端口  | 由于设备默认的本地SIP端口号5060,可能会被局域网屏蔽，建议修改为5061、5062等其他端口号         |

## **视频卡顿/拉流失败时，建议的参数配置** [#视频卡顿拉流失败时建议的参数配置]

当同一个网络内接入的设备过多时或者摄像头所处的网络环境波动较大时，会由于网络带宽的限制导致视频卡顿或者拉流失败，以海康nvr(录像机)为例，建议的参数配置

<br />

![nvr\_1.png](/docs-assets/products/qvs/%283-best-practices%29/1-nvr-gb-access-process/Fp0b-JRnEzcV0z_oEhVCSkYRjc8u-567c60dcd643.webp)

# **接入流程演示** [#接入流程演示]

以下演示的是海康NVR接入

<br />

<video id="video" preload="none" poster="https://dn-odum9helk.qbox.me/Fl4VrPs6534sJ669z2Up8ZVuDEZQ">
  <source id="mp4" src="https://dn-odum9helk.qbox.me/locBHNecnAd7iACpjlkDgV7FTINR" type="video/mp4" />
</video>


# 报警联动(收到报警触发录制截图) (/products/qvs/10-alarm-linkage)



最近更新时间: 2026-08-18 12:01:28

# **使用流程** [#使用流程]

1. 设备必须通过gb28181接入，并具备告警能力(登录到设备的web配置界面，能看到告警配置，代表有告警能力)![test.png](/docs-assets/products/qvs/%283-best-practices%29/10-alarm-linkage/FipySAV3S7DdkIYmNkwI0mGVLUwf-a8517f6ecb76.webp)
2. 如果是`海康`的设备，需要先请求[布防撤防](/products/qvs/gb-alarm/1-their-removal) API，命令为`SetGuard`，才会开启设备报警。
3. 打开设备的告警事件通知(qvs控制台“设备管理”->查看或编辑“设备信息”,以控制告警开关),[控制台告警配置详细步骤](/products/qvs/user-guide/equipment-control/3-alarm-event-notification)。其中`视频报警`必须开启。通过API配置设备的`alarmTypesForRecord`、`alarmTypesForSnap `参数，配置感兴趣的报警类型。如果配置了`alarmTypesForRecord`，还需要配置`recordTime `参数配置收到报警后录像的时长。详细参考[创建设备](/products/qvs/equipment-management-related-interfaces/0-create-device)和[更新设备](/products/qvs/equipment-management-related-interfaces/2-update-the-device)。
4. 创建`按需`录制或者截图模板。关于录制模板的使用方法参考[录制模板](/products/qvs/user-guide/template-management/0-recording-the-template)。关于截图模板的使用方法参考[截图模板](/products/qvs/user-guide/template-management/1-screenshot-of-the-template)。
5. 设备对应的流绑定`按需`录制或者截图模板。关于设备的国标ID和流ID的对应关系参考[使用流接口必读](/products/qvs/flow-management/9-use-the-stream-interface-is-required)。
6. 当设备收到配置的报警列表中的某一个报警时，会触发录制或者截图。
7. 录制或者截图结束之后，可以在视频流管理的[云端录制回放](/products/qvs/user-guide/1-video-streaming-management#3)和[视频截图](/products/qvs/user-guide/1-video-streaming-management#4)页面查看云端录像或者截图。


# RTMP接入流程 (/products/qvs/2-rtmp-access-process)



最近更新时间: 2026-08-18 12:01:51

本文主要简述使用摄像头或OBS进行RTMP接入测试的配置说明。

# **摄像头推流** [#摄像头推流]

## **操作步骤：** [#操作步骤]

1.首先需要在七牛云视频监控产品portal上查询已经添加好的对应的配置信息，获取对应的推流地址，如尚未创建请参考[快速入门](/products/qvs/0-qvs-quick-start)进行配置。
2.登录到摄像头的配置页面，找到RTMP配置页面。
3.请确保视频编码格式为h264，音频编码格式为aac。
4.平台`支持`h265接入和转发,但浏览器大都无法直接播放h265, 因此客户要自行集成[浏览器h265插件](https://github.com/numberwolf/h265web.js), `非浏览器`的h265播放，可以参考我们的[播放器sdk](/products/qvs/0-play-the-sdk)
5.将获取到的推流地址分别填入。
（1）无鉴权
![](/docs-assets/products/qvs/%283-best-practices%29/2-rtmp-access-process/Fonr-typRbxfWtjzIO45YvTfvMfw-892e22cb2f2d.webp)
（2）有鉴权
![](/docs-assets/products/qvs/%283-best-practices%29/2-rtmp-access-process/FhiF9dtuVfEV77tamLf1cTLKF8Hd-33f17a0bcbb9.webp)
5.配置完成后选择启用，点击保存即可。

# **OBS推流** [#obs推流]

## **操作步骤：** [#操作步骤-1]

1.打开 OBS 推流软件，点击设置进入配置页面，选择流这项进行流配置。
![](/docs-assets/products/qvs/%283-best-practices%29/2-rtmp-access-process/FtuR3hW6fitQCvemxkbw0g6A60Mz-a84f13be9f10.webp)
2.将获取到的推流地址分别填入 URL 和 流密钥。
（1）无鉴权
![](/docs-assets/products/qvs/%283-best-practices%29/2-rtmp-access-process/FjVHBktVRVjDqrd3SXNSEKFBjJBo-1ff5bda422e3.webp)
（2）有鉴权
![](/docs-assets/products/qvs/%283-best-practices%29/2-rtmp-access-process/Fg3qC9Q_grOQ2lnOMKM5FQ5qk3_I-95500a2361f8.webp)
3.配置完成后，点击开始推流，进行推流。
![](/docs-assets/products/qvs/%283-best-practices%29/2-rtmp-access-process/FiuTf2OfgPuROwlKbcL_odkevbsL-37adfdeec48a.webp)
4\. obs推流可选优化项，obs推流延迟较大，可以通过以下参数设置，降低端到端的播放延迟。
![OBS.png](/docs-assets/products/qvs/%283-best-practices%29/2-rtmp-access-process/Fund11eq7KmEgdZrTojaMeqqLzsx-344ab6c0ed2d.webp)
5\. 播放器低延迟设置。

* ffmpeg自带的ffplay播放器，命令行参数ffplay '播放地址' -fflags nobuffer
* vlc播放器，Preference=>Input/Codecs=>Default Caching Level下拉菜单选择"Lowest Latency"
* 其他播放器，可以自行参考文档，在播放器的设置选项里，选择对应的低延迟参数


# 按需拉流使用介绍 (/products/qvs/3-on-demand-pull-flow-introduced)



最近更新时间: 2022-12-13 11:58:04

**本文简述了按需拉流的使用方式**。
适用的空间类型为`gb28181`或者`主动拉流`或者`ONVIF`三种。

# **功能介绍** [#功能介绍]

视频的播放都是需要消耗带宽及流量的，为了节省用户流量和带宽，QVS平台支持“按需拉流”。当开启按需拉流后，只有在进行播放的情况下才会有视频流的产生，播放结束后, QVS会自动停止设备推流。

## 按需拉流的2层含义 [#按需拉流的2层含义]

* 有播放请求时自动推流。
* 无人观看时自动断流。
* 同时也可以调用API触发推流，[启动设备推流](/products/qvs/equipment-management-related-interfaces/6-start-device)等同于点击该按钮。<br />  <img src="/docs-assets/products/qvs/%283-best-practices%29/3-on-demand-pull-flow-introduced/FiREN3b9sFFPsQGUChrSdbr8USEH-fb40748820cf.webp" width="450" height="300" alt="开始推流" align="center" /> <br />调用API终止上行推流，[终止设备推流](/products/qvs/equipment-management-related-interfaces/7-stop-device)等同于点击该按钮 <br /> <img src="/docs-assets/products/qvs/%283-best-practices%29/3-on-demand-pull-flow-introduced/Fts8xYXQsozNmsDHM7qMkaQdZsym-7deaec399776.webp" width="450" height="300" alt="开始推流" align="center" />

# **使用流程** [#使用流程]

## **1.如何开启按需拉流** [#1如何开启按需拉流]

**未创建空间**
（1）在七牛云视频监控产品portal上空间管理中点击【创建空间】。
（2）输入空间配置必填项后，开启按需拉流开关即可。
![](/docs-assets/products/qvs/%283-best-practices%29/3-on-demand-pull-flow-introduced/FlI2TPtpmOTVuqjBKgSuErvQ4lUH-567aa21b9e2a.webp)
**已创建空间**
（1）在七牛云视频监控产品portal上查询已经创建的业务空间。
（2）打开对应业务空间的配置并进行编辑操作。
（3）开启按需拉流开关。
![按需拉流](/docs-assets/products/qvs/%283-best-practices%29/3-on-demand-pull-flow-introduced/FnVplc5T8UIeD9LOjfBxyvn_Qde2-767ee9027064.webp)

## **2.开启按需拉流后如何触发摄像头推流** [#2开启按需拉流后如何触发摄像头推流]

（1）portal上实时预览页面中点击“启动拉流” 操作。
（2）通过[启动设备拉流](/products/qvs/equipment-management-related-interfaces/6-start-device)api。
（3）播放器进行播放请求。
以上3种都会触发摄像头推流，并且在无人观看持续60s左右，会自动终止摄像头推流。

# **额外提示** [#额外提示]

1. 按需拉流, 适用的空间类型为`gb28181`或者`主动拉流`或者`ONVIF`三种; 如果是rtmp类型, 则需要客户先提交工单, 等后台开启后,可体验该功能。
2. 按需拉流和按需录制是无关的，两者之间没有关联。
3. 普通模板和按需模板区别:如果绑定了普通的录制/截图模板,设备只要开始推流, qvs就会自动开始录制/截图。 如果绑定了“按需”类型的模板，则需要通过api触发录制的[开始](/products/qvs/recording/0-start-record-stream)或者[结束](/products/qvs/recording/1-stop-record-stream)。


# 低延时实时直播-webrtc接入流程 (/products/qvs/4-low-latency-will-broadcast-live-webrtc-access-process)



最近更新时间: 2026-05-08 14:14:53

# webrtc拉流协议介绍 [#webrtc拉流协议介绍]

七牛云视频监控产品(qvs)在现有的3种播放协议(hls, http-flv, rtmp)基础上，拓展了第4种播放协议webrtc。该协议实时延迟可达到500毫秒左右，可以满足客户对低延迟场景的需求

# webrtc拉流播放实现架构 [#webrtc拉流播放实现架构]

![1\_1.png](/docs-assets/products/qvs/%283-best-practices%29/4-low-latency-will-broadcast-live-webrtc-access-process/FuMSZdOGcggsXgULqOsnJrj1jcCk-1d08537e1a26.webp)

# 核心优势 [#核心优势]

* 95%情况下, 实时监控延迟在300-500毫秒区间内

# 快速体验 [#快速体验]

* `http`环境: <a href="http://live-player-demo.qiniu.com/">http环境webrtc播放器测试</a>

* `https`环境:`当切仅当`为域名[配置ssl证书](/products/qvs/user-guide/equipment-control/0-qvs-https-configuration)后,方能体验 <a href="https://live-player-demo.qiniu.com/">https环境webrtc播放器测试</a>

* webrtc地址如何获取
  * 方式1 通过qvs控制台，点击实时预览页面，会返回webrtc播放地址。
  * 方式2 <a href="/products/qvs/flow-management/obtain-flow-address"> 通过API获取webrtc播放地址 </a>
  * 最终的地址形式
    * 1> 如果是动态接入的空间
    * http环境：webrtc://ip:1240/空间id/流id
      https环境：无法使用ip的形式进行播放 。
    * 2>如果是静态接入的空间
      http环境：webrtc://域名:1240/空间id/流id
      https环境：webrtc://域名:447/空间id/流id, 前提要[配置https ssl证书](/products/qvs/user-guide/equipment-control/0-qvs-https-configuration)

# 前提限制 [#前提限制]

* 需要使用七牛的播放器进行webrtc拉流播放
* rtmp推流时, 不能含有B帧(webrtc播放不支持B帧)，具体情况请参考以下tips
  * 1. 使用ffmpeg进行rtmp推流时,务必要携带 -bf 0参数, 例如ffmpeg -re -i xxx.mp4 -c copy -c:v libx264 `-bf 0` -f flv 'rtmp推流地址'
  * 2. 使用obs推流时, 如下图所示
    <img src="/docs-assets/products/qvs/%283-best-practices%29/4-low-latency-will-broadcast-live-webrtc-access-process/FgNBl1S2A0RimDhFuFHM86fA9b17-02880e2a815d.webp" width="450" height="300" alt="obs rtmp推流设置" align="center" />
  * 3. 小程序rtmp推流不包含B帧，可以跳过该条
  * 4. 使用七牛安卓/ios推流sdk，可以通过函数设置BaseProfile, 也可以去除B帧
  * 5. 其他第三方rtmp推流工具/sdk， 可以自行查看文档
  * 6. 安防行业的摄像头(ipc)或者录像机(nvr)，自带的rtmp推流，默认都不包含B帧，可以跳过该条
* 采用gb28181接入的摄像头(ipc)或者录像机(nvr)注意的情况
  * 1.建议在摄像头的视频参数配置界面。1>设置可变码率 2> I帧间隔 = 帧率 \* 2，3>如果需要开启音频， 设置为 g711-alaw, 采样率8K

<img src="/docs-assets/products/qvs/%283-best-practices%29/4-low-latency-will-broadcast-live-webrtc-access-process/Fs0WnLsU25BJzsacWqmuMcX3cUBw-517055317825.webp" width="450" height="300" alt="gb28181视频设置" align="center" />

# 正式接入流程 [#正式接入流程]

体验了以上流程之后，正式接入步骤参考如下

* 七牛webrtc快直播-低延时播放器SDK 下载
  * Android SDK 下载：[QNRTPlayer-Android](https://github.com/pili-engineering/QNRTPlayer-Android)、
    * [\<低延迟Android SDK使用说明>](/products/mikustream/miku-fast-live-sdk/2-miku-fast-live-android-sdk)
  * iOS SDK 下载：[QNRTPlayer-iOS](https://github.com/pili-engineering/QNRTPlayer-iOS)
    * [\<低延迟iOS SDK使用说明>](/products/mikustream/miku-fast-live-sdk/3-miku-fast-live-ios-sdk)
  * Web SDK 下载：[QNRTPlayer-Web](https://github.com/pili-engineering/QNRTPlayer-Web)
    * [\<低延时 Web SDK使用说明>](/products/mikustream/miku-fast-live-sdk/1-miku-fast-live-web-sdk) 低延迟web sdk需要浏览器支持 RTC 和 H264 解码，目前部分 Android 手机自带浏览器并未支持 RTC。在这种情况下，我们建议更换浏览器或直接使用移动端的 SDK, ios端:[\<低延时 iOS SDK>](https://github.com/pili-engineering/QNRTPlayer-iOS);安卓端:[\<低延时 Android SDK>](https://github.com/pili-engineering/QNRTPlayer-Android).

* Demo 体验
  Android Demo: [http://fir.qiniuapi.com/dun3](http://fir.qiniuapi.com/dun3)

<img src="/docs-assets/products/qvs/%283-best-practices%29/4-low-latency-will-broadcast-live-webrtc-access-process/Fv_8SGcyCOyUH6fhPgOyghoh_ZW-ac7b393dff5a.webp" width="200" height="200" alt="Android Demo" align="center" />

iOS Demo: [https://testflight.apple.com/join/qZY1QFvV](https://testflight.apple.com/join/qZY1QFvV)

<img src="/docs-assets/products/qvs/%283-best-practices%29/4-low-latency-will-broadcast-live-webrtc-access-process/FhPGfP-MpmShRHQzo_89gCV7I8tk-1dd6ecec662a.webp" width="200" height="200" alt="IOS Demo" align="center" />


# 设备本地录像上传云端存储 (/products/qvs/5-local-video-upload-the-cloud)



最近更新时间: 2026-05-06 16:46:20

本文讲述如何将设备本地录像上传到云端进行存储。本地录像上传需要提前在设备上开启开关，并配置独立的录制模板。平台通过国标协议拉取本地录像文件到云端后，并根据设备上设置的录制模板录制存放到云端。

# 前期准备 [#前期准备]

## **设备注册** [#设备注册]

设备已成功注册到七牛云视频监控平台，并且设备本地已存在录像文件。

## **设置录制模板** [#设置录制模板]

1.登录[七牛开发者平台](https://sso.qiniu.com/?client_id=PIapUKqa3u6S24H868BelwrG0OFu8dS7AxVQ8oz8HznLXhgrl2BnjaO9cs9LzxK2\&redirect_url=https:%2F%2Fportal.qiniu.com%2Fapi%2Fgaea%2Fsso%2Fsignin%3Fredirect%3D%252Fcreate)
2.选择**视频监控**产品，进入产品控制台，选择**设备管理**，进入设备管理页面，检索对应的设备，点击**查看**，进入设备详情页面选择**编辑**，开启本地录像开关并绑定对应的录制模板。如未创建录制模板请先创建录制模板在进行绑定录制模板操作。[【如何创建录制模板】](/products/qvs/user-guide/template-management/0-recording-the-template)
&#x2A;注：*
*1. 需要做两件事，1. 空间上绑定按需录制的模版, 2. 设备上绑定实时录制的模版*
&#x2A;2.在空间中绑定的模版，录制方式选项选择`按需录制`*
&#x2A;3.在设备本地录像开关里配置的录制模板中，录制方式选项只能是`实时录制`的模板。*
![设备列表](/docs-assets/products/qvs/%283-best-practices%29/5-local-video-upload-the-cloud/FifJ3QOiNC14Z2OkjajzqIpKF3YS-2d5e20c8841e.webp)
![编辑设备](/docs-assets/products/qvs/%283-best-practices%29/5-local-video-upload-the-cloud/FpYzAmROdTJxM4O7ecHvDjCi8J6i-0cd89fd9fdd3.webp)

# 本地录像上传 [#本地录像上传]

做完以上准备工作后可以开始本地录像上传操作。

## **1.开始本地录像上传** [#1开始本地录像上传]

调用[【本地录像上传云端API】](/products/qvs/local-video-playback/1-uploaded-to-the-cloud)
**请求示例**

```
curl --request POST \
  --url http://qvs.qiniuapi.com/v1/namespaces/2akrarvzvyijd/devices/31011500991320000028/sdcardsave/start \
  --header 'authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:u372aQV0359mzwTVGxn22sRgFYc=' \
  --header 'content-type: application/json'
  --data '{
	"channelId": "34020000001310000003",
	"start":1612191900,
	"end":1612191960
}'
```

**请求参数说明**
路径参数：

| 参数名称        | 必填 | 字段类型   | 说明     |
| ----------- | -- | ------ | ------ |
| namespaceId | 是  | string | 空间ID   |
| gbId        | 是  | string | 设备国标ID |

Body：

| 参数名称      | 必填 | 字段类型    | 说明                 |
| --------- | -- | ------- | ------------------ |
| channelId | 否  | string  | 平台设备指定需要启动的通道国标ID  |
| start     | 是  | integer | 开始时间(unix时间戳,单位为秒) |
| end       | 是  | integer | 结束时间(unix时间戳,单位为秒) |

## 注意事项： [#注意事项]

## **1.新建两个模板，模板A(按需)和模板B(实时),模板A和模板B设置的bucket保持一致即可;分别在空间上绑定A，在设备上绑定B； 就可以`只录制本地视频，不录制实时视频`, 如果需要同时录制本地和实时视频, 则把模板A和模板B都设置为“实时录制”** [#1新建两个模板模板a按需和模板b实时模板a和模板b设置的bucket保持一致即可分别在空间上绑定a在设备上绑定b-就可以只录制本地视频不录制实时视频-如果需要同时录制本地和实时视频-则把模板a和模板b都设置为实时录制]

## **2.上述中的API操作，会触发设备上传本地视频，若收到流状态回调，代表本地视频成功推流；也可以在流管理页面，查询到对应的流状态在线。** [#2上述中的api操作会触发设备上传本地视频若收到流状态回调代表本地视频成功推流也可以在流管理页面查询到对应的流状态在线]

## **3.在`需要提前终止录像上传`时，触发[终止本地录像上传](/products/qvs/local-video-playback/2-stop-uploaded-to-the-cloud)接口即可终止本地录像上传；否则等待视频上传结束即可** [#3在需要提前终止录像上传时触发终止本地录像上传接口即可终止本地录像上传否则等待视频上传结束即可]

## **4.本地录像上传时生成的流id为`31011500991320005819_history_1677744290_1677747005`类似形式，上传成功后只需要去QVS控制台打开id为`31011500991320005819`的流管理页面，然后选择对应日期检索(如上面1677744290\_1677747005时间戳对应的日期)即可找到上传成功的录像** [#4本地录像上传时生成的流id为31011500991320005819_history_1677744290_1677747005类似形式上传成功后只需要去qvs控制台打开id为31011500991320005819的流管理页面然后选择对应日期检索如上面1677744290_1677747005时间戳对应的日期即可找到上传成功的录像]


# 配置域名的CNAME (/products/qvs/6-configure-cname)



最近更新时间: 2021-08-30 19:28:52

本文主要讲述使用静态方式接入时，如何配置域名的CNAME。

# CNAME 概述 [#cname-概述]

CNAME 即指别名记录，也被称为规范名字。一般用来把域名解析到别的域名上，当需要将域名指向另一个域名，再由另一个域名提供 ip 地址，就需要添加 CNAME 记录。

# CNAME 配置 [#cname-配置]

如果需要对域名进行 CNAME 配置，您可以在配置完域名后，通过以下方式为您的域名添加解析。

## 一. 获取CNAME值 [#一-获取cname值]

在 **七牛开发者平台** 页面选择 [**视频监控**](https://portal.qiniu.com/qvs/overview) ，选择 [**空间管理**](https://portal.qiniu.com/qvs/namespace)，然后选择对应的空间并进入，选择**域名管理**模块，如下图所示：
&#x2A;注：域名管理只支持静态接入的空间。*
![1.png](/docs-assets/products/qvs/%283-best-practices%29/6-configure-cname/FrEdQKV3v3eO3Y8EtUrgsyUK-Gqx-5a9ff2d9d43f.webp)

## 二. 添加CNAME记录 [#二-添加cname记录]

添加CNAME记录需要在您的**域名厂商**处配置，比如您在 阿里云 / 腾讯云 / 新网 等处购买的域名，您需要前往**购买域名的厂商*&#x2A;相应管理控制台，添加域名解析。
1.打开您购买域名的厂商官网，登陆后在页面右上角找到 &#x2A;*`控制台`** 或 相关管理后台入口。
如果您不清楚域名解析的入口，建议查看您域名厂商的产品文档，或者寻求域名厂商的售后支持。
2\. 在域名厂商的控制台中，找到您的域名解析添加页面，例如：
a.  阿里云：在控制台页面的左侧，产品与服务栏中选择 **域名**。
b.  腾讯云：在控制台的云产品中，搜索并选择 **云解析**。
c.  DNSPOD：在控制台页面左侧，选择 **域名**。
其他域名厂商请参考产品文档说明或咨询产品售后。
3\. 在域名产品的列表中找到您域名对应的`主域名&#x60;，点击域名后面的 &#x2A;*`解析设置`** 或 `解析`，进入解析设置页。
4\. 选择 `添加记录` ，依次填写 **主机记录**，**记录类型** 以及 **记录值**，其他可设为默认值。
如果您不清楚如何填写主机记录，请参考下文第5步提供的示例。

<img src="/docs-assets/products/qvs/%283-best-practices%29/6-configure-cname/Fn5LvRsKMEUgBQM4PvvAccI-ISyO-fd142884247f.webp" width="1000" />

| 参数   | 填写说明             | 注意事项          |
| ---- | ---------------- | ------------- |
| 主机记录 | 填写域名对应的主机前缀      | 该参数唯一，请勿自定义   |
| 记录类型 | 选择 CNAME 类型      | 该参数唯一，请勿自定义   |
| 线路类型 | 保持默认             | 该参数可以根据需求自行调整 |
| 记录值  | 域名创建后，七牛提供的CNAME | 该参数唯一，请勿自定义   |
| TTL  | 保持默认             | 该参数可以根据需求自行调整 |

<br />

5.解析示例：

假设您购买的一级域名为 qiniu.com
您需要先在七牛视频监控控制台创建域名，比如您创建了 cdn.qiniu.com 或 img.qiniu.com 之类的自定义二级域名。
创建完成后，在域名厂商后台添加解析记录时，您需要填写主机记录为域名对应的前缀，如 cdn 或 img 即可。

常见的普通域名主机记录填写方式举例：

| 创建的域名                                 | 域名类型 | 主机记录      |
| ------------------------------------- | ---- | --------- |
| qiniu.com                             | 普通域名 | @         |
| [www.qiniu.com](http://www.qiniu.com) | 普通域名 | www       |
| cdn.qiniu.com                         | 普通域名 | cdn       |
| video.cdn.qiniu.com                   | 普通域名 | video.cdn |

# 如何判断 CNAME 是否正确配置？<a id="check" /> [#如何判断-cname-是否正确配置]

* linux/mac系统您可以通过如图所示的命令 `dig 您的域名` 查看，第一条是否解析到您配置的CNAME值。
  <img src="/docs-assets/products/qvs/%283-best-practices%29/6-configure-cname/FhZC_DzsNzPA6PzpD2ApNdy1udEE-780c5a91c6c6.webp" width="600" />

* windows系统可以通过Win+R 或 点击左下角的“开始”按钮打开“开始”菜单，打开“运行”，输入cmd回车。
  在命令行模式下输入`nslookup 您的域名`，例如 nslookup qn.vinchi.club,在结果中可以看到您复制的cname值即可。

  <img src="/docs-assets/products/qvs/%283-best-practices%29/6-configure-cname/FpCsAmZwHyxWvWpIUSQE59GXgGpV-0d2580d32294.webp" width="400" />


# 利用国标告警大幅减少云存储成本 (/products/qvs/7-using-national-standard-warning-greatly-reduces-costs-of-cloud-storage)



最近更新时间: 2022-07-13 11:50:03

# **前置准备** [#前置准备]

* 设备必须通过gb28181接入，并具备告警能力(登录到设备的web配置界面，能看到告警配置，代表有告警能力)![test.png](/docs-assets/products/qvs/%283-best-practices%29/7-using-national-standard-warning-greatly-reduces-costs-of-cloud-storage/FipySAV3S7DdkIYmNkwI0mGVLUwf-a8517f6ecb76.webp)
* 打开设备的告警事件通知(qvs控制台“设备管理”->查看或编辑“设备信息”,以控制告警开关),[控制台告警配置详细步骤](/products/qvs/user-guide/equipment-control/3-alarm-event-notification)
* 设置回调地址(控制台“空间管理”->选择某个空间点击“配置”->`基本信息`界面中点击`编辑`，可配置回调地址)。平台会把设备上的告警回调给客户
* 空间绑定录制模板。(控制台“空间管理”->选择某个空间点击“配置”->"模版配置")，录制模板`录制方式务必为“按需录制”`

# **使用流程** [#使用流程]

* 当客户收到qvs的回调通知时，解析回调[回调数据示例](/products/qvs/space-management/7-the-message-callback)
* 回调数据 "type": "alarm"，代表是来自设备的告警消息；客户可根据具体的告警类型，[触发云端录制](/products/qvs/recording/0-start-record-stream)，一段时间后(例如录制6s的视频后)或者一段时间内，无新的告警时，[终止云端录制](/products/qvs/recording/1-stop-record-stream)
* 通过以上功能组合，客户可以只保存告警发生时的视频，例如摄像头有画面移动时触发的`移动侦测，入侵检测等`，而不必7 \* 24小时录制，从而消减存储成本


# 摄像头ONVIF接入流程 (/products/qvs/8-onvif-access-process)



最近更新时间: 2026-05-06 17:01:37

**本文简述了使用ONVIF协议接入时配置流程**。

# 1. 添加ONVIF用户名和密码 [#1-添加onvif用户名和密码]

## **大华设备添加ONVIF用户名和密码示例** [#大华设备添加onvif用户名和密码示例]

（1） 登录摄像头web页面
（2） 依次点击"系统管理"→"用户管理"→"ONVIF用户"
（3）点击"增加用户"
![增加用户.png](/docs-assets/products/qvs/%283-best-practices%29/8-onvif-access-process/FsOChR7Qe4x5y53AfprS-cvSy0uA-bb57ac8da73a.webp)
（4） 输入用户名和密码
![用户名密码.png](/docs-assets/products/qvs/%283-best-practices%29/8-onvif-access-process/FrfcPZfjIdgmer-mGIeI6d2Kqpsp-46955c9faea7.webp)

# 2. 七牛控制台创建ONVIF空间 [#2-七牛控制台创建onvif空间]

创建空间时接入类型选择`ONVIF`
![创建空间.png](/docs-assets/products/qvs/%283-best-practices%29/8-onvif-access-process/Fg2TmN5lxTRZMP0LDvst882FnS-z-567521ac8b84.webp)

# 3. 创建ONVIF设备 [#3-创建onvif设备]

在第2步创建好的`ONVIF`空间，创建一个设备

（1）设备ip地址，填入设备的`公网IP`（内网设备可以使用内映射工具，比如花生壳）。
（2）填入设备ONVIF的端口，一般是80。如果设备没有公网ip，也可以将80端口映射到公网的某个端口，比如`8080`,则这里需要填入映射后的端口`8080`。
（3）填入流端口号，如果设备有`公网IP`，一般这个端口默认是`554`；如果设备没有公网IP，需要将该设备的`554`端口映射到公网的某个端口，例如映射到`8554`端口，则这里的流端口号填入`8554`。
（4）填入第1步在摄像头添加的ONVIF用户名和密码。
![创建onvif设备.png](/docs-assets/products/qvs/%283-best-practices%29/8-onvif-access-process/Fr0rc-zHKuEKA_fRp3DvvEdhoMpg-0ad1bf9d34ba.webp)

# 4. 实时预览 [#4-实时预览]

（1） 在设备列表页面，选择添加好的设备，点`实时预览`，进入到实时预览页面。
![设备列表.png](/docs-assets/products/qvs/%283-best-practices%29/8-onvif-access-process/FigshM98Px0G-FpKLnRbBaXadqHw-624060a1f5e6.webp)
（2）点`启动拉流`，观看摄像头的实时流。
![实时预览.png](/docs-assets/products/qvs/%283-best-practices%29/8-onvif-access-process/Fg6mNjwjvYOdVwiPOX5nQZ4RplHQ-550e02a65e28.webp)


# 任意时间段的本地录像回放 (/products/qvs/9-any-time-the-local-video-playback)



最近更新时间: 2022-12-13 10:50:23

1. 拼接流ID。
   对于本地录像回放，如果希望播放任意时间段内的录像，需要手动构造流ID。当设备类型为摄像头时，流ID格式为设备国标ID\_history\_开始时间戳\_结束时间戳；当设备类型为平台时，流ID格式为设备国标ID\_通道ID\_history\_开始时间戳\_结束时间戳。
   **示例**：
   假设目前有一个NVR国标ID为`31011500991320020874`，通道ID为`34020000001310000001`，希望观看`2022-12-22 00:00:00`到`2022-12-22 23:59:59`时间段内的录像。
   开始时间`2022-12-22 00:00:00`转换的`uninx时间戳`为`1671638400`。
   结束时间`2022-12-22 23:59:59`转换的`unix时间戳`为`167172479`
   则流ID为: `31011500991320020874_34020000001310000001_history_1671638400_1671724799`。

2. 获取播放地址。

   * 如果空间已经配置了域名，则请求[静态模式获取流地址](/products/qvs/flow-management/obtain-flow-address/0-static-model)接口获取流地址。
   * 如果空间没有配置域名， 则请求[动态模式获取流地址](/products/qvs/flow-management/obtain-flow-address/1-dynamic-model)接口获取流地址。

        请求示例

```
    curl --request POST \
    --url http://qvs.qiniuapi.com/v1/namespaces/d102sni9zryu/streams/31011500991320020874_34020000001310000001_history_1671638400_1671724799/urls \
    --header 'authorization: QiniuStub j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:u372aQV0359mzwTVGxn22sRgFYc=' \
    --header 'content-type: application/json' \
    --data '{
      "publishIp":"116.236.177.50",
      "playIp":"116.236.177.50"
    }'
```

        响应示例

```
{
  "playUrls": {
    "rtmp":"rtmp://180.101.136.82:2045/qiniu/31011500991180013390_34020000001310000006_history_1670799600_1670835600?e=1670851888\u0026token=52fdfc072182654d%3A1uPRRnu6M6aWZ_IVVHahdCjgFDk",
    "flv":"http://180.101.136.82:1360/qiniu/31011500991180013390_34020000001310000006_history_1670799600_1670835600.flv?e=1670851888\u0026token=52fdfc072182654d%3AQAghBKuIO35EJVlT0uYI9iEr_Ms",
    "hls":"http://180.101.136.82:1370/qiniu/31011500991180013390_34020000001310000006_history_1670799600_1670835600.m3u8?e=1670851888\u0026token=52fdfc072182654d%3A7ZmDc6X5bsZIuig7cRA6-HXInJU",
    "webrtc":"webrtc://180.101.136.82:1240/qiniu/31011500991180013390_34020000001310000006_history_1670799600_1670835600?e=1670851888\u0026token=52fdfc072182654d%3AYPD6HRoJFayO1iCMUiMlOrXsueg"
   },
  "onlineState":false,
  "disabled":false,
  "publishUrlExpired":1670851888
}
```

3. 在播放器中播放播放获取到的流地址。

```
fflay http://180.101.136.82:1370/qiniu/31011500991180013390_34020000001310000006_history_1670799600_1670835600.m3u8?e=1670851888\u0026token=52fdfc072182654d%3A7ZmDc6X5bsZIuig7cRA6-HXInJU
```


# 国标接入问题排查 (/products/qvs/0-gb-access-problems)



最近更新时间: 2026-08-18 12:02:29

# 设备注册失败/离线, 通道数量为0等问题 [#设备注册失败离线-通道数量为0等问题]

1. 本条建议`很很很很很`关键,设备网络设置成`自动获取IP`。以海康为例,登入设备的配置界面, 在`网络->基本设置->Tcp/Ip->勾选自动获取`。
2. `路由器`问题，某社区1500个摄像头，每天固定时间集体离线后并无法恢复；排查后是路由器定时重启造成的, 路由器重启后, 设备的gb28181 udp数据报被路由器莫名丢弃了，无法与外部通信；解决办法，1. `关闭`路由器定时重启 2. 重启摄像头或者NVR。
3. 设备网络如果是定向流量卡, 发出的网络数据都被运营商屏蔽,需要联系运营商添加IP白名单。
4. 检查摄像头/NVR所处的网络，是否能够连通SIP服务器的IP跟端口。
5. 检查摄像头/NVR的置国标配置页面，查看SIP服务器ID、SIP服务器IP和端口是否正确，是否为七牛云QVS提供的SIP服务器ID、IP和端口。
6. 是否配置了SIP域，如果配置了请确保SIP域为SIP服务器ID的前10位数字。
7. 检查是否正确配置,七牛云QVS设备管理中的设备国标ID。`宇视设备在“国标本地设置”选项卡中，SIP服务器编码是设备国标ID，而非SIP服务器ID。`
8. 设备的名称或者通道编号，含有特殊字符，`空格`等，会导致无法解析，而导致异常。
9. `视频通道ID`是空的，或者配置错误,NVR请参考[NVR接入最佳实践](/products/qvs/1-nvr-gb-access-process), 普通摄像头请参考[摄像头接入最佳实践](/products/qvs/0-gb-access-process)。
10. 个别摄像头或者NVR,设备固件存在bug, Catalog信令返回数量为0或没有应答Catalog, 如果确认配置正确的情况下,请反馈给设备厂商,升级国标固件。
11. 假如以上无果，`重启设备`，观察能否成功在线。

# 为什么设备是在线的，流是离线的？ [#为什么设备是在线的流是离线的]

* **先来了解，什么是设备状态，什么是流状态**

<img src="/docs-assets/products/qvs/%285-troubleshooting%29/0-gb-access-problems/FrhlPVQvSUfmdDZEMagXc9SpT0Lw-5f262c5cb355.webp" width="600" height="450" alt="gb28181视频设置" align="center" />

<br />

* 如上图所述，当设备和“qvs信令服务”之间通过信令通道，存在周期性的保活心跳，设备就处于在线状态。<br />
* 信令通道传递的是文本字符，流量很小，qvs不收取流量费用。<br />
* 只有流媒体通道打开时，既设备开始推流时，才会产生上行的推流费用。<br />
* 设备状态和流状态是独立的2种状态。设备在线时，流离线有以下几种可能。
  1.开启了按需拉流
  开启了按需拉流后，当视频流无人观看持续60s左右，会自动终止推流，此时流就显示离线。
  开启按需拉流时，启动流的三种方式：
  （1）portal上，“设备管理”界面下，实时预览中点击“启动拉流” 操作。
  （2）通过[api触发](/products/qvs/equipment-management-related-interfaces/6-start-device)摄像头推流。
  （3）播放器触发播放请求。
  （4）如果想保持视频流永远在线，可以关闭“按需拉流”。 操作如下,控制台界面中，“空间管理”-> 点击“配置”-> 空间信息，点击"编辑"-> 置灰"按需拉流"->点击 "确定"。则在此操作之后，视频流在下次重新推流时生效。

2. 如果以上都是正常的，依然无法拉流播放，请参考下面的片段[视频流卡顿，黑屏，无法观看等问题定位](#视频流卡顿，黑屏，无法观看等问题定位)。

# 视频流卡顿，画面异常，中断，首开慢等问题定位 [#视频流卡顿画面异常中断首开慢等问题定位]

如果是通过摄像头接入qvs的情况下，登录到摄像头的视音频参数配置界面；如果是通过NVR接入，或者摄像头被挂载到一个NVR下面时，则需要登录至NVR中修改相应参数。

1. 由于暂不支持H.265视频在web中预览，设备接入后,可在视频参数配置页面，修改成H.264。
2. 视频分辨率和帧率根据自身需求选择，若在同一网络下接入设备较多的情况下，可选择低分辨率，从1080p降低为720p，甚至更低的分辨率。
3. `最最重要的选项，码流控制/码率类型，选择 “可变码率”，等同于英文简写VBR。`
4. 在视频配置界面里，帧率设置有些设备默认是全帧率，帧率需调整为15，I帧间隔 = "视频帧率" \* 2，即30。
5. 码流上限，分辨率720P时选择1024；分辨率为1080p时选择2048；也可以根据实际视频效果在调整。
6. 如果不需要在web浏览器中预览，也可以选择h265，此时需要使用[七牛的播放器SDK](/products/qvs/0-play-the-sdk)或者自行去第三方播放器(例如vlc，ffplay等)进行实时播放。综上视频异常建配置如下图：
   分辨率720p的建议配置

<img src="/docs-assets/products/qvs/%285-troubleshooting%29/0-gb-access-problems/Fl-mFjONAWpXH5jOdAmwBAGJvm9U-8fe038b83a2f.webp" width="450" height="300" alt="gb28181视频设置" align="center" />

分辨率1080p的建议配置

<img src="/docs-assets/products/qvs/%285-troubleshooting%29/0-gb-access-problems/FuWma0CFM8BtQhJ2DbvkG30qL6CM-600f7a5e03b6.webp" width="450" height="300" alt="gb28181视频设置" align="center" />

<br />

7. 有些设备对gb28181存在兼容性问题.最典型的是设备通过gb28181推流时, 实际携带的ssrc(视频流的身份证)，与平台告诉设备的ssrc不一致，此时平台会拦截非法的视频流，导致无法观看。解决办法，尝试升级固件，如果还是解决不了，可提交工单，等待七牛进一步确认，如果确认是设备bug，我们会提供设备bug证据，客户可携带证据联系硬件设备厂商，修复设备上的bug。
8. 确认设备所在网络是否有防火墙，防火墙是否开启了入口的限制。
9. 有的设备只支持`tcp`或者`udp`拉流，在设备的`基本信息`页面，切换流传输模式，如果当前为`tcp`,则切换为`udp`;如果当前为`udp`, 则切换为`tcp`。一般可拉流成功。
10. 如果以上都尝试过，仍无法解决，请提[工单](https://support.qiniu.com/tickets/new/?space=%E8%A7%86%E9%A2%91%E7%9B%91%E6%8E%A7)提问。

# 预览界面声音异常或无声 [#预览界面声音异常或无声]

1. 首先确保设备有音频输入。
   &#x2A;*说明：**
   1.通过国标gb28181传输的音频，音频编码优先配置`g711alaw`, 采样率优先选择`8000`, 没有g711alaw的情况下, 选择aac + 8000采样率。

<img src="/docs-assets/products/qvs/%285-troubleshooting%29/0-gb-access-problems/Fo-AjhyR6-ssR_GkXHORglOt5Yo0-cf3d5f5f0b97.webp" width="450" height="300" alt="gb28181音频设置" align="center" />

2. gb28181接入的设备，在存在音频输入的条件下，标准规范是：视频和音频 （h264 + g711或者aac）要封装到ps包里发出(主流的海康，大华，宇视等都是这种标准音频打包方式。个别硬件厂商，会单独把音频包通过RTP包发出，这种格式不符合gb28181规范)，如果不是这种方式，则无法播放音频，如果不确定，可以跟摄像头供应商确认。


# QVS视频监控常见问题FAQ (/products/qvs/1-qvs-q-a)



最近更新时间: 2026-08-14 14:27:29

# 1、空间为何看不到域名配置 [#1空间为何看不到域名配置]

一.创建空间时，模式选择了`动态地址`，所以看不到域名配置；怎么才能看到`域名配置`界面?
1> 新建空间，模式选择“静态地址”
2> 不想新建空间? 请提工单，后台为您转换。

二. 空间转换为`静态地址`后，需要客户做
1> 在域名管理界面新增域名，并[配置cname](/products/qvs/6-configure-cname)
2> 可选项，如果需要https的环境播放实时视频流，则需要进一步为域名[配置https证书](/products/qvs/user-guide/equipment-control/0-qvs-https-configuration)

# 2、为什么配置了录制模板，却无法回看历史视频 [#2为什么配置了录制模板却无法回看历史视频]

一. 用户可在qvs的控制台，视频流管理板块，找到对应的视频流，当点击“云端录制回放时”，qvs会从存储空间(buceket)里读取文件；读取文件依赖有效的回放域名，此域名需要客户自行在七牛对象存储系统里配置(此域名与qvs自身的直播域名是独立的)。(存储空间会赠送有效期1个月的默认域名，1个月后该域名会被回收，客户需要提供自己的有效域名)[添加录制回看的CDN域名](https://portal.qiniu.com/cdn/domain/create)。

<img src="/docs-assets/products/qvs/%285-troubleshooting%29/1-qvs-q-a/FmRyS6FkcR4rLfLqLWkHYKh5DroD-c85bc386264d.webp" width="500" height="200" alt="cdn" align="center" />

# 3、推流或者播放地址如何提高安全性 [#3推流或者播放地址如何提高安全性]

* 建议打开时间戳防盗链，打开方法如下
* 如果空间类型是`动态地址`类型（IP形式的播放地址）, 点击 "空间管理"-> 选择某个空间, 点击"配置" ->在空间信息里，点击"编辑"->设置"URL 鉴权"即可。
  ![image.png](/docs-assets/products/qvs/%285-troubleshooting%29/1-qvs-q-a/FhYi9aEsbJrk9b2HdcCArIR4tz3d-1f0c79162341.webp)
* 如果如果空间类型是静态地址类型（域名形式的播放地址）。在域名管理里设置。点击 "空间管理"-> 选择某个空间, 点击"配置"->选择"域名管理"->找到想开启时间戳防盗链的域名,点击'配置'。
  ![image.png](/docs-assets/products/qvs/%285-troubleshooting%29/1-qvs-q-a/Fo4-l7tBcrh6c8WzNPYgwU75N6SF-41a0f7cb3eda.webp)

# 4、调试web播放时，浏览器为何出现跨域错误 [#4调试web播放时浏览器为何出现跨域错误]

一. 因为使用姿势错误，在http的环境里，使用了https的播放地址; 或者在https的环境中使用了http的播放地址。
二. 解决办法，先阅读入门文档，了解一下[基本概念](/products/qvs/0-qvs-quick-start#2)
三. 静态接入的情况下，在域名管理里，开启`https`开关后，刷新实时预览，看到的地址就是https环境专用地址；反之看到的就是http环境专用地址

# 5、WebRTC播放黑屏，无画面，怎么处理？ [#5webrtc播放黑屏无画面怎么处理]

* 可以先检查下环境协议与端口是否不匹配导致的：<br /> 1). http环境 “webrtc://播放域名:1240/空间id/流id”；<br /> 2). https环境"webrtc://播放域名:447/空间id/流id"。
* 环境协议与端口正常的话，可以再检查下视频编码格式，在设备端将视频编码格式修改为H.264，音频编码格式设置为AAC 格式，然后保存重启设备后，重新推流测试看下

# 6、java如何调用qvs接口？ [#6java如何调用qvs接口]

* 通过 Maven 引入java SDK

```bash
<dependency>
  <groupId>com.qiniu</groupId>
  <artifactId>qiniu-java-sdk</artifactId>
  <version>[7.19.0, 7.19.99]</version>
</dependency>
```

* 然后调用qvs相关方法即可，具体参考 [java SDK](/products/qvs/qvs-service-sdk/0-qvs-java-sdk) 说明文档和示例

# 7、视频监控和miku直播的差异？如何选择？ [#7视频监控和miku直播的差异如何选择]

一. 视频监控一般用于监控设备（摄像头、录像机）或监控平台等支持GB28181协议、且不需要大量客户端同时去拉流播放的监控场景使用；<br /> 二. miku直播主要用于RTMP/SRT 推流、大规模的 FLV/HLS 直播 CDN 分发、和超低延时的 WHEP 协议拉流直播的场景；<br /> 三. 可以根据您的设备支持的推流协议、是否需要大量拉流播放等情况来选择对应产品

# 8、按需拉流重新唤醒导致播放延迟 [#8按需拉流重新唤醒导致播放延迟]

一. 开启了按需拉流，这个流程是客户端拉流，服务端收到拉流请求，发信令给设备，设备推流，服务端收到推流后再发设备流，这个流程比较长会影响首开效率，不过首次拉流成功，退出后立即再拉流应该会很快。<br />二. 关键帧间隔，服务端要收到设备发的第一个关键帧才会下发流给拉流端，关键帧间隔越长，首开就越长，关键帧间隔建议2或3秒。

# 9、SIP服务器IP从原来的47.98.160.100变更为121.41.37.111，是否影响之前接入的设备？ [#9sip服务器ip从原来的4798160100变更为1214137111是否影响之前接入的设备]

一. 不影响，目前这2个SIP地址都可以正常使用，设备端配置任意一个即可；
二. 摄像头配置参考：[摄像头国标接入流程](/products/qvs/0-gb-access-process)
三. 录像机（NVR）设备配置参考：[NVR设备国标接入流程](/products/qvs/1-nvr-gb-access-process)

# 10、摄像头已经通过GB28181协议接入录像机，录像机已通过GB28181协议将监控画面传输到A平台；如果额外单独配置摄像头通过GB28181协议传画面到七牛视频监控平台，配置GB28181协议的摄像头是否会对原有录像机接入产生影响？ [#10摄像头已经通过gb28181协议接入录像机录像机已通过gb28181协议将监控画面传输到a平台如果额外单独配置摄像头通过gb28181协议传画面到七牛视频监控平台配置gb28181协议的摄像头是否会对原有录像机接入产生影响]

一. 是否会影响原有录像机接入，取决于摄像头和录像机本身是否支持 GB28181 同时并行接入多个上级平台。
二. 如果设备支持多平台并发接入，那么摄像头额外接入 七牛视频监控平台，通常不影响录像机继续汇聚并上传到 A 平台；如果设备只支持单上级或存在国标资源占用限制，就可能出现注册冲突、在线离线波动或原链路异常，这部分需要以设备厂商规格为准。

# 11、空间可以更换区域吗？ [#11空间可以更换区域吗]

已经创建的空间不支持更换区域，只能重新创建一个新的空间，选择区域。

# 12、视频监控是否有分辨率和码率限制？ [#12视频监控是否有分辨率和码率限制]

取决于设备端的支持情况，推荐配置：分辨率720P时，码率选择1024；分辨率为1080p时，码率选择2048


# 通配符证书域名验证策略变更 (/products/ssl/0-certificate-of-domain-name-validation-rules-change)



最近更新时间: 2021-08-20 11:12:38

**按照CA/B Forum规定，域名验证策略将会有如下重大变更：**
自2021年12月1日起，使用文件验证(HTTP)的域名 只能为被验证域名本身签发证书，不支持签发通配符证书和其下级子域名证书。

目前，行业允许仅对主域名( domain.com )进行域名验证即可，适用于通配符证书(如 \*.domain.com 或 \*.sub.domain.com 等)和其下级所有子域名(如 sub.domain.com 或 sub2.sub1.domain.com 等)。

2021年12月1日后，对于使用文件(HTTP)方式验证的域名，只能为被验证域名本身签发证书，如 使用文件(HTTP)验证方式验证域名 domain.com，则只能为 domain.com 签发证书，不能为 \*.domain.com 或 sub.domain.com 签发证书。

<br />

七牛云侧调整如下：
2021年11月01日起，将全面下线DV通配符类证书的文件验证方式，11月01日之后新申请DV通配符证书仅支持DNS验证，11月01日前已颁发的证书不受影响。其他类型证书的验证方式不受影响。

<br />

**DigiCert 公告** : [https://knowledge.digicert.com/alerts/domain-authentication-changes-in-2021.html](https://knowledge.digicert.com/alerts/domain-authentication-changes-in-2021.html)
**GlobalSign 公告** ：[https://www.globalsign.com/en/blog/upcoming-changes-publicly-trusted-tls-certificates](https://www.globalsign.com/en/blog/upcoming-changes-publicly-trusted-tls-certificates)


# 关于TrustAsia DV 域名型证书的有效期和收费策略调整通知 (/products/ssl/1-charging-strategy-adjustment)



最近更新时间: 2026-08-28 17:18:29

尊敬的七牛云用户:
接收到厂商关于免费证书服务收费策略调整。七牛云决定自2024年1月1日0点对证书的服务收费策略进行调整:
**对于免费领取的TrustAsia DV域名型证书，签发后的证书有效期统一变更为90天**。如果您希望继续使用12个月有效期的证书，则需要收取相关服务费，具体详见证书购买页。
感谢您对七牛云的支持与关注！
上海七牛信息技术有限公司


# 关于SSL证书有效期缩短的重要通知 (/products/ssl/2-ssl-certificate-subscription-service-notice)



最近更新时间: 2026-03-17 18:13:51

尊敬的七牛云用户，您好：

为配合CA/B论坛全球网络安全标准的更新，进一步提升网络通信的安全性，SSL/TLS证书的最长有效期将从2026年2月24日起逐步缩短。七牛云SSL证书服务将遵循行业标准，同步调整相关SSL证书的有效期策略。本次调整涉及七牛云在售的TrustAsia、GeoTrust、DigiCert等主要品牌。

> CA/B论坛（Certification Authority/Browser Forum）是全球数字证书领域的权威标准组织。任何被主流浏览器和操作系统公开信任的SSL/TLS证书，其颁发机构必须遵守CA/B论坛制定的基线要求。

# 变更背景 [#变更背景]

自2026年起，SSL/TLS证书最长有效期将分阶段缩短。各阶段调整计划如下：

| 签发日期        | SSL证书最长有效期 |
| :---------- | :--------- |
| 2026年3月15日起 | 200天       |
| 2027年3月15日起 | 100天       |
| 2029年3月15日起 | 47天        |

不同CA厂商的技术调整节奏存在差异，具体执行日期如下：

| 证书品牌                | 生效时间        | 变更内容                            |
| :------------------ | :---------- | :------------------------------ |
| DigiCert / GeoTrust | 2026年2月24日起 | 停止接受有效期超过199天的公开SSL证书请求（厂商提前执行） |
| TrustAsia           | 2026年3月1日起  | 停止接受有效期超过199天的公开SSL证书请求（厂商提前执行） |

注：TrustAsia品牌下的域名型（DV）免费证书有效期仍保持90天不变，不受本次调整影响。各证书品牌在生效时间之前购买的证书，有效期不受本次策略调整影响。

# 对您的影响 [#对您的影响]

七牛云将于各品牌生效时间起，按照CA/B论坛最新基线要求及各证书厂商实际执行政策调整相关流程。本次变更将从以下几个维度影响您的使用体验：

**证书有效期与购买年限的关系**

自生效时间起，您新申请的付费证书，单张证书的最大可用时长将按上表逐步缩短。七牛云目前支持购买1年或2年期的证书，在新的规则下，您购买1年或2年服务周期内，实际会获得多张连续有效期的证书，以确保总时长覆盖您购买的年限。

为确保服务不中断，我们将在当前证书到期前30天自动为您启动续签流程，并通过短信/邮件/站内信同步提醒您。您需在此期限内配合完成必要的操作（如域名所有权验证），即可无缝替换为新证书。

> 示例：在199天有效期阶段购买1年期TrustAsia证书，您实际会获得1张有效期为199天的证书和1张有效期为166天的证书（199+166=365天），两张证书前后相继，保证全年证书不中断。

**域名所有权验证周期同步缩短**

域名所有权验证的有效期将与证书有效期同步缩短。未来我们将优化为长效验证机制，根据您购买的证书时长一次性完成对应周期的域名验证，减少频繁验证的困扰。

**不同业务场景的续签处理方式**

| 业务场景        | 续签方式                   | 是否需要人工操作 |
| :---------- | :--------------------- | :------- |
| 七牛CDN业务     | 域名归属验证完成后，系统自动续签并部署新证书 | 否        |
| 自有服务器或其它云服务 | 需手动下载并更换新证书            | 是        |

注：若您的证书用于自有服务器或其它云服务，请务必关注证书到期提醒，及时手动下载并更换新证书，以免影响业务访问。

**价格与购买页面实时更新**

本次变更后，按购买年限享受的折扣策略保持不变。具体生效时间、单张证书有效期、对应年限下的证书数量及最终价格，请以七牛云官网控制台证书购买页面的实时信息为准。

# 我们的建议 [#我们的建议]

为帮助您平稳过渡，建议您关注以下事项：

* **提前规划续签管理**：证书更新频率将显著增加，建议根据业务需求提前规划证书的续签和替换流程，特别是未使用七牛CDN的业务，需重点关注到期提醒，避免因证书过期影响服务。
* **关注关键生效节点**：请根据您使用的证书品牌，特别注意2026年2月24日（针对DigiCert用户）及2026年3月1日（针对TrustAsia/GeoTrust用户）。
* **留意提醒通知**：请确保联系方式畅通，及时接收提前30天的验证/续签提醒，并按要求完成操作。
* **持续关注公告**：七牛云将持续跟进行业动态，并通过官网公告及时同步最新信息。

***

七牛云致力于为您提供安全、可靠的云服务。如您对此变更或SSL证书管理有任何疑问，欢迎随时提交工单联系我们。

感谢您对七牛云的信赖与支持！

七牛云 SSL证书团队

2026年3月1日


# 2年续期证书 (/products/ssl/3-year-renewal-certificate)



最近更新时间: 2026-05-28 14:48:50

# 简介 [#简介]

自2020年9月起，全球CA机构不再签发两年期证书。为了填补两年期证书的空白，保证用户的使用体验，七牛推出2年续期证书。

# 服务模式 [#服务模式]

2年续期证书由两张先后生效的一年期证书组成，在您支付2年续期证书的费用后，七牛购买第一张证书。第一张证书失效之前，自动续购新证书，新证书颁发后您会接收到邮件提示，同时新证书将自动部署至之前绑定的CDN加速域名。

# 产品优势 [#产品优势]

2年续期证书在最大程度上提供了之前两年期证书的服务体验，在其中的第一张证书到期后，七牛为您提供CDN加速域名的自动部署服务，且不收取任何托管费用。同时，购买2年续期证书可以享&#x53D7;&#x2A;**更低的折扣***。

# 说明 [#说明]

* 在2年续期证书的第二年证书颁发并完成部署后，您会接收到邮件通知。目前续期服务支持 CDN 的自动部署，如果您在七牛的其他产品（包括对象存储、负载均衡、视频直播、视频监控等）中使用了2年续期证书，请在收到邮件后手动完成部署。
* 由于证书为一次性分配商品，所有证书（包括2年续期证书的续费证书）在完成付款七天后或证书完成颁发后不支持退款，请确认后购买。
* 在您购买2年续期证书后，订单列表中会出现其中第一张证书的订单，有效期显示“2年续期证书”；当七牛为您自动购买第二张证书后，订单列表中会出现新的订单，有效期显示“1年”。两笔订单的证书备注名相同。


# 证书接口 (/products/ssl/0-certificate-of-relevant)



最近更新时间: 2026-03-27 15:32:54

请点击查看 [证书API](/products/cdn/9-fusion-api-cert-management)


# 产品概述 (/products/tutugo/0-tutugo-product-overview)



最近更新时间: 2025-08-27 14:22:03

# 产品概述 [#产品概述]

七牛云拓图AI通过AI生图技术和图像高清技术，来帮助您快速提取商品图核心印花图案，短时间内集成爆款商品元素与风格，为后续设计与应用提供高质量素材，缩短产品设计开发周期。

## 产品能力 [#产品能力]

### 核心印花图案提取 [#核心印花图案提取]

智能提取商品图的核心印花图案，只需一张商品图的正面图像，就可导出商品图的高清核心印花图案，用于爆款商品分析或是作为设计创意发散的灵感库

### 印花图输出定制 [#印花图输出定制]

可根据商品品类定制印花规格，标准化输出印花图片的尺寸与比例，以保障产品从设计到生产环节的效率


# 产品优势 (/products/tutugo/1-tutugo-benefits)



最近更新时间: 2025-08-27 14:22:14

# 产品优势 [#产品优势]

## 一键批量处理，效率倍增 [#一键批量处理效率倍增]

* 最多支持同时解析一百张商品图，自动识别并提取核心印花图案，节省人工抠图90%以上时间。
* 无需AI应用使用经验，3步操作即可完成批量图片印花提取，适合小白商家快速上手使用。

## 智能印花精准识别，细节无损 [#智能印花精准识别细节无损]

* 精准锁定图像中的印花图案区域，有效去除背景及无关元素，一键导出完整且高清的商品印花图。
* 自动矫正印花图案至标准正面视角，输出正面视觉的高清大图，实现图像的精确定位。

## 定制化配置，满足多场景需求 [#定制化配置满足多场景需求]

* 采用AI视觉算法，可定制化输出比例与尺寸，适配手机壳、地毯、T恤等不同商品品类。
* 支持图像智能修复、增强细节表现力，实现印花图片高清无损输出，避免放大模糊。


# 应用场景 (/products/tutugo/2-tutugo-application-scenario)



最近更新时间: 2025-08-27 14:22:22

# 应用场景 [#应用场景]

## 文创类商品迭代 [#文创类商品迭代]

### 场景描述 [#场景描述]

文创商家可利用拓图AI，从市面上热销商品图中快速提取高清印花图案，用于文具、手机壳、画册封面、明信片等多种创意延展设计，实现从爆款商品图案采集到设计启发的高效衔接。

### 能够解决的问题 [#能够解决的问题]

* 缩短从灵感收集到设计方案的周期，减少人工处理时间
* 输出比例与尺寸可定制以匹配不同文创品类，避免二次排版
* 导出高质量高清的图案素材，修复细节，保证成品质感

## 家居软装类商品迭代 [#家居软装类商品迭代]

### 场景描述 [#场景描述-1]

家居软装类商品设计师可将热门图案元素快速提取并高清化，应用于抱枕、窗帘、床品、地毯、挂画等家居软装商品设计的灵感启发，并可灵活定制输出尺寸比例，贴合不同设计需求。

### 能够解决的问题 [#能够解决的问题-1]

* 避免重复寻找或重绘素材，高效辅助创意设计稿的完成
* 定制化输出保证图案在不同家居产品上的比例协调
* 支持批量处理多款图案，快速丰富家居产品设计灵感库

## 服类饰商品迭代 [#服类饰商品迭代]

### 场景描述 [#场景描述-2]

服装设计师和商家可基于爆款服饰商品图，快速完成图案提取与高清化处理，并将其作为灵感元素进行高效设计创作，适用于 T 恤、卫衣、帆布袋等多类服饰产品。

#### 能够解决的问题： [#能够解决的问题-2]

* 快速分析爆款商品图案类型与风格，提高上新命中率。
* 定制分辨率与尺寸输出，确保适配不同服饰印花位置
* 节省创意设计调研与分析时间，降低产品开发成本


# 计费概览 (/products/tutugo/0-tutugo-price-overview)



最近更新时间: 2026-05-08 16:09:56

# 计费概览 [#计费概览]

通过阅读本文，您可以快速了解拓图AI的计费项、计费模式、欠费说明等信息。拓图采用积分制计费模式，您可根据实际业务需求灵活购买积分，并按实际调用功能进行消耗抵扣。平台支持按量使用、长期有效、无强制订阅，适用于个人用户、电商商家、设计团队及企业级批量生产场景。

## 计费项 [#计费项]

拓图AI的费用包括商品图印花提取的使用服务费用，详细的计费信息请参考 [计费项](/products/tutugo/1-tutugo-price)。

## 计费模式 [#计费模式]

拓图目前提供了积分资源包按量扣减的方式

* 积分资源包按量扣减：您购买积分资源包后，平台采用按量扣减方式，按照实际使用的功能抵扣积分，抵扣积分 = 服务次数\*服务类型所需积分。您可以根据 [财务中心](https://portal.qiniu.com/financial/bills/estimated-consume) 查看实时消费明细

## 欠费说明 [#欠费说明]

为了保证您的业务持续地正常运行，请提前关注您的账号的积分余额，积分余额不足以支付当前任务时，新的任务将无法提交，在充值后可继续使用相关服务。


# 计费项 (/products/tutugo/1-tutugo-price)



最近更新时间: 2026-05-08 16:09:59

# 计费项 [#计费项]

拓图AI的费用包括商品图印花提取和智能裂变使用服务费用。您可申请免费试用智能裂变服务。

## 印花提取 [#印花提取]

### 标准单价 [#标准单价]

积分计费模式，平台根据不同图像处理服务消耗对应积分，当前计费规则如下

| 服务类型           | 积分消耗规则 |
| -------------- | ------ |
| 印花图像提取         | 2 积分/次 |
| 印花图像+高清放大/背景移除 | 4 积分/次 |
| 印花图像+高清放大+背景移除 | 8 积分/次 |

### 资源包收费模式 [#资源包收费模式]

| 资源包 | 总积分   | 价格   |
| --- | ----- | ---- |
| 基础包 | 100   | 10   |
| 进阶包 | 2000  | 170  |
| 专业包 | 8000  | 560  |
| 企业包 | 20000 | 1200 |

### 定价逻辑 [#定价逻辑]

资源包积分越多，积分单价越低

* 基础资源包，单价为原价
* 进阶资源包，单价按原价的 8.5 折
* 专业资源包，单价按原价的 7 折
* 企业资源包，单价按原价的 6 折

需要更多积分可定制报价

### 计费逻辑 [#计费逻辑]

* 余额不足时，不能创建任务；任务创建后会冻结预计积分，任务成功后正式扣除积分。积分扣除总数=服务次数\*服务类型所需积分

## 智能裂变 [#智能裂变]

### 标准单价 [#标准单价-1]

积分计费模式，平台根据图像处理服务消耗对应积分，当前计费规则如下

| 服务类型 | 积分消耗规则 |
| ---- | ------ |
| 智能裂变 | 6      |

一次智能裂变服务可生成四张图

### 资源包收费模式 [#资源包收费模式-1]

| 资源包 | 总积分   | 价格   |
| --- | ----- | ---- |
| 基础包 | 100   | 10   |
| 进阶包 | 2000  | 170  |
| 专业包 | 8000  | 560  |
| 企业包 | 20000 | 1200 |

### 定价逻辑 [#定价逻辑-1]

资源包积分越多，积分单价越低

* 基础资源包，单价为原价
* 进阶资源包，单价按原价的 8.5 折
* 专业资源包，单价按原价的 7 折
* 企业资源包，单价按原价的 6 折

需要更多积分可定制报价

### 计费逻辑 [#计费逻辑-1]

* 余额不足时，不能创建任务；任务创建后会冻结预计积分，任务成功后正式扣除积分。积分扣除总数=服务次数\*服务类型所需积分


# CDN 相关接口操作 (/account/access-management/iam-actions/0-cdn-actions)



最近更新时间: 2023-06-29 20:01:40

CDN 对应的 IAM 服务别名为 `cdn`，在授予权限时，需要通过 `alias/action`的方式指定授权操作接口，如 `cdn/CreateDomain` 表示 CDN 服务下的创建域名操作。

可通过以下形式定义策略对用户进行访问授权：

```
{
    "alias": "PolicyTest",
    "description": "this is description",
    "statement": [
        {
            "action": ["cdn/CreateDomain"],
            "resource": [],
            "effect": "Allow"
        },
        {
            "action": ["cdn/GetDomainList"],
            "resource": ["*"],
            "effect": "Allow"
        },
        {
            "action": ["cdn/UpdateSource"],
            "resource": ["qrn:cdn:::www.qiniu.com"],
            "effect": "Allow"
        },
    ]
}
```

# 接口授权粒度 [#接口授权粒度]

接口授权粒度分为资源级和服务级两个级别：

* 资源级接口：该类型接口支持按照资源进行授权。资源标识符格式为 `qrn:cdn:::www.qiniu.com` 表示对域名为 `www.qiniu.com` 的资源进行授权，若想授权所有资源，可通过 `*` 或者 `qrn:cdn:::*` 表示
* 服务级接口：该类型接口不支持对特定的资源进行授权。默认授予对该服务下所有资源授予权限

# 操作列表 [#操作列表]

| Action               | 名称            | 授权粒度 |
| -------------------- | ------------- | ---- |
| Dashboard            | 概览            | 服务级  |
| CreateDomain         | 创建域名          | 服务级  |
| DeleteDomain         | 删除域名          | 资源级  |
| GetDomainList        | 获取域名列表        | 资源级  |
| GetDomainInfo        | 获取域名信息        | 资源级  |
| OnlineDomain         | 启用域名          | 资源级  |
| OfflineDomain        | 停用域名          | 资源级  |
| UpdateSource         | 回源配置          | 资源级  |
| UpdateCache          | 缓存配置          | 资源级  |
| UpdateReferer        | Referer 防盗链配置 | 资源级  |
| UpdateTimeACL        | 时间戳防盗链配置      | 资源级  |
| UpdateBSAuth         | 回源鉴权配置        | 资源级  |
| UpdateHttps          | HTTPS 配置      | 资源级  |
| UpdateIpACL          | IP 黑白名单配置     | 资源级  |
| UpdateExternal       | 修改特殊配置        | 资源级  |
| UpdateResponseHeader | 修改响应头         | 资源级  |
| UpdateIPv6           | IPv6 配置       | 资源级  |
| Refresh              | 缓存刷新          | 服务级  |
| Prefetch             | 文件预取          | 服务级  |
| GetBandwidthAndFlux  | 查询流量/带宽       | 服务级  |
| GetISPReqCount       | 各运营商请求次数      | 服务级  |
| GetReqCount          | 查询区域请求次数      | 服务级  |
| GetTop               | TOP 查询        | 服务级  |
| GetStateCode         | 查询状态码         | 服务级  |
| GetHitRate           | 查询命中率         | 服务级  |
| GetUV                | 查询独立 IP       | 服务级  |
| GetSpeed             | 查询下载速度        | 服务级  |
| DownloadCDNLog       | 日志下载          | 服务级  |
| GetDomainTag         | 查询域名标签        | 服务级  |
| EditDomainTag        | 编辑域名标签        | 服务级  |


# 全站加速相关接口操作 (/account/access-management/iam-actions/0-dcdn-iam-actions)



最近更新时间: 2023-06-29 19:57:28

全站加速对应的 IAM 服务别名为 `dcdn`，在授予权限时，需要通过 `alias/action`的方式指定授权操作接口，如 `dcdn/CreateDomain` 表示全站加速服务下的创建域名操作。

可通过以下形式定义策略对用户进行访问授权：

```
{
    "alias": "PolicyTest",
    "description": "this is description",
    "statement": [
        {
            "action": ["dcdn/CreateDomain"],
            "resource": [],
            "effect": "Allow"
        },
        {
            "action": ["dcdn/GetDomainList"],
            "resource": ["*"],
            "effect": "Allow"
        },
        {
            "action": ["dcdn/UpdateSource"],
            "resource": ["qrn:dcdn:::www.qiniu.com"],
            "effect": "Allow"
        },
    ]
}
```

# 接口授权粒度 [#接口授权粒度]

接口授权粒度分为资源级和服务级两个级别：

* 资源级接口：该类型接口支持按照资源进行授权。资源标识符格式为 `qrn:dcdn:::www.qiniu.com` 表示对域名为 `www.qiniu.com` 的资源进行授权，若想授权所有资源，可通过 `*` 或者 `qrn:dcdn:::*` 表示
* 服务级接口：该类型接口不支持对特定的资源进行授权。默认授予对该服务下所有资源授予权限

# 操作列表 [#操作列表]

| Action               | 名称            | 授权粒度 |
| -------------------- | ------------- | ---- |
| Dashboard            | 概览            | 服务级  |
| CreateDomain         | 创建域名          | 服务级  |
| DeleteDomain         | 删除域名          | 资源级  |
| GetDomainList        | 获取域名列表        | 资源级  |
| GetDomainInfo        | 获取域名信息        | 资源级  |
| OnlineDomain         | 启用域名          | 资源级  |
| OfflineDomain        | 停用域名          | 资源级  |
| UpdateSource         | 回源配置          | 资源级  |
| UpdateCache          | 缓存配置          | 资源级  |
| UpdateReferer        | Referer 防盗链配置 | 资源级  |
| UpdateHttps          | HTTPS 配置      | 资源级  |
| UpdateIpACL          | IP 黑白名单配置     | 资源级  |
| UpdateResponseHeader | 修改响应头         | 资源级  |
| UpdateIPv6           | IPv6 配置       | 资源级  |
| Refresh              | 缓存刷新          | 服务级  |
| Prefetch             | 文件预取          | 服务级  |
| GetBandwidthAndFlux  | 查询流量/带宽       | 服务级  |
| GetISPReqCount       | 各运营商请求次数      | 服务级  |
| GetReqCount          | 查询区域请求次数      | 服务级  |
| GetTop               | TOP 查询        | 服务级  |
| GetStateCode         | 查询状态码         | 服务级  |
| GetUV                | 查询独立 IP       | 服务级  |
| DownloadCDNLog       | 日志下载          | 服务级  |
| GetDomainTag         | 查询域名标签        | 服务级  |
| EditDomainTag        | 编辑域名标签        | 服务级  |


# 对象存储相关接口操作 (/account/access-management/iam-actions/0-kodo-iam-actions)



最近更新时间: 2026-07-20 13:43:22

对象空间对应的 IAM 服务别名为 `kodo`，在授予权限时，需要通过 `alias/action`的方式指定授权操作接口，如 `kodo/mkbucket` 表示 kodo 服务下的创建存储空间的操作。

可通过以下形式定义策略对用户进行访问授权：

```
{
    "alias": "PolicyTest",
    "description": "this is description",
    "statement": [
        {
            "action": ["kodo/mkbucket"],
            "resource": [],
            "effect": "Allow"
        },
        {
            "action": ["kodo/list"],
            "resource": ["*"],
            "effect": "Allow"
        },
        {
            "action": ["kodo/delete"],
            "resource": ["qrn:kodo:::bucket-test/*"],
            "effect": "Allow"
        },
    ]
}
```

# 接口授权粒度 [#接口授权粒度]

接口授权粒度分为资源级和服务级两个级别：

* 资源级接口：该类型接口支持按照资源进行授权。资源标识符格式为 `qrn:kodo:::bucket-test/*` 表示对 bucket-test 空间进行授权，若想授权所有资源，可通过 `*` 或者 `qrn:kodo:::*` 表示。目前资源的授权粒度**仅支持空间级别**。
* 服务级接口：该类型接口不支持对特定的资源进行授权。默认授予对该服务下所有资源授予权限。

# 操作列表 [#操作列表]

| Action                   | 名称                | 授权粒度 |
| ------------------------ | ----------------- | ---- |
| mkbucket                 | 创建存储空间            | 服务级  |
| drop                     | 删除存储空间            | 服务级  |
| upload                   | 上传单文件             | 资源级  |
| mkfile                   | 分片上传文件            | 资源级  |
| fetchfiles               | 抓取上传文件            | 资源级  |
| listParts                | 列举已上传 Parts       | 资源级  |
| abortMultipartUpload     | 中止分块上传任务          | 资源级  |
| listMultipartUploads     | 列举所有 UploadId     | 资源级  |
| list                     | 列举空间内文件           | 资源级  |
| stat                     | 获取资源的 Metadata 信息 | 资源级  |
| get                      | 下载文件              | 资源级  |
| chgm                     | 修改文件的 MIME 类型信息   | 资源级  |
| objectLifecycleSet       | 设置资源的生命周期         | 资源级  |
| chtype                   | 修改文件的存储类型信息       | 资源级  |
| restoreAr                | 解冻归档存储文件          | 资源级  |
| chstatus                 | 禁/启用文件            | 资源级  |
| delete                   | 删除资源              | 资源级  |
| statistics               | 查询计量数据            | 资源级  |
| getBucketStyle           | 查询样式列表            | 资源级  |
| setSeparator             | 设置样式分隔符           | 资源级  |
| putImageStyle            | 添加/修改样式           | 资源级  |
| deleteImageStyle         | 删除样式              | 资源级  |
| getBucketLifecycle       | 查询生命周期规则          | 资源级  |
| putBucketLifecycle       | 设置生命周期规则          | 资源级  |
| deleteBucketLifecycle    | 删除生命周期规则          | 资源级  |
| getBucketNotification    | 查询事件通知规则          | 资源级  |
| putBucketNotification    | 设置事件通知规则          | 资源级  |
| deleteBucketNotification | 删除事件通知规则          | 资源级  |
| getBucketMirror          | 查询镜像回源规则          | 资源级  |
| putBucketMirror          | 设置镜像回源规则          | 资源级  |
| deleteBucketMirror       | 删除镜像回源规则          | 资源级  |
| setBucketPrivate         | 设置空间访问权限          | 资源级  |
| getBucketWebsite         | 查询空间静态网站托管规则      | 资源级  |
| putBucketWebsite         | 设置空间静态网站托管        | 资源级  |
| putBucketReferer         | 设置空间 Referer 防盗   | 资源级  |
| getBucketCORS            | 查询空间跨域规则          | 资源级  |
| putBucketCORS            | 设置空间跨域规则          | 资源级  |
| getBucketTagging         | 查询空间标签            | 资源级  |
| putBucketTagging         | 设置空间标签            | 资源级  |
| getCustomDomain          | 查询空间域名列表          | 资源级  |
| postCustomDomain         | 绑定空间源站域名          | 资源级  |
| deleteCustomDomain       | 解绑空间源站域名          | 资源级  |
| postCustomDomainHttps    | 源站域名 HTTPS 配置     | 资源级  |
| unfreezeCustomDomain     | 解冻空间源站域名          | 资源级  |


# 日志查询（log-query） (/account/audit-log/api-reference/0-audit-log-api-log-query)



最近更新时间: 2023-06-13 11:28:52

# 请求 [#请求]

```
GET /audit/log-query HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <管理凭证>
```

## 头部信息 [#头部信息]

| 头部名称          | 必填 | 说明                                                                                                                  |
| ------------- | -- | ------------------------------------------------------------------------------------------------------------------- |
| Host          | 是  | 固定为 `api.qiniu.com`，必须以 **HTTPS 方式** 访问                                                                             |
| Content-Type  | 是  | 固定为 `application/x-www-form-urlencoded`                                                                             |
| Authorization | 是  | 账号管理凭证，该参数应严格按照账号管理凭证格式进行填充，否则会返回 401 错误码。<br />[文档地址](/products/kodo/development-guidelines/security/access-token) |

## 请求参数 [#请求参数]

请求参数以表单形式组织，作为请求内容提交。

| 字段名称            | 类型              | 是否必须 | 说明                                                  |
| --------------- | --------------- | ---- | --------------------------------------------------- |
| start\_time     | String          | 是    | 检索日志的开始时间，日期格式按照 ISO8601 标准，并使用 UTC 时间              |
| end\_time       | String          | 是    | 检索日志的结束时间，日期格式按照 ISO8601 标准，并使用 UTC 时间              |
| service\_name   | String          | 否    | 服务名称，[参考](/account/audit-log/0-audit-log-events)    |
| event\_names    | Array of String | 否    | 事件名称集合，[参考](/account/audit-log/0-audit-log-events)  |
| principal\_id   | String          | 否    | 请求者的 ID，[参考](/account/audit-log/0-audit-log-object) |
| access\_key\_id | String          | 否    | 请求身份所属的 AccessKey ID                                |
| limit           | Integer         | 否    | 允许返回的最大结果数目，取值范围：1\~50，不传值默认为：20                    |
| next\_mark      | String          | 否    | 用于请求下一页检索的结果                                        |

# 响应 [#响应]

```
HTTP/1.1 200 OK
Content-Type: application/json
```

## 头部信息 [#头部信息-1]

| 头部名称         | 说明                                                |
| ------------ | ------------------------------------------------- |
| Content-Type | 正常情况下该值将被设为 `application/json`，表示返回 JSON 格式的文本信息。 |

## 响应内容 [#响应内容]

* 如果请求成功，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "audit_log_infos": [],
    "next_mark": "",
}
```

| 字段名称              | 类型              | 说明                                               |
| ----------------- | --------------- | ------------------------------------------------ |
| audit\_log\_infos | Array of Object | 日志集合，[参考](/account/audit-log/0-audit-log-object) |
| next\_mark        | String          | 返回下一页的检索结果                                       |

* 如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "error": "",
    "code": 0,
    "message": ""
}
```

| 字段名称    | 类型      | 说明      |
| ------- | ------- | ------- |
| error   | String  | 错误信息    |
| code    | Integer | 错误 code |
| message | String  | 信息      |

| HTTP 状态码 | code | message         | description |
| -------- | ---- | --------------- | ----------- |
| 200      |      |                 | 成功          |
| 400      | 3    | InvalidArgument | 请求参数错误      |


# Account（账号） (/account/audit-log/audit-log-events/0-audit-log-events-account)



最近更新时间: 2026-01-15 18:00:58

| 事件名称                        | 事件含义       | 接入时间       |
| --------------------------- | ---------- | ---------- |
| ChangeEmail                 | 修改邮箱       | 2023-03-13 |
| BindEmail                   | 绑定邮箱       | 2023-03-13 |
| ChangePhoneNumber           | 修改手机号      | 2023-03-13 |
| BindPhoneNumber             | 绑定手机号      | 2023-03-13 |
| ChangePassword              | 修改密码       | 2023-03-13 |
| ForgetPasswordByEmail       | 邮箱找回密码     | 2023-03-13 |
| ForgetPasswordByPhoneNumber | 手机号找回密码    | 2023-03-13 |
| ResetPassword               | 重置密码       | 2023-03-13 |
| ConsoleLogin                | 控制台登录      | 2023-03-13 |
| ConsoleLogout               | 控制台登出      | 2023-03-13 |
| SSOLogin                    | SSO 登录     | 2023-03-13 |
| SSOLogout                   | SSO 登出     | 2023-03-13 |
| WechatLogin                 | 微信端登录      | 2023-03-13 |
| WechatAuthLogin             | 微信端授权登录    | 2023-03-13 |
| TicketLogin                 | Ticket 登录  | 2023-03-13 |
| WeChatMPSignup              | 微信端小程序注册   | 2023-03-13 |
| WeChatMPQRSignup            | 微信端扫码小程序注册 | 2023-03-13 |
| PortalSignup                | Portal 注册  | 2023-03-13 |
| BaiduFormSignUp             | 百度表单注册     | 2023-03-13 |
| CreateKey                   | 创建密钥       | 2023-03-13 |
| DeleteKey                   | 删除密钥       | 2023-03-13 |
| EnableKey                   | 启用密钥       | 2023-03-13 |
| DisableKey                  | 禁用密钥       | 2023-03-13 |


# CDN 相关事件 (/account/audit-log/audit-log-events/0-audit-log-events-cdn)



最近更新时间: 2026-01-15 18:00:58

| 事件名称                 | 事件含义         | 接入时间       |
| -------------------- | ------------ | ---------- |
| CreateDomain         | 创建域名         | 2024-01-03 |
| DeleteDomain         | 删除域名         | 2024-01-03 |
| OfflineDomain        | 下线域名         | 2024-01-03 |
| OnlineDomain         | 上线域名         | 2024-01-03 |
| UpdateSource         | 修改源站         | 2024-01-03 |
| UpdateRange          | 修改Range回源    | 2024-01-03 |
| UpdateCache          | 修改缓存         | 2024-01-03 |
| SSLIZE               | 升级https      | 2024-01-03 |
| UnSSLIZE             | https降级      | 2024-01-03 |
| UpdateHttpsConf      | 修改https配置    | 2024-01-03 |
| UpdateReferer        | 修改referer防盗链 | 2024-01-03 |
| UpdateIpACL          | 修改IP黑白名单配置   | 2024-01-03 |
| UpdateTimeAcl        | 修改时间戳防盗链     | 2024-01-03 |
| UpdateBsAuth         | 修改回源鉴权       | 2024-01-03 |
| OfflineBsAuth        | 下线回源鉴权       | 2024-01-03 |
| UpdateRespHeader     | 更新响应头        | 2024-01-03 |
| UpdateIpv6           | 更新IPv6配置     | 2024-01-03 |
| UpdateGeoCover       | 修改域名覆盖       | 2024-01-03 |
| UpdateMultiple       | 全量更新         | 2024-01-03 |
| PanTestNormalization | 泛子域名具体化      | 2024-01-03 |
| FindBackDomain       | 域名找回         | 2024-01-03 |
| FreezeDomain         | 冻结域名         | 2024-01-03 |
| UnFreezeDomain       | 解冻域名         | 2024-01-03 |
| TimeFreezeDomain     | 定时冻结         | 2024-01-03 |
| TimeUnfreezeDomain   | 解除定时冻结       | 2024-01-03 |
| TransferUser         | 域名过户         | 2024-01-03 |


# Financial（财务） (/account/audit-log/audit-log-events/0-audit-log-events-financial)



最近更新时间: 2026-01-15 18:00:58

| 事件名称                    | 事件含义     | 接入时间       |
| ----------------------- | -------- | ---------- |
| AlipayRechargePaying    | 支付宝充值中   | 2023-03-13 |
| AlipayRechargePayed     | 支付宝充值完成  | 2023-03-13 |
| WeChatPayRechargePaying | 微信充值中    | 2023-03-13 |
| WeChatPayRechargePayed  | 微信充值完成   | 2023-03-13 |
| EbankRechargePaying     | 网上银行充值中  | 2023-03-13 |
| EbankRechargePayed      | 网上银行充值完成 | 2023-03-13 |
| ActivateVoucher         | 激活账单抵用券  | 2023-03-13 |


# Kodo（对象存储） (/account/audit-log/audit-log-events/0-kodo-audit-log-events)



最近更新时间: 2026-01-15 18:00:58

| 事件名称             | 事件含义     | 接入时间       |
| ---------------- | -------- | ---------- |
| mkbucket         | 创建存储空间   | 2026-01-15 |
| drop             | 删除存储空间   | 2026-01-15 |
| getBucketTagging | 查询空间标签   | 2026-01-15 |
| putBucketTagging | 设置空间标签   | 2026-01-15 |
| setBucketPrivate | 设置空间访问权限 | 2026-01-15 |


# 邀请组织成员 (/account/enterprise-account-management/member-account-management/0-add-organizational-members)



最近更新时间: 2026-05-08 17:14:28

管理员账号即组织创建者，可通过邀请的方式添加成员账号。

## 一 允许邀请条件 [#一-允许邀请条件]

1、完成企业实名认证
2、非异常状态
3、若邀请主账号：则要求主账号与管理账号实名认证相同
4、若邀请从账号：则要求该账号与主账号实名认证
5、非 oem 子账号
6、账号商务归属相同，若不同请联系商务为您添加

## 二 操作 [#二-操作]

1、成员账号管理页面 - 邀请成员账号
![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/member-account-management/0-add-organizational-members/FpgArZToI0Q-6wyaCEKft_5LzuLc-d873a2619b67.webp)
2、填写被邀请账号邮箱、成员昵称（在组织中）、财务主/从账号
![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/member-account-management/0-add-organizational-members/FgCN3Cdum54K6LT1k9s0d6YjlE0A-b65c6f3590bb.webp)
3、邀请记录 15 天有效，您可在 **组织管理>邀请记录** 查看邀请信息。
4、若邀请财务主账号，需被邀请账号登陆 **组织管理>邀请记录** 接受邀请。
若邀请财务从账号，则需被邀请账号和对应的财务主账号分别登陆 **组织管理>邀请记录** 接受邀请。


# 创建组织成员账号 (/account/enterprise-account-management/member-account-management/0-create-organization-member)



最近更新时间: 2026-05-08 17:26:22

管理员账号即组织创建者，可通过创建账号的方式添加成员账号。

## 一 创建成员账号约束 [#一-创建成员账号约束]

1、仅支持创建财务从账号
2、创建的从账号默认继承主账号的认证主体信息，无需再次认证
3、创建成员账号后，需要创建的成员账号激活邮箱和手机号（若手机号与主账号不一致）后，才会生成实际可用的账号，在成员列表中可见
3、若创建的从账号关联的主账号是当前管理员账号，创建的成员账号激活后即可使用
4、若创建的从账号关联的主账号不是当前管理员账号，需要先经主账号确认通过后，再进行账号激活方可使用

## 二 操作 [#二-操作]

1、[成员账号管理页面](https://portal.qiniu.com/organization/members) - 添加成员账号
![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/member-account-management/0-create-organization-member/FgNBeyxc6WpwIqTidoJXu3XQfyu0-4fac10186fb2.webp)
2、选择创建成员，填写从账号相关信息
默认使用主账号手机号，不需要二次验证，若使用其他手机号，在激活过程中需要进行手机号验证
![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/member-account-management/0-create-organization-member/Fr7b_G15Pbg-DosPBOdJkxjPK-cK-bdfd4a082516.webp)
3、提交后在\[成员创建记录]列表页面可查询到当前创建账号的状态
![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/member-account-management/0-create-organization-member/FswGRkeXRL-7Mo9dFZgX7FEbacRo-71cb5c406598.webp)
4、被创建的从账号关联的手机号和邮箱会收到短信和邮件通知，根据消息中提供的激活链接进行账号激活
![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/member-account-management/0-create-organization-member/Fq7GsJ68mn5EtTsbwUECAxgPsKXr-a473abb7f04f.webp)
5、若创建的财务从账号所属主账号不是当前管理员账号，需对应主账号在控制台[成员创建记录](https://portal.qiniu.com/organization/org/creation-records)列表页进行账号创建的确认操作。


# 移除成员账号 (/account/enterprise-account-management/member-account-management/0-remove-member-account)



最近更新时间: 2026-03-30 11:44:19

## 一 移除条件 [#一-移除条件]

1、若移除财务主账号，则该账号下无财务从账号，且可用额度要大于等于 0。
2、若移除财务从账号，则该账号的可用额度要大于等于 0。
3、财务托管类从账号不支持自助移除，请联系商务或提交工单代您处理。
4、管理员账号无法移除，当组织内只有管理员账号时，您可以删除组织。

## 二 操作 [#二-操作]

登陆 **组织账号管理 > 成员账号管理** 移除成员账号
![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/member-account-management/0-remove-member-account/FuZc6_V0z3FrSUCOHm1VYoKdsIG-1102f5bbb6db.webp)


# 撤回邀请 (/account/enterprise-account-management/member-account-management/0-withdraw-invitation)



最近更新时间: 2026-03-30 11:44:19

## 一 允许撤回邀请条件 [#一-允许撤回邀请条件]

邀请记录未被处理完成，尚处于“确认中”状态。

## 二 操作 [#二-操作]

邀请账号（管理员账号）登陆 **组织管理>邀请记录** 找到待操作记录点击“撤回”。
![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/member-account-management/0-withdraw-invitation/FiJ4tjg5dHSjwLvP9UuVsT8EBnG4-cbe11518314f.webp)


# 管理员账号财务权限 (/account/enterprise-account-management/member-finance-management/0-administrator-financial-permissions)



最近更新时间: 2024-08-15 19:40:36

| 财务权限       | 描述                                                                               |
| ---------- | -------------------------------------------------------------------------------- |
| 查看成员账号月结算单 | 管理员账号可查看成员账号月结算单。（暂时不支持查看“实时消费明细”。）                                              |
| 查看成员账号可用额度 | 管理员账号可查看成员账号的现金余额、赠送金余额、信用额度、欠费金额、实时消费金额。                                        |
| 划拨资金       | 管理账号可为成员账号划拨资金。应用：因财务主账号会为从账号自动支付欠费，当组织内有多个主账号时，可统一充值给管理员账号，再为其他主账号统一划拨。         |
| 回收资金       | 划拨资金未使用时，管理员账号可将其回收。                                                             |
| 设置汇总可用额度预警 | 汇总可用额度是针对一组主从账号整体计算的。管理员账号可设置某组主从账号的汇总可用额度阈值，当额度低于该阈值时，为管理员发送通知，提醒管理员为其他主账号划拨资金。 |


# 财务类型介绍 (/account/enterprise-account-management/member-finance-management/0-introduction-to-financial-types)



最近更新时间: 2024-08-15 19:13:49

|        | 财务管理                                                                 | 财务托管                                                                  |
| ------ | -------------------------------------------------------------------- | --------------------------------------------------------------------- |
| 按量计费账单 | 主、从账号分别出账，主账号可以查看从账号账单。从账号每月月初出账后，优先使用自己余额支付，自己余额不足时系统自动划拨主账号资金为其支付。 | 从账号用量合并到主账号上统一出账，从账单无账单，从账单能看到自己使用量但看不到自己消费金额。                        |
| 订单支付   | 从账号优先使用自己可用额度支付，自身可用额度不足时使用主账号可用额度支付。                                | 购买普通商品时，使用主账号的可用额度支付。由于从账号的用量统一在主账号上出账，从账号资源包无法使用，从账号无需购买资源包。         |
| 充值     | 可在主账号下统一充值，主账号自动为从账号付款。也可以分别在主、从账号下充值。                               | 在主账号下充值（从账号下的充值无法使用）。                                                 |
| 开票     | 按充值开票，A 账号充值则在 A 账号下开票。                                              | 按充值开票，A 账号充值则在 A 账号下开票。                                               |
| 抵用券    | 抵用券不可共享，只能用自身抵用券抵扣消费金额。                                              | 订单类抵用券：下单时各自使用各自的抵用券抵扣。按量计费类抵用券：由于从账号无账单，统一在主账号下出账，使用主账号抵用券抵扣按量计费类消费。 |


# 创建组织 (/account/enterprise-account-management/organization-management/0-create-organization)



最近更新时间: 2024-08-15 19:11:49

## 一 创建组织条件 [#一-创建组织条件]

1）企业认证账号
2）未加入过其他组织
3）账号为正常（非冻结）状态

## 二 操作 [#二-操作]

1）进入【企业账号管理-基本信息】页面，点击“创建组织”按钮
![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/organization-management/0-create-organization/Fqms0375CODF7opdiOsAIXIfF4AU-0e9261dea244.webp)
2）请您仔细阅读并同意使用企业管理功能的协议
![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/organization-management/0-create-organization/FhYAFN5TzhdUpXK5UT7-MhWVLcuO-4e282772b69c.webp)
3）填写组织名称，选择管理员账号作为财务主账号的财务模式
![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/organization-management/0-create-organization/Fn0qoSopkXiILtmQIJwbnUUu1zDL-09e9bc3a4fd3.webp)


# 删除组织 (/account/enterprise-account-management/organization-management/0-delete-organization)



最近更新时间: 2024-08-15 19:11:54

## 一 允许删除条件 [#一-允许删除条件]

组织内除管理员账号外，无其他成员账号

## 二 操作 [#二-操作]

![image.png](/docs-assets/account/%280-manual%29/enterprise-account-management/organization-management/0-delete-organization/FkDXHaE5tGzs8r4LBo3v0EX4BoHw-9a8e38700953.webp)


# cdn 日志下载全选 (/faq/cdn/other-fusion/introduction-to-the-cdn-log-format/5909-cdn-log-download-selection)



最近更新时间: 2019-06-04 12:08:21

**Q: cdn 日志下载全选但是为什么只下载了第一个？**
&#x2A;*A:** 当浏览器检测到非用户操作产生的新弹出窗口，则会对其进行阻止。因为浏览器认为这可能是一个广告，不是一个用户希望看到的页面。所以当下载全选的时候，会出现类似拦截窗口的界面

<br />

<br />

![](/docs-assets/faq/cdn/other-fusion/introduction-to-the-cdn-log-format/5909-cdn-log-download-selection/FpoAheeo1UzIqsxshycoNNI1o7xF-a4849d10e4de.webp)

<br />

<br />

点解拦截按钮，然后允许弹出窗口访问即可

![](/docs-assets/faq/cdn/other-fusion/introduction-to-the-cdn-log-format/5909-cdn-log-download-selection/FodNZfkPD-Xh8oXJJsq6ZhIXh9ke-cfb0e433df26.webp)


# 手机端网络测试工具 (android、iOS) (/faq/cdn/other-fusion/problem-diagnosis-method/1324-mobile-terminal-network-test-tool-android-ios)



最近更新时间: 2021-06-28 18:37:24

## 此教程适用场景 [#此教程适用场景]

当用户在移动端上传/下载 慢 或 失败 时，使用以下方法可以检测出用户本地网络是否正常。

教程操作完成后，把检测结果截屏发到工单中，方便客服人员定位问题。

## 手机端带宽测试 [#手机端带宽测试]

国外测试地址：[http://www.bandwidthplace.com/](http://www.bandwidthplace.com/)

测试结束后会看到上传下载带宽。检测方法：打开网页时，点击start。检测结果如下：

![blob.png](/docs-assets/faq/cdn/other-fusion/problem-diagnosis-method/1324-mobile-terminal-network-test-tool-android-ios/001575e20e1a753a196f7c931af9246-0d90a7db478a.webp)

国内测试地址：[http://www.speedtest.cn](http://www.speedtest.cn)
测试结束后会看到上传下载带宽。检测方法：打开网页时，点击测试。检测结果如下：

![speed.jpg](/docs-assets/faq/cdn/other-fusion/problem-diagnosis-method/1324-mobile-terminal-network-test-tool-android-ios/FopFZt_AUV1SoGZVDDHj7y1D71jL-54290659fd0f.webp)

## Android 网络测试工具 [#android-网络测试工具]

android 检测工具：[下载](https://dn-odum9helk.qbox.me/qiniu-detecion.apk)

* 第一步：用户安装软件到手机，并打开手机
* 第二步：复制域名到文本框中，点击检测

![00157b5b0903b99311d7a8e8f02a41f](/docs-assets/faq/cdn/other-fusion/problem-diagnosis-method/1324-mobile-terminal-network-test-tool-android-ios/00157b5b0903b99311d7a8e8f02a41f-c6dcfa89ee35.webp)

网络测试专用版(推荐使用)：[下载](http://dn-odum9helk.qbox.me/qiniu-detection-download.apk)

* a. 下载测试，输入 url 中的域名进行测试
* b. 上传测试，输入 upload.qiniup.com 进行测试

## IOS 端网络测试环境 [#ios-端网络测试环境]

> 注：在ios9中安装运行时会出提示：现需要信任这个企业及开发者才能运行该软件
>
> ![00157b5b044679adb2ba77099b57ceb](/docs-assets/faq/cdn/other-fusion/problem-diagnosis-method/1324-mobile-terminal-network-test-tool-android-ios/00157b5b044679adb2ba77099b57ceb-ed73d4394788.webp)
>
> 您需要打开系统设置》通用》描述文件》选择Shanghai Qiniu Information Technologies Co.Ltd.》点击中间蓝色文字信任该企业》在弹出的提示框中点击信任

* 第一步：安装软件 [**下载**](https://dn-devtools.qbox.me/NetDiagnoDemo-v1.1.5.html)

![00157b5b05fb0d83477b67fad8d303d](/docs-assets/faq/cdn/other-fusion/problem-diagnosis-method/1324-mobile-terminal-network-test-tool-android-ios/00157b5b05fb0d83477b67fad8d303d-b554be942390.webp)

* 第二步：复制域名到文本框中，点击检测

![00157b5b078198a05447c88818846fe](/docs-assets/faq/cdn/other-fusion/problem-diagnosis-method/1324-mobile-terminal-network-test-tool-android-ios/00157b5b078198a05447c88818846fe-b5b7a8679910.webp)


# 资源无法访问排查步骤（PC 端，手机端） (/faq/cdn/other-fusion/problem-diagnosis-method/1353-user-can-t-access-screening-step-pc-mobile-phone)



最近更新时间: 2022-05-17 16:19:01

首先和客户拿到无法访问的报错信息，以确定排除诸如 404，403 等资源不可访问的问题

# 1 检测 dns 信息 [#1-检测-dns-信息]

1）ios，windows 检测 dns

dns 检测链接：

[https://ping.huatuo.qq.com/](https://ping.huatuo.qq.com/)

2）linux 系统 dns 测试，输入下述命令： `curl http://1000.testns.cdnunion.net/`

3）手机端一键检测链接：

[手机端网络测试工具 (android、iOS)](/faq/cdn/other-fusion/problem-diagnosis-method/1324-mobile-terminal-network-test-tool-android-ios)

如果检测结果dns配置不正确，修改即可解决。

# 2 提供 ping 域名 [#2-提供-ping-域名]

如：图片 `http://7xo9nf.com2.z0.glb.qiniucdn.com/123.jpg` 无法访问

ping 域名，将结果贴过来

```
ping 7xo9nf.com2.z0.glb.qiniucdn.com
PING qiniunor.xdwscache.ourglb0.com (112.90.240.150): 56 data bytes
64 bytes from 112.90.240.150: icmp_seq=0 ttl=49 time=52.046 ms
...

112.90.240.150 # 这个就是我们重点需要的
```

综上：将每步的检测结果贴到工单发给我们。收到您提供的信息截图后，我们会进行检测，如果节点存在问题我们会进行调整，调整好后会及时通知您。


# 如何在浏览器中获取网络请求信息 (/faq/cdn/other-fusion/problem-diagnosis-method/1478-how-to-access-network-in-the-browser-request-information)



最近更新时间: 2019-11-04 16:29:14

# 获取网络请求信息 [#获取网络请求信息]

打开谷歌浏览器调出调试窗口

| 操作系统    | 组合按键                   |
| ------- | ---------------------- |
| windows | `Ctrl + shift + i`     |
| macOS   | `option + commond + i` |

![blob.png](/docs-assets/faq/cdn/other-fusion/problem-diagnosis-method/1478-how-to-access-network-in-the-browser-request-information/00157063542529cc45018ca5010bc14-0449e943f0fb.webp)

# 参数解释 [#参数解释]

| 关键字      | 名词解释                |
| -------- | ------------------- |
| header   | HTTP 头部信息，包含请求头和响应头 |
| preview  | HTTP 请求响应结果的预览信息    |
| response | HTTP 响应信息           |

如图：

![blob.png](/docs-assets/faq/cdn/other-fusion/problem-diagnosis-method/1478-how-to-access-network-in-the-browser-request-information/001571a0a540e0984e0ce6bb57d4336-c000d1b71c70.webp)


# CDN 节点 IP 的获取方法 (/faq/cdn/other-fusion/problem-diagnosis-method/3641-get-the-cdn-node-ip-method)



最近更新时间: 2018-06-12 16:41:47

七牛 CDN （Content Delivery Network，内容分发网络）会将网站的静态资源发布到离用户最近的网络边缘。

当用户访问一个配置了七牛 CDN 的域名时，七牛的 CDN 智能调度系统会让用户解析到一个离他最近的 CDN 边缘节点。

于是，不同地区不同运营商的客户端访问同一个域名时，解析到的 IP 很大概率上是不同的。

另外，在中心城市（如上海电信网络），七牛 CDN 可能使用多个甚至多组节点覆盖。

同一终端在相同的网络环境下访问，两次访问解析到的 CDN 节点 IP 也有可能不同。

# 获取 CDN 节点 IP 的两种方法： [#获取-cdn-节点-ip-的两种方法]

使用浏览器调试窗口查看 remote address 得到节点 IP 。  由于在相同网络环境下，两次解析的结果也有可能会解析到不同节点。

所以下面介绍的方法 1 不能保证一定能得到实际访问到的节点，而方法 2 是可以的。

## 方法一 [#方法一]

用终端 ping 域名的方式，可以得到解析到的 IP 节点（以获取访问 [www.qiniu.com](http://www.qiniu.com) 的节点ip为例，客户需要根据自身情况更改域名，以获取访问对应域名的节点ip）：

![](/docs-assets/faq/cdn/other-fusion/problem-diagnosis-method/3641-get-the-cdn-node-ip-method/FhlSq8VdpTUvImvCTCfbtuD0yc2f-0980f45ecf33.webp)

## 方法二 [#方法二]

下面介绍 chrome 浏览器获取 remote address 操作流程（以获取访问 [www.qiniu.com](http://www.qiniu.com) 的节点ip为例，客户需要根据自身情况更改域名，以获取访问对应域名的节点ip）：
在页面空白区域点击右键 -> 检查 -> 点击 “network” -> 点击资源名

![](/docs-assets/faq/cdn/other-fusion/problem-diagnosis-method/3641-get-the-cdn-node-ip-method/Fve91BAfpRKpscF_V9qjndBD_hz6-31a387f4e3a3.webp)

截图中红框即访问 [www.qiniu.com](http://www.qiniu.com) 根目录的 remote address ：


# 获取本地 IP 和 DNS 方法 (/faq/cdn/other-fusion/problem-diagnosis-method/3642-get-the-local-ip-and-dns-method)



最近更新时间: 2024-08-20 14:51:21

目前获取本地 IP 和 DNS 的第三方服务有多种，比较推荐的有：
[http://ping.huatuo.qq.com/](http://ping.huatuo.qq.com/)

如本地设置的 DNS 服务器与本地 IP 所在地区相距较远，或者跨运营商，可能导致访问 CDN 时不能解析到相距较近的节点，影响访问效果。


# 通过 http 状态码，判断下载失败原因 (/faq/cdn/other-fusion/problem-diagnosis-method/3885-through-the-http-status-code-download-failure-reason)



最近更新时间: 2017-09-29 10:10:48

如果使用浏览器访问，可以 [在浏览器中获取网络请求信息](/faq/cdn/other-fusion/problem-diagnosis-method/1478-how-to-access-network-in-the-browser-request-information)

常见的集中错误如下：

| 错误码 | 说明                                                                                                                                                                                                                                                 |
| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 | 鉴权失败。<br />· `token not specified` 表示访问时没有带 token 。如果确认访问 URL 是带了 token 的，需要核实域名是否开启了忽略 URL 参数，私有空间域名此项必须关闭。 <br />· `download token auth failed` 表示 token 错误，说明生成 token 的算法有问题，建议直接使用七牛的服务端 SDK 生成 token。<br />· `token out of date` 表示 token 过期。 |
| 403 | 权限不足。通常是因为域名开启了防盗链，需要确认一下防盗链规则是否跟访问请求相符。                                                                                                                                                                                                           |
| 404 | 文件不存在。需要确认一下文件是否真的上传成功，或者是上传后执行了删除操作。                                                                                                                                                                                                              |
| 478 | 镜像回源失败。<br />通常报错是 `get image from source failed :E xxx ` ，其中 xxx 是回源拉取文件时源站响应的状态码，需要以此为依据排查源站服务是否正常。                                                                                                                                              |
| 5xx | 错误是服务端异常。<br />· 域名的源站是自有源，建议优先排查源站是否对七牛回源请求给了 5xx 的响应。<br /> · 域名的源站是七牛存储空间，需要给七牛提交工单，提供 [CDN 节点 IP](/faq/cdn/other-fusion/problem-diagnosis-method/3641-get-the-cdn-node-ip-method) 。                                                            |


# HTTP 请求返回状态码 (/faq/cdn/other-fusion/status-tool/1352-the-http-request-return-a-status-code)



最近更新时间: 2019-03-25 19:49:00

| HTTP 状态码 | 说明                                                                                                                                                                                            |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200      | 操作执行成功。                                                                                                                                                                                       |
| 298      | 部分操作执行成功。                                                                                                                                                                                     |
| 400      | 请求报文格式错误。包括上传时，上传表单格式错误；URL 触发图片处理时，处理参数错误；\[资源管理]\[rsHref] 或 [持久化数据处理 (pfop)](/faq/cdn/other-fusion/status-tool/1352-the-http-request-return-a-status-code#pfop-existing-resource) 操作请求格式错误。 |
| 401      | 认证授权失败。  包括密钥信息不正确；数字签名错误；授权已超时。                                                                                                                                                              |
| 403      | token中的key和put方法的key不一致;mimelimit类型限制;fsizelimit大小限制                                                                                                                                          |
| 404      | 资源不存在。  包括空间资源不存在；镜像源资源不存在。                                                                                                                                                                   |
| 405      | 请求方式错误。  主要指非预期的请求方式。                                                                                                                                                                         |
| 406      | 上传的数据 CRC32 校验错误。                                                                                                                                                                             |
| 419      | 用户账号被冻结。                                                                                                                                                                                      |
| 478      | 镜像回源失败。  主要指镜像源服务器出现异常。                                                                                                                                                                       |
| 503      | 服务端不可用。                                                                                                                                                                                       |
| 504      | 服务端操作超时。                                                                                                                                                                                      |
| 573      | 单个资源访问频率过高                                                                                                                                                                                    |
| 579      | 上传成功但是回调失败。  包括业务服务器异常；七牛服务器异常；服务器间网络异常。                                                                                                                                                      |
| 599      | 服务端操作失败。                                                                                                                                                                                      |
| 608      | 资源内容被修改。                                                                                                                                                                                      |
| 612      | 指定资源不存在或已被删除。                                                                                                                                                                                 |
| 614      | 目标资源已存在。                                                                                                                                                                                      |
| 630      | 已创建的空间数量达到上限，无法创建新空间。                                                                                                                                                                         |
| 631      | 指定空间不存在。                                                                                                                                                                                      |
| 640      | 调用[列举资源 (list)](/faq/cdn/other-fusion/status-tool/1352-the-http-request-return-a-status-code) 接口时，指定非法的`marker`参数。                                                                            |
| 701      | 在断点续上传过程中，后续上传接收地址不正确或`ctx`信息已过期。                                                                                                                                                             |


# 手机抓包 (/faq/cdn/other-fusion/status-tool/1373-mobile-phone-caught)



最近更新时间: 2017-08-30 17:26:38

**电脑做wifi热点，手机连上后电脑上使用wireshark抓包**

**方法如下：**

1、使用电脑作为无线热点，使用的共享无线的软件可以有很多种(这里使用的是猎豹免费wifi)；

2、开启猎豹免费wifi后将手机连入，并找到对应的手机IP，这里是192.168.191.2

![blob.png](/docs-assets/faq/cdn/other-fusion/status-tool/1373-mobile-phone-caught/001579dabd6c646409937aa9abc5572-2c150b8ca441.webp)

![blob.png](/docs-assets/faq/cdn/other-fusion/status-tool/1373-mobile-phone-caught/001579db56edfdcc590ca34dcc60c73-59220e0221d4.webp)

3、查找对应的热点的网卡。打开控制面板=》网络和Internet=》网络和共享中心，查找到无线对应的网卡，例如下图：

![blob.png](/docs-assets/faq/cdn/other-fusion/status-tool/1373-mobile-phone-caught/001579dac6668d343aa365586f100ec-417afa674325.webp)

4、开启wireshark，找到对应的网卡并点击开始抓包

![blob.png](/docs-assets/faq/cdn/other-fusion/status-tool/1373-mobile-phone-caught/001579db4fb1466d3b1d7b31c564554-94cde35e9378.webp)

5、点击捕获=》捕获过滤器，会弹出一个窗口，之后选择HTTP TCP port(80)，这个过滤条件。或者直接在应用显示过滤器中敲入http来过滤出http协议的数据包。

![blob.png](/docs-assets/faq/cdn/other-fusion/status-tool/1373-mobile-phone-caught/001579db50c79517ddd838456ecc2f7-c956beb84295.webp)

![blob.png](/docs-assets/faq/cdn/other-fusion/status-tool/1373-mobile-phone-caught/001579db51434686f0f072f3c37e4b3-4cfcbb9a32e6.webp)

6、找到您手机IP对应的HTTP包，点击Hypertext Transfer Protocol查看详细信息； ![blob.png](/docs-assets/faq/cdn/other-fusion/status-tool/1373-mobile-phone-caught/001579db52416f00caffce231fbb733-2e260c3efbc3.webp)

7、显示详细信息后下拉，并将下图中的1和2的信息提供给我们，这边来帮您排查。

![blob.png](/docs-assets/faq/cdn/other-fusion/status-tool/1373-mobile-phone-caught/001579db53e2e88a6be2f9c040b678a-a1fcbfb25b83.webp)

8、或者将wireshark抓包信息导出提供我们，选择一个需要的导出的数据包文件，选中完成之后，进行点击菜单中的“file”的菜单，下拉中进行选择为export specified packets的选项。

导出可以参考这个详细文档：
[http://jingyan.baidu.com/article/1612d500bbafa3e20e1eee92.html](http://jingyan.baidu.com/article/1612d500bbafa3e20e1eee92.html)


# iOS抓包步骤 (/faq/cdn/other-fusion/status-tool/1392-ios-caught-steps)



最近更新时间: 2018-12-29 15:11:40

## 需求： [#需求]

iOS设备获取http请求或响应报文，适用于 无线 或 3/4G移动网络环境

## 软件： [#软件]

Replica
![001579af2f5128a56484e9580bb8267](/docs-assets/faq/cdn/other-fusion/status-tool/1392-ios-caught-steps/001579af2f5128a56484e9580bb8267-c24fb52b3913.webp)

首次运行需添加VPN配置：
![001579af9ba76ab0c92d2dad73f50c9](/docs-assets/faq/cdn/other-fusion/status-tool/1392-ios-caught-steps/001579af9ba76ab0c92d2dad73f50c9-8f3666d3e6e3.webp)

## 上传抓包示例： [#上传抓包示例]

#### 1.打开Replica App，点击Start开始抓包（注意免费版只能记录20条） [#1打开replica-app点击start开始抓包注意免费版只能记录20条]

![001579afe33bb2b716f57c8452e77e8](/docs-assets/faq/cdn/other-fusion/status-tool/1392-ios-caught-steps/001579afe33bb2b716f57c8452e77e8-44acbb7f06b8.webp)

#### 2.在手机浏览器或app中进行上传操作（这里以七牛js sdk demo为例：[http://jssdk.demo.qiniu.io](http://jssdk.demo.qiniu.io)）： [#2在手机浏览器或app中进行上传操作这里以七牛js-sdk-demo为例httpjssdkdemoqiniuio]

![001579affd88a006a1b5a75fdaf96d6](/docs-assets/faq/cdn/other-fusion/status-tool/1392-ios-caught-steps/001579affd88a006a1b5a75fdaf96d6-2dea706ce806.webp)

#### 3.返回Replica ，点击Stop停止抓包-->然后点击屏幕下方Analytics按钮 [#3返回replica-点击stop停止抓包--然后点击屏幕下方analytics按钮]

此时可以看到抓包信息，点击最上面的进入本次抓包：

![001579b0121602eb88b34dc94a2d50f](/docs-assets/faq/cdn/other-fusion/status-tool/1392-ios-caught-steps/001579b0121602eb88b34dc94a2d50f-23c2c8669286.webp)

#### 4.从中找出本次上传记录,并点击进入（ **POST** 方法，域名一般是:`http://upload.qiniup.com` 或 `http://up.qiniup.com` ） [#4从中找出本次上传记录并点击进入-post-方法域名一般是httpuploadqiniupcom-或-httpupqiniupcom-]

![001579b02047c1e5be45bb1a12361aa](/docs-assets/faq/cdn/other-fusion/status-tool/1392-ios-caught-steps/001579b02047c1e5be45bb1a12361aa-4c86becab184.webp)

#### 5.可以得到以下信息： [#5可以得到以下信息]

**Overview标签可以得到远程ip信息：**

![001579b07c88e67f79eefb3705c8ab6](/docs-assets/faq/cdn/other-fusion/status-tool/1392-ios-caught-steps/001579b07c88e67f79eefb3705c8ab6-01e9d7bd106e.webp)

**Request标签中显示请求头：**

![001579b03bf8e3cf5989388a4159863](/docs-assets/faq/cdn/other-fusion/status-tool/1392-ios-caught-steps/001579b03bf8e3cf5989388a4159863-49284e3dc5d8.webp)

**Response标签可以看到响应头** （可以获得reqid信息，必要的时候可以将文本复制出来发给七牛技术支持）：

![001579b04523679397b65c42d397d18](/docs-assets/faq/cdn/other-fusion/status-tool/1392-ios-caught-steps/001579b04523679397b65c42d397d18-e5ed68eae8a3.webp)

## 其他 [#其他]

如果是下载或播放视频抓包的话，方式类似。先打开Replica开始抓包，然后访问资源，点击停止后进入分析界面，提供相关信息即可。


# HTTP状态码大全 (/faq/cdn/other-fusion/status-tool/1425-the-http-status-code-books)



最近更新时间: 2017-08-30 17:26:38

# 标准扩展码 [#标准扩展码]

## 1xx Informational 信息化 [#1xx-informational-信息化]

100 Continue 继续

101 Switching Protocols 交换协议

102 Processing 处理

## 2xx Success 成功 [#2xx-success-成功]

200 OK

201 Created 创建

202 Accepted 已接受

203 Non-Authoritative Information 非授权信息

204 No Content 无内容

205 Reset Content 重置内容

206 Partial Content 部分内容

207 Multi-Status 多状态

208 Already Reported 已报告

226 IMIM Used 使用的

## 3xx Redirection 重定向 [#3xx-redirection-重定向]

300 Multiple Choices 多种选择

301 Moved Permanently 永久移动

302 Found 发现

303 See Other 查看其它

304 Not Modified 未修改

305 Use Proxy 使用代理

306 Switch Proxy 开关代理

307 Temporary Redirect 临时重定向

308 Permanent Redirect 永久重定向

## 4xx Client Error 客户端错误 [#4xx-client-error-客户端错误]

400 Bad Request 错误的请求

401 Unauthorized 未授权

402 Payment Required 需要付费

403Forbidden 拒绝访问

404 Not Found 未找到

405 Method Not Allowed 不允许的方法

406 Not Acceptable 不可接受

407 Proxy Authentication Required 代理服务器需要身份验证

408 Request Timeout 请求超时

409 Conflict 冲突

410 Gone 完成

411 Length Required 需要长度

412 Precondition Failed 前提条件失败

413 Payload Too Large 负载过大

414 URI Too Long 太长

415 Unsupported Media Type 不支持的媒体类型

416 Range Not Satisfiable 的范围不合适

417 Expectation Failed 预期失败

418 I'm a teapot 我是一个茶壶

421 Misdirected Request 误导请求

422 Unprocessable Entity 无法处理的实体

423 Locked 锁定

424 Failed Dependency 失败的依赖

426 Upgrade Required 升级所需

428 Precondition Required 所需的先决条件

429 Too Many Requests 太多的请求

431 Request Header Fields Too Large 请求头字段太大

451 Unavailable For Legal Reasons 不可出于法律原因

**5xx Server Error 服务器错误**

500 Internal Server Error 内部服务器错误

501 Not Implemented 未执行

502 Bad Gateway 错误的网关

503 Service Unavailable 服务不可用

504 Gateway Timeout 网关超时

505 HTTP Version Not Supported 不支持HTTP版本

506 Variant Also Negotiates 变体也进行协商

507 Insufficient Storage 存储空间不足

508 Loop Detected 检测到循环

510 Not Extended 不延长

511 Network Authentication Required 网络需要身份验证

# **非官方扩展码** [#非官方扩展码]

103 Checkpoint 检查点

420 Method Failure (Spring Framework) 故障的方法（Spring框架）

420 Enhance Your Calm (Twitter) 增强您的平静（微博）

450 Blocked by Windows Parental Controls (Microsoft) 被Windows阻止家长控制（微软）

498 Invalid Token (Esri) 无效的令牌（ESRI的）

499 Token Required (Esri) 令牌必需（ESRI的）

499 Request has been forbidden by antivirus 请求已被禁止反病毒

509 Bandwidth Limit Exceeded (Apache Web Server/cPanel) 超出带宽限制（Apache的Web服务器/的cPanel）

530 Site is frozen 网站被冻结

# **互联网信息服务扩展状态码** [#互联网信息服务扩展状态码]

440 Login Timeout 登录超时

449 Retry With 重新发送带

451 Redirect 重定向

# **NGINX 扩展状态码** [#nginx-扩展状态码]

444 No Response 没有响应

495 SSL Certificate Error 证书错误

496 SSL Certificate Required证书要求

497 HTTP Request Sent to HTTPS Port 发送到HTTPS端口请求

499 Client Closed Request 客户端请求关闭

以上内容参考维基百科：[https://en.wikipedia.org/wiki/List\_of\_HTTP\_status\_codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)

# **七牛扩展状态码** [#七牛扩展状态码]

298 部分操作执行成功。

419 用户账号被冻结。

478 镜像回源失败。 主要指镜像源服务器出现异常。

573 单个资源访问频率过高

579 上传成功但是回调失败。 包括业务服务器异常；七牛服务器异常；服务器间网络异常。

599 服务端操作失败。

608 资源内容被修改。

612 指定资源不存在或已被删除。

614 目标资源已存在。

630 已创建的空间数量达到上限，无法创建新空间。

631 指定空间不存在。

640 调用列举资源 (list) 接口时，指定非法的marker参数。

701 在断点续上传过程中，后续上传接收地址不正确或ctx信息已过期。


# 视频教程 - 如何 CNAME (/faq/cdn/other-fusion/video-tutorial-fusion/1684-video-tutorials-how-to-cname)



最近更新时间: 2020-02-14 16:59:19

[cname配置视频教程](https://dn-odum9helk.qbox.me/lgnLdGqZXkb5bqac09Lw_sGB2jxP)


# 视频教程--申请ssl证书验证 (/faq/cdn/other-fusion/video-tutorial-fusion/3861-video-tutorials-apply-for-ssl-certificate-authentication)



最近更新时间: 2019-01-07 17:15:21

[如何申请ssl免费证书视频教程](http://dn-odum9helk.qbox.me/wjw/spjc/avthumb/ssl-txt.mov.mp4)


# 视频教程 - 多媒体数据处理 (/faq/dora/av-processing/video-tutorial-dora/1396-video-tutorials-multimedia-data-processing)



最近更新时间: 2019-01-07 17:02:12

[多媒体数据处理视频教程](https://dn-odum9helk.qbox.me/spjc/5.mp4)


# 视频教程--命令行进行数据处理 (/faq/dora/av-processing/video-tutorial-dora/3860-video-pfop)



最近更新时间: 2019-01-07 17:12:29

[pfop 数据处理视频教程](http://dn-odum9helk.qbox.me/wjw/spjc/avthumb/pfop.mov.mp4)


# 如何获取存储文件的外链接 (/faq/kodo/basic-use-of/access-to-resources-common-problems/1321-how-to-acquire-the-outside-storage-file-links)



最近更新时间: 2026-04-30 17:09:01

# 公开空间 [#公开空间]

1. 直接在内容管理界面上获得链接
   ![image.png](/docs-assets/faq/kodo/basic-use-of/access-to-resources-common-problems/1321-how-to-acquire-the-outside-storage-file-links/FgK8UpiixKSiU7KmiLA3jJhwoyd-cefb084aafe4.webp)

2. 通过以下地址访问。

```
http://<domain>/<key>
```

其中`<domain>`是 bucket 所对应的域名。七牛会给每个 bucket 分配一个测试域名，但由于 [测试域名的访问限制](/faq/cdn/other-fusion/1319-test-domain-access-restriction-rules)，生产环境需要 [绑定自定义域名](https://portal.qiniu.com/domain/create) 访问。 `<key>`可理解为文件名，但可包含文件分隔符等其它字符。可参考：[特殊 key 资源的访问](/faq/kodo/basic-use-of/2636-special-access-to-key-resources)
**注意： key必须采用utf8编码，如使用非utf8编码访问七牛云将反馈错误**

3. [批量获取下载链接](/faq/kodo/4072-batch-obtains-download-chain-method)

# 私有空间 [#私有空间]

1.私有空间与公开空间相同
![image.png](/docs-assets/faq/kodo/basic-use-of/access-to-resources-common-problems/1321-how-to-acquire-the-outside-storage-file-links/Fhkr2zb2D16fyweaxtST2Q04gpng-9bca19a6de60.webp)

2.私有资源必须通过临时 \[下载凭证] (/kodo/manual/download-token)(downloadToken)进行下载，如下：

\[GET] http\://\<domain>/\<key>?e=\<deadline>\&token=\<downloadToken>

注意，尖括号不是必需，代表替换项。

`deadline` 由服务器时间加上 指定秒数 表示过期时间点。默认 3600 秒，服务器时间需校准，不要与标准时间相差太大。 `downloadToken` 可以使用 SDK 提供的方法生成。

以下提供python生成私有空间外链的参考代码，更多详细请参考[官方sdk](/sdk-tools/sdk#official-sdk)

```python
# -*- coding: utf-8 -*-
# flake8: noqa

import requests
from qiniu import Auth

access_key = '...'
secret_key = '...'

q = Auth(access_key, secret_key)
bucket_domain = "..."
key = "..."

# 有两种方式构造base_url的形式
base_url = 'http://%s/%s' % (bucket_domain, key)

# 或者直接输入url的方式下载
# base_url = 'http://domain/key'

# 可以设置token过期时间
private_url = q.private_download_url(base_url, expires=3600)

print(private_url)
r = requests.get(private_url)
assert r.status_code == 200
```


# 存储空间遇到 404 文件不返回 404 状态码 (/faq/kodo/basic-use-of/access-to-resources-common-problems/1630-404-file-does-not-return-a-status-code-of-404)



最近更新时间: 2017-08-30 18:01:48

当文件不存在或者访问不到时，返回一个404页面，如果要求响应状态码必须是非404时应如何操作呢？

这里举一个返回 301 状态码的例子。

# 步骤一 404页面设置 [#步骤一-404页面设置]

点击空间设置 -> 404 页面设置，如下图：

<img src="/docs-assets/faq/kodo/basic-use-of/access-to-resources-common-problems/1630-404-file-does-not-return-a-status-code-of-404/FsViFJIbwFtUK-1PRCrVECJT4b5G-4b97f8c29b09.webp" width="800" />

设置完成后，内容管理会自动生成一个叫 errno-404 的文件

注：errno-404 是在空间设置的 404 文件的文件名，为系统默认，不可修改。

<img src="/docs-assets/faq/kodo/basic-use-of/access-to-resources-common-problems/1630-404-file-does-not-return-a-status-code-of-404/FjhnHJ3L3-TOFqA88M9NdwEcPdZx-0c9b6f7960cd.webp" width="800" />

这时候再访问不存在的资源会返回设置好的 404 图片，如图：

<img src="/docs-assets/faq/kodo/basic-use-of/access-to-resources-common-problems/1630-404-file-does-not-return-a-status-code-of-404/FqXDxeyvWAst2NyVc_RW0Bc07Bq2-ab9a9864cce9.webp" width="800" />

# 步骤二 下载工具 [#步骤二-下载工具]

下载 [qrsctl 工具](/products/kodo/0-qshell)，加入系统环境参考如下：

```
# LINUX 系统
➜  Downloads mv qrsctl-v3.2.20170501 qrsctl
➜  Downloads chmod +x qrsctl
➜  Downloads sudo mv qrsctl /usr/local/bin

# 新打开一个终端执行
➜  ~ qrsctl

Usage:
  qrsctl [-l|d|lan|it|-f <hostFile>] -v login <User> <Passwd>                                               - Login
  qrsctl [-l|d|lan|it|-f <hostFile>] -v info                                                                - Show user information
  qrsctl [-l|d|lan|it|-f <hostFile>] -v appinfo [<AppName>]                                                 - Get application info
  qrsctl [-l|d|lan|it|-f <hostFile>] -v put -c <Bucket> <Key> <SrcFile>                                     - Put file
  qrsctl [-l|d|lan|it|-f <hostFile>] -v get <Bucket> <Key> <DestFile>                                       - Get file
  qrsctl [-l|d|lan|it|-f <hostFile>] -v stat <Bucket> <Key>                                                 - Stat file
  qrsctl [-l|d|lan|it|-f <hostFile>] -v cat <Bucket> <Key>                                                  - Cat file
  qrsctl [-l|d|lan|it|-f <hostFile>] -v del <Bucket> <Key>                                                  - Delete a file
(省略部分，更多命令请自行查看。)
```

这里我们用到的命令是：

```
qrsctl [-l|d|lan|it|-f <hostFile>] -v redirect <Bucekt> <Key> <RedirectUrl> [<RedirectCode>]              - Redirec
```

# 步骤三 设置跳转 [#步骤三-设置跳转]

# 1. 登陆账号 [#1-登陆账号]

首先需要用您的开发者帐号登录七牛云存储，登录成功后，才能进行接下来所有其他指令操作。

登录成功后，会话的有效期是 3600 秒（一个小时），一个小时后需要重新登录。

```
qrsctl login <User> <Passwd>
```

| 参数     | 说明   |
| ------ | ---- |
| User   | 注册邮箱 |
| Passwd | 登录密码 |

# 2. 设置跳转 [#2-设置跳转]

命令格式：

```
qrsctl redirect <bucketname> errno-404 <finalurl> 301
```

例子：

```
qrsctl redirect bucket01 errno-404 http://otshsz9r2.bkt.clouddn.com/apple.png 301
```

操作完后，curl 文件可以看到，返回了301


# 空间文件字节数为 0B (/faq/kodo/basic-use-of/access-to-resources-common-problems/1676-bytes-0-b-space-file)



最近更新时间: 2017-08-30 18:00:25

表现： 
加载图片时显示成功，但是显示为空白；空间中的文件大小为 0B

原因： 

1. 七牛允许 0B 字节的文件存在。 
2. 客户端上传时读取文件错误。

解决方法： 

1. 更新使用的客户端sdk，最新的sdk中已经禁止 0B 的文件上传。 
2. 在上传策略中设置 fsizeMin 为1，保证上传的文件大于 1B 。


# 如何修改链接中的默认域名？ (/faq/kodo/basic-use-of/access-to-resources-common-problems/1706-how-to-modify-the-link-to-the-default-domain-name)



最近更新时间: 2017-08-30 17:59:26

**按照如下方式修改：**

![](/docs-assets/faq/kodo/basic-use-of/access-to-resources-common-problems/1706-how-to-modify-the-link-to-the-default-domain-name/FshPpkYtLI5AyIq0KywSxxc0bKYe-f71c12ba83e8.webp)


# 如何从测试域名过渡到自定义域名 (/faq/kodo/basic-use-of/access-to-resources-common-problems/5158-how-to-transition-from-test-domain-name-to-a-custom-domain-name)



最近更新时间: 2026-05-15 11:12:19

如果您的空间正在使用测试域名，需要绑定自定义域名来避免访问受限，您可以通过以下步骤进行域名的过渡。

# 空间绑定自定义域名的配置流程 [#空间绑定自定义域名的配置流程]

* 创建加速域名
* 保存加速域名为默认域名
* 添加cname解析
* 验证外链是否可以访问
* 替换旧外链
  `请勿跳过任何步骤`

***

## 详细步骤 [#详细步骤]

1. 打开控制台中的[对象存储](https://portal.qiniu.com/kodo/bucket)，点击具体的空间名。
   域名管理页面可以选择绑定`cdn域名`和`源站域名`；
   点击 **绑定域名** 进入创建加速域名页面，您可以在跳转页面中绑定一个自定义域名到存储空间。
   ![image.png](/docs-assets/faq/kodo/basic-use-of/access-to-resources-common-problems/5158-how-to-transition-from-test-domain-name-to-a-custom-domain-name/FsXrNA7Rxg4pfM5_Yt-t49yj3iw4-86afa06a8c06.webp)

***

2. 创建域名过程中详细的参数解释可以参考[域名接入文档](/products/cdn/the-domain-name-management/0-the-domain-name-to-access)
   * 域名类型如果没有特殊需求，选择\*\*`普通域名`\*\*即可，如果您需要了解泛域名，请参考上面的[域名接入文档](/products/cdn/the-domain-name-management/0-the-domain-name-to-access)。
   * 加速域名处建议填写的您\*\*`未在使用`\*\*的二级或三级域名等，请勿轻易绑定www域名避免影响您的源站服务。
     （例如，您购买的主域名是example.com，二级域名可以为cdn.example.com，前缀可以自行定义即可）
   * 当您为存储空间绑定自定义域名的时候，源站配置\*\*`默认为七牛云存储`\*\*即可.
     <img src="/docs-assets/faq/kodo/basic-use-of/access-to-resources-common-problems/5158-how-to-transition-from-test-domain-name-to-a-custom-domain-name/Fs20S2K501FrUlhjieaU4YoE96qC-255ab8deec65.webp" width="600" />

***

3. 点击 创建 后，您可以在控制台中的[对象存储](https://portal.qiniu.com/kodo/bucket)，点击具体的空间,在 `域名管理` 里看到该空间绑定域名的状态
   域名状态为 `“处理中”` 是处于创建状态，需要等待后台创建完成；
   域名状态为 `“等待CNAME”` ，需要您配置cname解析，解析步骤可以参考教程的步骤5，您也可以先操作步骤4，再执行步骤5，解析未配置的情况下，该域名暂时还无法用于访问；
   域名状态为` “成功”` ，域名可以正常使用，可以进入下一步骤。
   ![image.png](/docs-assets/faq/kodo/basic-use-of/access-to-resources-common-problems/5158-how-to-transition-from-test-domain-name-to-a-custom-domain-name/Ft8z5VOFThqvyniYZiTV8r7_53-1-e846a905c940.webp)

***

4.域名状态为 “等待CNAME” 或 “成功” 后，在 **文件管理** 中，**外链域名**的下拉框里选中您需要绑定的自定义域名，点击对应域名进行选择。

* 注意：域名状态为处理中时，无法设置为默认域名，请等待域名处理完成。
  ![image.png](/docs-assets/faq/kodo/basic-use-of/access-to-resources-common-problems/5158-how-to-transition-from-test-domain-name-to-a-custom-domain-name/FgSdBQz8YGvxkjkyBzZcvEPZ_DiN-ddb4f5b59de4.webp)

***

5.绑定成功后，需要配置您域名的cname解析，您可以根据控制台的引导文档，也可以直接点击[如何配置域名的CNAME](/faq/cdn/domain-name-configuration-problem/1322-how-to-configure-cname-domain-name)
`注意：未配置解析或解析未生效，该域名将无法用于访问，确保解析生效后再使用新域名访问。`

6.**文件管理**中，点击**更多**，点击 **复制外链*&#x2A; ，即可获得新外链，您可以在浏览器中访问新外链，成功访问后，&#x2A;*`请在您调用旧外链的地方使用新外链替换`**。
如果您的新外链无法访问，请[检查域名是否配置成功](/faq/cdn/domain-name-configuration-problem/5326-how-to-check-whether-the-configuration-is-successful)。
![image.png](/docs-assets/faq/kodo/basic-use-of/access-to-resources-common-problems/5158-how-to-transition-from-test-domain-name-to-a-custom-domain-name/Fnv2U6PO5cTSohdUqWaWxEd2LuRC-25d4e15dd779.webp)
7\. 完成上述步骤后，通过自定义域名访问资源时，不会受到限制。

***

# 常见问题答疑 [#常见问题答疑]

* Q: 保存自定义域名为默认域名后，是否之前的链接就恢复访问了呢？
  A: 不是，保存自定义域名为默认域名后，新旧链接都可以正常访问，但是新生成的链接会通过自定义域名访问，而旧的链接依旧是通过测试域名访问，依旧会受到限制。

* Q: 可以将同一个域名绑定到多个空间吗？
  A: 不可以，一个域名只能绑定一个空间，建议您绑定二级或三级域名，按照cname配置流程在厂商处配置解析即可。

* Q: 是否可以不绑定自定义域名，申请一直使用测试域名呢？
  A: 不可以，测试域名仅供测试使用，不在SLA保障范围内，有效期30天，请勿用于线上环境。


# 视频教程 - 基本使用 (/faq/kodo/basic-use-of/video-tutorial/1394-video-tutorials-basic-use)



最近更新时间: 2019-01-04 17:46:18

全局使用:

[http://dn-odum9helk.qbox.me/spjc/1.mp4](http://dn-odum9helk.qbox.me/spjc/1.mp4)

创建空间讲解

[http://dn-odum9helk.qbox.me/spjc/2.mp4](http://dn-odum9helk.qbox.me/spjc/2.mp4)


# 批量删除 (/faq/kodo/basic-use-of/data-migration-issues/12959-kodo-batch-delete)



最近更新时间: 2026-08-18 11:54:41

## 关于删除 [#关于删除]

目前存储控制台不支持删除整个空间或者整个目录文件，可以通过工具或者sdk api进行删除，`删除的本质是基于文件列表进行删除`，所以在删除前，如果不是使用kodo-borwser的话，都需要先获取文件列表。

## 七牛提供如下解决方案： [#七牛提供如下解决方案]

* 七牛工具 [qshell](/products/kodo/0-qshell) 进行批量删除，`适用于大量文件、没有目录结构文件的删除`，优先推荐使用qshell,,windows使用参考这里，[windows安装使用教程](/faq/kodo/tools-common-problems/12960-windows-environment-installation-qshell-tutorial#2)
* 七牛工具 [kodo-browser](/products/kodo/1-kodo-browser)进行批量删除，`适用于少量文件删除，或者指定文件夹删除`
* [官方服务端SDK](/sdk-tools/sdk#official-sdk)，使用SDK调用文件列表，然后基于文件列表循环调用delete方法删除

## 使用经验 [#使用经验]

### qshll 删除 [#qshll-删除]

<br />

`使用batchdelet 和 listbucket2 前，必须先登录账号，使用qshell account 进行登录，如果已经登陆过，那么无需重复登录`。ak sk 空间名称如果不了解是什么，可以阅读[常见的关键参数](/faq/kodo/7450-the-third-party-plug-in-key-parameters) , 想要获取指定的文件列表，可以参考[批量获取文件列表](/faq/kodo/basic-use-of/12958-kodo-batch-keylist),listbucket2的参数不同，就会获取不同的待删除文件列表。

```bash
  qshell account 您的ak 您的sk 账号邮箱(名称)
```

<br />

1: 删除空间全部文件

```bash
  qshell listbucket2 空间名称 --show-fields Key -o todelete.txt
  qshell batchdelete 空间名称 -i todelete.txt
```

<br />

2: 删除空间指定前缀文件，比如需要删除image/文件夹文件

```bash
  qshell listbucket2 空间名称   --show-fields Key --prefix 'iamge/' -o todelete.txt
  qshell batchdelete 空间名称 -i todelete.txt
```

### kodo-browser删除 [#kodo-browser删除]

参考 [kodo-browser](/products/kodo/1-kodo-browser)，登录后，界面勾选目录或者文件进行删除，windows 和 mac 端都可以使用，linux建议使用qshell

### SDK删除 [#sdk删除]

以java为列：
参考
1：获取文件名称
/products/kodo#rs-list
2：基于list获取的文件名称，循环删除或者批量删除
/products/kodo#rs-delete
/products/kodo#rs-batch-delete
其他SDK类似，可参考[官方服务端SDK](/sdk-tools/sdk#official-sdk)


# 数据迁移-S3通用迁移任务 (/faq/kodo/basic-use-of/data-migration-issues/12961-kodo-s3-migration)



最近更新时间: 2026-04-17 15:32:04

# 简介 [#简介]

目前市面上主流的云厂商基本都已支持S3协议，可以使用S3协议直接获取原账号资源，然后将文件迁移到存储空间，迁移支持同一个七牛账号内数据迁移，也支持不同七牛账号间数据迁移，或者将其他厂商的数据迁移到七牛账号

# 计费 [#计费]

迁移会对目标源产生一个外网流出流量计费，比如：目标源是其他厂商，费用参考各厂商价格，目标源是七牛存储空间，迁移时会产生七牛存储空间的外网流出流量的计费，详情见[计费说明](/products/kodo/1-metering-and-billing)
如果有资源包需求，请查看 [https://portal.qiniu.com/financial/price?product=kodo](https://portal.qiniu.com/financial/price?product=kodo)

# 使用方式 [#使用方式]

一般都是在迁入的新账号创建迁移任务,控制台 [https://portal.qiniu.com/kodo/data-migration](https://portal.qiniu.com/kodo/data-migration) 创建任务，选择S3迁移方式

1: 填写 原始空间所属账号的 AK 、SK 、S3空间名称(空间名称)、S3\_Region(源端区域) 以及 S3\_Endpoint(区域Endpoint)

需要注意的是：`S3空间名称、S3_Region 以及 S3_Endpoint 是什么，怎么获取`，以七牛存储为例
可以在空间概览中查看 空间域名，空间的S3域名是 [https://80e4gu.s3.cn-east-1.qiniucs.com](https://80e4gu.s3.cn-east-1.qiniucs.com)

```
S3空间名称 : 80e4gu
S3_Region : cn-east-1
S3_Endponit : https://s3.cn-east-1.qiniucs.com
```

一般而言，S3域名的组成就是 https\://S3\_空间名称.Endpoint的格式组成，Endpoint中包含区域，S3域名的第三段就是region，如果不知道自己空间的S3域名是什么，可以咨询下您的空间供应商即可

![image.png](/docs-assets/faq/kodo/basic-use-of/data-migration-issues/12961-kodo-s3-migration/FoWIh4FaN_ZFv4WXCWvlWuZlGWwH-54527c06c91d.webp)

2: 选择需要迁入的七牛存储空间

最终，我们填写的任务应该是这样的，这个就是表示，从bugtest空间，利用bugtest空间的S3域名方式进行迁移，将空间数据迁移到当前账号其他空间

![image.png](/docs-assets/faq/kodo/basic-use-of/data-migration-issues/12961-kodo-s3-migration/FiMnBLtN5BX-kFzHMbg2HD1DVjsv-eb69f1e3f431.webp)


# 如何将线上的数据热迁移到七牛云？ (/faq/kodo/basic-use-of/data-migration-issues/1344-how-to-heat-transfer-to-the-qiniu-online-data)



最近更新时间: 2019-02-14 12:04:33

> 想将线上的数据迁移到七牛云，如何在不影响现有服务的前提下进行热迁移？

## 方案一：完全使用七牛镜像存储功能 [#方案一完全使用七牛镜像存储功能]

**注意：此方法仅针对少量数据的网站，对于数据量比较大（尤其是 UGC -- 用户产生内容）的网站，建议用下面的方案二**

利用七牛提供的镜像存储功能，可以非常简单地将源站的数据 **被动** 地同步到七牛云存储中，所谓 **被动同步** 即——只有在资源被访问时，七牛才会回源站获取一次，此后对该资源的访问都不会再发生回源动作，而是直接从七牛这里拿到数据。

有人可能会问，既然七牛对一个资源只会发生一次回源请求，后面的都不回源获取，那么如果源站的资源发生了变动，该如何将新的资源同步到七牛？这里我们提供两个方案：

1. 调用七牛提供的 `delete` 接口，将变化的资源删除既可。这样七牛在下一次被访问的时候，会再次回源获取。如果资源变动数量很小，可以更加简单地在开发者后台的内容管理中，或者使用七牛提供的 qboxrsctl 命令行工具直接删除已变化的文件既可。

2. 调用七牛提供的 `prefetch` 接口，该接口会比 `delete` 接口多做一个 **预取** 的操作，即在该接口调用时，七牛会立刻回源获取一次新的数据，而不是等到下一次访问的时候才去源站获取。

PS：

1. 登录[开发者后台](http://portal.qiniu.com/)开启镜像存储功能

2. qrsctl 工具获取方式：[http://developer.qiniu.com/docs/v6/tools/qboxrsctl.html#download](/faq/kodo/basic-use-of/data-migration-issues/1344-how-to-heat-transfer-to-the-qiniu-online-data)

3. `delete` 接口[相关文档](/faq/kodo/basic-use-of/data-migration-issues/1344-how-to-heat-transfer-to-the-qiniu-online-data)

4. `prefetch` 接口[相关文档](/faq/kodo/basic-use-of/data-migration-issues/1344-how-to-heat-transfer-to-the-qiniu-online-data)

## 方案二：七牛镜像存储功能 + 一套迁移方案 [#方案二七牛镜像存储功能--一套迁移方案]

方案一适用于将源站保留的前提下进行数据的热迁移，同时享受到七牛提供的加速和数据处理服务。如果您想将源站的数据完全一下子迁移到七牛，而源站的数据量又十分庞大，担心在数据迁移的过程中出现源站的资源被动态更新，但导入到七牛的数据还是老数据的情况，那么可以使用如下的数据迁移方案。

如何在不影响现有服务的前提下，将源站的数据完整地迁移到七牛呢？我们提供一套成熟的迁移方案供您参考：

1. 第一步，开启镜像存储，并将用户对源站资源的访问切换到从七牛这里访问，同时在源站保持使用 `prefetch` 接口预取更新变化了的资源。

2. 第二步，将资源的上传动作从源站切换到七牛，这样用户对资源的修改动作会直接更新七牛中存储的内容，此时源站的资源数据已经变成一个静态的集合，因此可以撤销第一步中对 `prefetch` 接口的使用。

3. 第三步，放心地将源站的静态资源数据增量地导入七牛的存储，存储中已有的资源不再导入，只导入存储中还不存在的资源。


# 如何将阿里云 OSS上 的文件迁移到七牛云存储？ (/faq/kodo/basic-use-of/data-migration-issues/1347-how-to-ali-cloud-oss-files-on-migration-to-seven-niuyun-storage)



最近更新时间: 2026-04-30 17:38:47

很多用户有需求将阿里云对象存储（OSS）中的文件同步到七牛云对象存储空间（KODO）中，对此，七牛云提供了相应的 [qshell工具](/products/kodo/0-qshell) 帮助用户，下面以一个具体的案例讲解操作步骤：

首先需要下载七牛云提供的 [qshell工具](/products/kodo/0-qshell)。大致流程是使用 qshell 工具的  [alilistbucket](https://github.com/qiniu/qshell/blob/master/docs/alilistbucket.md) 命令获取一份包含阿里云对象存储中文件的文件列表，然后再使用 qshell 工具的  [batchfetch](https://github.com/qiniu/qshell/blob/master/docs/batchfetch.md) 命令批量抓取文件列表中的文件到七牛云存储空间中。

# 本案例中的参数 [#本案例中的参数]

## 七牛云对象存储参数 [#七牛云对象存储参数]

* AccessKey/SecretKey：[获取](https://portal.qiniu.com/user/key)
* Bucket：`qiniu-test-bucket`

## 阿里云对象存储参数 [#阿里云对象存储参数]

* DataCenter：`oss-cn-shanghai.aliyuncs.com`
* Bucket：`ali-qiniu`
* AccessKeyId、AccessKeySecret：[获取](https://ak-console.aliyun.com/#/accesskey)
* ListBucketResultFile：`alitoqiniu.txt`

# 1、获取阿里对象存储的文件列表 [#1获取阿里对象存储的文件列表]

1.使用 `qshell account <AK> <SK> name` 设置或显示当前用户的 AccessKey 和 SecretKey ，name为在本地自定义的用户名，可以填写您的七牛云账户邮箱。
2.使用 qshell 里面的 [alilistbucket](https://github.com/qiniu/qshell/blob/master/docs/alilistbucket.md) 命令 列举出阿里云 OSS 中的文件的文件列表

此例中的 OSS 文件列表如下：
![](/docs-assets/faq/kodo/basic-use-of/data-migration-issues/1347-how-to-ali-cloud-oss-files-on-migration-to-seven-niuyun-storage/how-to-ali-cloud-oss-files-on-migration-to-seven-niuyun-storage--c91f83fb313e.webp)

qshell alilistbucket \<DataCenter> \<Bucket> \<AccessKeyId> \<AccessKeySecret> \[Prefix] \<ListBucketResultFile>

其中`DataCenter` `Bucket` `AccessKeyId` `AccessKeySecret`要和 OSS 里面相对应，更详细的说明：[点我查看](https://github.com/qiniu/qshell/blob/master/docs/batchfetch.md)。

qshell 运行的命令如下：

qshell alilistbucket oss-cn-shanghai.aliyuncs.com alitoqiniu xxx xxx alitoqiniu.txt

如果不写`Prefix`则列举出所有的文件，后面的`alitoqiniu.txt`也可以写成绝对路径。
运行后可以看到本地`alitoqiniu.txt`里面的文件如下：
![](/docs-assets/faq/kodo/basic-use-of/data-migration-issues/1347-how-to-ali-cloud-oss-files-on-migration-to-seven-niuyun-storage/how-to-ali-cloud-oss-files-on-migration-to-seven-niuyun-storage--f7697330d265.webp)

# 2、抓取阿里云对象存储文件到七牛存储空间 [#2抓取阿里云对象存储文件到七牛存储空间]

1.使用  [batchfetch](https://github.com/qiniu/qshell/blob/master/docs/batchfetch.md) 命令将这个文件里面的文件批量抓取到七牛云存储空间中，但是 `batchfetch` 抓取的是可访问的文件的外链，所以在这之前还需要对上面的 `alitoqiniu.txt` 进行处理，需要拼接为可访问的文件外链的形式。
这一步可以使用 linux 下 awk 文本处理工具进行拼接，这里直接给出命令如下：

cat alitoqiniu.txt | awk '\{print "[http://ali-qiniu.oss-cn-shanghai.aliyuncs.com/"$1\&#125](http://ali-qiniu.oss-cn-shanghai.aliyuncs.com/"$1\&#125);' >batchfetchurls.txt

再次`cat batchfetchurls.txt`里面的文件列表如下：
![](/docs-assets/faq/kodo/basic-use-of/data-migration-issues/1347-how-to-ali-cloud-oss-files-on-migration-to-seven-niuyun-storage/how-to-ali-cloud-oss-files-on-migration-to-seven-niuyun-storage--4a066a65db8c.webp)

2.使用 `batchfetch` 命令进行同步，这里直接给出同步命令：

qshell batchfetch qiniu-test-bucket -i batchfetchurls.txt

运行结果如下：
![](/docs-assets/faq/kodo/basic-use-of/data-migration-issues/1347-how-to-ali-cloud-oss-files-on-migration-to-seven-niuyun-storage/how-to-ali-cloud-oss-files-on-migration-to-seven-niuyun-storage--a049387f4a65.webp)

至此即同步成功，可以看到七牛云存储空间里面也有相关的文件了：
![](/docs-assets/faq/kodo/basic-use-of/data-migration-issues/1347-how-to-ali-cloud-oss-files-on-migration-to-seven-niuyun-storage/how-to-ali-cloud-oss-files-on-migration-to-seven-niuyun-storage--bc1ac1d00a3a.webp)

\#3、通过对象存储 Kodo 提供的数据迁移服务
对象存储 Kodo 提供的[数据迁移服务](/products/kodo/kodo-console-guide/set-data-migration)，支持您将第三方数据源轻松迁移至七牛云对象存储 Kodo。当前 Kodo 提供全托管迁移模式进行在线数据迁移服务，用户只需提交迁移任务、服务会自动执行数据迁移


# 获取空间当前的存储总量 (/faq/kodo/basic-use-of/data-migration-issues/3743-amount-of-storage-space-of-the-current)



最近更新时间: 2017-08-30 17:41:46

调用list接口
[/products/kodo/rs/4-list](/products/kodo/rs/4-list)，
会返回空间内文件的相关信息，其中包括文件的大小fsize，对每个文件的fsize相加即可获得空间的当前存储总量

![](/docs-assets/faq/kodo/basic-use-of/data-migration-issues/3743-amount-of-storage-space-of-the-current/FnVnJeHQKCh4cL_ODOqR5OLJ8acU-ec6abcd8fb36.webp)

以python代码为例：

# -&#x2A;- coding: utf-8 -*- [#---coding-utf-8---]

from qiniu import Auth
from qiniu import BucketManager

access\_key = ''
secret\_key = ''

q = Auth(access\_key, secret\_key)
bucket = BucketManager(q)

bucket\_name = ''

# 前缀 [#前缀]

prefix = None

# 列举条目 [#列举条目]

limit = 200

# 列举出除'/'的所有文件以及以'/'为分隔的所有前缀 [#列举出除的所有文件以及以为分隔的所有前缀]

delimiter = None

# 标记 [#标记]

marker = None

total\_fize = 0

ret, eof, info = bucket.list(bucket\_name, prefix, marker, limit, delimiter)
for i in ret\['items']:
print(i\['fsize'])
total\_fize += i\['fsize']

print(total\_fize)


# 运行时和模型 (/products/agentapi/development_guidelines/agentapi-agent-configuration/13589-agentapi-agent-configuration-runtime-and-models)



最近更新时间: 2026-10-13 15:31:14

智能体的 `runtime` 选择执行引擎，`model` 选择模型；创建会话时用 `environment_id` 选择工具执行环境。

## 运行时的执行方式 [#运行时的执行方式]

### Claude Code [#claude-code]

`claudecode` 由 Claude Code SDK 驱动，在云端沙箱中组织模型与工具调用。继续会话依赖原沙箱可恢复。

### Codex [#codex]

`codex` 以 Codex harness 作为智能体循环（agent loop）的主体驱动，在云端沙箱中组织模型与工具调用。继续会话同样依赖原沙箱；两个运行时的版本与预装软件见[云端环境参考](/products/agentapi/development_guidelines/agentapi-execution-environments/13609-agentapi-execution-environments-cloud-environments)。

### AgentAPI Native [#agentapi-native]

`native` 由 AgentAPI 直接管理模型循环，根据会话事件重建上下文，不依赖特定沙箱存续。文件和命令工具在云端沙箱或自托管 worker 中执行；需要长期保留的产物，写入 `/mnt/session/outputs/` 后可通过[文件交付](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)下载。Native 不能使用 Claude Code 与 Codex 运行时特有的工具能力。

## 按场景选择配置 [#按场景选择配置]

先按场景选定运行时，再确定执行环境与工具：

| 场景                          | 起步配置                             | 选择理由与接入说明                                                                                                                                                                 |
| --------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 首次接入，验证端到端流程                | `claudecode` + `cloud` + 内置工具集   | 工具链开箱即用，按[快速开始](/products/agentapi/quick_start/13587-agentapi-quickstart)即可跑通。                                                                                            |
| 已有 Claude Code 或 Codex 使用经验 | `claudecode` 或 `codex` + `cloud` | 沿用熟悉的工具行为与提示词习惯，核对原工作流所需工具与软件即可。                                                                                                                                          |
| 应用需要执行自定义业务工具               | `native` + 自定义工具                 | 应用经事件[回传结果](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)，链路最短；`claudecode`、`codex` 需要额外的工具桥接服务。        |
| MCP 工具调用需要应用审批              | `native` + MCP + `always_ask`    | 应用处理[工具确认](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)；`claudecode`、`codex` 的 MCP 仅支持 `always_allow`。 |
| 文件与命令须在自有基础设施执行             | `native` + `self_hosted`         | 部署 [worker](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)，在自有环境完成隔离与产物交付。                  |
| 跨任务读取项目规范                   | 云端 `claudecode`/`codex` + 只读记忆存储 | 云端 Native 不自动挂载记忆；其他方式见[记忆接入](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13603-agentapi-data-and-integrations-memory)。                      |

建议始终显式传入 `runtime`：省略时默认使用 `claudecode`，未必符合任务需要；对执行耗时敏感、或需要应用逐次确认工具的场景，建议评估并显式选择 `native`。网页访问、仓库挂载等细节在[工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)与[GitHub](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13604-agentapi-data-and-integrations-github)专题中说明。没有既有偏好时，用相同输入与验收标准比较完成率、恢复行为、耗时和用量，再固定选择。

## 选择模型 [#选择模型]

从[七牛 MaaS 模型列表](https://portal.qiniu.com/ai-inference/model)选择当前账户与区域可用、Key 有权调用的模型，并核对其思考强度。智能体请求中的 `model` 可只传模型 ID，也可使用对象：

```json
{
  "id": "your-model-id",
  "effort": {"type": "high"}
}
```

模型配置与运行时都属于智能体版本，已有会话不会随更新切换。发布与临时覆盖见[会话配置](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)。


# 创建与管理智能体 (/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)



最近更新时间: 2026-10-13 15:31:16

智能体（Agent）是一种可复用、带版本的配置，用于定义角色和能力。它将运行时、模型、系统提示、工具、MCP 服务器和技能组合在一起，共同决定智能体在会话中的行为。

智能体可供多个[会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)复用。创建智能体仅保存配置，不启动任务或分配沙箱。更新配置时生成新版本；配置未变化时返回现有版本。

![运行时、模型、系统提示和工具能力共同组成智能体配置](/docs-assets/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent/FqNUvdxm9GAx1XmKD1r5NmzyP95L-5d1ede6a5f57.webp)

## 运行时、模型和云端环境 [#运行时模型和云端环境]

智能体配置 `runtime` 和 `model`，创建会话时通过 `environment_id` 选择环境。运行时的执行位置与任务选型见[运行时和模型](/products/agentapi/development_guidelines/agentapi-agent-configuration/13589-agentapi-agent-configuration-runtime-and-models)；本页说明智能体字段与版本管理。

## 创建智能体 [#创建智能体]

以下示例定义一个编程助手，使用 `claudecode` 运行时和所选模型，并启用内置工具集。该工具集允许智能体编写代码、读取文件和访问网页。有关支持的工具，请参阅[工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)。

> 生成可下载的文件
>
> 云端环境默认引导智能体将下载产物写入 `/mnt/session/outputs/`，执行后可通过 Portal 文件页或 Files API 获取，无需重复添加提示。临时文件留在工作目录或临时目录，项目文件在原路径修改。自托管 worker 不提供这条目录指引。

开始前，请先按照[接入准备](/products/agentapi/quick_start/13585-agentapi-access)配置 `AGENTAPI_BASE_URL`、`AGENTAPI_API_KEY` 和 `AGENTAPI_MODEL_ID`。SDK 示例使用已经初始化的 `client`，初始化代码和依赖导入见[SDK 客户端初始化](/products/agentapi/quick_start/13587-agentapi-quickstart)。`runtime` 通过各 SDK 的扩展请求参数传入。

cURL

```bash
agent=$(curl --request POST -fsSL "$AGENTAPI_BASE_URL/v1/agents" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data "$(jq -n --arg model "$AGENTAPI_MODEL_ID" '{
    name: "编程助手",
    runtime: "claudecode",
    model: {id: $model},
    system: "你是一名编程助手，请编写结构清晰、注释完善的代码。",
    tools: [{type: "agent_toolset_20260401"}]
  }')")

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")
```

Python

```python
import os

agent = client.beta.agents.create(
    name="编程助手",
    model={"id": os.environ["AGENTAPI_MODEL_ID"]},
    system="你是一名编程助手，请编写结构清晰、注释完善的代码。",
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
    extra_body={"runtime": "claudecode"},
)
```

TypeScript

````typescript
const params = {
  name: "编程助手",
  model: { id: process.env.AGENTAPI_MODEL_ID! },
  system: "你是一名编程助手，请编写结构清晰、注释完善的代码。",
  tools: [{ type: "agent_toolset_20260401" }],
} satisfies Parameters<typeof client.beta.agents.create>[0];
const agent = await client.beta.agents.create(params, {
  body: { ...params, runtime: "claudecode" },
});
```csharp
```csharp
using System.Linq;
using System.Text.Json;

var parameters = new AgentCreateParams
{
    Name = "编程助手",
    Model = new BetaManagedAgentsModelConfigParams
    {
        ID = Environment.GetEnvironmentVariable("AGENTAPI_MODEL_ID")!,
    },
    System = "你是一名编程助手，请编写结构清晰、注释完善的代码。",
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = "agent_toolset_20260401",
        },
    ],
};
var body = parameters.RawBodyData.ToDictionary(entry => entry.Key, entry => entry.Value);
body["runtime"] = JsonSerializer.SerializeToElement("claudecode");
parameters = AgentCreateParams.FromRawUnchecked(
    parameters.RawHeaderData, parameters.RawQueryData, body);
var agent = await client.Beta.Agents.Create(parameters);
````

Go

```go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "编程助手",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: os.Getenv("AGENTAPI_MODEL_ID"),
	},
	System: anthropic.String("你是一名编程助手，请编写结构清晰、注释完善的代码。"),
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
		},
	}},
}, option.WithJSONSet("runtime", "claudecode"))
if err != nil {
	panic(err)
}
```

Java

```java
import com.anthropic.core.JsonValue;

var agent = client.beta().agents().create(
    AgentCreateParams.builder()
        .name("编程助手")
        .model(BetaManagedAgentsModelConfigParams.builder()
            .id(System.getenv("AGENTAPI_MODEL_ID")).build())
        .putAdditionalBodyProperty("runtime", JsonValue.from("claudecode"))
        .system("你是一名编程助手，请编写结构清晰、注释完善的代码。")
        .addTool(
            BetaManagedAgentsAgentToolset20260401Params.builder()
                .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                .build()
        )
        .build()
);
```

PHP

```php
$agent = $client->beta->agents->create(
    name: '编程助手',
    model: ['id' => getenv('AGENTAPI_MODEL_ID')],
    system: '你是一名编程助手，请编写结构清晰、注释完善的代码。',
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
        ),
    ],
    requestOptions: ['extraBodyParams' => ['runtime' => 'claudecode']],
);
```

Ruby

```ruby
agent = client.beta.agents.create(
  name: "编程助手",
  model: {id: ENV.fetch("AGENTAPI_MODEL_ID")},
  system_: "你是一名编程助手，请编写结构清晰、注释完善的代码。",
  tools: [{type: "agent_toolset_20260401"}],
  request_options: {extra_body: {runtime: "claudecode"}}
)
```

响应返回保存的配置，以及 `id`、`type`、`version`、`runtime`、`status`、`created_at` 和 `updated_at`。`version` 从 1 开始，配置发生变化时递增；未提交的可选模型配置不会自动加入响应。

```json
{
  "id": "agt_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "编程助手",
  "runtime": "claudecode",
  "model": { "id": "your-model-id" },
  "system": "你是一名编程助手，请编写结构清晰、注释完善的代码。",
  "tools": [{"type": "agent_toolset_20260401"}],
  "version": 1,
  "status": "ready",
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z"
}
```

## 智能体配置字段 [#智能体配置字段]

| 字段                 | 描述                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`             | 必填。用于在 Portal 和资源列表中识别智能体的名称。                                                                                                                                                                                                                                                                                                                                                    |
| `runtime`          | 可选。指定智能体使用的运行时：`claudecode`、`codex` 或 `native`。省略时使用 `claudecode`，建议按任务场景显式指定，选择方法见[运行时和模型](/products/agentapi/development_guidelines/agentapi-agent-configuration/13589-agentapi-agent-configuration-runtime-and-models)。                                                                                                                                                       |
| `model`            | 必填。驱动智能体的模型。可以传入模型 ID 字符串，也可以传入对象，例如 `{"id": "your-model-id", "effort": {"type": "high"}}`。可用模型取决于当前账户和服务配置，请前往[七牛 MaaS 模型管理页](https://portal.qiniu.com/ai-inference/model)查看。                                                                                                                                                                                                   |
| `agentapi_options` | 可选。AgentAPI 扩展配置。`thinking` 控制 Native 思考，详见思考配置。`system_prompt_mode` 控制 `claudecode` 和 `codex` 如何放置 `system`，取值为 `append` 或 `replace`，详见系统提示词放置方式。                                                                                                                                                                                                                               |
| `system`           | 定义智能体行为和角色设定的系统提示。系统提示用于描述智能体应如何工作，[用户消息](/products/agentapi/api/13618-agentapi-api-conventions)用于描述本次要完成的任务。默认与云端环境说明一起追加到运行时产品提示词之后；需要用它替换产品提示词时，见系统提示词放置方式。                                                                                                                                                                                                                   |
| `tools`            | 智能体可用的[内置工具集](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)、[MCP 工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13592-agentapi-agent-configuration-mcp)和[自定义工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)。 |
| `mcp_servers`      | 提供标准化第三方能力的 [MCP 服务器](/products/agentapi/development_guidelines/agentapi-agent-configuration/13592-agentapi-agent-configuration-mcp)。                                                                                                                                                                                                                                            |
| `skills`           | 智能体按任务需要加载的[技能](/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills)，包含工作说明和辅助文件。                                                                                                                                                                                                                                   |
| `description`      | 对智能体功能的描述。                                                                                                                                                                                                                                                                                                                                                                       |
| `metadata`         | 用于业务跟踪的键值对。                                                                                                                                                                                                                                                                                                                                                                      |

## 思考配置 [#思考配置]

`model.effort` 调整思考强度，支持 `low`、`medium`、`high`、`xhigh` 和 `max`。`low` 不关闭思考，`none` 是无效值。

省略 effort 时：创建智能体不发送思考强度；更新时模型 `id` 不变则保留原值，模型 `id` 改变则使用新模型的默认值。

如需关闭思考，请显式使用 `runtime: "native"`，并设置 `agentapi_options.thinking`。这是 AgentAPI 扩展字段，可以通过 SDK 的扩展请求参数传入。

| 设置                         | 行为                                                                 |
| -------------------------- | ------------------------------------------------------------------ |
| `disabled`                 | 要求模型关闭思考，优先于已保存的 effort，但不删除 effort。                               |
| `default`                  | 取消智能体层面的关闭要求，恢复服务端模型服务默认配置和已保存 effort 的正常映射；不代表强制开启思考，也不代表 medium。 |
| 创建时省略整个 `agentapi_options` | 沿用默认行为，不额外设置思考开关。                                                  |
| 更新时省略整个 `agentapi_options` | 保留已有设置；若思考已关闭，则继续保持关闭。                                             |

恢复默认、更新与校验规则如下：

* Messages 协议下，服务端若没有配置 thinking 默认值，`default` 会让上游模型自行决定是否思考；若服务端默认配置本身就是关闭，恢复默认后仍然关闭。
* Responses 协议下恢复已保存的 `reasoning.effort`，未保存 effort 时省略 reasoning 字段。
* `thinking` 取 `null`、空字符串或其他值，以及对象中出现未知字段，在创建和更新时都会返回 400。
* `claudecode` 和 `codex` 不支持此关闭选项，发送 `disabled` 会返回错误。
* `agentapi_options: {}` 是合法请求：创建时按 `thinking: "default"` 保存，更新时不改变已保存的 `thinking` 和 `system_prompt_mode`。只提交其中一个字段时，另一个字段保持原值。`system_prompt_mode` 的取值见系统提示词放置方式。

下面的示例创建一个关闭思考的智能体。请先按照[接入准备](/products/agentapi/quick_start/13585-agentapi-access)设置 `AGENTAPI_BASE_URL`、`AGENTAPI_API_KEY` 和 `AGENTAPI_MODEL_ID`，并选用支持关闭思考的 Native 模型。

cURL

```bash
agent=$(curl --request POST -fsSL "$AGENTAPI_BASE_URL/v1/agents" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data "$(jq -n --arg model "$AGENTAPI_MODEL_ID" '{
    name: "复盘助手",
    runtime: "native",
    model: {id: $model},
    agentapi_options: {thinking: "disabled"}
  }')")

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")
echo "$agent" | jq '.agentapi_options'
```

Go

```go
package main

import (
    "context"
    "fmt"
    "os"

    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
)

func main() {
    client := anthropic.NewClient(
        option.WithBaseURL(os.Getenv("AGENTAPI_BASE_URL")),
        option.WithAPIKey(os.Getenv("AGENTAPI_API_KEY")),
    )
    params := anthropic.BetaAgentNewParams{
        Name: "复盘助手",
        Model: anthropic.BetaManagedAgentsModelConfigParams{
            ID: os.Getenv("AGENTAPI_MODEL_ID"),
        },
    }
    params.SetExtraFields(map[string]any{
        "runtime": "native",
        "agentapi_options": map[string]any{"thinking": "disabled"},
    })
    agent, err := client.Beta.Agents.New(context.Background(), params)
    if err != nil {
        panic(err)
    }
    fmt.Println(agent.ID, agent.Version)
    fmt.Println(agent.JSON.ExtraFields["agentapi_options"].Raw())
}
```

Agent 和 AgentVersion 响应会返回显式保存的 `agentapi_options`；从未设置时省略该字段。Go SDK 从 `JSON.ExtraFields` 读取，更新时可在 `BetaAgentUpdateParams` 上使用同样的 `SetExtraFields`，并携带当前版本号。

要取消上述关闭设置，请更新为 `default`：

```bash
updated_agent=$(curl --request POST -fsSL "$AGENTAPI_BASE_URL/v1/agents/$AGENT_ID" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data "$(jq -n --argjson version "$AGENT_VERSION" '{
    version: $version,
    agentapi_options: {thinking: "default"}
  }')")

AGENT_VERSION=$(jq -r '.version' <<< "$updated_agent")
```

> 思考配置与会话版本
>
> `agentapi_options.thinking` 随智能体版本保存。已有会话继续使用固定版本，修改智能体后需创建新会话才能使用新配置；会话覆盖 `model` 不会改变这个思考开关，但可以指定模型的 `effort`。将已关闭思考的智能体切换到其他运行时时，需要同时传入 `{"thinking":"default"}`。

Native 的 Messages 协议会发送 `thinking: {"type":"disabled"}`，不发送 `output_config.effort`；Responses 协议会发送 `reasoning: {"effort":"none"}`。具体模型必须支持对应参数，不支持时会返回模型服务的错误，AgentAPI 不会移除关闭设置后重试。关闭思考不保证固定的首字响应时间，实际延迟仍取决于模型和请求内容。

## 系统提示词放置方式 [#系统提示词放置方式]

`agentapi_options.system_prompt_mode` 决定 `claudecode` 和 `codex` 如何使用智能体的 `system`。它和 `thinking` 一样是 AgentAPI 扩展，可以通过 SDK 的扩展请求参数传入。

| 取值            | 行为                                                                                                                                                                                                                                                   |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 省略，或 `append` | 默认。`system` 与云端环境的目录、文件说明组成追加内容，附加在运行时自带的产品提示词之后；云端说明位于 `system` 之后。`claudecode` 使用 `--append-system-prompt`，`codex` 使用 `developer_instructions`。保存前会去除 `system` 首尾空白。                                                                               |
| `replace`     | `system` 替换运行时产品提示词，并且不再追加到产品提示词之后。`claudecode` 使用 `--system-prompt`。`codex` 将正文写入模型指令文件，并在沙箱的 `config.toml` 中通过 `model_instructions_file` 引用；新建会话和续接会话均读取此配置，正文不再写入 `developer_instructions`。缩进和末尾换行会原样保存并传给运行时。云端环境的目录和文件说明仍然追加在正文之后，不属于被替换的产品提示词。 |

> 系统提示词替换限制
>
> `native` 不支持 `replace`，创建或更新时会返回 400。`system` 去除空白后为空时，即使保存了 `replace`，运行时仍按追加方式处理，不会清除产品提示词。

配置随智能体版本保存。已有会话继续使用创建时固定的版本；修改放置方式后，需要创建新会话才会生效。之后只更新 `system`、不带 `agentapi_options` 时，仍按已保存的模式决定是否保留原文。

```bash
agent=$(curl --request POST -fsSL "$AGENTAPI_BASE_URL/v1/agents" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  -d '{
    "name": "编程助手",
    "runtime": "claudecode",
    "model": {"id": "gpt-5.6-sol"},
    "system": "你是一名编程助手，请编写结构清晰、注释完善的代码。",
    "agentapi_options": {"system_prompt_mode": "replace"}
  }')

echo "$agent" | jq '.agentapi_options'
```

Go SDK 用 `SetExtraFields` 传入，读取时从 `JSON.ExtraFields` 取回，写法与思考配置相同。

## 智能体版本与会话 [#智能体版本与会话]

智能体的 `version` 从 1 开始。创建会话时可指定版本，或省略版本号以使用当时的最新版本。已有会话始终使用固定版本，不随智能体更新。

更新请求需要携带当前版本号，规则见更新智能体。

创建会话时，可以使用 `agent_with_overrides` 为这次会话覆盖 `model`、`system`、`tools`、`mcp_servers` 或 `skills`。覆盖只对当前会话生效，不修改智能体资源，也不会生成新版本；未覆盖的字段继承所固定的智能体版本。详见[为会话覆盖智能体配置](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)。

![会话级智能体配置覆盖](/docs-assets/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent/Fq0QhStHjqLCutUdJSoJieI4j8Vz-0a03e9f9f4a3.webp)

## 更新智能体 [#更新智能体]

当配置发生变化时，更新智能体会生成一个新版本。请求必须携带当前 `version`，用于防止覆盖其他调用方的更新；版本不匹配时返回 409。

![智能体更新后生成新版本](/docs-assets/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent/FpxunNTBoIZ0Xc7fVM0gihnv4KDz-ce7bef388134.webp)

cURL

```bash
updated_agent=$(curl --request POST -fsSL "$AGENTAPI_BASE_URL/v1/agents/$AGENT_ID" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  -d @- <<EOF
{
  "version": $AGENT_VERSION,
  "system": "你是一名编程助手，请始终为代码编写测试。"
}
EOF
)

echo "New version: $(jq -r '.version' <<< "$updated_agent")"
```

Python

```python
updated_agent = client.beta.agents.update(
    agent.id,
    version=agent.version,
    system="你是一名编程助手，请始终为代码编写测试。",
)

print(f"New version: {updated_agent.version}")
```

TypeScript

````typescript
const updatedAgent = await client.beta.agents.update(agent.id, {
  version: agent.version,
  system: "你是一名编程助手，请始终为代码编写测试。",
});

console.log(`New version: ${updatedAgent.version}`);
```csharp
```csharp
var updatedAgent = await client.Beta.Agents.Update(agent.ID, new()
{
    Version = agent.Version,
    System = "你是一名编程助手，请始终为代码编写测试。",
});

Console.WriteLine($"New version: {updatedAgent.Version}");
````

Go

```go
updatedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
	Version: anthropic.Int(agent.Version),
	System:  anthropic.String("你是一名编程助手，请始终为代码编写测试。"),
})
if err != nil {
	panic(err)
}

fmt.Printf("New version: %d\n", updatedAgent.Version)
```

Java

```java
var updatedAgent = client.beta().agents().update(
    agent.id(),
    AgentUpdateParams.builder()
        .version(agent.version())
        .system("你是一名编程助手，请始终为代码编写测试。")
        .build()
);

IO.println("New version: " + updatedAgent.version());
```

PHP

```php
$updatedAgent = $client->beta->agents->update(
    $agent->id,
    version: $agent->version,
    system: '你是一名编程助手，请始终为代码编写测试。',
);

echo "New version: {$updatedAgent->version}\n";
```

Ruby

```ruby
updated_agent = client.beta.agents.update(
  agent.id,
  version: agent.version,
  system_: "你是一名编程助手，请始终为代码编写测试。"
)

puts "New version: #{updated_agent.version}"
```

示例使用创建响应中的 `version` 更新智能体。若配置已被其他调用方修改，更新将失败。`POST /v1/agents/{id}` 要求版本号至少为 1；省略或传入更小的值会返回 400。

### 更新语义 [#更新语义]

* `version` 必填，且必须至少为 1。如果它与智能体当前版本不匹配，请求返回 409，即使提交的其他字段已与存储值一致。此时请重新读取智能体，确认最新配置后再提交更新。

* 省略的字段会被保留。 仅提交需要更改的字段。

* `agentapi_options`：省略对象或其中字段时保留原值，`{}` 不改变配置。`thinking` 和 `system_prompt_mode` 独立更新。`null`、空字符串或非法枚举会返回 400。恢复思考默认行为用 `{"thinking":"default"}`；恢复提示词追加模式用 `{"system_prompt_mode":"append"}`。详见思考配置和系统提示词放置方式。

* `name`、`system`、`description` 会整体替换为新值。`name` 无法清除；要清空 `system` 或 `description`，请传入空字符串。`replace` 模式下，`system` 的缩进和末尾换行原样保存；其他模式会去掉首尾空白。

* `model` 无法清除。提交模型对象时，`inference_geo` 和 `speed` 随对象整体替换，省略会清除已保存的旧值。`effort` 的继承规则见下表。

* 数组字段（`tools`、`mcp_servers`、`skills`）会被新数组完全替换。若要完全清除某个数组字段，请传递空数组。

* Metadata 按键合并：提交的键新增或更新，省略的键保留，值为 `null` 的键删除。

* 未发生配置变化的更新。 如果更新相对于当前版本没有产生任何变化，则不会创建新版本，并返回现有版本。

更新智能体时，模型思考强度按以下规则处理。这与[会话级模型覆盖](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)的整体替换规则不同。

| 模型更新内容               | `effort` 行为                   |
| -------------------- | ----------------------------- |
| 模型 ID 不变，省略 `effort` | 保留该智能体已保存的思考强度。               |
| 更换模型 ID，省略 `effort`  | 清除已保存的显式强度，使用新模型的默认值。         |
| 显式提供 `effort`        | 使用指定强度，例如 `{"type": "high"}`。 |

## 智能体生命周期 [#智能体生命周期]

您可以在 Portal 的智能体列表中按名称或 ID 搜索。搜索会去掉关键词首尾的空白，并按字面量包含关系匹配；`%`、`_` 和 `!` 不作为通配符。分页总数只统计符合搜索条件的智能体。

对应的 Portal 接口为 `GET /portal/v1/agents?page_index=1&q=关键词`，`q` 必须与 `page_index` 一起使用。公开接口 `GET /v1/agents` 不接受 `q`；使用 SDK 的游标列表时，请继续沿用该接口原有的分页参数。

| 操作   | 行为                                      |
| ---- | --------------------------------------- |
| 更新   | 当配置发生变化时生成新的智能体版本。                      |
| 列出版本 | 返回完整的版本历史，用于跟踪配置变化。                     |
| 归档   | 归档后不能创建新会话引用它；现有会话会继续运行。当前实现仍允许更新归档智能体。 |

### 列出版本 [#列出版本]

获取完整的版本历史，以跟踪智能体随时间的变化。结果是分页的，SDK 示例会自动获取每一页。

cURL

```bash
curl --request GET -fsSL "$AGENTAPI_BASE_URL/v1/agents/$AGENT_ID/versions" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  | jq -r '.data[] | "Version \(.version): \(.updated_at)"'
```

Python

```python
for version in client.beta.agents.versions.list(agent.id):
    print(f"Version {version.version}: {version.updated_at.isoformat()}")
```

TypeScript

````typescript
for await (const version of client.beta.agents.versions.list(agent.id)) {
  console.log(`Version ${version.version}: ${version.updated_at}`);
}
```csharp
```csharp
var versions = await client.Beta.Agents.Versions.List(agent.ID);
await foreach (var version in versions.Paginate())
{
    Console.WriteLine($"Version {version.Version}: {version.UpdatedAt:O}");
}
````

Go

```go
iter := client.Beta.Agents.Versions.ListAutoPaging(ctx, agent.ID, anthropic.BetaAgentVersionListParams{})
for iter.Next() {
	version := iter.Current()
	fmt.Printf("Version %d: %s\n", version.Version, version.UpdatedAt.Format(time.RFC3339))
}
if err := iter.Err(); err != nil {
	panic(err)
}
```

Java

```java
for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) {
    IO.println("Version " + version.version() + ": " + version.updatedAt());
}
```

PHP

```php
foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) {
    echo "Version {$version->version}: {$version->updatedAt->format(DateTimeInterface::ATOM)}\n";
}
```

Ruby

```ruby
client.beta.agents.versions.list(agent.id).auto_paging_each do |agent_version|
  puts "Version #{agent_version.version}: #{agent_version.updated_at.iso8601}"
end
```

### 归档智能体 [#归档智能体]

归档无法撤销。现有会话会继续运行，但新会话无法引用该智能体。当前实现仍允许更新归档智能体；响应会将 `archived_at` 设置为归档时间戳。

cURL

```bash
archived=$(curl --request POST -fsSL "$AGENTAPI_BASE_URL/v1/agents/$AGENT_ID/archive" \
  --header "x-api-key: $AGENTAPI_API_KEY")

echo "Archived at: $(jq -r '.archived_at' <<< "$archived")"
```

Python

```python
archived = client.beta.agents.archive(agent.id)

print(f"Archived at: {archived.archived_at.isoformat()}")
```

TypeScript

````typescript
const archived = await client.beta.agents.archive(agent.id);
console.log(`Archived at: ${archived.archived_at}`);
```csharp
```csharp
var archived = await client.Beta.Agents.Archive(agent.ID);
Console.WriteLine($"Archived at: {archived.ArchivedAt:O}");
````

Go

```go
archived, err := client.Beta.Agents.Archive(ctx, agent.ID, anthropic.BetaAgentArchiveParams{})
if err != nil {
	panic(err)
}
fmt.Printf("Archived at: %s\n", archived.ArchivedAt.Format(time.RFC3339))
```

Java

```java
var archived = client.beta().agents().archive(agent.id());
IO.println("Archived at: " + archived.archivedAt().orElseThrow());
```

PHP

```php
$archived = $client->beta->agents->archive($agent->id);

echo "Archived at: {$archived->archivedAt->format(DateTimeInterface::ATOM)}\n";
```

Ruby

```ruby
archived = client.beta.agents.archive(agent.id)
puts "Archived at: #{archived.archived_at.iso8601}"
```

## 后续步骤 [#后续步骤]

* [工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)：配置智能体可用的操作。
* [技能](/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills)：提供任务所需的专业知识和工作流程。
* [会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)：使用已创建的智能体启动任务。
* [API 约定](/products/agentapi/api/13618-agentapi-api-conventions)：查看事件类型、速率限制和接口约束。


# 工具 (/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)



最近更新时间: 2026-10-13 15:31:18

工具让智能体在推理之外执行操作，例如处理文件、运行代码、访问网页或调用业务系统。AgentAPI 支持运行时内置工具、MCP 工具和自定义工具；具体能力和执行位置取决于工具类型以及智能体的 `runtime`。

![AgentAPI 运行时与工具](/docs-assets/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools/FoXzCKHo1rk03QsLsJOfeUu5ya52-6369745e4769.webp)

## 按任务选择能力 [#按任务选择能力]

| 任务需要           | 使用方式                                                                                                                                                                                                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 读取文件、修改代码、执行命令 | 声明内置工具集，并选择提供相应能力的运行时。                                                                                                                                                                                                                                              |
| 访问已有 MCP 服务    | 在智能体上声明 MCP 服务器和工具集，在会话上关联所需凭证。                                                                                                                                                                                                                                     |
| 查询订单、调用业务 API  | 声明自定义工具，由应用执行并回传结果。                                                                                                                                                                                                                                                 |
| 复用领域知识或工作流程    | 附加 [Agent Skills](/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills)，让智能体按任务需要加载说明和辅助文件。                                                                                                             |
| 提供任务数据或代码仓库    | 在会话中挂载[文件](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)或 [GitHub 仓库](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13604-agentapi-data-and-integrations-github)。 |

工具提供可执行的操作，技能提供工作方法，文件和仓库提供任务材料。例如，分析一份 CSV 时，可以挂载文件、启用代码执行工具，再附加自定义分析技能。

## 可用工具 [#可用工具]

| 运行时          | 内置工具                                                                |
| ------------ | ------------------------------------------------------------------- |
| `claudecode` | Claude Code 原生工具                                                    |
| `codex`      | Codex 原生工具                                                          |
| `native`     | `bash`、`read`、`write`、`edit`、`glob`、`grep`、`web_fetch`、`web_search` |

MCP 工具通过 [MCP 连接器](/products/agentapi/development_guidelines/agentapi-agent-configuration/13592-agentapi-agent-configuration-mcp)接入外部服务。自定义工具由应用执行，并通过会话事件返回结果。

智能体的 `tools` 数组最多包含 64 个条目。`native` 将工具集展开后，可用工具总数最多为 128 个，包括内置、自定义和 MCP 工具；一个 MCP 工具集可能包含多个工具。

## 配置内置工具集 [#配置内置工具集]

在智能体的 `tools` 中声明 `agent_toolset_20260401` 可启用内置工具集，适用于 `claudecode`、`codex`、`native`。[通过 API 构建](/products/agentapi/quick_start/13587-agentapi-quickstart)中的 HTTP 示例使用此配置。

最简形式只需声明该工具集类型：

```json
{"type": "agent_toolset_20260401"}
```

工具集还支持通过 `configs` / `default_config` 启用或禁用单个工具。将工具的 `enabled` 设为 `false` 即可禁用该工具：

```json
{
  "type": "agent_toolset_20260401",
  "configs": [
    {"name": "web_search", "enabled": false}
  ]
}
```

也可以先禁用全部工具，再只启用需要的工具：

```json
{
  "type": "agent_toolset_20260401",
  "default_config": {"enabled": false},
  "configs": [
    {"name": "bash", "enabled": true}
  ]
}
```

> 单个工具的启用和禁用配置仅对 \`native\` 生效
>
> 上面的 `enabled` / `default_config` 逐工具配置只在 `native` 运行时被应用，对应 `bash`、`read`、`write`、`edit`、`glob`、`grep`、`web_fetch`、`web_search`。不写 `permission_policy` 时，这些工具默认直接执行。`claudecode` 和 `codex` 使用各自运行时自带的工具集，不响应这些逐工具的启用/禁用开关。

工具确认策略参阅[权限策略](/products/agentapi/development_guidelines/agentapi-agent-configuration/13593-agentapi-agent-configuration-permissions)。

## 网页访问 [#网页访问]

`claudecode` 和 `codex` 的网页访问能力由对应运行时提供。`native` 的网页工具由 AgentAPI 执行，不在自托管 worker 上执行：

* `web_fetch` 请求网址并返回页面文本，不执行页面脚本。可用 `config.max_content_tokens` 限制返回给模型的正文长度。
* `web_search` 调用服务端配置的搜索服务，返回搜索结果文本。可在 `config.user_location` 中设置 `type: approximate` 和两位国家代码 `country`；城市、地区和时区也可以写入该对象，但当前搜索服务不会使用这三项。
* 两个工具均可通过 `config.allowed_domains` 或 `config.blocked_domains` 限制域名。两项不能同时填写；省略时不额外限制域名。

## 自定义工具 [#自定义工具]

自定义工具由智能体决定是否调用、由应用执行，适合查询订单、读取内部数据库或调用业务 API。

![自定义工具执行流程](/docs-assets/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools/FqP3AWcm2myXxbS90_g7Zhtbdqrs-645621907649.webp)

图中两类工具的执行位置不同：

* 自定义工具：业务代码始终运行在应用进程中。AgentAPI 只负责传递调用和结果，不执行这段代码或通过它访问内网。
* 文件工具和代码执行：在会话的执行环境中运行，和应用进程相互隔离。Native 网页工具由 AgentAPI 执行，远程 MCP 工具则由对应服务执行。

以下示例使用 `native`，通过事件直接完成自定义工具调用和结果回传。`claudecode`、`codex` 需要服务侧已经配置自定义工具桥接，才能使用同一类调用；运行时差异见[智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)。

自定义工具调用流程包含以下四个步骤：

1. 在智能体的 `tools` 中声明工具名称、用途和 `input_schema`。
2. 监听 `agent.custom_tool_use`，执行对应业务函数；会话会通过 `session.status_idle` 暂停等待。
3. 用 `user.custom_tool_result` 回传结果，并通过 `custom_tool_use_id` 对应原调用。
4. 所有待处理的工具调用都返回后，会话才恢复运行，模型再根据结果继续推理。一次可能发出多个工具调用，因此回传单个结果后不一定会立即恢复。

应用侧还需要自行处理鉴权、参数校验、权限确认、超时和错误。失败时也应回传可供模型理解的错误结果，避免会话一直等待。完整事件字段和处理示例请参阅[处理自定义工具调用](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)。

下面以天气查询为例，在智能体中声明自定义工具；`input_schema` 描述模型传给应用的参数。请先完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)，从[七牛 MaaS 模型管理页](https://portal.qiniu.com/ai-inference/model)选择支持工具调用的模型，并设置 `AGENTAPI_MODEL_ID`。SDK 示例沿用[SDK 客户端初始化](/products/agentapi/quick_start/13587-agentapi-quickstart)中的 `client`。

cURL

```bash
agent=$(curl --request POST "$AGENTAPI_BASE_URL/v1/agents" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  -d @- <<EOF
{
  "name": "天气助手",
  "runtime": "native",
  "model": {"id": "$AGENTAPI_MODEL_ID"},
  "tools": [
    {
      "type": "agent_toolset_20260401"
    },
    {
      "type": "custom",
      "name": "get_weather",
      "description": "查询指定城市当前的天气。",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "城市名称"}
        },
        "required": ["location"]
      }
    }
  ]
}
EOF
)
```

Python

```python
import os

agent = client.beta.agents.create(
    name="天气助手",
    model={"id": os.environ["AGENTAPI_MODEL_ID"]},
    tools=[
        {
            "type": "agent_toolset_20260401",
        },
        {
            "type": "custom",
            "name": "get_weather",
            "description": "查询指定城市当前的天气。",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "城市名称"},
                },
                "required": ["location"],
            },
        },
    ],
    extra_body={"runtime": "native"},
)
```

TypeScript

````typescript
const params = {
  name: "天气助手",
  model: { id: process.env.AGENTAPI_MODEL_ID! },
  tools: [
    { type: "agent_toolset_20260401" },
    {
      type: "custom",
      name: "get_weather",
      description: "查询指定城市当前的天气。",
      input_schema: {
        type: "object",
        properties: { location: { type: "string", description: "城市名称" } },
        required: ["location"]
      }
    }
  ]
} satisfies Parameters<typeof client.beta.agents.create>[0];
const agent = await client.beta.agents.create(params, {
  body: { ...params, runtime: "native" },
});
```csharp
```csharp
using System.Linq;
using System;
using System.Text.Json;
using Anthropic.Models.Beta.Agents;

var parameters = new AgentCreateParams
{
    Name = "天气助手",
    Model = new BetaManagedAgentsModelConfigParams { ID = Environment.GetEnvironmentVariable("AGENTAPI_MODEL_ID")! },
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = "agent_toolset_20260401",
        },
        new BetaManagedAgentsCustomToolParams
        {
            Type = "custom",
            Name = "get_weather",
            Description = "查询指定城市当前的天气。",
            InputSchema = new()
            {
                Properties = new Dictionary<string, JsonElement>
                {
                    ["location"] = JsonSerializer.SerializeToElement(
                        new { type = "string", description = "城市名称" }
                    ),
                },
                Required = ["location"],
            },
        },
    ],
};
var body = parameters.RawBodyData.ToDictionary(entry => entry.Key, entry => entry.Value);
body["runtime"] = JsonSerializer.SerializeToElement("native");
parameters = AgentCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body);
var agent = await client.Beta.Agents.Create(parameters);
````

Go

```go
import "github.com/anthropics/anthropic-sdk-go/option"
import "os"
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "天气助手",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: os.Getenv("AGENTAPI_MODEL_ID"),
	},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
		},
	}, {
		OfCustom: &anthropic.BetaManagedAgentsCustomToolParams{
			Type:        anthropic.BetaManagedAgentsCustomToolParamsTypeCustom,
			Name:        "get_weather",
			Description: "查询指定城市当前的天气。",
			InputSchema: anthropic.BetaManagedAgentsCustomToolInputSchemaParam{
				Properties: map[string]any{
					"location": map[string]any{
						"type":        "string",
						"description": "City name",
					},
				},
				Required: []string{"location"},
			},
		},
	}},
}, option.WithJSONSet("runtime", "native"))
if err != nil {
	panic(err)
}
_ = agent
```

Java

```java
import com.anthropic.core.JsonValue;
import com.anthropic.models.beta.agents.*;
import java.util.Map;

var agent = client.beta().agents().create(AgentCreateParams.builder()
    .name("Weather Agent")
    .model(BetaManagedAgentsModelConfigParams.builder().id(System.getenv("AGENTAPI_MODEL_ID")).build())
    .addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
        .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
        .build())
    .addTool(BetaManagedAgentsCustomToolParams.builder()
        .type(BetaManagedAgentsCustomToolParams.Type.CUSTOM)
        .name("get_weather")
        .description("Get current weather for a location")
        .inputSchema(BetaManagedAgentsCustomToolInputSchema.builder()
            .properties(BetaManagedAgentsCustomToolInputSchema.Properties.builder()
                .putAdditionalProperty("location", JsonValue.from(Map.of(
                    "type", "string",
                    "description", "City name")))
                .build())
            .addRequired("location")
            .build())
        .build())
    .putAdditionalBodyProperty("runtime", JsonValue.from("native"))
        .build());
```

PHP

```php
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolInputSchema;
use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolParams;

$agent = $client->beta->agents->create(
    name: '天气助手',
    model: ['id' => getenv('AGENTAPI_MODEL_ID')],
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
        ),
        BetaManagedAgentsCustomToolParams::with(
            type: 'custom',
            name: 'get_weather',
            description: '查询指定城市当前的天气。',
            inputSchema: BetaManagedAgentsCustomToolInputSchema::with(
                properties: ['location' => ['type' => 'string', 'description' => '城市名称']],
                required: ['location'],
            ),
        ),
    ],
    requestOptions: ['extraBodyParams' => ['runtime' => 'native']],
);
```

Ruby

```ruby
agent = client.beta.agents.create(
  name: "天气助手",
  model: {id: ENV.fetch("AGENTAPI_MODEL_ID")},
  tools: [
    {type: :agent_toolset_20260401},
    {
      type: :custom,
      name: "get_weather",
      description: "查询指定城市当前的天气。",
      input_schema: {
        type: :object,
        properties: {location: {type: "string", description: "城市名称"}},
        required: ["location"]
      }
    }
  ],
  request_options: {extra_body: {runtime: "native"}}
)
```

声明工具后，创建会话并发送包含天气查询要求的 `user.message`。工具声明本身不会执行查询，也不会自动提供天气服务；应用需要消费调用事件、执行查询并回传结果。

### 自定义工具定义的最佳实践 [#自定义工具定义的最佳实践]

* 明确用途和参数。 说明适用场景、参数含义和重要限制，便于智能体选择工具。
* 按权限划分职责。 读取、写入和审批要求不同的操作应独立声明。避免用一个 `action` 参数包揽拉取请求的创建、审查和合并。
* 使用资源前缀。 跨服务或资源时，用 `db_query`、`storage_read` 等名称区分工具。
* 仅返回必要字段。 使用稳定的标识符（例如 slug 或 UUID），只返回智能体确定下一步所需的信息，减少上下文占用。

## 后续步骤 [#后续步骤]

* [MCP 连接器](/products/agentapi/development_guidelines/agentapi-agent-configuration/13592-agentapi-agent-configuration-mcp)：将 MCP 服务器连接到智能体，以访问外部工具和数据源。

* [权限策略](/products/agentapi/development_guidelines/agentapi-agent-configuration/13593-agentapi-agent-configuration-permissions)：控制智能体和 MCP 工具何时执行。

* [事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)：发送事件、流式传输响应，并在执行过程中中断执行或补充任务要求。


# MCP 连接器 (/products/agentapi/development_guidelines/agentapi-agent-configuration/13592-agentapi-agent-configuration-mcp)



最近更新时间: 2026-10-13 15:31:20

AgentAPI 支持将 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 服务器连接到云端智能体。连接后，智能体可以通过标准化协议访问外部工具、数据源和服务。

接入 MCP 服务时，需要关联服务器连接、工具集和认证凭证：

1. 在智能体的 `mcp_servers` 中声明服务器名称和 URL。
2. 在同一个智能体的 `tools` 中声明 `mcp_toolset`，用 `mcp_server_name` 引用服务器，并设置工具权限策略。
3. 服务需要认证时，在 Vault（保管库）中保存与服务器 URL 匹配的凭证，再通过会话的 `vault_ids` 引用。无需认证的服务器可以省略这一步。

凭证不保存在智能体定义中，可按会话独立配置。

![MCP 连接配置与凭据分离](/docs-assets/products/agentapi/development_guidelines/agentapi-agent-configuration/13592-agentapi-agent-configuration-mcp/Fq9GXY5DgtyE73ephUTXYm6K-0Jc-84ecb9464844.webp)

MCP 服务器必须是远程 URL。`claudecode`、`codex` 在会话沙箱中连接服务器，`native` 由 AgentAPI 服务端连接。使用 `limited` 环境时，MCP 服务主机必须包含在 `allowed_hosts` 中，Native 同样会校验该配置。Native 中 `allow_mcp_servers: false` 会禁止 MCP 工具接入；设为 `true` 不会绕过白名单。网络配置见[云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)。

## 运行时支持 [#运行时支持]

MCP 连接会随智能体的 `runtime` 在云端执行：

| 运行时          | MCP 连接方式                                    | 权限策略                                          |
| ------------ | ------------------------------------------- | --------------------------------------------- |
| `claudecode` | 将已启用的 MCP 服务器传递给 Claude Code 运行时。           | MCP 工具必须使用 `always_allow`。                    |
| `codex`      | 将已启用的 MCP 服务器传递给 Codex 运行时。                 | MCP 工具必须使用 `always_allow`。                    |
| `native`     | AgentAPI 在云端直接发现并调用 MCP 工具；服务器端点必须使用 HTTPS。 | 支持 `always_allow` 和 `always_ask`，后者会暂停会话等待确认。 |

> MCP 工具确认
>
> * 每次调用前需要应用确认：选择 `runtime: "native"` 和 `always_ask`。
> * 使用 `claudecode` 或 `codex`：必须设置 `always_allow`，否则智能体创建或会话启动会失败。

## 配置 MCP 服务器 [#配置-mcp-服务器]

创建智能体时，在 `mcp_servers` 数组中指定 MCP 服务器。每个服务器需要一个 `type`、一个唯一的 `name` 和一个 `url`。此阶段不提供任何身份验证令牌。

要启用某个服务器的工具，还需在 `tools` 数组中声明匹配的 `mcp_toolset` 条目。该工具集的 `mcp_server_name` 必须与服务器的 `name` 匹配；仅声明服务器不会启用其工具。

> 说明
>
> 示例准备：
>
> * 完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)，从[七牛 MaaS 模型管理页](https://portal.qiniu.com/ai-inference/model)获取模型 ID，设置 `AGENTAPI_MODEL_ID`。
> * 将 `MCP_SERVER_URL` 替换为真实服务地址；`https://mcp.example.com` 为占位符。
> * 按[使用 SDK](/products/agentapi/quick_start/13587-agentapi-quickstart)配置和初始化客户端。
>
> 示例使用 `native`，需处理[工具确认请求](/products/agentapi/development_guidelines/agentapi-agent-configuration/13593-agentapi-agent-configuration-permissions)。

cURL

```bash
MCP_SERVER_URL="${MCP_SERVER_URL:-https://mcp.example.com}"

agent_response=$(curl --request POST "$AGENTAPI_BASE_URL/v1/agents" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
  "name": "GitHub 助手",
  "model": {"id": "$AGENTAPI_MODEL_ID"},
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "$MCP_SERVER_URL"
    }
  ],
  "tools": [
    {"type": "agent_toolset_20260401"},
    {"type": "mcp_toolset", "mcp_server_name": "github"}
  ],
  "runtime": "native"
}
EOF
)
agent_id=$(jq -r '.id' <<<"$agent_response")
```

Python

```python
import os

agent = client.beta.agents.create(
    name="GitHub 助手",
    model={"id": os.environ["AGENTAPI_MODEL_ID"]},
    mcp_servers=[
        {
            "type": "url",
            "name": "github",
            "url": os.getenv("MCP_SERVER_URL", "https://mcp.example.com"),
        },
    ],
    tools=[
        {"type": "agent_toolset_20260401"},
        {"type": "mcp_toolset", "mcp_server_name": "github"},
    ],
    extra_body={"runtime": "native"},
)
```

TypeScript

````typescript
const params = {
  name: "GitHub 助手",
  model: { id: process.env.AGENTAPI_MODEL_ID! },
  mcp_servers: [
    {
      type: "url",
      name: "github",
      url: process.env.MCP_SERVER_URL || "https://mcp.example.com",
    },
  ],
  tools: [
    { type: "agent_toolset_20260401" },
    { type: "mcp_toolset", mcp_server_name: "github" },
  ]
} satisfies Parameters<typeof client.beta.agents.create>[0];
const agent = await client.beta.agents.create(params, {
  body: { ...params, runtime: "native" },
});
```csharp
```csharp
using System;
using System.Linq;
using System.Text.Json;
using Anthropic;
using Anthropic.Core;
using Anthropic.Models.Beta.Agents;

var parameters = new AgentCreateParams
{
    Name = "GitHub 助手",
    Model = new BetaManagedAgentsModelConfigParams { ID = Environment.GetEnvironmentVariable("AGENTAPI_MODEL_ID")! },
};
var body = parameters.RawBodyData.ToDictionary(entry => entry.Key, entry => entry.Value);
body["mcp_servers"] = JsonSerializer.SerializeToElement(new[] {
    new { type = "url", name = "github", url = Environment.GetEnvironmentVariable("MCP_SERVER_URL") ?? "https://mcp.example.com" },
});
body["tools"] = JsonSerializer.SerializeToElement(new object[] {
    new { type = "agent_toolset_20260401" },
    new { type = "mcp_toolset", mcp_server_name = "github" },
});
body["runtime"] = JsonSerializer.SerializeToElement("native");
parameters = AgentCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body);
var agent = await client.Beta.Agents.Create(parameters);
````

Go

```go
import "os"
import "github.com/anthropics/anthropic-sdk-go/option"

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "GitHub 助手",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: os.Getenv("AGENTAPI_MODEL_ID"),
	},
	MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{
		Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,
		Name: "github",
		URL:  envOr("MCP_SERVER_URL", "https://mcp.example.com"),
	}},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{
		{
			OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
				Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			},
		},
		{
			OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{
				Type:          anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset,
				MCPServerName: "github",
			},
		},
	},
}, option.WithJSONSet("runtime", "native"))
if err != nil {
	panic(err)
}

func envOr(name, fallback string) string {
	if value := os.Getenv(name); value != "" {
		return value
	}
	return fallback
}
```

Java

```java
import com.anthropic.core.JsonValue;

var agent = client.beta().agents().create(
    AgentCreateParams.builder()
        .name("GitHub 助手")
        .model(BetaManagedAgentsModelConfigParams.builder().id(System.getenv("AGENTAPI_MODEL_ID")).build())
        .addMcpServer(
            BetaManagedAgentsUrlMcpServerParams.builder()
                .type(BetaManagedAgentsUrlMcpServerParams.Type.URL)
                .name("github")
                .url(System.getenv().getOrDefault("MCP_SERVER_URL", "https://mcp.example.com"))
                .build()
        )
        .addTool(
            BetaManagedAgentsAgentToolset20260401Params.builder()
                .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                .build()
        )
        .addTool(
            BetaManagedAgentsMcpToolsetParams.builder()
                .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET)
                .mcpServerName("github")
                .build()
        )
        .putAdditionalBodyProperty("runtime", JsonValue.from("native"))
        .build()
);
```

PHP

```php
$agent = $client->beta->agents->create(
    name: 'GitHub 助手',
    model: ['id' => getenv('AGENTAPI_MODEL_ID')],
    mcpServers: [
        BetaManagedAgentsURLMCPServerParams::with(
            type: 'url',
            name: 'github',
            url: getenv('MCP_SERVER_URL') ?: 'https://mcp.example.com',
        ),
    ],
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
        ),
        BetaManagedAgentsMCPToolsetParams::with(
            type: 'mcp_toolset',
            mcpServerName: 'github',
        ),
    ],
    requestOptions: ['extraBodyParams' => ['runtime' => 'native']],
);
```

Ruby

```ruby
agent = client.beta.agents.create(
  name: "GitHub 助手",
  model: {id: ENV.fetch("AGENTAPI_MODEL_ID")},
  mcp_servers: [
    {
      type: "url",
      name: "github",
      url: ENV.fetch("MCP_SERVER_URL", "https://mcp.example.com")
    }
  ],
  tools: [
    {type: "agent_toolset_20260401"},
    {type: "mcp_toolset", mcp_server_name: "github"}
  ],
  request_options: {extra_body: {runtime: "native"}}
)
```

### `mcp_servers` 字段参考 [#mcp_servers-字段参考]

`mcp_servers` 数组中的每个条目定义一个连接。

| 字段     | 描述                                                                                                                                                                                                              |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | 必填。必须为 `"url"`。AgentAPI 当前不支持通过 `stdio` 等方式启动 MCP 服务器。                                                                                                                                                          |
| `name` | 必填。此服务器在智能体内的唯一名称（1–64 个字符，必须以字母开头）。用作 `tools` 数组中的 `mcp_server_name`，并显示在[事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)中的 MCP 工具事件上。 |
| `url`  | 必填。MCP 服务器的 `http` 或 `https` 端点，不能在 URL 中携带用户信息或凭据。                                                                                                                                                             |

约束：

* 一个智能体最多可以声明 16 个 MCP 服务器。服务器名称在数组内必须唯一。
* `mcp_toolset` 必须引用一个已声明的 MCP 服务器。

## 配置可用的 MCP 工具 [#配置可用的-mcp-工具]

`native` 支持通过 `default_config` 和 `configs` 启用或禁用单个 MCP 工具：

```json
{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "default_config": {"enabled": false},
  "configs": [
    {"name": "get_issue", "enabled": true}
  ]
}
```

`claudecode` 和 `codex` 只支持启用整个 MCP 服务器，不支持逐工具配置。

## 配置会话认证凭证 [#配置会话认证凭证]

先按[凭证管理](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13606-agentapi-data-and-integrations-vaults)创建与服务器 URL 匹配的 Vault 凭证，再在创建会话时通过 `vault_ids` 引用。多个会话可引用同一 Vault。

cURL

```bash
session_response=$(curl --request POST "$AGENTAPI_BASE_URL/v1/sessions" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
  "agent": {"type": "agent", "id": "$agent_id", "version": 1},
  "environment_id": "$environment_id",
  "vault_ids": ["$vault_id"]
}
EOF
)
session_id=$(jq -r '.id' <<<"$session_response")
```

Python

```python
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)
```

TypeScript

````typescript
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  vault_ids: [vault.id],
});
```csharp
```csharp
var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    VaultIds = [vault.ID],
});
````

Go

```go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent:         anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
	EnvironmentID: environment.ID,
	VaultIDs:      []string{vault.ID},
})
if err != nil {
	panic(err)
}
```

Java

```java
var session = client.beta().sessions().create(
    SessionCreateParams.builder()
        .agent(agent.id())
        .environmentId(environment.id())
        .addVaultId(vault.id())
        .build()
);
```

PHP

```php
$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
    vaultIDs: [$vault->id],
);
```

Ruby

```ruby
session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id,
  vault_ids: [vault.id]
)
```

Vault 凭据通过 `mcp_server_url` 与 MCP 服务器匹配。没有匹配凭据时，AgentAPI 会尝试不带身份验证连接。凭据配置参阅[添加凭据](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13606-agentapi-data-and-integrations-vaults)。

### 处理连接和身份验证失败 [#处理连接和身份验证失败]

会话创建成功仅表示配置已保存。请发送用户消息，观察连接和工具调用事件，验证 MCP 服务是否可用。

出现连接或认证失败时，依次检查：

1. 服务地址：是否为真实、可访问的远程 MCP 端点；Native 需要 HTTPS。
2. 网络策略：环境是否允许连接 MCP 服务；使用 `limited` 时，目标主机是否在 `allowed_hosts` 中。
3. 工具配置：`mcp_server_name` 是否与服务器名称匹配，所需工具是否启用，权限策略是否受运行时支持。
4. 凭证匹配：会话是否引用正确的 Vault，凭证的 `mcp_server_url` 是否与服务器 URL 匹配，令牌是否有效。
5. 确认等待：若停止原因是 `requires_action`，先处理确认事件；这并不表示连接失败。

完整确认与回传流程见[工具确认](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)。

## 后续步骤 [#后续步骤]

* [权限策略](/products/agentapi/development_guidelines/agentapi-agent-configuration/13593-agentapi-agent-configuration-permissions)：控制智能体工具和 MCP 工具何时运行。

* [事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)：发送事件、流式传输响应，并在执行过程中中断执行或补充任务要求。

* [支持的 MCP 服务器类型](/products/agentapi/api/13618-agentapi-api-conventions)：远程 MCP 服务器的传输要求。


# 权限策略 (/products/agentapi/development_guidelines/agentapi-agent-configuration/13593-agentapi-agent-configuration-permissions)



最近更新时间: 2026-10-13 15:31:22

权限策略控制云端运行时的工具执行方式：直接执行或等待应用确认。它适用于 AgentAPI 执行的内置工具和 MCP 工具；自定义工具由应用执行，其执行权限由应用管理。

创建智能体时，请根据运行时显式设置权限策略：

* `native` 支持自动执行和人工确认。
* `claudecode`、`codex` 的 MCP 工具必须使用 `always_allow`，不支持 AgentAPI 确认流程。

运行时差异见[运行时](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)和[工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)。

![工具调用的权限策略流程](/docs-assets/products/agentapi/development_guidelines/agentapi-agent-configuration/13593-agentapi-agent-configuration-permissions/FgBNbtJm3QDj23HMslc_JZAMTM98-3ffdcf308cb2.webp)

## 权限策略类型 [#权限策略类型]

| 策略             | 行为                                                                                                                                                         |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `always_allow` | 工具自动执行，无需确认。                                                                                                                                               |
| `always_ask`   | 工具调用前暂停会话，等待应用程序确认。确认流程请参阅[响应确认请求](/products/agentapi/development_guidelines/agentapi-agent-configuration/13593-agentapi-agent-configuration-permissions)。 |

MCP 工具集在 AgentAPI 中默认使用 `always_ask`。内置工具的默认策略由运行时决定；为避免行为差异，建议在 `default_config.permission_policy` 中显式设置策略。对于 `claudecode` 和 `codex`，MCP 工具必须配置为 `always_allow`。

权限策略控制已启用的工具何时运行。若要阻止某个工具被调用，请将它设为禁用。逐工具开关的运行时支持范围见[配置内置工具集](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)。

允许工具执行后，仍需配置[环境网络策略](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)和 [Vault](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13606-agentapi-data-and-integrations-vaults)，分别提供目标服务的网络访问权限和认证凭证。

## 为工具集设置策略 [#为工具集设置策略]

创建智能体时，在 `tools` 配置中设置权限策略；之后可以通过[更新智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)修改。已经创建的会话会保留创建时的工具配置，更新只对之后创建的会话生效。

> 说明
>
> * 完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)，从[七牛 MaaS 模型管理页](https://portal.qiniu.com/ai-inference/model)获取模型 ID，设置 `AGENTAPI_MODEL_ID`。
> * SDK 使用[SDK 客户端初始化](/products/agentapi/quick_start/13587-agentapi-quickstart)中的 `client`，通过扩展请求参数指定 `runtime`。
> * MCP 服务器 URL 替换为实际服务地址。

### 智能体工具集权限 [#智能体工具集权限]

创建智能体时，可以使用 `default_config.permission_policy` 为 `agent_toolset_20260401` 中的工具设置统一策略。下面的示例选择 `native` 运行时，并要求调用工具前确认：

cURL

```bash
agent=$(curl --request POST "$AGENTAPI_BASE_URL/v1/agents" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
    "name": "编程助手",
    "runtime": "native",
    "model": {"id": "$AGENTAPI_MODEL_ID"},
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": {
          "permission_policy": {"type": "always_ask"}
        }
      }
    ]
  }
EOF
)
```

Python

```python
import os

agent = client.beta.agents.create(
    name="编程助手",
    model={"id": os.environ["AGENTAPI_MODEL_ID"]},
    tools=[
        {
            "type": "agent_toolset_20260401",
            "default_config": {
                "permission_policy": {"type": "always_ask"},
            },
        },
    ],
    extra_body={"runtime": "native"},
)
```

TypeScript

````typescript
const params = {
  name: "编程助手",
  model: { id: process.env.AGENTAPI_MODEL_ID! },
  tools: [
    {
      type: "agent_toolset_20260401",
      default_config: {
        permission_policy: { type: "always_ask" }
      }
    }
  ]
} satisfies Parameters<typeof client.beta.agents.create>[0];
const agent = await client.beta.agents.create(params, {
  body: { ...params, runtime: "native" },
});
```csharp
```csharp
using System.Text.Json;
using System.Linq;
using System;
using Anthropic.Models.Beta.Agents;

var parameters = new AgentCreateParams
{
    Name = "编程助手",
    Model = new BetaManagedAgentsModelConfigParams { ID = Environment.GetEnvironmentVariable("AGENTAPI_MODEL_ID")! },
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
            DefaultConfig = new()
            {
                PermissionPolicy = new BetaManagedAgentsAlwaysAskPolicy { Type = "always_ask" },
            },
        },
    ],
};
var body = parameters.RawBodyData.ToDictionary(entry => entry.Key, entry => entry.Value);
body["runtime"] = JsonSerializer.SerializeToElement("native");
parameters = AgentCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body);
var agent = await client.Beta.Agents.Create(parameters);
````

Go

```go
import "github.com/anthropics/anthropic-sdk-go/option"
import "os"
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "编程助手",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: os.Getenv("AGENTAPI_MODEL_ID"),
	},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			DefaultConfig: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParams{
				PermissionPolicy: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnion{
					OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{
						Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk,
					},
				},
			},
		},
	}},
}, option.WithJSONSet("runtime", "native"))
if err != nil {
	panic(err)
}
_ = agent
```

Java

```java
import com.anthropic.core.JsonValue;
import com.anthropic.models.beta.agents.*;

var agent = client.beta().agents().create(
    AgentCreateParams.builder()
        .name("编程助手")
        .model(BetaManagedAgentsModelConfigParams.builder().id(System.getenv("AGENTAPI_MODEL_ID")).build())
        .addTool(
            BetaManagedAgentsAgentToolset20260401Params.builder()
                .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                .defaultConfig(
                    BetaManagedAgentsAgentToolsetDefaultConfigParams.builder()
                        .permissionPolicy(
                            BetaManagedAgentsAlwaysAskPolicy.builder()
                                .type(BetaManagedAgentsAlwaysAskPolicy.Type.ALWAYS_ASK)
                                .build()
                        )
                        .build()
                )
                .build()
        )
        .putAdditionalBodyProperty("runtime", JsonValue.from("native"))
        .build()
);
```

PHP

```php
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolsetDefaultConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAskPolicy;

$agent = $client->beta->agents->create(
    name: '编程助手',
    model: ['id' => getenv('AGENTAPI_MODEL_ID')],
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
            defaultConfig: BetaManagedAgentsAgentToolsetDefaultConfigParams::with(
                permissionPolicy: BetaManagedAgentsAlwaysAskPolicy::with(type: 'always_ask'),
            ),
        ),
    ],
    requestOptions: ['extraBodyParams' => ['runtime' => 'native']],
);
```

Ruby

```ruby
agent = client.beta.agents.create(
  name: "编程助手",
  model: {id: ENV.fetch("AGENTAPI_MODEL_ID")},
  tools: [
    {
      type: "agent_toolset_20260401",
      default_config: {
        permission_policy: {type: "always_ask"}
      }
    }
  ],
  request_options: {extra_body: {runtime: "native"}}
)
```

`default_config` 是可选的。省略时，内置工具的默认策略由所选运行时决定；如果应用程序依赖确认流程，请显式设置 `always_ask` 并选择支持该流程的 `native` 运行时。

### MCP 工具集权限 [#mcp-工具集权限]

MCP 工具集默认为 `always_ask`，新增工具也需要确认。自动执行受信任服务器的工具时，在 `mcp_toolset` 上将 `default_config.permission_policy` 设置为 `always_allow`。`claudecode` 和 `codex` 只支持 `always_allow`；需要确认时请选择 `native`。

`mcp_server_name` 必须与 `mcp_servers` 数组中某个服务器的 `name` 匹配。

此示例连接一个 GitHub MCP 服务器，并允许其工具无需确认即可运行：

cURL

```bash
agent=$(curl --request POST "$AGENTAPI_BASE_URL/v1/agents" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
    "name": "研发助手",
    "runtime": "codex",
    "model": {"id": "$AGENTAPI_MODEL_ID"},
    "mcp_servers": [
      {"type": "url", "name": "github", "url": "https://mcp.example.com/github"}
    ],
    "tools": [
      {"type": "agent_toolset_20260401"},
      {
        "type": "mcp_toolset",
        "mcp_server_name": "github",
        "default_config": {
          "permission_policy": {"type": "always_allow"}
        }
      }
    ]
  }
EOF
)
```

Python

```python
import os

agent = client.beta.agents.create(
    name="研发助手",
    model={"id": os.environ["AGENTAPI_MODEL_ID"]},
    mcp_servers=[
        {"type": "url", "name": "github", "url": "https://mcp.example.com/github"},
    ],
    tools=[
        {"type": "agent_toolset_20260401"},
        {
            "type": "mcp_toolset",
            "mcp_server_name": "github",
            "default_config": {
                "permission_policy": {"type": "always_allow"},
            },
        },
    ],
    extra_body={"runtime": "codex"},
)
```

TypeScript

````typescript
const params = {
  name: "研发助手",
  model: { id: process.env.AGENTAPI_MODEL_ID! },
  mcp_servers: [{ type: "url", name: "github", url: "https://mcp.example.com/github" }],
  tools: [
    { type: "agent_toolset_20260401" },
    {
      type: "mcp_toolset",
      mcp_server_name: "github",
      default_config: {
        permission_policy: { type: "always_allow" }
      }
    }
  ]
} satisfies Parameters<typeof client.beta.agents.create>[0];
const agent = await client.beta.agents.create(params, {
  body: { ...params, runtime: "codex" },
});
```csharp
```csharp
using System.Text.Json;
using System.Linq;
using System;
using Anthropic.Models.Beta.Agents;

var parameters = new AgentCreateParams
{
    Name = "研发助手",
    Model = new BetaManagedAgentsModelConfigParams { ID = Environment.GetEnvironmentVariable("AGENTAPI_MODEL_ID")! },
    McpServers =
    [
        new()
        {
            Type = BetaManagedAgentsUrlMcpServerParamsType.Url,
            Name = "github",
            Url = "https://mcp.example.com/github",
        },
    ],
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
        },
        new BetaManagedAgentsMcpToolsetParams
        {
            Type = BetaManagedAgentsMcpToolsetParamsType.McpToolset,
            McpServerName = "github",
            DefaultConfig = new()
            {
                PermissionPolicy = new BetaManagedAgentsAlwaysAllowPolicy { Type = "always_allow" },
            },
        },
    ],
};
var body = parameters.RawBodyData.ToDictionary(entry => entry.Key, entry => entry.Value);
body["runtime"] = JsonSerializer.SerializeToElement("codex");
parameters = AgentCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body);
var agent = await client.Beta.Agents.Create(parameters);
````

Go

```go
import "github.com/anthropics/anthropic-sdk-go/option"
import "os"
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "研发助手",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: os.Getenv("AGENTAPI_MODEL_ID"),
	},
	MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{
		Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,
		Name: "github",
		URL:  "https://mcp.example.com/github",
	}},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{
		{
			OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
				Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			},
		},
		{
			OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{
				Type:          anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset,
				MCPServerName: "github",
				DefaultConfig: anthropic.BetaManagedAgentsMCPToolsetDefaultConfigParams{
					PermissionPolicy: anthropic.BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnion{
						OfAlwaysAllow: &anthropic.BetaManagedAgentsAlwaysAllowPolicyParam{
							Type: anthropic.BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow,
						},
					},
				},
			},
		},
	},
}, option.WithJSONSet("runtime", "codex"))
if err != nil {
	panic(err)
}
_ = agent
```

Java

```java
import com.anthropic.core.JsonValue;
import com.anthropic.models.beta.agents.*;

var agent = client.beta().agents().create(
    AgentCreateParams.builder()
        .name("研发助手")
        .model(BetaManagedAgentsModelConfigParams.builder().id(System.getenv("AGENTAPI_MODEL_ID")).build())
        .addMcpServer(
            BetaManagedAgentsUrlMcpServerParams.builder()
                .type(BetaManagedAgentsUrlMcpServerParams.Type.URL)
                .name("github")
                .url("https://mcp.example.com/github")
                .build()
        )
        .addTool(
            BetaManagedAgentsAgentToolset20260401Params.builder()
                .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                .build()
        )
        .addTool(
            BetaManagedAgentsMcpToolsetParams.builder()
                .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET)
                .mcpServerName("github")
                .defaultConfig(
                    BetaManagedAgentsMcpToolsetDefaultConfigParams.builder()
                        .permissionPolicy(
                            BetaManagedAgentsAlwaysAllowPolicy.builder()
                                .type(BetaManagedAgentsAlwaysAllowPolicy.Type.ALWAYS_ALLOW)
                                .build()
                        )
                        .build()
                )
                .build()
        )
        .putAdditionalBodyProperty("runtime", JsonValue.from("codex"))
        .build()
);
```

PHP

```php
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAllowPolicy;
use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetDefaultConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetParams;
use Anthropic\Beta\Agents\BetaManagedAgentsURLMCPServerParams;

$agent = $client->beta->agents->create(
    name: '研发助手',
    model: ['id' => getenv('AGENTAPI_MODEL_ID')],
    mcpServers: [
        BetaManagedAgentsURLMCPServerParams::with(
            type: 'url',
            name: 'github',
            url: 'https://mcp.example.com/github',
        ),
    ],
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
        ),
        BetaManagedAgentsMCPToolsetParams::with(
            type: 'mcp_toolset',
            mcpServerName: 'github',
            defaultConfig: BetaManagedAgentsMCPToolsetDefaultConfigParams::with(
                permissionPolicy: BetaManagedAgentsAlwaysAllowPolicy::with(type: 'always_allow'),
            ),
        ),
    ],
    requestOptions: ['extraBodyParams' => ['runtime' => 'codex']],
);
```

Ruby

```ruby
agent = client.beta.agents.create(
  name: "研发助手",
  model: {id: ENV.fetch("AGENTAPI_MODEL_ID")},
  mcp_servers: [
    {type: "url", name: "github", url: "https://mcp.example.com/github"}
  ],
  tools: [
    {type: "agent_toolset_20260401"},
    {
      type: "mcp_toolset",
      mcp_server_name: "github",
      default_config: {
        permission_policy: {type: "always_allow"}
      }
    }
  ],
  request_options: {extra_body: {runtime: "codex"}}
)
```

## 覆盖单个工具的策略 [#覆盖单个工具的策略]

在 `native` 运行时中，使用 `configs` 数组覆盖单个工具的默认值。智能体工具集的 `name` 值列于[可用工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)中。此示例默认允许完整的智能体工具集，但要求在运行任何 bash 命令之前进行确认：

cURL

```bash
tools='[
  {
    "type": "agent_toolset_20260401",
    "default_config": {
      "permission_policy": {"type": "always_allow"}
    },
    "configs": [
      {
        "name": "bash",
        "permission_policy": {"type": "always_ask"}
      }
    ]
  }
]'
```

Python

```python
tools = [
    {
        "type": "agent_toolset_20260401",
        "default_config": {
            "permission_policy": {"type": "always_allow"},
        },
        "configs": [
            {
                "name": "bash",
                "permission_policy": {"type": "always_ask"},
            },
        ],
    },
]
```

TypeScript

````typescript
const tools = [
  {
    type: "agent_toolset_20260401",
    default_config: {
      permission_policy: { type: "always_allow" }
    },
    configs: [
      {
        name: "bash",
        permission_policy: { type: "always_ask" }
      }
    ]
  }
] satisfies Anthropic.Beta.AgentCreateParams["tools"];
```csharp
```csharp
using Anthropic.Models.Beta.Agents;
using Tool = Anthropic.Models.Beta.Agents.Tool;

Tool[] tools =
[
    new BetaManagedAgentsAgentToolset20260401Params
    {
        Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
        DefaultConfig = new()
        {
            PermissionPolicy = new BetaManagedAgentsAlwaysAllowPolicy { Type = "always_allow" },
        },
        Configs =
        [
            new BetaManagedAgentsBashToolConfigParams
            {
                PermissionPolicy = new BetaManagedAgentsAlwaysAskPolicy { Type = "always_ask" },
            },
        ],
    },
];
````

Go

```go
tools := []anthropic.BetaAgentNewParamsToolUnion{{
	OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
		Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
		DefaultConfig: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParams{
			PermissionPolicy: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnion{
				OfAlwaysAllow: &anthropic.BetaManagedAgentsAlwaysAllowPolicyParam{
					Type: anthropic.BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow,
				},
			},
		},
		Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{
			OfBash: &anthropic.BetaManagedAgentsBashToolConfigParams{
				PermissionPolicy: anthropic.BetaManagedAgentsBashToolConfigParamsPermissionPolicyUnion{
					OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{
						Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk,
					},
				},
			},
		}},
	},
}}
_ = tools
```

Java

```java
import com.anthropic.models.beta.agents.*;
import java.util.List;

var tools = List.of(
    AgentCreateParams.Tool.ofAgentToolset20260401(
        BetaManagedAgentsAgentToolset20260401Params.builder()
            .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
            .defaultConfig(
                BetaManagedAgentsAgentToolsetDefaultConfigParams.builder()
                    .permissionPolicy(
                        BetaManagedAgentsAlwaysAllowPolicy.builder()
                            .type(BetaManagedAgentsAlwaysAllowPolicy.Type.ALWAYS_ALLOW)
                            .build()
                    )
                    .build()
            )
            .addConfig(
                BetaManagedAgentsBashToolConfigParams.builder()
                    .permissionPolicy(
                        BetaManagedAgentsAlwaysAskPolicy.builder()
                            .type(BetaManagedAgentsAlwaysAskPolicy.Type.ALWAYS_ASK)
                            .build()
                    )
                    .build()
            )
            .build()
    )
);
```

PHP

```php
use Anthropic\Beta\Agents\BetaManagedAgentsBashToolConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolsetDefaultConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAllowPolicy;
use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAskPolicy;

$tools = [
    BetaManagedAgentsAgentToolset20260401Params::with(
        type: 'agent_toolset_20260401',
        defaultConfig: BetaManagedAgentsAgentToolsetDefaultConfigParams::with(
            permissionPolicy: BetaManagedAgentsAlwaysAllowPolicy::with(type: 'always_allow'),
        ),
        configs: [
            BetaManagedAgentsBashToolConfigParams::with(
                permissionPolicy: BetaManagedAgentsAlwaysAskPolicy::with(type: 'always_ask'),
            ),
        ],
    ),
];
```

Ruby

```ruby
tools = [
  {
    type: "agent_toolset_20260401",
    default_config: {
      permission_policy: {type: "always_allow"}
    },
    configs: [
      {
        name: "bash",
        permission_policy: {type: "always_ask"}
      }
    ]
  }
]
```

在智能体创建请求中传递此 `tools` 配置。MCP 工具集支持相同的按工具覆盖，其中 `name` 设置为 MCP 服务器报告的工具名称。请参阅[配置哪些 MCP 工具可用](/products/agentapi/development_guidelines/agentapi-agent-configuration/13592-agentapi-agent-configuration-mcp)。

`claudecode`、`codex` 不应用这些逐工具的确认策略。需要在 AgentAPI 中等待应用确认时，请选择 `native`。

## 响应确认请求 [#响应确认请求]

Native 的 `always_ask` 调用会以 `requires_action` 等待应用审批。批准或拒绝时，必须使用实际阻塞调用的事件 ID；消息结构、批量确认与恢复消费见[工具确认流程](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)。

## 自定义工具 [#自定义工具]

权限策略不适用于自定义工具。当智能体调用自定义工具时，应用会收到 `agent.custom_tool_use` 事件，并负责在发回 `user.custom_tool_result` 之前决定是否执行它。有关完整流程，请参阅[事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)。

## 后续步骤 [#后续步骤]

* [技能](/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills)：为智能体附加可复用的、基于文件系统的专业知识，以支持特定领域的工作流程。

* [事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)：发送事件、流式传输响应，并在执行过程中中断执行或补充任务要求。


# Agent Skills (/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills)



最近更新时间: 2026-10-13 15:31:29

Agent Skills 是基于文件系统的可复用技能包，为云端智能体提供领域知识和操作步骤。附加技能会占用会话上下文，请仅选择当前任务需要的技能。

AgentAPI 支持上传自定义技能后通过智能体的 `skills` 数组附加，也支持 `claudecode`、`codex` 从挂载的 GitHub 仓库发现技能。`native` 只使用显式附加的自定义技能。

![Agent Skills 进入云端运行的两种方式](/docs-assets/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills/Flc9jwigHC6J7iWcY2VhTZB6wUgR-2ffb015c3af6.webp)

> 说明
>
> 当前 AgentAPI 没有内置的供应商技能目录。虽然 API 为兼容请求结构接受 `type: "anthropic"`，但这类技能在执行时无法解析。请上传自定义技能，并使用 `type: "custom"`。

## 运行时差异 [#运行时差异]

技能的来源和加载方式取决于智能体的 `runtime`：

| 运行时          | 显式附加的自定义技能                                   | GitHub 仓库中的技能              |
| ------------ | -------------------------------------------- | -------------------------- |
| `native`     | AgentAPI 在云端按需加载 `SKILL.md`，并提供技能包中的辅助文件。    | 不自动发现；请先上传并附加技能。           |
| `claudecode` | AgentAPI 会在云端运行环境启动前准备技能目录，供 Claude Code 使用。 | 由 Claude Code 的原生技能发现能力处理。 |
| `codex`      | AgentAPI 会在云端运行环境启动前准备技能目录，供 Codex 使用。       | 由 Codex 的原生技能发现能力处理。       |

自定义技能的主体是一个包含 `SKILL.md` 的目录。要编写技能，请在 `SKILL.md` 的 YAML frontmatter 中提供 `name` 和 `description`，再加入说明正文、脚本和参考文件。

## 编写技能包 [#编写技能包]

技能适合保存重复使用的工作方法，例如代码审查规则、报表分析步骤或文档格式要求。在 `description` 中说明适用场景和任务目标，在正文中编写具体操作步骤；较长的参考资料和脚本存放在包内的辅助文件中，并在正文中引用。

技能提供指令和文件，实际操作仍依赖智能体的工具以及会话环境。例如，技能中的 Python 脚本需要代码执行能力和相应依赖；涉及业务系统时，还需要 MCP 或自定义工具。请同时检查[工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)和[云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)配置。

最小的 `SKILL.md` 示例：

```md
---
name: code-review
description: 审查代码变更并输出可执行的修改建议。
---

# 代码审查

先检查变更范围，再根据项目约定给出问题、风险和修改建议。
```

## 创建自定义技能 [#创建自定义技能]

自定义技能可以打包成 zip 压缩包上传，也可以通过技能 API 上传一个或多个文件。创建技能会返回 `skill_*` ID，之后在智能体的 `skills` 数组中引用它即可。上传的文件必须位于同一个顶层目录下，且该目录根部必须包含 `SKILL.md`。

请先完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)。以下示例假定已将技能目录打包为 `example_skill.zip`，压缩包内保留顶层目录，例如 `code-review/SKILL.md`。技能包直接上传到 `/v1/skills`，无需先上传到 Files API。

以下示例省略了可选的 `display_title` 字段，因此技能的显示标题使用 `SKILL.md` frontmatter 中的 `name`。

| 限制                         | 当前值                           |
| -------------------------- | ----------------------------- |
| 每个技能版本的文件数                 | 默认最多 200 个，可由服务配置调整           |
| 每个技能版本的文件总大小               | 默认最多 8 MiB，按解压后的文件计算，可由服务配置调整 |
| 单个 multipart 请求大小          | 最多 32 MiB，包含请求封装，不随技能包限制调整    |
| `native` 加载的 `SKILL.md` 大小 | 最多 128 KiB，内容必须为 UTF-8        |

cURL

```bash
skill=$(curl --request POST -fsSL "$AGENTAPI_BASE_URL/v1/skills" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --form 'files=@example_skill.zip;filename=example_skill.zip;type=application/zip')
SKILL_ID=$(jq -er '.id' <<<"$skill")
```

Python

```python
import os
from pathlib import Path

from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["AGENTAPI_API_KEY"],
    base_url=os.environ["AGENTAPI_BASE_URL"],
)

skill = client.beta.skills.create(
    files=[
        (
            "example_skill.zip",
            Path("example_skill.zip").read_bytes(),
            "application/zip",
        )
    ],
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")
```

TypeScript

````typescript
import Anthropic from "@anthropic-ai/sdk";
import { toFile } from "@anthropic-ai/sdk";
import fs from "node:fs";

const client = new Anthropic({
  apiKey: process.env.AGENTAPI_API_KEY!,
  baseURL: process.env.AGENTAPI_BASE_URL,
});

const skill = await client.beta.skills.create({
  files: [await toFile(fs.createReadStream("example_skill.zip"), "example_skill.zip")]
});

console.log(`Created skill: ${skill.id}`);
console.log(`Latest version: ${skill.latest_version}`);
```csharp
```csharp
using System;
using System.IO;
using System.Net.Http.Headers;
using Anthropic;
using Anthropic.Core;
using Anthropic.Models.Beta.Skills;

var client = new AnthropicClient(new ClientOptions
{
    ApiKey = Environment.GetEnvironmentVariable("AGENTAPI_API_KEY"),
    BaseUrl = Environment.GetEnvironmentVariable("AGENTAPI_BASE_URL"),
});

await using var skillFile = File.OpenRead("example_skill.zip");
var parameters = new SkillCreateParams {
    Files = [
        new BinaryContent {
            Stream = skillFile,
            FileName = "example_skill.zip",
            ContentType = new MediaTypeHeaderValue("application/zip"),
        },
    ],
};

var skill = await client.Beta.Skills.Create(parameters);

Console.WriteLine($"Created skill: {skill.ID}");
Console.WriteLine($"Latest version: {skill.LatestVersion}");
````

Go

```go
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"os"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/option"
)

func main() {
	client := anthropic.NewClient(
		option.WithoutEnvironmentDefaults(),
		option.WithBaseURL(os.Getenv("AGENTAPI_BASE_URL")),
		option.WithAPIKey(os.Getenv("AGENTAPI_API_KEY")),
	)

	zipFile, err := os.Open("example_skill.zip")
	if err != nil {
		log.Fatal(err)
	}
	defer zipFile.Close()

	skill, err := client.Beta.Skills.New(context.TODO(), anthropic.BetaSkillNewParams{
		Files: []io.Reader{anthropic.File(zipFile, "example_skill.zip", "application/zip")},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Created skill: %s\n", skill.ID)
	fmt.Printf("Latest version: %s\n", skill.LatestVersion)
}
```

Java

```java
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.skills.Skill;
import com.anthropic.models.beta.skills.SkillCreateParams;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;

void main() throws IOException {
    AnthropicClient client = AnthropicOkHttpClient.builder()
        .apiKey(System.getenv("AGENTAPI_API_KEY"))
        .baseUrl(System.getenv("AGENTAPI_BASE_URL"))
        .build();

    SkillCreateParams params = SkillCreateParams.builder()
        .addFile(MultipartField.<InputStream>builder()
            .value(Files.newInputStream(Path.of("example_skill.zip")))
            .filename("example_skill.zip")
            .contentType("application/zip")
            .build())
        .build();

    Skill skill = client.beta().skills().create(params);

    IO.println("Created skill: " + skill.id());
    IO.println("Latest version: " + skill.latestVersion());
}
```

PHP

```php
<?php

use Anthropic\Client;
use Anthropic\Core\FileParam;

$client = new Client(
    apiKey: getenv('AGENTAPI_API_KEY') ?: throw new RuntimeException('AGENTAPI_API_KEY is required'),
    baseUrl: getenv('AGENTAPI_BASE_URL') ?: throw new RuntimeException('AGENTAPI_BASE_URL is required'),
);

$skill = $client->beta->skills->create(
    files: [
        FileParam::fromResource(fopen('example_skill.zip', 'r')),
    ],
);

echo "Created skill: {$skill->id}\n";
echo "Latest version: {$skill->latestVersion}\n";
```

Ruby

```ruby
require "anthropic"

client = Anthropic::Client.new(
  api_key: ENV.fetch("AGENTAPI_API_KEY"),
  base_url: ENV.fetch("AGENTAPI_BASE_URL")
)

skill = client.beta.skills.create(
  files: [
    File.open("example_skill.zip", "rb")
  ]
)

puts "Created skill: #{skill.id}"
puts "Latest version: #{skill.latest_version}"
```

创建完成后，可通过以下接口管理技能和版本。

## 管理技能和版本 [#管理技能和版本]

Portal 的 Skill 列表支持按名称或 ID 搜索。关键词会去除首尾空白，按字面量包含关系匹配，并在统计总数和分页前执行。对应接口为 `GET /portal/v1/skills?page_index=1&q=关键词`，`q` 必须与 `page_index` 一起使用；公开的 `GET /v1/skills` 不接受该参数。

技能和技能版本分别有独立的资源接口：

| 操作      | API                                                                                       |
| ------- | ----------------------------------------------------------------------------------------- |
| 列出或查看技能 | `GET /v1/skills`、`GET /v1/skills/{skill_id}`                                              |
| 删除技能    | `DELETE /v1/skills/{skill_id}`                                                            |
| 创建版本    | `POST /v1/skills/{skill_id}/versions`，请求格式与创建技能相同                                         |
| 列出或查看版本 | `GET /v1/skills/{skill_id}/versions`、`GET /v1/skills/{skill_id}/versions/{version}`       |
| 下载完整技能包 | `GET /v1/skills/{skill_id}/versions/{version}/content`，请求头设置 `accept: application/zip`    |
| 查看包内文件  | `GET /v1/skills/{skill_id}/versions/{version}/files`，或通过 `/files/content?path=...` 下载单个文件 |
| 删除版本    | `DELETE /v1/skills/{skill_id}/versions/{version}`                                         |

版本号由 AgentAPI 在上传时生成：

* 省略 `version` 或传入 `latest`：使用当前最新的有效版本。
* 删除最新版本：`latest_version` 更新为最近的有效版本。
* 已删除的技能或版本：不能再附加到智能体。

需要复现某次任务或分阶段发布技能时，请保存上传响应中的版本号并明确引用它。智能体版本和技能版本是两套独立的版本：把智能体固定到某个版本，不能把其中的 `latest` 技能引用变成固定技能版本。

> 最新版本的生效范围
>
> `native` 在每个新轮次重新解析 `latest`。CLI 运行时复用已有沙箱时，不会重新初始化技能文件，因此已有会话不保证立即使用新版本。需要确定技能内容时，应固定版本并创建新会话。

## 将技能附加到智能体 [#将技能附加到智能体]

> 说明
>
> 挂载更多技能会增加会话沙箱启动所需的时间。请仅附加每个智能体完成其任务所需的技能。

`skills` 数组中的每个条目使用以下字段：

| 字段         | 描述                                                      |
| ---------- | ------------------------------------------------------- |
| `type`     | 当前使用 `custom`。`anthropic` 仅为请求结构兼容而保留，AgentAPI 执行时无法解析。 |
| `skill_id` | 自定义技能标识符，使用创建技能时返回的 `skill_*` ID。                       |
| `version`  | 可固定到某个版本，也可以使用 `latest`；省略时使用当前最新版本。                    |

一个智能体最多附加 20 个技能。以下示例使用上传响应中的技能 ID，选择 `native` 运行时，并引用最新有效技能版本。请先从[七牛 MaaS 模型管理页](https://portal.qiniu.com/ai-inference/model)选择可用模型，设置 `AGENTAPI_MODEL_ID`。如需固定技能版本，将 `latest` 替换为上传响应中的版本号。

cURL

```bash
agent=$(curl --request POST "$AGENTAPI_BASE_URL/v1/agents" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
  "name": "代码审查助手",
  "runtime": "native",
  "model": {"id": "$AGENTAPI_MODEL_ID"},
  "system": "你是一名严谨的代码审查助手，请按技能中的检查项审查代码。",
  "skills": [
    {"type": "custom", "skill_id": "$SKILL_ID", "version": "latest"}
  ]
}
EOF
)
```

Python

```python
import os

agent = client.beta.agents.create(
    name="代码审查助手",
    model={"id": os.environ["AGENTAPI_MODEL_ID"]},
    system="你是一名严谨的代码审查助手，请按技能中的检查项审查代码。",
    skills=[
        {
            "type": "custom",
            "skill_id": skill.id,
            "version": "latest",
        },
    ],
    extra_body={"runtime": "native"},
)
```

TypeScript

````typescript
const params = {
  name: "代码审查助手",
  model: { id: process.env.AGENTAPI_MODEL_ID! },
  system: "你是一名严谨的代码审查助手，请按技能中的检查项审查代码。",
  skills: [
    {
      type: "custom",
      skill_id: skill.id,
      version: "latest"
    }
  ]
} satisfies Parameters<typeof client.beta.agents.create>[0];
const agent = await client.beta.agents.create(params, {
  body: { ...params, runtime: "native" },
});
```csharp
```csharp
using System;
using System.Linq;
using System.Text.Json;
using Anthropic;
using Anthropic.Core;
using Anthropic.Models.Beta.Agents;

var parameters = new AgentCreateParams
{
    Name = "代码审查助手",
    Model = new BetaManagedAgentsModelConfigParams { ID = Environment.GetEnvironmentVariable("AGENTAPI_MODEL_ID")! },
    System = "你是一名严谨的代码审查助手，请按技能中的检查项审查代码。",
    Skills =
    [
        new BetaManagedAgentsCustomSkillParams { Type = BetaManagedAgentsCustomSkillParamsType.Custom, SkillID = skill.ID, Version = "latest" },
    ],
};
var body = parameters.RawBodyData.ToDictionary(entry => entry.Key, entry => entry.Value);
body["runtime"] = JsonSerializer.SerializeToElement("native");
parameters = AgentCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body);
var agent = await client.Beta.Agents.Create(parameters);
````

Go

```go
import "os"
import "github.com/anthropics/anthropic-sdk-go/option"

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "代码审查助手",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: os.Getenv("AGENTAPI_MODEL_ID"),
	},
	System: anthropic.String("你是一名严谨的代码审查助手，请按技能中的检查项审查代码。"),
	Skills: []anthropic.BetaManagedAgentsSkillParamsUnion{
		{OfCustom: &anthropic.BetaManagedAgentsCustomSkillParams{
			SkillID: skill.ID,
			Type:    anthropic.BetaManagedAgentsCustomSkillParamsTypeCustom,
			Version: anthropic.String("latest"),
		}},
	},
}, option.WithJSONSet("runtime", "native"))
if err != nil {
	panic(err)
}
_ = agent
```

Java

```java
import com.anthropic.core.JsonValue;
import com.anthropic.models.beta.agents.*;

var agent = client.beta().agents().create(
    AgentCreateParams.builder()
        .name("代码审查助手")
        .model(BetaManagedAgentsModelConfigParams.builder().id(System.getenv("AGENTAPI_MODEL_ID")).build())
        .system("你是一名严谨的代码审查助手，请按技能中的检查项审查代码。")
        .addSkill(
            BetaManagedAgentsCustomSkillParams.builder()
                .type(BetaManagedAgentsCustomSkillParams.Type.CUSTOM)
                .skillId(skill.id())
                .version("latest")
                .build()
        )
        .putAdditionalBodyProperty("runtime", JsonValue.from("native"))
        .build()
);
```

PHP

```php
$agent = $client->beta->agents->create(
    name: '代码审查助手',
    model: ['id' => getenv('AGENTAPI_MODEL_ID')],
    system: '你是一名严谨的代码审查助手，请按技能中的检查项审查代码。',
    skills: [
        ['type' => 'custom', 'skillID' => $skill->id, 'version' => 'latest'],
    ],
    requestOptions: ['extraBodyParams' => ['runtime' => 'native']],
);
```

Ruby

```ruby
agent = client.beta.agents.create(
  name: "代码审查助手",
  model: {id: ENV.fetch("AGENTAPI_MODEL_ID")},
  system_: "你是一名严谨的代码审查助手，请按技能中的检查项审查代码。",
  skills: [
    {type: "custom", skill_id: skill.id, version: "latest"}
  ],
  request_options: {extra_body: {runtime: "native"}}
)
```

## 从 GitHub 仓库加载技能 [#从-github-仓库加载技能]

挂载 GitHub 仓库后，`claudecode` 和 `codex` 可以按各自运行时的规则发现仓库中的 Skill。AgentAPI 不扫描这些目录。

`native` 不会自动发现仓库中的 Skill。使用 `native` 时，请先上传 Skill，再通过智能体的 `skills` 字段引用。

> 说明
>
> 仓库中的 Skill 会作为智能体指令加载。请只挂载可信仓库。

仓库挂载方式参阅[访问 GitHub](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13604-agentapi-data-and-integrations-github)。

## 后续步骤 [#后续步骤]

* [云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)：为会话自定义云沙箱。

* [创建自定义技能](/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills)：上传包含 `SKILL.md` 的自定义技能包，并在智能体中引用它。

* [文件](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)：上传文件并在会话资源中引用。

* [通过 API 构建](/products/agentapi/quick_start/13587-agentapi-quickstart)：了解如何创建智能体、云端环境和会话，并运行云端任务。


# 附加和下载文件 (/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)



最近更新时间: 2026-10-13 15:31:44

文件交付包含两个结果：任务能在云端沙箱中读取输入材料，应用能下载最终产物。Files API 保存文件对象，会话资源负责把输入文件挂载到沙箱；沙箱中的任意文件不会自动成为可下载的产物。

以 CSV 分析任务为例，约定输入路径 `/data.csv` 与报告文件 `report.md`，再按任务阶段操作：

1. 上传 CSV，保存源文件的 `file_id`。
2. 创建会话并挂载文件，指定沙箱内的读取路径。
3. 向会话发送分析要求，让智能体读取数据并把报告写入 `/mnt/session/outputs/report.md`。
4. 本轮执行结束后，列出并下载会话文件，确认预期产物已经收集。

任务中途收到新的数据，可补充会话文件。报告下载并验收后，再清理文件对象。会话创建和消息发送见[会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)。

![File Object 的数据来源与生命周期](/docs-assets/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files/FlVhNRdts2sP9ww5zSUdbOlSKxg7-411aeaeade7d.webp)

同一份数据上传、挂载和生成输出时对应不同文件对象。保留策略需要区分这些对象，不能仅按沙箱路径判断：

| 文件对象   | 如何产生                               | `scope_id` | 沙箱中删除路径 | 归档会话 | 删除会话 |
| ------ | ---------------------------------- | ---------- | ------- | ---- | ---- |
| 上传源文件  | `POST /v1/files`                   | 无          | 不适用     | 不受影响 | 不受影响 |
| 会话挂载副本 | 将源文件加入 `resources`                 | 会话 ID      | 不影响文件对象 | 保留   | 删除   |
| 会话输出文件 | 智能体写入 `/mnt/session/outputs/` 后被收集 | 会话 ID      | 不影响文件对象 | 保留   | 删除   |

## 准备任务输入 [#准备任务输入]

先确认输入格式能由所选运行时、模型或工具处理，再上传材料并确定读取路径。需要分析多份数据时，把每个文件及其用途写入任务要求，避免智能体自行猜测。

### 判断材料能否处理 [#判断材料能否处理]

Files API 将文件按原始字节保存，不限制扩展名。智能体是否能理解或处理某种格式取决于所选运行时、模型和已安装工具。常见输入包括：

* 源代码（`.py`、`.js`、`.ts`、`.go`、`.rs` 等）
* 数据文件（`.csv`、`.json`、`.xml`、`.yaml`）
* 文档（`.txt`、`.md`）
* 归档文件（`.zip`、`.tar.gz`）
* 图片、PDF 和其他二进制文件

### 上传源材料 [#上传源材料]

完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)后，上传本地 `data.csv`，保存返回的 `file_id`，供会话引用。此时文件仍只是源材料，尚未进入任何会话。以下 SDK 示例沿用[SDK 客户端初始化](/products/agentapi/quick_start/13587-agentapi-quickstart)中的 `client`。

cURL

```bash
file=$(curl --request POST "$AGENTAPI_BASE_URL/v1/files" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --form "file=@data.csv")
file_id=$(jq -er '.id' <<<"${file}")
printf 'File ID: %s\n' "${file_id}"
```

Python

```python
file = client.beta.files.upload(file=Path("data.csv"))
print(f"File ID: {file.id}")
```

TypeScript

````typescript
const file = await client.beta.files.upload({
  file: await toFile(readFile("data.csv"), "data.csv", { type: "text/csv" }),
});
console.log(`File ID: ${file.id}`);
```csharp
```csharp
await using var stream = File.OpenRead(csvPath);
var file = await client.Beta.Files.Upload(new() { File = stream });
Console.WriteLine($"File ID: {file.ID}");
````

Go

```go
csvFile, err := os.Open("data.csv")
if err != nil {
	panic(err)
}
defer csvFile.Close()

file, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
	File: csvFile,
})
if err != nil {
	panic(err)
}
fmt.Printf("File ID: %s\n", file.ID)
```

Java

```java
var file = client.beta().files().upload(
    FileUploadParams.builder().file(dataCsv).build()
);
IO.println("File ID: " + file.id());
```

PHP

```php
$file = $client->beta->files->upload(
    file: FileParam::fromResource(fopen($csvPath, 'r'), filename: 'data.csv', contentType: 'text/csv'),
);
echo "File ID: {$file->id}\n";
```

Ruby

```ruby
file = client.beta.files.upload(file: Pathname(csv_path))
puts "File ID: #{file.id}"
```

### 约定会话读取路径 [#约定会话读取路径]

创建[智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)和[云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)后，用会话的 `resources` 引用源材料。以下示例把 CSV 挂载到 `/data.csv`；后续任务要求应使用同一路径，而不是本地上传路径。

> 说明
>
> 可省略 `mount_path`，此时读取路径为 `/mnt/session/uploads/<file_id>`。显式指定路径便于在任务要求中定位材料。

cURL

```bash
session=$(
  jq -n \
    --arg agent_id "${agent_id}" \
    --arg environment_id "${environment_id}" \
    --arg file_id "${file_id}" \
    '{
      agent: $agent_id,
      environment_id: $environment_id,
      resources: [
        {
          type: "file",
          file_id: $file_id,
          mount_path: "/data.csv"
        }
      ]
    }' | curl --fail-with-body -sS -H "x-api-key: $AGENTAPI_API_KEY" "$AGENTAPI_BASE_URL/v1/sessions" -H "content-type: application/json" --data @-
)
session_id=$(jq -er '.id' <<<"${session}")
```

Python

```python
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": file.id,
            "mount_path": "/data.csv",
        },
    ],
)
```

TypeScript

````typescript
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "file",
      file_id: file.id,
      mount_path: "/data.csv",
    },
  ],
});
```csharp
```csharp
var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    Resources =
    [
        new BetaManagedAgentsFileResourceParams
        {
            Type = "file",
            FileID = file.ID,
            MountPath = "/data.csv",
        },
    ],
});
````

Go

```go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfString: anthropic.String(agent.ID),
	},
	EnvironmentID: environment.ID,
	Resources: []anthropic.BetaSessionNewParamsResourceUnion{{
		OfFile: &anthropic.BetaManagedAgentsFileResourceParams{
			Type:      anthropic.BetaManagedAgentsFileResourceParamsTypeFile,
			FileID:    file.ID,
			MountPath: anthropic.String("/data.csv"),
		},
	}},
})
if err != nil {
	panic(err)
}
```

Java

```java
var session = client.beta().sessions().create(
    SessionCreateParams.builder()
        .agent(agent.id())
        .environmentId(environment.id())
        .addResource(
            BetaManagedAgentsFileResourceParams.builder()
                .type(BetaManagedAgentsFileResourceParams.Type.FILE)
                .fileId(file.id())
                .mountPath("/data.csv")
                .build()
        )
        .build()
);
```

PHP

```php
$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
    resources: [
        BetaManagedAgentsFileResourceParams::with(
            type: 'file',
            fileID: $file->id,
            mountPath: '/data.csv',
        ),
    ],
);
```

Ruby

```ruby
session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "file",
      file_id: file.id,
      mount_path: "/data.csv"
    }
  ]
)
```

使用上述 `mount_path`，智能体将在 `/data.csv` 读取该文件。`mount_path` 是沙箱内的绝对路径，不会自动拼接 uploads 目录；省略时才使用 `/mnt/session/uploads/<file_id>`。请参阅文件路径。

AgentAPI 会为会话中的只读副本创建新的 `file_id`。删除原始上传文件不会影响已经挂载到会话中的副本。

### 区分输入路径与输出路径 [#区分输入路径与输出路径]

> 说明
>
> 挂载到沙箱中的文件是只读副本。智能体可以读取它们，但无法修改原始上传的文件。若要使用修改后的版本，智能体会将其写入沙箱内的新路径。

* `mount_path` 是沙箱内的绝对路径：`/data.csv` 会挂载到 `/data.csv`
* 如果省略 `mount_path`，文件将被放置在 `/mnt/session/uploads/<file_id>`
* 父目录会自动创建
* 路径应为绝对路径（以 `/` 开头）
* 智能体写入 `/mnt/session/outputs/` 的文件可通过 Files API 获取，且限定于该会话范围内；请参阅列出和下载会话文件

### 为一项任务准备多份材料 [#为一项任务准备多份材料]

例如同时分析原始数据和参考数据时，为每份材料添加一个 `resources` 条目，并分别指定读取路径：

cURL

```json
"resources": [
  { "type": "file", "file_id": "file_abc123", "mount_path": "/data.csv" },
  { "type": "file", "file_id": "file_def456", "mount_path": "/config.json" },
  { "type": "file", "file_id": "file_ghi789", "mount_path": "/src/main.py" }
]
```

Python

```python
resources = [
    {"type": "file", "file_id": "file_abc123", "mount_path": "/data.csv"},
    {"type": "file", "file_id": "file_def456", "mount_path": "/config.json"},
    {"type": "file", "file_id": "file_ghi789", "mount_path": "/src/main.py"},
]
```

TypeScript

````typescript
resources: [
  { type: "file", file_id: "file_abc123", mount_path: "/data.csv" },
  { type: "file", file_id: "file_def456", mount_path: "/config.json" },
  { type: "file", file_id: "file_ghi789", mount_path: "/src/main.py" }
]
```csharp
```csharp
using Anthropic.Models.Beta.Sessions;

var resources = new[]
{
    new BetaManagedAgentsFileResourceParams { Type = BetaManagedAgentsFileResourceParamsType.File, FileID = "file_abc123", MountPath = "/data.csv" },
    new BetaManagedAgentsFileResourceParams { Type = BetaManagedAgentsFileResourceParamsType.File, FileID = "file_def456", MountPath = "/config.json" },
    new BetaManagedAgentsFileResourceParams { Type = BetaManagedAgentsFileResourceParamsType.File, FileID = "file_ghi789", MountPath = "/src/main.py" },
};
````

Go

```go
resources := []anthropic.BetaSessionNewParamsResourceUnion{
	{OfFile: &anthropic.BetaManagedAgentsFileResourceParams{Type: "file", FileID: "file_abc123", MountPath: anthropic.String("/data.csv")}},
	{OfFile: &anthropic.BetaManagedAgentsFileResourceParams{Type: "file", FileID: "file_def456", MountPath: anthropic.String("/config.json")}},
	{OfFile: &anthropic.BetaManagedAgentsFileResourceParams{Type: "file", FileID: "file_ghi789", MountPath: anthropic.String("/src/main.py")}},
}
```

Java

```java
import com.anthropic.models.beta.sessions.*;
import java.util.List;

var resources = List.of(
    BetaManagedAgentsFileResourceParams.builder()
        .type(BetaManagedAgentsFileResourceParams.Type.FILE).fileId("file_abc123").mountPath("/data.csv").build(),
    BetaManagedAgentsFileResourceParams.builder()
        .type(BetaManagedAgentsFileResourceParams.Type.FILE).fileId("file_def456").mountPath("/config.json").build(),
    BetaManagedAgentsFileResourceParams.builder()
        .type(BetaManagedAgentsFileResourceParams.Type.FILE).fileId("file_ghi789").mountPath("/src/main.py").build()
);
```

PHP

```php
$resources = [
    ['type' => 'file', 'fileID' => 'file_abc123', 'mountPath' => '/data.csv'],
    ['type' => 'file', 'fileID' => 'file_def456', 'mountPath' => '/config.json'],
    ['type' => 'file', 'fileID' => 'file_ghi789', 'mountPath' => '/src/main.py'],
];
```

Ruby

```ruby
resources = [
  {type: "file", file_id: "file_abc123", mount_path: "/data.csv"},
  {type: "file", file_id: "file_def456", mount_path: "/config.json"},
  {type: "file", file_id: "file_ghi789", mount_path: "/src/main.py"}
]
```

一个会话最多可以包含 500 个资源，文件、GitHub 仓库和记忆存储资源共同计数。

## 执行中补充或撤下材料 [#执行中补充或撤下材料]

任务开始后新增材料，无需为了附加文件重新创建会话。先上传文件，再用会话资源 API 添加到现有会话，并在后续消息中说明新增路径和用途。资源响应中的 `id` 用于管理会话关联，与上传返回的 `file_id` 分别保存。

cURL

```bash
resource=$(
  jq -n --arg file_id "${file_id}" '{type: "file", file_id: $file_id}' \
    | curl --fail-with-body -sS -H "x-api-key: $AGENTAPI_API_KEY" \
        "$AGENTAPI_BASE_URL/v1/sessions/${session_id}/resources" -H "content-type: application/json" --data @-
)
resource_id=$(jq -er '.id' <<<"${resource}")
printf '%s\n' "${resource_id}"  # "sr_01ABC..."
```

Python

```python
resource = client.beta.sessions.resources.add(
    session.id,
    type="file",
    file_id=file.id,
)
print(resource.id)  # "sr_01ABC..."
```

TypeScript

````typescript
const resource = await client.beta.sessions.resources.add(session.id, {
  type: "file",
  file_id: file.id,
});
if (resource.type !== "file") {
  throw new Error(`Unexpected resource type: ${resource.type}`);
}
console.log(resource.id); // "sr_01ABC..."
```csharp
```csharp
var resource = await client.Beta.Sessions.Resources.Add(session.ID, new()
{
    Type = "file",
    FileID = file.ID,
});
Console.WriteLine(resource.ID);  // "sr_01ABC..."
````

Go

```go
resource, err := client.Beta.Sessions.Resources.Add(ctx, session.ID, anthropic.BetaSessionResourceAddParams{
	BetaManagedAgentsFileResourceParams: anthropic.BetaManagedAgentsFileResourceParams{
		Type:   anthropic.BetaManagedAgentsFileResourceParamsTypeFile,
		FileID: file.ID,
	},
})
if err != nil {
	panic(err)
}
fmt.Println(resource.ID) // "sr_01ABC..."
```

Java

```java
var resource = client.beta().sessions().resources().add(
    session.id(),
    ResourceAddParams.builder()
        .betaManagedAgentsFileResourceParams(
            BetaManagedAgentsFileResourceParams.builder()
                .type(BetaManagedAgentsFileResourceParams.Type.FILE)
                .fileId(file.id())
                .build()
        )
        .build()
);
IO.println(resource.id()); // "sr_01ABC..."
```

PHP

```php
$resource = $client->beta->sessions->resources->add(
    $session->id,
    type: 'file',
    fileID: $file->id,
);
echo "{$resource->id}\n";  // "sr_01ABC..."
```

Ruby

```ruby
resource = client.beta.sessions.resources.add(
  session.id,
  type: "file",
  file_id: file.id
)
puts resource.id # "sr_01ABC..."
```

材料不再作为会话输入时，先用 `resources.list` 查找对应资源，再以资源 ID 调用 `resources.delete`。文件对象的删除和保留规则见清理说明。

cURL

```bash
curl --fail-with-body -sS -H "x-api-key: $AGENTAPI_API_KEY" \
  "$AGENTAPI_BASE_URL/v1/sessions/${session_id}/resources" \
  | jq -r '.data[] | "\(.id) \(.type)"'

curl --fail-with-body -sS -H "x-api-key: $AGENTAPI_API_KEY" -X DELETE \
  "$AGENTAPI_BASE_URL/v1/sessions/${session_id}/resources/${resource_id}" >/dev/null
```

Python

```python
listed = client.beta.sessions.resources.list(session.id)
for entry in listed.data:
    print(entry.id, entry.type)

client.beta.sessions.resources.delete(resource.id, session_id=session.id)
```

TypeScript

````typescript
const listed = await client.beta.sessions.resources.list(session.id);
for (const entry of listed.data) {
  if (entry.type !== "memory_store") {
    console.log(entry.id, entry.type);
  }
}

await client.beta.sessions.resources.delete(resource.id, {
  session_id: session.id,
});
```csharp
```csharp
var listed = await client.Beta.Sessions.Resources.List(session.ID);
await foreach (var entry in listed.Paginate())
{
    var type = entry.Match<string>(repo => repo.Type, fileRes => fileRes.Type, memoryStore => memoryStore.Type);
    Console.WriteLine($"{entry.ID} {type}");
}

await client.Beta.Sessions.Resources.Delete(resource.ID, new() { SessionID = session.ID });
````

Go

```go
listed, err := client.Beta.Sessions.Resources.List(ctx, session.ID, anthropic.BetaSessionResourceListParams{})
if err != nil {
	panic(err)
}
for _, entry := range listed.Data {
	fmt.Println(entry.ID, entry.Type)
}

if _, err := client.Beta.Sessions.Resources.Delete(ctx, resource.ID, anthropic.BetaSessionResourceDeleteParams{
	SessionID: session.ID,
}); err != nil {
	panic(err)
}
```

Java

```java
var listed = client.beta().sessions().resources().list(session.id());
for (var entry : listed.data()) {
    if (entry.isFile()) {
        var fileResource = entry.asFile();
        IO.println(fileResource.id() + " " + fileResource.type());
    } else if (entry.isGitHubRepository()) {
        var repoResource = entry.asGitHubRepository();
        IO.println(repoResource.id() + " " + repoResource.type());
    }
}

client.beta().sessions().resources().delete(
    resource.id(),
    ResourceDeleteParams.builder().sessionId(session.id()).build()
);
```

PHP

```php
$listed = $client->beta->sessions->resources->list($session->id);
foreach ($listed->data as $entry) {
    echo "{$entry->id} {$entry->type}\n";
}

$client->beta->sessions->resources->delete($resource->id, sessionID: $session->id);
```

Ruby

```ruby
listed = client.beta.sessions.resources.list(session.id)
listed.data.each { puts "#{it.id} #{it.type}" }

client.beta.sessions.resources.delete(resource.id, session_id: session.id)
```

## 验收与下载任务产物 [#验收与下载任务产物]

任务要求应同时约定交付文件，例如分析报告、处理后的数据或补丁。智能体的最终回答与文件交付是两个检查项：收到完成消息后，还应查询会话文件，确认预期产物存在并下载检查。

Portal 文件列表支持按文件名或 ID 搜索。搜索去除首尾空白，按字面量包含关系匹配，并在页码分页前计算总数；可以同时使用 `scope_id` 限定 Session。对应接口为 `GET /portal/v1/files?page_index=1&q=关键词`，`q` 必须与 `page_index` 一起使用，公开的 `GET /v1/files` 不接受该参数。

> 智能体生成的交付物
>
> 云端环境默认提供文件交付指引：供用户下载的最终文件写入 `/mnt/session/outputs/`，临时文件和项目文件保留在各自的工作路径。普通会话与 Outcome 均适用，无需客户端额外拼接目录提示。自托管 worker 不使用这条云端指引，其文件不会通过云端输出目录自动收集。
>
> AgentAPI 在执行完成后收集输出目录中的文件。文件出现在会话列表中后才能下载；若尚未出现，稍后重新查询。持续缺失时，结合[事件](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)检查执行结果，并确认产物确实写入交付目录且未超过输出限额。

cURL

```bash
# 列出与会话关联的文件
curl --request GET "$AGENTAPI_BASE_URL/v1/files?scope_id=$SESSION_ID" \
  --header "x-api-key: $AGENTAPI_API_KEY"

# 下载文件
curl --request GET "$AGENTAPI_BASE_URL/v1/files/$FILE_ID/content" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --output output.txt
```

Python

```python
# 列出与会话关联的文件
files = client.beta.files.list(scope_id="ses_abc123")
for file in files:
    print(file.id, file.filename)

# 下载文件
content = client.beta.files.download(files.data[0].id)
content.write_to_file("output.txt")
```

TypeScript

````typescript
import { writeFile } from "node:fs/promises";

// 列出与会话关联的文件
const files = await client.beta.files.list({
  scope_id: "ses_abc123"
});
for (const file of files.data) {
  console.log(file.id, file.filename);
}

// 下载文件
const content = await client.beta.files.download(files.data[0].id);
await writeFile("output.txt", new Uint8Array(await content.arrayBuffer()));
```csharp
```csharp
// 列出与会话关联的文件
var files = await client.Beta.Files.List(new()
{
    ScopeID = "ses_abc123",
});

// 下载文件
using var content = await client.Beta.Files.Download(files.Items[0].ID);
await using var output = File.Create("output.txt");
await (await content.ReadAsStream()).CopyToAsync(output);
````

Go

```go
// 列出与会话关联的文件
files, err := client.Beta.Files.List(ctx, anthropic.BetaFileListParams{
	ScopeID: anthropic.String("ses_abc123"),
})
if err != nil {
	panic(err)
}

// 下载文件
resp, err := client.Beta.Files.Download(ctx, files.Data[0].ID)
if err != nil {
	panic(err)
}
defer resp.Body.Close()
out, err := os.Create("output.txt")
if err != nil {
	panic(err)
}
defer out.Close()
if _, err := io.Copy(out, resp.Body); err != nil {
	panic(err)
}
```

Java

```java
// 列出与会话关联的文件
var files = client.beta().files().list(FileListParams.builder()
    .scopeId("ses_abc123")
    .build());

// 下载文件
try (HttpResponse response = client.beta().files().download(files.data().get(0).id())) {
    try (InputStream body = response.body()) {
        Files.copy(body, Path.of("output.txt"), StandardCopyOption.REPLACE_EXISTING);
    }
}
```

PHP

```php
// 列出与会话关联的文件
$files = $client->beta->files->list(
    scopeID: 'ses_abc123',
);
foreach ($files->getItems() as $file) {
    echo "{$file->id} {$file->filename}\n";
}

// 下载文件
$content = $client->beta->files->download($files->getItems()[0]->id);
file_put_contents('output.txt', $content);
```

Ruby

```ruby
# 列出与会话关联的文件
files = client.beta.files.list(
  scope_id: "ses_abc123"
)

# 下载文件
content = client.beta.files.download(files.data[0].id)
File.binwrite("output.txt", content.read)
```

## 控制交付大小与清理文件 [#控制交付大小与清理文件]

交付前控制输入和输出大小，下载时处理分页：

* 单个文件的上传上限默认为 100 MiB；会话沙箱挂载的输入文件不能超过 100 MiB。自部署服务可调整上传上限，但不会改变沙箱挂载上限。
* 执行结束后收集到 Files API 的输出文件，单文件和本轮输出目录中的文件总计均不能超过 100 MiB。任一限制被超过时，本轮输出文件收集失败，并非只跳过超限文件；请缩小产物或移出不需要下载的文件后重试。
* 文件列表采用分页响应，包含 `has_more`、`first_id`、`last_id` 和 `next_page`。查询下一页时，将 `next_page` 原样作为 `page` 参数传入；也兼容 `after_id`/`before_id`。详见 [API 通用约定](/products/agentapi/api/13618-agentapi-api-conventions)。

报告或数据下载验收后，按本页开头的对象类型决定保留范围。归档会话会保留会话文件；需要删除时分别处理源材料和会话对象：

* 删除单个对象：调用 `DELETE /v1/files/{file_id}`；会话作用域的对象还会移除对应资源关联。
* 清理某个会话的全部文件：删除会话。目前没有按会话批量删除文件对象的专用接口。
* 独立上传文件需单独删除；删除源文件不会清理已挂载的副本。


# 构建持久记忆 (/products/agentapi/development_guidelines/agentapi-data-and-integrations/13603-agentapi-data-and-integrations-memory)



最近更新时间: 2026-10-13 15:31:46

多个独立任务需要共用项目约定时，可以将资料保存到 Memory Store（记忆存储），在各自的会话中显式引用。存储由 UTF-8 文档组成，资料的读取与写回方式取决于运行时和访问模式。

生成 CSV 报告时，可以只读报告规范，将经确认的新经验保存到另一份可写存储；报告作为[输出文件](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)交付。

## 区分任务材料与跨会话资料 [#区分任务材料与跨会话资料]

| 需要保存的信息         | 使用方式                                                                                                                                      |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| 当前任务的对话和执行历史    | 保留会话，并在同一会话继续交互。                                                                                                                          |
| 当前任务的数据或最终产物    | 使用[文件资源与 Files API](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)。 |
| 跨任务复用的用户偏好、项目约定 | 创建记忆存储，在新会话中显式引用。                                                                                                                         |
| 访问外部系统的令牌与密钥    | 保存到 [Vault](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13606-agentapi-data-and-integrations-vaults)。        |

先确定哪些信息需要进入下一个任务，再选择保存方式。只用于当前任务的数据不必写入记忆；第三方令牌与密钥应交给 Vault。项目约定需要跨任务复用，但通常不应由每次任务自行修改，因此应以 `read_only` 附加。

## 确定运行时与写入责任 [#确定运行时与写入责任]

存储属于当前账户，HTTP API 不依赖运行时。将它用于任务时，需要先确认由 AgentAPI、worker 还是应用负责准备和保存内容：

| 执行方式                    | 内容如何进入任务                | 修改如何保存                                                                                                                                              |
| ----------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 云端 `claudecode`、`codex` | 自动准备挂载目录，由文件工具读取        | 成功执行后同步 `read_write` 目录                                                                                                                             |
| 云端 `native`             | 应用通过 API 获取内容，或准备普通文件资源 | 应用显式调用记忆 API                                                                                                                                        |
| 自托管 `native`            | 支持记忆的 worker 下载并挂载      | worker 负责同步，见[自托管记忆接入](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted) |

应用也可以通过 API 或 Portal 维护存储，与运行时是否支持自动挂载无关。

存储中的每条记忆（memory）用路径组织，例如 `/project/report-format.md`；返回的 `mem_*` ID 用于检索、更新和删除接口。路径必须以 `/` 开头，不能包含空路径段、`.` 或 `..`，内容必须是 UTF-8 文本。智能体访问的是挂载目录内的文件路径，应用调用 API 时使用的是存储路径或记忆 ID。

每次内容变更都会生成不可变的记忆版本（memory version）。版本用于检查写入方和历史内容；恢复旧内容需要通过 API 重新写入，不会自动恢复沙箱中的文件。

## 记忆读取与更新可见性 [#记忆读取与更新可见性]

![云端 CLI 会话从记忆存储准备挂载目录，智能体通过文件工具访问；成功执行后同步 read\_write 改动并生成版本，云端 Native 不自动挂载](/docs-assets/products/agentapi/development_guidelines/agentapi-data-and-integrations/13603-agentapi-data-and-integrations-memory/FkD6N1R22lpDIF6r8OAXEhMs6iO6-a6276f822400.webp)

对于支持挂载的运行时，任务读取沙箱中的文件，应用通过 API 查询服务端内容。系统提示包含存储说明与路径，但不会自动包含全部文档。排查“任务没有使用最新资料”时，先区分修改发生在哪个位置：

* 挂载路径。 请读取会话记忆存储资源返回的 `mount_path`，不要自行构造。目录名由存储显示名转换而来，例如“Demo Memory”对应 `/mnt/memory/demo-memory/`。
* 任务读写。 智能体通过[文件工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)操作挂载目录。云端成功执行后，`read_write` 目录的修改才会写回服务端并形成版本；文件工具成功不等于持久化完成。
* 写回范围。 挂载目录外的文件不参与记忆同步。需要交付的报告应作为会话输出文件收集，需要跨任务复用的经验才写入记忆目录。
* 模型获知的内容。 系统提示包含显示名、挂载路径、访问模式、`description` 和 `instructions`。应用应在任务要求中说明读取哪些约定，而非假定模型已经获得全文。

云端环境中的 `native` 不会创建上述挂载，请改用本页的 HTTP API 示例。

> 记忆同步范围
>
> 新建沙箱时读取存储内容；复用沙箱时保留已有文件，不会每轮重新下载。API 或其他会话的修改不会实时同步到已有挂载；需要最新内容时，请通过 API 查询或创建新会话。

对于 `self_hosted`，AgentAPI 只下发 `memory_store` 资源，记忆的下载、挂载和同步则由自托管执行器（worker）或启动器（launcher）负责，详见 [自托管执行器](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

云端 `read_write` 目录成功写回后，会生成归属于该会话的记忆版本。自托管 worker 的保护措施见[保护记忆副本](/products/agentapi/development_guidelines/agentapi-execution-environments/13615-agentapi-execution-environments-self-hosted-security)。

> 说明
>
> 云端 `read_only` 目录移除写权限位，不同步回存储。root 进程可绕过这些权限位，因此它不构成文件系统隔离；若执行后检测到内容变化，AgentAPI 会拒绝写回并报告错误。

智能体使用工具访问挂载目录时，读写操作会在[事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)中记录为普通的 `agent.tool_use` 和 `agent.tool_result` 事件。

## 控制写入范围与存储容量 [#控制写入范围与存储容量]

当存储达到 2,000 条记忆的上限时，新建记忆会失败，包括直接调用 `memories.create` 和智能体在挂载目录中新建文件。现有记忆仍可读取和更新。

按业务决定存储的写入方，而不是把每次任务的全部信息都追加进去：

| 内容             | 写入方与维护方式                          |
| -------------- | --------------------------------- |
| 报告格式、验收口径等共享基准 | 应用审核后通过 API 更新，任务只读               |
| 单个用户或项目的已确认经验  | 对应任务可写，应用核对持久化内容及版本               |
| 多个会话同时维护的内容    | 通过 API 使用内容哈希前置条件协调更新，不依赖挂载副本实时同步 |

存储接近容量上限时，整理失效内容或按项目、保留周期拆分。旧资料不再增长时，可以只读引用旧存储，将新信息写入另一份存储；每个会话合计仍不能超过 8 个存储。

## 准备可复用的资料 [#准备可复用的资料]

将稳定的共享约定和任务产生的可写经验放到不同存储，分别决定访问模式与保留周期。下面的示例创建存储、预填充一条报告格式约定，再将存储附加到新会话。

### 创建资料存储 [#创建资料存储]

`name` 用于识别存储，`description` 会进入智能体上下文。描述应说明资料适用的任务范围，不应代替具体文档内容。

请先完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)，SDK 客户端初始化见[通过 API 构建](/products/agentapi/quick_start/13587-agentapi-quickstart)。以下操作创建独立的记忆存储，不会自动修改现有会话。

cURL

```bash
store=$(curl --request POST --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/memory_stores" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data '{"name": "项目报告规范", "description": "CSV 报告的格式和验收约定。"}')
store_id=$(jq -r '.id' <<< "$store")
echo "$store_id"  # memstore_01Hx...
```

Python

```python
store = client.beta.memory_stores.create(
    name="项目报告规范",
    description="CSV 报告的格式和验收约定。",
)
print(store.id)  # memstore_01Hx...
```

TypeScript

````typescript
const store = await client.beta.memoryStores.create({
  name: "项目报告规范",
  description: "CSV 报告的格式和验收约定。"
});
console.log(store.id); // memstore_01Hx...
```csharp
```csharp
var store = await client.Beta.MemoryStores.Create(new()
{
    Name = "项目报告规范",
    Description = "CSV 报告的格式和验收约定。",
});
Console.WriteLine(store.ID);  // memstore_01Hx...
````

Go

```go
store, err := client.Beta.MemoryStores.New(ctx, anthropic.BetaMemoryStoreNewParams{
	Name:        "项目报告规范",
	Description: anthropic.String("CSV 报告的格式和验收约定。"),
})
if err != nil {
	panic(err)
}
fmt.Println(store.ID) // memstore_01Hx...
```

Java

```java
var store = client.beta().memoryStores().create(
    MemoryStoreCreateParams.builder()
        .name("项目报告规范")
        .description("CSV 报告的格式和验收约定。")
        .build()
);
IO.println(store.id());  // memstore_01Hx...
```

PHP

```php
$store = $client->beta->memoryStores->create(
    name: '项目报告规范',
    description: 'CSV 报告的格式和验收约定。',
);
echo "{$store->id}\n"; // memstore_01Hx...
```

Ruby

```ruby
store = client.beta.memory_stores.create(
  name: "项目报告规范",
  description: "CSV 报告的格式和验收约定。"
)
puts store.id # memstore_01Hx...
```

记忆存储的 `id`（`memstore_...`）是附加记忆存储时需要传入的值。

### 写入初始约定 [#写入初始约定]

首次任务开始前，可以由应用直接写入已经审核的资料。示例在 `/project/report-format.md` 写入 CSV 报告格式要求；后续任务应读取约定，而不是从旧会话里猜测格式。

cURL

```bash
curl --request POST --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/memory_stores/$store_id/memories" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data '{"path": "/project/report-format.md", "content": "报告使用 Markdown，包含数据来源、区域汇总表、合计和计算方法。"}' > /dev/null
```

Python

```python
client.beta.memory_stores.memories.create(
    store.id,
    path="/project/report-format.md",
    content="报告使用 Markdown，包含数据来源、区域汇总表、合计和计算方法。",
)
```

TypeScript

````typescript
await client.beta.memoryStores.memories.create(store.id, {
  path: "/project/report-format.md",
  content: "报告使用 Markdown，包含数据来源、区域汇总表、合计和计算方法。"
});
```csharp
```csharp
await client.Beta.MemoryStores.Memories.Create(store.ID, new()
{
    Path = "/project/report-format.md",
    Content = "报告使用 Markdown，包含数据来源、区域汇总表、合计和计算方法。",
});
````

Go

```go
_, err = client.Beta.MemoryStores.Memories.New(ctx, store.ID, anthropic.BetaMemoryStoreMemoryNewParams{
	Path:    "/project/report-format.md",
	Content: anthropic.String("报告使用 Markdown，包含数据来源、区域汇总表、合计和计算方法。"),
})
if err != nil {
	panic(err)
}
```

Java

```java
client.beta().memoryStores().memories().create(
    store.id(),
    MemoryCreateParams.builder()
        .path("/project/report-format.md")
        .content("报告使用 Markdown，包含数据来源、区域汇总表、合计和计算方法。")
        .build()
);
```

PHP

```php
$client->beta->memoryStores->memories->create(
    $store->id,
    path: '/project/report-format.md',
    content: '报告使用 Markdown，包含数据来源、区域汇总表、合计和计算方法。',
);
```

Ruby

```ruby
client.beta.memory_stores.memories.create(
  store.id,
  path: "/project/report-format.md",
  content: "报告使用 Markdown，包含数据来源、区域汇总表、合计和计算方法。"
)
```

> 说明
>
> 单条记忆最大为 100 KiB，一个存储最多包含 2,000 条记忆。请按主题拆分文件，避免把无关内容集中到一个大文档中。

### 为任务选择访问模式 [#为任务选择访问模式]

先创建 `claudecode` 或 `codex` [智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)和[云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)，再通过会话的 `resources` 引用存储。自托管环境使用 `native` 智能体，由 worker 挂载。

* 存储只能在会话创建时附加。更换存储或访问模式需创建新会话，不能在运行中通过会话资源接口修改。
* `instructions` 可选，最多 4,096 个字符，与存储的 `name`、`description` 一起展示给智能体。
* `access` 默认为 `read_write`，仅读取时请设置为 `read_only`。

以下示例以 `read_only` 附加已预填的报告规范，并说明任务需要读取的文件。云端 Native 不自动挂载这份资源，应由应用通过 API 获取内容并提供给任务。需要沉淀新经验时，使用独立可写存储。

cURL

```bash
curl --request POST --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/sessions" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
  "agent": {"type": "agent", "id": "$agent_id", "version": 1},
  "environment_id": "$environment_id",
  "resources": [
    {
      "type": "memory_store",
      "memory_store_id": "$store_id",
      "access": "read_only",
      "instructions": "生成报告前从本存储的实际挂载目录读取 project/report-format.md，按规范交付报告，不修改共享约定。"
    }
  ]
}
EOF
```

Python

```python
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "memory_store",
            "memory_store_id": store.id,
            "access": "read_only",
            "instructions": "生成报告前从本存储的实际挂载目录读取 project/report-format.md，按规范交付报告，不修改共享约定。",
        }
    ],
)
```

TypeScript

````typescript
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "memory_store",
      memory_store_id: store.id,
      access: "read_only",
      instructions: "生成报告前从本存储的实际挂载目录读取 project/report-format.md，按规范交付报告，不修改共享约定。"
    }
  ]
});
```csharp
```csharp
var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    Resources =
    [
        new BetaManagedAgentsMemoryStoreResourceParam
        {
            Type = "memory_store",
            MemoryStoreID = store.ID,
            Access = "read_only",
            Instructions = "生成报告前从本存储的实际挂载目录读取 project/report-format.md，按规范交付报告，不修改共享约定。",
        },
    ],
});
````

Go

```go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfString: anthropic.String(agent.ID),
	},
	EnvironmentID: environment.ID,
	Resources: []anthropic.BetaSessionNewParamsResourceUnion{{
		OfMemoryStore: &anthropic.BetaManagedAgentsMemoryStoreResourceParam{
			Type:          anthropic.BetaManagedAgentsMemoryStoreResourceParamTypeMemoryStore,
			MemoryStoreID: store.ID,
			Access:        anthropic.BetaManagedAgentsMemoryStoreResourceParamAccessReadOnly,
			Instructions:  anthropic.String("生成报告前从本存储的实际挂载目录读取 project/report-format.md，按规范交付报告，不修改共享约定。"),
		},
	}},
})
if err != nil {
	panic(err)
}
```

Java

```java
var session = client.beta().sessions().create(
    SessionCreateParams.builder()
        .agent(agent.id())
        .environmentId(environment.id())
        .addResource(
            BetaManagedAgentsMemoryStoreResourceParam.builder()
                .type(BetaManagedAgentsMemoryStoreResourceParam.Type.MEMORY_STORE)
                .memoryStoreId(store.id())
                .access(BetaManagedAgentsMemoryStoreResourceParam.Access.READ_ONLY)
                .instructions("生成报告前从本存储的实际挂载目录读取 project/report-format.md，按规范交付报告，不修改共享约定。")
                .build()
        )
        .build()
);
```

PHP

```php
$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
    resources: [
        [
            'type' => 'memory_store',
            'memory_store_id' => $store->id,
            'access' => 'read_only',
            'instructions' => '生成报告前从本存储的实际挂载目录读取 project/report-format.md，按规范交付报告，不修改共享约定。',
        ],
    ],
);
```

Ruby

```ruby
session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "memory_store",
      memory_store_id: store.id,
      access: "read_only",
      instructions: "生成报告前从本存储的实际挂载目录读取 project/report-format.md，按规范交付报告，不修改共享约定。"
    }
  ]
)
```

创建会话只会保存资源配置。请继续发送任务消息，要求智能体按需读取记忆；存储说明与 `instructions` 会进入上下文，但全部文档内容不会自动成为完整的对话输入。

> 说明
>
> 不受信任的用户输入、网页或工具输出可能通过提示注入污染记忆，影响后续会话。参考资料、共享查询数据等无需修改的存储，请使用 `read_only`。

每个会话最多附加 8 个记忆存储。可按用户、团队或项目拆分，分别管理访问权限和保留周期；共享只读资料与会话读写记忆应分开存储。

### 将已确认的经验保存到独立存储 [#将已确认的经验保存到独立存储]

需要保存经业务确认的新经验时，另建存储，并在附加资源时设置以下访问模式。此资源片段用于支持云端记忆挂载的 `claudecode` 或 `codex` 会话：

```json
{
  "resources": [
    {"type": "memory_store", "memory_store_id": "your-rules-store-id", "access": "read_only"},
    {"type": "memory_store", "memory_store_id": "your-experience-store-id", "access": "read_write",
     "instructions": "仅保存业务明确确认的新经验，使用本存储的实际挂载路径。"}
  ]
}
```

共享规范由应用审核后维护，可写经验不替代规范。任务结束后，按下节查询服务端内容与版本确认写回。

## 核对本轮持久化结果 [#核对本轮持久化结果]

任务结束后，应用应读取服务端记忆并核对预期内容。报告任务的回答中出现“已保存”或文件工具返回成功，均不能代替这一步。读写异常应先检查运行时是否支持挂载、是否以只读方式引用，以及修改是否位于挂载目录。

先列出任务涉及的文档，再读取服务端内容。发现误写时，通过版本历史追查来源，再修正资料。业务资料的审核规则由应用执行；AgentAPI 不会自动判断一次写入是否适合供后续任务使用。

### 确定检查范围 [#确定检查范围]

按项目路径列出需要检查的文档，而不是每次将整个存储加入任务输入。列表顺序由服务端稳定定义，不表示内容的重要性。

* `path_prefix` 将列表范围限定到一个目录。它必须以 `/` 结尾，并匹配完整的路径段，因此 `path_prefix=/notes/` 会返回 `/notes/todo.md`，但不会返回 `/notes-archive/todo.md`。
* `depth` 控制列表在 `path_prefix` 之下深入的层级：省略它以列出整个子树；传递正整数 `N` 则展开到第 `N` 层（`1` 仅列出直接子项）。`0` 或任何非正整数会返回 `400 depth must be a positive integer` 错误。

cURL

```bash
curl --request GET --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/memory_stores/$store_id/memories?path_prefix=/" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for item in page.data:
    print(item.type, item.path)
```

TypeScript

````typescript
const page = await client.beta.memoryStores.memories.list(store.id, {
  path_prefix: "/"
});
for (const item of page.data) {
  console.log(item.type, item.path);
}
```csharp
```csharp
var page = await client.Beta.MemoryStores.Memories.List(store.ID, new()
{
    PathPrefix = "/",
});
await foreach (var item in page.Paginate())
{
    var line = item.Match(m => $"memory  {m.Path}", p => $"memory_prefix  {p.Path}");
    Console.WriteLine(line);
}
````

Go

```go
page, err := client.Beta.MemoryStores.Memories.List(ctx, store.ID, anthropic.BetaMemoryStoreMemoryListParams{
	PathPrefix: anthropic.String("/"),
})
if err != nil {
	panic(err)
}
for _, item := range page.Data {
	fmt.Println(item.Type, item.Path)
}
```

Java

```java
var page = client.beta().memoryStores().memories().list(
    store.id(),
    MemoryListParams.builder()
        .pathPrefix("/")
        .build()
);
for (var item : page.data()) {
    item.memory().ifPresent(m -> IO.println("memory  " + m.path()));
    item.memoryPrefix().ifPresent(p -> IO.println("memory_prefix  " + p.path()));
}
```

PHP

```php
$page = $client->beta->memoryStores->memories->list(
    $store->id,
    pathPrefix: '/',
);
foreach ($page->data as $item) {
    echo "{$item->type}  {$item->path}\n";
}
```

Ruby

```ruby
page = client.beta.memory_stores.memories.list(
  store.id,
  path_prefix: "/"
)
page.data.each do |entry|
  puts "#{entry.type}  #{entry.path}"
end
```

### 读取服务端内容 [#读取服务端内容]

使用记忆 ID 获取完整内容，核对本轮要求保存的约定或经验是否已经出现在服务端。尚未写回时，不要仅凭会话回答向后续任务宣布资料已更新。

cURL

```bash
curl --request GET --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/memory_stores/$store_id/memories/$mem_id" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
retrieved = client.beta.memory_stores.memories.retrieve(
    mem.id,
    memory_store_id=store.id,
)
print(retrieved.content)
```

TypeScript

````typescript
const retrieved = await client.beta.memoryStores.memories.retrieve(mem.id, {
  memory_store_id: store.id
});
console.log(retrieved.content);
```csharp
```csharp
var retrieved = await client.Beta.MemoryStores.Memories.Retrieve(mem.ID, new()
{
    MemoryStoreID = store.ID,
});
Console.WriteLine(retrieved.Content);
````

Go

```go
retrieved, err := client.Beta.MemoryStores.Memories.Get(ctx, mem.ID, anthropic.BetaMemoryStoreMemoryGetParams{
	MemoryStoreID: store.ID,
})
if err != nil {
	panic(err)
}
fmt.Println(retrieved.Content)
```

Java

```java
var retrieved = client.beta().memoryStores().memories().retrieve(
    mem.id(),
    MemoryRetrieveParams.builder().memoryStoreId(store.id()).build()
);
IO.println(retrieved.content().orElseThrow());
```

PHP

```php
$retrieved = $client->beta->memoryStores->memories->retrieve($mem->id, memoryStoreID: $store->id);
echo "{$retrieved->content}\n";
```

Ruby

```ruby
retrieved = client.beta.memory_stores.memories.retrieve(
  mem.id,
  memory_store_id: store.id
)
puts retrieved.content
```

## 检查变更来源并恢复资料 [#检查变更来源并恢复资料]

后续任务使用了错误约定时，先读取当前内容，再查看版本历史，确定是哪次写入引入了变化。记忆版本（`memver_...`）保存变更的执行方、时间和内容；模型在当前任务中的解释不能替代这份记录。

版本接口属于记忆存储。`memories.retrieve` 返回当前内容，版本接口返回历史快照；删除当前记忆不会删除已经生成的版本。处理误写敏感信息时，必须同时检查当前内容与历史版本，不能只删除当前文档。

恢复流程由应用完成：读取仍被保留的目标版本，用 `memories.update` 将其 `content` 写回；父记忆已删除时使用 `memories.create` 重新创建。没有单独的恢复端点，恢复后也不能假定已有沙箱已下载新内容。

AgentAPI 当前不在公共契约中承诺固定的版本保留时长。需要长期留存审计记录时，请定期通过 API 导出版本。

### 定位发生变化的版本 [#定位发生变化的版本]

列出存储的版本历史，最新的在前。以下示例筛选出单条记忆的历史：

cURL

```bash
versions=$(curl --request GET --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/memory_stores/$store_id/memory_versions?memory_id=$mem_id" \
  --header "x-api-key: $AGENTAPI_API_KEY")
jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -r '.data[1].id' <<< "$versions")
```

Python

```python
versions = client.beta.memory_stores.memory_versions.list(
    store.id,
    memory_id=mem.id,
)
for version in versions:
    print(f"{version.id}: {version.operation}")

version_id = versions.data[1].id
```

TypeScript

````typescript
const versions = await client.beta.memoryStores.memoryVersions.list(store.id, {
  memory_id: mem.id
});
for await (const v of versions) {
  console.log(`${v.id}: ${v.operation}`);
}

const versionId = versions.data[1].id;
```csharp
```csharp
var versions = await client.Beta.MemoryStores.MemoryVersions.List(store.ID, new()
{
    MemoryID = mem.ID,
});
var versionIds = new List<string>();
await foreach (var v in versions.Paginate())
{
    Console.WriteLine($"{v.ID}: {v.Operation.Raw()}");
    versionIds.Add(v.ID);
}

var versionId = versionIds[1];
````

Go

```go
versions := client.Beta.MemoryStores.MemoryVersions.ListAutoPaging(ctx, store.ID, anthropic.BetaMemoryStoreMemoryVersionListParams{
	MemoryID: anthropic.String(mem.ID),
})
for versions.Next() {
	v := versions.Current()
	fmt.Printf("%s: %s\n", v.ID, v.Operation)
}
if err := versions.Err(); err != nil {
	panic(err)
}

vpage, err := client.Beta.MemoryStores.MemoryVersions.List(ctx, store.ID, anthropic.BetaMemoryStoreMemoryVersionListParams{
	MemoryID: anthropic.String(mem.ID),
})
if err != nil {
	panic(err)
}
versionID := vpage.Data[1].ID
```

Java

```java
var versions = client.beta().memoryStores().memoryVersions().list(
    store.id(),
    MemoryVersionListParams.builder().memoryId(mem.id()).build()
);
for (var v : versions.autoPager()) {
    IO.println(v.id() + ": " + v.operation());
}

var versionId = versions.data().get(1).id();
```

PHP

```php
$versions = $client->beta->memoryStores->memoryVersions->list(
    $store->id,
    memoryID: $mem->id,
);
foreach ($versions->pagingEachItem() as $v) {
    echo "{$v->id}: {$v->operation}\n";
}

$versionId = $versions->data[1]->id;
```

Ruby

```ruby
versions = client.beta.memory_stores.memory_versions.list(
  store.id,
  memory_id: mem.id
)
versions.auto_paging_each do |version|
  puts "#{version.id}: #{version.operation}"
end

version_id = versions.data[1].id
```

### 读取待恢复的快照 [#读取待恢复的快照]

获取单个版本会返回与列表响应相同的字段，外加完整的 `content` 正文。

cURL

```bash
curl --request GET --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/memory_stores/$store_id/memory_versions/$version_id" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
version = client.beta.memory_stores.memory_versions.retrieve(
    version_id,
    memory_store_id=store.id,
)
print(version.content)
```

TypeScript

````typescript
const version = await client.beta.memoryStores.memoryVersions.retrieve(versionId, {
  memory_store_id: store.id
});
console.log(version.content);
```csharp
```csharp
var version = await client.Beta.MemoryStores.MemoryVersions.Retrieve(versionId, new()
{
    MemoryStoreID = store.ID,
});
Console.WriteLine(version.Content);
````

Go

```go
version, err := client.Beta.MemoryStores.MemoryVersions.Get(ctx, versionID, anthropic.BetaMemoryStoreMemoryVersionGetParams{
	MemoryStoreID: store.ID,
})
if err != nil {
	panic(err)
}
fmt.Println(version.Content)
```

Java

```java
var version = client.beta().memoryStores().memoryVersions().retrieve(
    versionId,
    MemoryVersionRetrieveParams.builder().memoryStoreId(store.id()).build()
);
IO.println(version.content().orElseThrow());
```

PHP

```php
$version = $client->beta->memoryStores->memoryVersions->retrieve(
    $versionId,
    memoryStoreID: $store->id,
);
echo "{$version->content}\n";
```

Ruby

```ruby
version = client.beta.memory_stores.memory_versions.retrieve(
  version_id,
  memory_store_id: store.id
)
puts version.content
```

### 清除历史中的敏感内容 [#清除历史中的敏感内容]

脱敏会从历史版本中清除内容，同时保留执行方、变更时间等审计信息。可将其用于合规工作流，例如移除泄露的密钥、个人身份信息（PII）或处理用户删除请求。

当前记忆正在使用的最新版本不能脱敏。请先写入一个新版本（或删除该记忆），然后再对旧版本进行脱敏。

cURL

```bash
curl --fail-with-body --silent --show-error --request POST "$AGENTAPI_BASE_URL/v1/memory_stores/$store_id/memory_versions/$version_id/redact" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data '{}'
```

Python

```python
client.beta.memory_stores.memory_versions.redact(
    version_id,
    memory_store_id=store.id,
)
```

TypeScript

````typescript
await client.beta.memoryStores.memoryVersions.redact(versionId, {
  memory_store_id: store.id
});
```csharp
```csharp
await client.Beta.MemoryStores.MemoryVersions.Redact(versionId, new()
{
    MemoryStoreID = store.ID,
});
````

Go

```go
_, err = client.Beta.MemoryStores.MemoryVersions.Redact(ctx, versionID, anthropic.BetaMemoryStoreMemoryVersionRedactParams{
	MemoryStoreID: store.ID,
})
if err != nil {
	panic(err)
}
```

Java

```java
client.beta().memoryStores().memoryVersions().redact(
    versionId,
    MemoryVersionRedactParams.builder().memoryStoreId(store.id()).build()
);
```

PHP

```php
$client->beta->memoryStores->memoryVersions->redact(
    $versionId,
    memoryStoreID: $store->id,
);
```

Ruby

```ruby
client.beta.memory_stores.memory_versions.redact(
  version_id,
  memory_store_id: store.id
)
```

## 审核后修正资料 [#审核后修正资料]

确认错误来源后，再更新或删除当前内容。涉及多个写入方时，使用内容哈希前置条件，避免审核期间产生的新修改被覆盖。修正服务端资料后，已有沙箱的文件仍可能保留旧内容；后续任务需要最新资料时，通过 API 获取或创建新会话。

### 补充已审核的资料 [#补充已审核的资料]

应用确认新资料适合跨任务使用后，通过 `memories.create` 写入指定路径。该操作不覆盖已有内容；已存在的约定需要用 `memories.update` 修改，不能通过重复创建替换。

cURL

```bash
mem=$(curl --request POST --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/memory_stores/$store_id/memories" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data '{"path": "/project/report-checks.md", "content": "报告必须说明数据来源、统计范围和计算方法。"}')
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")
```

Python

```python
mem = client.beta.memory_stores.memories.create(
    store.id,
    path="/project/report-checks.md",
    content="报告必须说明数据来源、统计范围和计算方法。",
)
```

TypeScript

````typescript
const mem = await client.beta.memoryStores.memories.create(store.id, {
  path: "/project/report-checks.md",
  content: "报告必须说明数据来源、统计范围和计算方法。"
});
```csharp
```csharp
var mem = await client.Beta.MemoryStores.Memories.Create(store.ID, new()
{
    Path = "/project/report-checks.md",
    Content = "报告必须说明数据来源、统计范围和计算方法。",
});
````

Go

```go
mem, err := client.Beta.MemoryStores.Memories.New(ctx, store.ID, anthropic.BetaMemoryStoreMemoryNewParams{
	Path:    "/project/report-checks.md",
	Content: anthropic.String("报告必须说明数据来源、统计范围和计算方法。"),
})
if err != nil {
	panic(err)
}
```

Java

```java
var mem = client.beta().memoryStores().memories().create(
    store.id(),
    MemoryCreateParams.builder()
        .path("/project/report-checks.md")
        .content("报告必须说明数据来源、统计范围和计算方法。")
        .build()
);
```

PHP

```php
$mem = $client->beta->memoryStores->memories->create(
    $store->id,
    path: '/project/report-checks.md',
    content: '报告必须说明数据来源、统计范围和计算方法。',
);
```

Ruby

```ruby
mem = client.beta.memory_stores.memories.create(
  store.id,
  path: "/project/report-checks.md",
  content: "报告必须说明数据来源、统计范围和计算方法。"
)
```

### 修正或迁移已有内容 [#修正或迁移已有内容]

纠正内容时通过 ID 更新 `content`；调整资料目录时更新 `path`，也可以同时修改。下面的示例将原路径改为归档目录，这是内容组织方式，不等同于归档整个存储。

cURL

```bash
curl --fail-with-body --silent --show-error --request POST "$AGENTAPI_BASE_URL/v1/memory_stores/$store_id/memories/$mem_id" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data '{"path": "/archive/report-checks.md"}' > /dev/null
```

Python

```python
client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id=store.id,
    path="/archive/report-checks.md",
)
```

TypeScript

````typescript
await client.beta.memoryStores.memories.update(mem.id, {
  memory_store_id: store.id,
  path: "/archive/report-checks.md"
});
```csharp
```csharp
await client.Beta.MemoryStores.Memories.Update(mem.ID, new()
{
    MemoryStoreID = store.ID,
    Path = "/archive/report-checks.md",
});
````

Go

```go
_, err = client.Beta.MemoryStores.Memories.Update(ctx, mem.ID, anthropic.BetaMemoryStoreMemoryUpdateParams{
	MemoryStoreID: store.ID,
	Path:          anthropic.String("/archive/report-checks.md"),
})
if err != nil {
	panic(err)
}
```

Java

```java
client.beta().memoryStores().memories().update(
    mem.id(),
    MemoryUpdateParams.builder()
        .memoryStoreId(store.id())
        .path("/archive/report-checks.md")
        .build()
);
```

PHP

```php
$client->beta->memoryStores->memories->update(
    $mem->id,
    memoryStoreID: $store->id,
    path: '/archive/report-checks.md',
);
```

Ruby

```ruby
client.beta.memory_stores.memories.update(
  mem.id,
  memory_store_id: store.id,
  path: "/archive/report-checks.md"
)
```

#### 避免覆盖其他写入方的修改 [#避免覆盖其他写入方的修改]

为避免覆盖并发写入，请先读取当前记忆，再传递 `content_sha256` 前置条件。只有当存储的内容哈希仍与读取时的哈希匹配时，更新才会生效；不匹配时返回 `409`。请重新读取并合并变更后重试，避免直接去掉前置条件覆盖其他写入。

cURL

```bash
curl --fail-with-body --silent --show-error --request POST "$AGENTAPI_BASE_URL/v1/memory_stores/$store_id/memories/$mem_id" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- > /dev/null <<EOF
{
  "content": "报告必须说明数据来源、统计范围和计算方法，并核对区域数据与合计。",
  "precondition": {"type": "content_sha256", "content_sha256": "$mem_sha"}
}
EOF
```

Python

```python
client.beta.memory_stores.memories.update(
    memory_id=mem.id,
    memory_store_id=store.id,
    content="报告必须说明数据来源、统计范围和计算方法，并核对区域数据与合计。",
    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)
```

TypeScript

````typescript
await client.beta.memoryStores.memories.update(mem.id, {
  memory_store_id: store.id,
  content: "报告必须说明数据来源、统计范围和计算方法，并核对区域数据与合计。",
  precondition: { type: "content_sha256", content_sha256: mem.content_sha256 }
});
```csharp
```csharp
await client.Beta.MemoryStores.Memories.Update(mem.ID, new()
{
    MemoryStoreID = store.ID,
    Content = "报告必须说明数据来源、统计范围和计算方法，并核对区域数据与合计。",
    Precondition = new BetaManagedAgentsPrecondition
    {
        Type = "content_sha256",
        ContentSha256 = mem.ContentSha256,
    },
});
````

Go

```go
_, err = client.Beta.MemoryStores.Memories.Update(ctx, mem.ID, anthropic.BetaMemoryStoreMemoryUpdateParams{
	MemoryStoreID: store.ID,
	Content:       anthropic.String("报告必须说明数据来源、统计范围和计算方法，并核对区域数据与合计。"),
	Precondition: anthropic.BetaManagedAgentsPreconditionParam{
		Type:          anthropic.BetaManagedAgentsPreconditionTypeContentSha256,
		ContentSha256: anthropic.String(mem.ContentSha256),
	},
})
if err != nil {
	panic(err)
}
```

Java

```java
client.beta().memoryStores().memories().update(
    mem.id(),
    MemoryUpdateParams.builder()
        .memoryStoreId(store.id())
        .content("报告必须说明数据来源、统计范围和计算方法，并核对区域数据与合计。")
        .precondition(
            BetaManagedAgentsPrecondition.builder()
                .type(BetaManagedAgentsPrecondition.Type.CONTENT_SHA256)
                .contentSha256(mem.contentSha256())
                .build()
        )
        .build()
);
```

PHP

```php
$client->beta->memoryStores->memories->update(
    $mem->id,
    memoryStoreID: $store->id,
    content: '报告必须说明数据来源、统计范围和计算方法，并核对区域数据与合计。',
    precondition: ['type' => 'content_sha256', 'content_sha256' => $mem->contentSha256],
);
```

Ruby

```ruby
client.beta.memory_stores.memories.update(
  mem.id,
  memory_store_id: store.id,
  content: "报告必须说明数据来源、统计范围和计算方法，并核对区域数据与合计。",
  precondition: {type: "content_sha256", content_sha256: mem.content_sha256}
)
```

### 移除不再使用的资料 [#移除不再使用的资料]

cURL

```bash
curl --fail-with-body --silent --show-error --request DELETE "$AGENTAPI_BASE_URL/v1/memory_stores/$store_id/memories/$mem_id" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
client.beta.memory_stores.memories.delete(
    mem.id,
    memory_store_id=store.id,
)
```

TypeScript

````typescript
await client.beta.memoryStores.memories.delete(mem.id, {
  memory_store_id: store.id
});
```csharp
```csharp
await client.Beta.MemoryStores.Memories.Delete(mem.ID, new()
{
    MemoryStoreID = store.ID,
});
````

Go

```go
_, err = client.Beta.MemoryStores.Memories.Delete(ctx, mem.ID, anthropic.BetaMemoryStoreMemoryDeleteParams{
	MemoryStoreID: store.ID,
})
if err != nil {
	panic(err)
}
```

Java

```java
client.beta().memoryStores().memories().delete(
    mem.id(),
    MemoryDeleteParams.builder().memoryStoreId(store.id()).build()
);
```

PHP

```php
$client->beta->memoryStores->memories->delete($mem->id, memoryStoreID: $store->id);
```

Ruby

```ruby
client.beta.memory_stores.memories.delete(
  mem.id,
  memory_store_id: store.id
)
```

## 退出复用与清理资料 [#退出复用与清理资料]

项目结束或约定不再适用时，先停止为新任务选择该存储，再决定归档或删除。归档保留资料、停止新会话引用及后续写回；删除用于永久移除存储、记忆和版本。需要长期审计的内容应在删除前导出。

以下示例用于找到待清理的存储并归档。分页和响应格式见 [API 通用约定](/products/agentapi/api/13618-agentapi-api-conventions)。

### 列出存储 [#列出存储]

列出当前账户下的记忆存储。默认排除已归档的存储；传递 `include_archived: true` 可将其包含在内。

Portal 的 Memory Store 列表支持按名称或 ID 搜索，并与可用、已归档、全部状态筛选组合。关键词会去除首尾空白，按字面量包含关系匹配；搜索和状态筛选均在统计总数和分页前执行。对应接口为 `GET /portal/v1/memory_stores?page_index=1&q=关键词&status=active`，`status` 可取 `active` 或 `archived`；查看全部状态时省略 `status` 并传入 `include_archived=true`。`q` 和 `status` 必须与 `page_index` 一起使用，公开的 `GET /v1/memory_stores` 不接受这两个参数。

cURL

```bash
curl --request GET --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/memory_stores?include_archived=true" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
for memory_store in client.beta.memory_stores.list(include_archived=True):
    print(memory_store.id, memory_store.name, memory_store.archived_at)
```

TypeScript

````typescript
for await (const s of client.beta.memoryStores.list({ include_archived: true })) {
  console.log(s.id, s.name, s.archived_at);
}
```csharp
```csharp
var stores = await client.Beta.MemoryStores.List(new() { IncludeArchived = true });
await foreach (var s in stores.Paginate())
{
    Console.WriteLine($"{s.ID} {s.Name} {s.ArchivedAt}");
}
````

Go

```go
stores := client.Beta.MemoryStores.ListAutoPaging(ctx, anthropic.BetaMemoryStoreListParams{
	IncludeArchived: anthropic.Bool(true),
})
for stores.Next() {
	s := stores.Current()
	fmt.Println(s.ID, s.Name, s.ArchivedAt)
}
if err := stores.Err(); err != nil {
	panic(err)
}
```

Java

```java
for (var s : client.beta().memoryStores().list(
    MemoryStoreListParams.builder().includeArchived(true).build()
).autoPager()) {
    IO.println(s.id() + " " + s.name() + " " + s.archivedAt());
}
```

PHP

```php
foreach ($client->beta->memoryStores->list(includeArchived: true)->pagingEachItem() as $s) {
    // archivedAt 仅在已归档的存储上设置。
    $archivedAt = isset($s->archivedAt) ? $s->archivedAt->format(DATE_ATOM) : '';
    echo "{$s->id} {$s->name} {$archivedAt}\n";
}
```

Ruby

```ruby
client.beta.memory_stores.list(include_archived: true).auto_paging_each do |memory_store|
  puts "#{memory_store.id} #{memory_store.name} #{memory_store.archived_at}"
end
```

### 归档存储 [#归档存储]

归档会使存储变为只读，并阻止其被附加到新会话。归档是单向的；没有取消归档操作。已有会话再次执行时也不能向已归档的存储写回。

cURL

```bash
curl --fail-with-body --silent --show-error --request POST "$AGENTAPI_BASE_URL/v1/memory_stores/$store_id/archive" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
client.beta.memory_stores.archive(store.id)
```

TypeScript

````typescript
await client.beta.memoryStores.archive(store.id);
```csharp
```csharp
await client.Beta.MemoryStores.Archive(store.ID);
````

Go

```go
_, err = client.Beta.MemoryStores.Archive(ctx, store.ID, anthropic.BetaMemoryStoreArchiveParams{})
if err != nil {
	panic(err)
}
```

Java

```java
client.beta().memoryStores().archive(store.id());
```

PHP

```php
$client->beta->memoryStores->archive($store->id);
```

Ruby

```ruby
client.beta.memory_stores.archive(store.id)
```

要永久移除存储及其所有记忆和版本，请调用 `DELETE /v1/memory_stores/{memory_store_id}`。


# 访问 GitHub (/products/agentapi/development_guidelines/agentapi-data-and-integrations/13604-agentapi-data-and-integrations-github)



最近更新时间: 2026-10-14 17:39:34

GitHub 任务应先确定交付结果：读取代码形成审查结论，查询 Issue 等协作信息，还是修改代码并提交 Pull Request。三类任务需要的访问能力不同，仓库挂载和 GitHub MCP 分别提供文件操作与远程 API 调用能力。

## 按任务选择访问能力 [#按任务选择访问能力]

按任务选择接入路径：

| 任务                                        | 所需配置                                                        |
| ----------------------------------------- | ----------------------------------------------------------- |
| 读取代码并生成审查结论                               | 给会话添加 `github_repository` 资源，使用能读取目标仓库的令牌。                  |
| 查询 Issue、创建 Pull Request 或调用其他 GitHub API | 给智能体配置 GitHub MCP 工具，并通过会话引用的 Vault 提供 MCP 凭证。              |
| 修改代码并提交 Pull Request                      | 同时配置仓库资源和 GitHub MCP；仓库访问需允许提交和推送，MCP 访问需允许创建 Pull Request。 |

仓库挂载后，`claudecode`、`codex` 或已启用沙箱执行工具的 `native` 在云端沙箱中读取和修改代码。只做代码审查时，可以使用[已创建的智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)直接挂载仓库；最终报告可通过[文件交付](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)下载。

## 划定读取与写入权限 [#划定读取与写入权限]

仓库访问和 MCP 访问分别授权，凭证互不复用：

* 仓库资源用 `authorization_token` 克隆仓库。
* GitHub MCP 用会话引用 Vault 中与服务器 URL 匹配的凭证连接服务。

![GitHub 两条认证路径：仓库挂载用 github\_repository 资源的 authorization\_token 克隆仓库；GitHub MCP 由 AgentAPI 按 mcp\_server\_url 从会话引用的 Vault 匹配凭证注入](/docs-assets/products/agentapi/development_guidelines/agentapi-data-and-integrations/13604-agentapi-data-and-integrations-github/FtNFrUCMmpOB0ISbLbGcSSAGjOAN-26659cb61a1d.webp)

代码审查通常只需读取权限；提交变更才需要写入权限。先限定任务可访问的仓库，再为所需操作授予权限：

* 读取私有仓库：至少需要仓库内容的读取权限。
* 提交和推送：授予仓库内容的写入权限。
* 创建 Pull Request 或 Issue：再分别授予对应资源的读写权限。

> 说明
>
> 优先使用细粒度个人访问令牌（fine-grained personal access token），将授权限定到任务需要的仓库和操作。

## 配置任务访问 [#配置任务访问]

完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)，从[七牛 MaaS 模型管理页](https://portal.qiniu.com/ai-inference/model)选择可用模型并设置 `AGENTAPI_MODEL_ID`。SDK 客户端初始化见[通过 API 构建](/products/agentapi/quick_start/13587-agentapi-quickstart)。下面示例组合了仓库资源与 GitHub MCP，适用于修改代码后提交 Pull Request 的任务。

### 配置 GitHub MCP [#配置-github-mcp]

远程协作操作由 GitHub MCP 工具完成。以下智能体使用 `claudecode` 并显式允许工具执行；服务器地址写入智能体，认证凭证留在 Vault。需要应用逐次确认 MCP 操作时，使用 `native` 和 `always_ask`，并处理[工具确认事件](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)。

cURL

```bash
agent_id=$(curl --request POST "$AGENTAPI_BASE_URL/v1/agents" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<JSON | jq -r '.id'
{
  "name": "代码审查助手",
  "runtime": "claudecode",
  "model": {"id": "$AGENTAPI_MODEL_ID"},
  "system": "You are a code review assistant with access to GitHub.",
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  ],
  "tools": [
    {"type": "agent_toolset_20260401"},
    {
      "type": "mcp_toolset",
      "mcp_server_name": "github",
      "default_config": {"permission_policy": {"type": "always_allow"}}
    }
  ]
}
JSON
)
```

Python

```python
import os

agent = client.beta.agents.create(
    name="代码审查助手",
    model={"id": os.environ["AGENTAPI_MODEL_ID"]},
    system="You are a code review assistant with access to GitHub.",
    mcp_servers=[
        {
            "type": "url",
            "name": "github",
            "url": "https://api.githubcopilot.com/mcp/",
        },
    ],
    tools=[
        {"type": "agent_toolset_20260401"},
        {
            "type": "mcp_toolset",
            "mcp_server_name": "github",
            "default_config": {"permission_policy": {"type": "always_allow"}},
        },
    ],
    extra_body={"runtime": "claudecode"},
)
```

TypeScript

````typescript
const params = {
  name: "代码审查助手",
  model: { id: process.env.AGENTAPI_MODEL_ID! },
  system: "You are a code review assistant with access to GitHub.",
  mcp_servers: [
    {
      type: "url",
      name: "github",
      url: "https://api.githubcopilot.com/mcp/",
    },
  ],
  tools: [
    { type: "agent_toolset_20260401" },
    {
      type: "mcp_toolset",
      mcp_server_name: "github",
      default_config: { permission_policy: { type: "always_allow" } },
    },
  ]
} satisfies Parameters<typeof client.beta.agents.create>[0];
const agent = await client.beta.agents.create(params, {
  body: { ...params, runtime: "claudecode" },
});
```csharp
```csharp
using Anthropic.Models.Beta.Agents;
using System.Text.Json;
using System.Linq;
using System;
var parameters = new AgentCreateParams
{
    Name = "代码审查助手",
    Model = new BetaManagedAgentsModelConfigParams { ID = Environment.GetEnvironmentVariable("AGENTAPI_MODEL_ID")! },
    System = "You are a code review assistant with access to GitHub.",
    McpServers =
    [
        new() { Type = "url", Name = "github", Url = "https://api.githubcopilot.com/mcp/" },
    ],
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = "agent_toolset_20260401",
        },
        new BetaManagedAgentsMcpToolsetParams
        {
            Type = "mcp_toolset",
            McpServerName = "github",
            DefaultConfig = new()
            {
                PermissionPolicy = new BetaManagedAgentsAlwaysAllowPolicy { Type = "always_allow" },
            },
        },
    ],
};
var body = parameters.RawBodyData.ToDictionary(entry => entry.Key, entry => entry.Value);
body["runtime"] = JsonSerializer.SerializeToElement("claudecode");
parameters = AgentCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body);
var agent = await client.Beta.Agents.Create(parameters);
````

Go

```go
import "github.com/anthropics/anthropic-sdk-go/option"
import "os"
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "代码审查助手",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: os.Getenv("AGENTAPI_MODEL_ID"),
	},
	System: anthropic.String("You are a code review assistant with access to GitHub."),
	MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{
		{
			Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,
			Name: "github",
			URL:  "https://api.githubcopilot.com/mcp/",
		},
	},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{
		{
			OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
				Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			},
		},
		{
			OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{
				Type:          anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset,
				MCPServerName: "github",
			},
		},
	},
}, option.WithJSONSet("runtime", "claudecode"),
    option.WithJSONSet("tools.1.default_config.permission_policy", map[string]string{"type": "always_allow"}))
if err != nil {
	panic(err)
}
```

Java

```java
import com.anthropic.core.JsonValue;
var agent = client.beta().agents().create(AgentCreateParams.builder()
    .name("代码审查助手")
    .model(BetaManagedAgentsModelConfigParams.builder().id(System.getenv("AGENTAPI_MODEL_ID")).build())
    .system("You are a code review assistant with access to GitHub.")
    .addMcpServer(BetaManagedAgentsUrlMcpServerParams.builder()
        .type(BetaManagedAgentsUrlMcpServerParams.Type.URL)
        .name("github")
        .url("https://api.githubcopilot.com/mcp/")
        .build())
    .addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
        .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
        .build())
    .addTool(BetaManagedAgentsMcpToolsetParams.builder()
        .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET)
        .mcpServerName("github")
        .defaultConfig(BetaManagedAgentsMcpToolsetDefaultConfigParams.builder()
            .permissionPolicy(BetaManagedAgentsAlwaysAllowPolicy.builder()
                .type(BetaManagedAgentsAlwaysAllowPolicy.Type.ALWAYS_ALLOW)
                .build())
            .build())
        .build())
    .putAdditionalBodyProperty("runtime", JsonValue.from("claudecode"))
        .build());
```

PHP

```php
$agent = $client->beta->agents->create(
    name: '代码审查助手',
    model: ['id' => getenv('AGENTAPI_MODEL_ID')],
    system: 'You are a code review assistant with access to GitHub.',
    mcpServers: [
        [
            'type' => 'url',
            'name' => 'github',
            'url' => 'https://api.githubcopilot.com/mcp/',
        ],
    ],
    tools: [
        ['type' => 'agent_toolset_20260401'],
        [
            'type' => 'mcp_toolset',
            'mcpServerName' => 'github',
            'defaultConfig' => ['permissionPolicy' => ['type' => 'always_allow']],
        ],
    ],
    requestOptions: ['extraBodyParams' => ['runtime' => 'claudecode']],
);
```

Ruby

```ruby
agent = client.beta.agents.create(
  name: "代码审查助手",
  model: {id: ENV.fetch("AGENTAPI_MODEL_ID")},
  system_: "You are a code review assistant with access to GitHub.",
  mcp_servers: [
    {
      type: "url",
      name: "github",
      url: "https://api.githubcopilot.com/mcp/"
    }
  ],
  tools: [
    {type: "agent_toolset_20260401"},
    {
      type: "mcp_toolset",
      mcp_server_name: "github",
      default_config: {permission_policy: {type: "always_allow"}}
    }
  ],
  request_options: {extra_body: {runtime: "claudecode"}}
)
```

### 挂载仓库并创建会话 [#挂载仓库并创建会话]

会话把仓库、云端环境和 MCP 授权组合成一次任务。先创建[云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)；使用上面的智能体时，再按[凭证管理](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13606-agentapi-data-and-integrations-vaults)创建 `static_bearer` 或 `mcp_oauth` 凭证，确保 `mcp_server_url` 与智能体中的 GitHub MCP URL 匹配。

下面的会话用仓库令牌克隆代码，通过 `vault_ids` 提供 MCP 授权。将仓库 URL 和 `GITHUB_TOKEN` 替换为任务目标及其令牌。只挂载仓库时，引用不含 MCP 的智能体并省略 `vault_ids`；AgentAPI 请求仍使用 MaaS API Key。

cURL

```bash
session_id=$(curl --request POST "$AGENTAPI_BASE_URL/v1/sessions" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<JSON | jq -r '.id'
{
  "agent": {"type": "agent", "id": "$agent_id", "version": 1},
  "environment_id": "$environment_id",
  "vault_ids": ["$vault_id"],
  "resources": [
    {
      "type": "github_repository",
      "url": "https://github.com/org/repo",
      "mount_path": "/workspace/repo",
      "authorization_token": "$GITHUB_TOKEN"
    }
  ]
}
JSON
)
```

Python

```python
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
    resources=[
        {
            "type": "github_repository",
            "url": "https://github.com/org/repo",
            "mount_path": "/workspace/repo",
            "authorization_token": "ghp_your_github_token",
        },
    ],
)
```

TypeScript

````typescript
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  vault_ids: [vault.id],
  resources: [
    {
      type: "github_repository",
      url: "https://github.com/org/repo",
      mount_path: "/workspace/repo",
      authorization_token: "ghp_your_github_token",
    },
  ],
});
```csharp
```csharp
var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    VaultIds = [vault.ID],
    Resources =
    [
        new BetaManagedAgentsGitHubRepositoryResourceParams
        {
            Type = "github_repository",
            Url = "https://github.com/org/repo",
            MountPath = "/workspace/repo",
            AuthorizationToken = "ghp_your_github_token",
        },
    ],
});
````

Go

```go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
		Agent:         anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
		EnvironmentID: environment.ID,
		VaultIDs:      []string{vault.ID},
	Resources: []anthropic.BetaSessionNewParamsResourceUnion{
		{
			OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{
				Type:               anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository,
				URL:                "https://github.com/org/repo",
				MountPath:          anthropic.String("/workspace/repo"),
				AuthorizationToken: "ghp_your_github_token",
			},
		},
	},
})
if err != nil {
	panic(err)
}
```

Java

```java
var session = client.beta().sessions().create(SessionCreateParams.builder()
    .agent(agent.id())
    .environmentId(environment.id())
    .vaultIds(List.of(vault.id()))
    .addResource(BetaManagedAgentsGitHubRepositoryResourceParams.builder()
        .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY)
        .url("https://github.com/org/repo")
        .mountPath("/workspace/repo")
        .authorizationToken("ghp_your_github_token")
        .build())
    .build());
```

PHP

```php
$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
    vaultIDs: [$vault->id],
    resources: [
        [
            'type' => 'github_repository',
            'url' => 'https://github.com/org/repo',
            'mountPath' => '/workspace/repo',
            'authorizationToken' => 'ghp_your_github_token',
        ],
    ],
);
```

Ruby

```ruby
session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id,
  vault_ids: [vault.id],
  resources: [
    {
      type: "github_repository",
      url: "https://github.com/org/repo",
      mount_path: "/workspace/repo",
      authorization_token: "ghp_your_github_token"
    }
  ]
)
```

`github_repository` 资源接受以下字段：

| 字段                    | 描述                                                                                                                                                                   |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                | 必填。必须为 `"github_repository"`。                                                                                                                                        |
| `url`                 | 必填。仓库的 HTTPS 克隆 URL，例如 `https://github.com/&lt;owner&gt;/&lt;repo&gt;`。必须使用 `https`（SSH 等非 https URL 一律拒绝），且主机不能是 localhost 或私网地址；结尾的 `.git` 会自动去除。                  |
| `authorization_token` | 必填。用于克隆仓库的 GitHub 令牌。它不会在 API 响应中回显。请参阅[令牌权限](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13604-agentapi-data-and-integrations-github)。 |
| `mount_path`          | 可选。沙箱内用于克隆仓库的绝对路径，不能为根目录或包含 `..`。默认为 `/workspace/&lt;repo-name&gt;`。                                                                                                 |
| `checkout`            | 可选。要检出的分支（`{"type": "branch", "name": "main"}`）或提交（`{"type": "commit", "sha": "..."}`）。默认为仓库的默认分支。                                                                   |

挂载仓库后，运行时会按自身规则发现仓库级技能：Claude Code 读取 `.claude/skills`，Codex 读取 `.agents/skills`。AgentAPI 不会替运行时扫描这些目录；技能只在会话启动时发现一次，依据是当时检出的仓库状态。请参阅[从 GitHub 仓库加载技能](/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills)。

### 为跨仓库任务配置材料 [#为跨仓库任务配置材料]

分析多个项目的接口关系时，为每个仓库添加一个 `resources` 条目。每项资源可以使用独立的 `authorization_token`，例如来自不同 GitHub App installation 的短期 token；任务要求中应明确各仓库的用途和允许修改的范围。

cURL

```bash
resources='[
  {
    "type": "github_repository",
    "url": "https://github.com/org/frontend",
    "mount_path": "/workspace/frontend",
    "authorization_token": "ghp_frontend_repository_token"
  },
  {
    "type": "github_repository",
    "url": "https://github.com/org/backend",
    "mount_path": "/workspace/backend",
    "authorization_token": "ghp_backend_repository_token"
  }
]'
```

Python

```python
resources = [
    {
        "type": "github_repository",
        "url": "https://github.com/org/frontend",
        "mount_path": "/workspace/frontend",
        "authorization_token": "ghp_frontend_repository_token",
    },
    {
        "type": "github_repository",
        "url": "https://github.com/org/backend",
        "mount_path": "/workspace/backend",
        "authorization_token": "ghp_backend_repository_token",
    },
]
```

TypeScript

````typescript
const resources = [
  {
    type: "github_repository",
    url: "https://github.com/org/frontend",
    mount_path: "/workspace/frontend",
    authorization_token: "ghp_frontend_repository_token",
  },
  {
    type: "github_repository",
    url: "https://github.com/org/backend",
    mount_path: "/workspace/backend",
    authorization_token: "ghp_backend_repository_token",
  },
];
```csharp
```csharp
BetaManagedAgentsGitHubRepositoryResourceParams[] resources =
[
    new()
    {
        Type = "github_repository",
        Url = "https://github.com/org/frontend",
        MountPath = "/workspace/frontend",
        AuthorizationToken = "ghp_frontend_repository_token",
    },
    new()
    {
        Type = "github_repository",
        Url = "https://github.com/org/backend",
        MountPath = "/workspace/backend",
        AuthorizationToken = "ghp_backend_repository_token",
    },
];
````

Go

```go
resources := []anthropic.BetaSessionNewParamsResourceUnion{
	{
		OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{
			Type:               anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository,
			URL:                "https://github.com/org/frontend",
			MountPath:          anthropic.String("/workspace/frontend"),
			AuthorizationToken: "ghp_frontend_repository_token",
		},
	},
	{
		OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{
			Type:               anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository,
			URL:                "https://github.com/org/backend",
			MountPath:          anthropic.String("/workspace/backend"),
			AuthorizationToken: "ghp_backend_repository_token",
		},
	},
}
```

Java

```java
var resources = List.of(
    BetaManagedAgentsGitHubRepositoryResourceParams.builder()
        .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY)
        .url("https://github.com/org/frontend")
        .mountPath("/workspace/frontend")
        .authorizationToken("ghp_frontend_repository_token")
        .build(),
    BetaManagedAgentsGitHubRepositoryResourceParams.builder()
        .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY)
        .url("https://github.com/org/backend")
        .mountPath("/workspace/backend")
        .authorizationToken("ghp_backend_repository_token")
        .build());
```

PHP

```php
$resources = [
    [
        'type' => 'github_repository',
        'url' => 'https://github.com/org/frontend',
        'mountPath' => '/workspace/frontend',
        'authorizationToken' => 'ghp_frontend_repository_token',
    ],
    [
        'type' => 'github_repository',
        'url' => 'https://github.com/org/backend',
        'mountPath' => '/workspace/backend',
        'authorizationToken' => 'ghp_backend_repository_token',
    ],
];
```

Ruby

```ruby
resources = [
  {
    type: "github_repository",
    url: "https://github.com/org/frontend",
    mount_path: "/workspace/frontend",
    authorization_token: "ghp_frontend_repository_token"
  },
  {
    type: "github_repository",
    url: "https://github.com/org/backend",
    mount_path: "/workspace/backend",
    authorization_token: "ghp_backend_repository_token"
  }
]
```

## 提交变更并验收结果 [#提交变更并验收结果]

配置完成后，在任务要求中写清变更目标、验证要求和交付形式。以下示例要求修复类型错误并创建拉取请求：智能体修改代码、创建分支、提交并推送，再调用 GitHub MCP。执行前需具备仓库写入权限和 Pull Request 权限，见权限配置。

发送消息成功只表示任务已接收。继续读取[事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)，检查代码修改、验证命令和远程操作是否出错；任务结束后打开返回的 Pull Request 链接，核对目标仓库、分支和变更内容。只要求审查报告的任务则检查报告文件，无需执行推送和创建 Pull Request。

cURL

```bash
curl -fsS "$AGENTAPI_BASE_URL/v1/sessions/$session_id/events" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  -o /dev/null \
  --data @- <<JSON
{
  "events": [
    {
      "type": "user.message",
      "input": {"parts": [
        {
          "type": "text",
          "text": "修复 src/utils.ts 中的类型错误，运行相关测试，将变更提交到新分支并推送，然后创建拉取请求，在最终回复中返回链接。"
        }
      ]}
    }
  ]
}
JSON
```

Python

```python
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {
                    "type": "text",
                    "text": "修复 src/utils.ts 中的类型错误，运行相关测试，将变更提交到新分支并推送，然后创建拉取请求，在最终回复中返回链接。",
                },
            ],
        },
    ],
)
```

TypeScript

````typescript
await client.beta.sessions.events.send(session.id, {
  events: [
    {
      type: "user.message",
      content: [
        {
          type: "text",
          text: "修复 src/utils.ts 中的类型错误，运行相关测试，将变更提交到新分支并推送，然后创建拉取请求，在最终回复中返回链接。",
        },
      ],
    },
  ],
});
```csharp
```csharp
await client.Beta.Sessions.Events.Send(session.ID, new()
{
    Events =
    [
        new BetaManagedAgentsUserMessageEventParams
        {
            Type = "user.message",
            Content =
            [
                new BetaManagedAgentsTextBlock
                {
                    Type = "text",
                    Text = "修复 src/utils.ts 中的类型错误，运行相关测试，将变更提交到新分支并推送，然后创建拉取请求，在最终回复中返回链接。",
                },
            ],
        },
    ],
});
````

Go

```go
_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
	Events: []anthropic.BetaManagedAgentsEventParamsUnion{
		{
			OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
				Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
				Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{
					{
						OfText: &anthropic.BetaManagedAgentsTextBlockParam{
							Type: anthropic.BetaManagedAgentsTextBlockTypeText,
							Text: "修复 src/utils.ts 中的类型错误，运行相关测试，将变更提交到新分支并推送，然后创建拉取请求，在最终回复中返回链接。",
						},
					},
				},
			},
		},
	},
})
if err != nil {
	panic(err)
}
```

Java

```java
client.beta().sessions().events().send(session.id(), EventSendParams.builder()
    .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
        .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
        .addContent(BetaManagedAgentsTextBlock.builder()
            .type(BetaManagedAgentsTextBlock.Type.TEXT)
            .text("修复 src/utils.ts 中的类型错误，运行相关测试，将变更提交到新分支并推送，然后创建拉取请求，在最终回复中返回链接。")
            .build())
        .build())
    .build());
```

PHP

```php
$client->beta->sessions->events->send(
    $session->id,
    events: [
        [
            'type' => 'user.message',
            'content' => [
                [
                    'type' => 'text',
                    'text' => '修复 src/utils.ts 中的类型错误，运行相关测试，将变更提交到新分支并推送，然后创建拉取请求，在最终回复中返回链接。',
                ],
            ],
        ],
    ],
);
```

Ruby

```ruby
client.beta.sessions.events.send_(
  session.id,
  events: [
    {
      type: "user.message",
      content: [
        {
          type: "text",
          text: "修复 src/utils.ts 中的类型错误，运行相关测试，将变更提交到新分支并推送，然后创建拉取请求，在最终回复中返回链接。"
        }
      ]
    }
  ]
)
```

## 维护后续任务的授权 [#维护后续任务的授权]

复用会话继续工作时，先确认仓库令牌仍可用于后续操作。需要轮换时，通过 `resources.list` 找到目标仓库的资源 `id`，再更新其授权令牌；会话创建响应也会返回该 ID。

* 更新只影响选中的仓库，不会覆盖其他仓库的 token。
* 复用会话不会自动轮换 token。
* 仓库在会话生命周期内保持挂载；更换仓库需创建新会话。

cURL

```bash
# 列出会话上的资源
repo_resource_id=$(curl --request GET "$AGENTAPI_BASE_URL/v1/sessions/$session_id/resources" \
  --header "x-api-key: $AGENTAPI_API_KEY" | jq -r '.data[] | select(.type == "github_repository") | .id')
echo "$repo_resource_id"  # "sr_01ABC..."

# 轮换授权令牌
curl --request POST "$AGENTAPI_BASE_URL/v1/sessions/$session_id/resources/$repo_resource_id" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --output /dev/null \
  --data @- <<JSON
{
  "authorization_token": "ghp_your_new_github_token"
}
JSON
```

Python

```python
# 列出会话上的资源
listed = client.beta.sessions.resources.list(session.id)
repo_resource_id = listed.data[0].id
print(repo_resource_id)  # "sr_01ABC..."

# 轮换授权令牌
client.beta.sessions.resources.update(
    repo_resource_id,
    session_id=session.id,
    authorization_token="ghp_your_new_github_token",
)
```

TypeScript

````typescript
// 列出会话上的资源
const listed = await client.beta.sessions.resources.list(session.id);
const repoResource = listed.data.find(
  (entry) => entry.type === "github_repository",
);
if (!repoResource) {
  throw new Error("No GitHub repository resource on the session");
}
const repoResourceId = repoResource.id;
console.log(repoResourceId); // "sr_01ABC..."

// 轮换授权令牌
await client.beta.sessions.resources.update(repoResourceId, {
  session_id: session.id,
  authorization_token: "ghp_your_new_github_token",
});
```csharp
```csharp
// 列出会话上的资源
var listed = await client.Beta.Sessions.Resources.List(session.ID);
var repoResourceId = (await listed.Paginate().FirstAsync()).ID;
Console.WriteLine(repoResourceId); // "sr_01ABC..."

// 轮换授权令牌
await client.Beta.Sessions.Resources.Update(repoResourceId, new()
{
    SessionID = session.ID,
    AuthorizationToken = "ghp_your_new_github_token",
});
````

Go

```go
// 列出会话上的资源
listed, err := client.Beta.Sessions.Resources.List(ctx, session.ID, anthropic.BetaSessionResourceListParams{})
if err != nil {
	panic(err)
}
repoResourceID := listed.Data[0].ID
fmt.Println(repoResourceID) // "sr_01ABC..."

// 轮换授权令牌
_, err = client.Beta.Sessions.Resources.Update(ctx, repoResourceID, anthropic.BetaSessionResourceUpdateParams{
	SessionID:          session.ID,
	AuthorizationToken: "ghp_your_new_github_token",
})
if err != nil {
	panic(err)
}
```

Java

```java
// 列出会话上的资源
var listed = client.beta().sessions().resources().list(session.id());
var repoResourceId = listed.data().getFirst().asGitHubRepository().id();
IO.println(repoResourceId);  // "sr_01ABC..."

// 轮换授权令牌
client.beta().sessions().resources().update(repoResourceId, ResourceUpdateParams.builder()
    .sessionId(session.id())
    .authorizationToken("ghp_your_new_github_token")
    .build());
```

PHP

```php
// 列出会话上的资源
$listed = $client->beta->sessions->resources->list($session->id);
$repoResourceId = $listed->data[0]->id;
echo $repoResourceId, PHP_EOL; // "sr_01ABC..."

// 轮换授权令牌
$client->beta->sessions->resources->update(
    $repoResourceId,
    sessionID: $session->id,
    authorizationToken: 'ghp_your_new_github_token',
);
```

Ruby

```ruby
# 列出会话上的资源
listed = client.beta.sessions.resources.list(session.id)
repo_resource_id = listed.data.first.id
puts repo_resource_id # "sr_01ABC..."

# 轮换授权令牌
client.beta.sessions.resources.update(
  repo_resource_id,
  session_id: session.id,
  authorization_token: "ghp_your_new_github_token"
)
```

## 后续步骤 [#后续步骤]

* [事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)：跟踪代码任务执行，处理错误与工具确认

* [MCP 连接器](/products/agentapi/development_guidelines/agentapi-agent-configuration/13592-agentapi-agent-configuration-mcp)：配置远程工具与连接授权

* [附加和下载文件](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)：补充参考材料并下载审查报告


# Webhook 通知 (/products/agentapi/development_guidelines/agentapi-data-and-integrations/13605-agentapi-data-and-integrations-webhooks)



最近更新时间: 2026-10-13 15:43:57

应用需要在会话停止、定时部署触发或资源变更后更新业务状态时，可以配置 Webhook。AgentAPI 将订阅事件以 JSON POST 发送到应用的接收地址，无需一直保持连接。

Webhook 提供资源与生命周期通知，不包含完整回答、文本增量或逐条工具调用。展示实时执行进度时使用[会话事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)；收到通知后按资源 ID 查询详情和历史事件，确认实际业务结果。

## 创建通知端点 [#创建通知端点]

1. 准备公网 HTTPS 接收地址，例如 `https://hooks.example.com/agentapi`。仅支持 443 端口；域名必须只解析到公网地址，不支持 IP 地址、内网域名或 HTTP 重定向。
2. 打开 [AgentAPI Portal 的 Webhook 页面](https://portal.qiniu.com/agentapi/webhooks)，选择资源所在的地域。端点与订阅属于当前账户和当前地域，其他地域需要单独配置。
3. 点击“创建 Webhook”，在右侧抽屉中填写接收地址、可选描述，并选择需要的事件。事件按资源类别分组，可使用每组的“全选”勾选该组可新增的事件，也可取消整组选择。至少选择一项；新增订阅只提供已有触发点的事件。
4. 创建成功后，在“Webhook 签名密钥”弹窗中点击“复制密钥”，将一次性显示的 `whsec_...` 配置到接收服务中，用于验证通知来源和内容。完成配置后关闭弹窗；“关闭”按钮不执行保存，后续编辑和列表也不会再次返回密钥。丢失时需要轮换。
5. 在同一地域执行一次对应操作，例如更新智能体，检查接收服务是否已验证签名并可靠保存事件。页面上的“已启用”仅表示允许投递，不代表接收服务已通过验证。

端点归属于当前登录账户和当前地域。Portal 从登录身份确定 owner，用户无需填写任何租户字段；不同账户之间的端点和事件投递相互隔离。

签名密钥用于验证 AgentAPI 发来的通知，与[调用 AgentAPI 的 MaaS API Key](/products/agentapi/quick_start/13585-agentapi-access)用途不同。Webhook 管理由已登录的 Portal 通过专用控制面完成；MaaS API Key 不提供端点管理权限。页面无法加载或提示服务不可用时，需联系服务管理员检查配置，无需完成服务开通流程。

列表展示接收地址、订阅数量、状态和连续失败次数。点击表格内容、接收地址或在“操作”菜单中选择“编辑”，可在侧栏按资源分组查看和修改订阅；菜单还提供启停、删除和签名密钥轮换。停用原因可在状态提示和编辑侧栏查看。当前不提供用户侧投递历史，需在接收服务保存收到的消息与处理结果。

## 验证签名并读取资源 [#验证签名并读取资源]

每个请求包含三个签名头：

| 请求头                 | 内容                                       |
| ------------------- | ---------------------------------------- |
| `webhook-id`        | `whe_...` 事件 ID；同一事件的重试保持不变。             |
| `webhook-timestamp` | 本次发送时的 Unix 秒数；重试会重新签名。                  |
| `webhook-signature` | `v1,&lt;Base64 签名&gt;`，签名使用 HMAC-SHA256。 |

去掉密钥的 `whsec_` 前缀并 Base64 解码，得到 HMAC 密钥。签名输入是 `webhook-id + "." + webhook-timestamp + "." + 原始请求体` 的字节序列。必须使用 JSON 解码前的原始字节，不能重新序列化 JSON 后验签。建议同时拒绝与接收时间相差超过 5 分钟的请求，并保持服务器时钟同步；此时间窗口校验由接收端执行。

示例通知：

```json
{
  "type": "event",
  "id": "whe_example",
  "created_at": "2026-10-10T06:30:00Z",
  "data": {
    "type": "session.status_idled",
    "id": "sess_example"
  }
}
```

外层 `id` 用于去重，`data.type` 是订阅类型，`data.id` 是发生变化的资源 ID。线程事件另含 `session_thread_id`，凭证事件另含 `vault_id`。Webhook 的 `session.status_idled` 与 SSE 的 `session.status_idle` 名称不同，不应直接复用 SSE 类型判断。

例如，会话停止通知不能证明任务成功：用 `data.id` 查询会话事件中的停止原因、回答和产物。请求使用资源所在地域的服务地址与已绑定 API Key：

```bash
curl --fail-with-body -sS \
  "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events?limit=100" \
  -H "x-api-key: $AGENTAPI_API_KEY"
```

根据[接入准备](/products/agentapi/quick_start/13585-agentapi-access)选择 `AGENTAPI_BASE_URL`；将 `$SESSION_ID` 替换为通知中的 `data.id`，有下一页时继续读取。删除事件对应的资源可能已无法查询，应按删除通知清理本地状态。

### 接收服务示例 [#接收服务示例]

下面的 Python 标准库示例验证原始请求体、时间戳和签名，然后把通知提交到带唯一事件 ID 的 SQLite 持久收件箱，提交成功后才返回 204。业务处理由另一个 worker 消费 `pending` 记录；不是收到 HTTP 请求就直接完成业务操作。

运行前设置 `AGENTAPI_WEBHOOK_SECRET` 和 `WEBHOOK_INBOX_PATH`，后者指向可写的持久磁盘路径。通过 HTTPS 反向代理把公网 443 地址转发至 `127.0.0.1:8000/agentapi`，保留原始请求体和三个签名头。此示例仅提供本地接收与持久化，不实现公网 TLS 部署或业务 worker。

```python
import base64
import hashlib
import hmac
import json
import os
import sqlite3
import time
from http.server import BaseHTTPRequestHandler, HTTPServer

secret = os.environ["AGENTAPI_WEBHOOK_SECRET"]
if not secret.startswith("whsec_"):
    raise ValueError("expected a whsec_ signing secret")
key = base64.b64decode(secret[6:], validate=True)
if len(key) != 32:
    raise ValueError("expected a 32-byte signing key")

inbox_path = os.environ["WEBHOOK_INBOX_PATH"]
with sqlite3.connect(inbox_path) as db:
    db.execute("PRAGMA journal_mode=WAL")
    db.execute("""
        CREATE TABLE IF NOT EXISTS webhook_inbox (
            event_id TEXT PRIMARY KEY,
            body BLOB NOT NULL,
            received_at INTEGER NOT NULL,
            status TEXT NOT NULL DEFAULT 'pending'
        )
    """)


def verify(headers, body):
    event_id = headers.get("webhook-id", "")
    timestamp = headers.get("webhook-timestamp", "")
    signatures = headers.get("webhook-signature", "")
    if not event_id or not timestamp.isascii() or not timestamp.isdigit():
        raise ValueError("missing or invalid signature headers")
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError("signature timestamp outside tolerance")
    signed = event_id.encode("utf-8") + b"." + timestamp.encode("ascii") + b"." + body
    expected = hmac.new(key, signed, hashlib.sha256).digest()
    for entry in signatures.split():
        version, separator, encoded = entry.partition(",")
        if version != "v1" or not separator:
            continue
        try:
            actual = base64.b64decode(encoded, validate=True)
        except ValueError:
            continue
        if hmac.compare_digest(expected, actual):
            return event_id
    raise ValueError("invalid signature")


class Receiver(BaseHTTPRequestHandler):
    def do_POST(self):
        if self.path != "/agentapi":
            self.send_error(404)
            return
        try:
            size = int(self.headers.get("Content-Length", "0"))
        except ValueError:
            self.send_error(400)
            return
        if not 0 < size <= 1024 * 1024:
            self.send_error(413)
            return
        self.connection.settimeout(10)
        try:
            body = self.rfile.read(size)
        except OSError:
            self.send_error(400)
            return
        if len(body) != size:
            self.send_error(400)
            return
        try:
            event_id = verify(self.headers, body)
        except ValueError:
            self.send_error(401)
            return
        try:
            event = json.loads(body)
            if (not isinstance(event, dict)
                    or event.get("type") != "event"
                    or event.get("id") != event_id
                    or not isinstance(event.get("data"), dict)):
                raise ValueError("invalid envelope")
        except (ValueError, UnicodeError):
            self.send_error(400)
            return
        try:
            with sqlite3.connect(inbox_path, timeout=5) as db:
                db.execute("PRAGMA synchronous=FULL")
                db.execute("""
                    INSERT INTO webhook_inbox (event_id, body, received_at)
                    VALUES (?, ?, ?)
                    ON CONFLICT(event_id) DO NOTHING
                """, (event_id, body, int(time.time())))
            # Exiting the transaction commits before acknowledgement.
        except sqlite3.Error:
            self.send_error(503)
            return
        self.send_response(204)
        self.end_headers()


HTTPServer(("127.0.0.1", 8000), Receiver).serve_forever()
```

业务 worker 应在完成可恢复的业务更新后再标记 `done`。同库的业务状态和消费进度可在一个事务中提交；调用第三方服务时使用业务幂等键或事务性 outbox，避免崩溃后重复执行。不要先把 ID 记为“处理完成”再执行业务操作。收件箱存储、访问权限、保留期限和 worker 失败重试由接收应用维护。

## 处理重试、重复与乱序 [#处理重试重复与乱序]

* 确认与重试：任意 2xx 表示确认。网络错误、超时或非 2xx 会触发有限重试；每条投递最多尝试 3 次，退避使用抖动，范围限制在 5–120 秒。只有可靠持久化、入队或事务性处理成功后才应返回 2xx。
* 重复投递：请求处理完成但确认响应丢失等情况可能产生重复。按外层 `id` 或 `webhook-id` 去重，不能按资源 ID 去重，同一资源可以有多个变更事件。
* 乱序：通知不保证顺序。需要当前状态时回查资源，避免较晚收到的旧通知覆盖新状态；已删除资源应结合本地记录处理。
* 有限重试后的恢复：端点有 MySQL 持久投递队列，可跨 AgentAPI 重启恢复，但不会无限重试，也不提供用户侧投递历史、测试发送或手动重放。关键业务应定期查询资源或事件历史对账。

接收服务应快速完成可靠入队，耗时业务交给 worker。默认单次发送超时为 10 秒，服务管理员可以调整；不要依赖长时间同步处理来确认通知。

## 管理和恢复端点 [#管理和恢复端点]

列表显示接收地址、订阅数量、状态及连续失败尝试次数；订阅配置在编辑侧栏按资源分组展示，停用原因可在状态提示和编辑侧栏查看。连续失败尝试次数不等于总投递次数或失败事件数；任意成功确认会重置失败窗口和计数。

| 操作   | 结果与注意事项                                               |
| ---- | ----------------------------------------------------- |
| 编辑   | 修改 URL、描述或订阅。修改 URL 不会自动恢复已停用端点。                      |
| 停用   | 不再接收新通知，并放弃未完成投递。已在途的 HTTP 请求无法保证撤回。                  |
| 重新启用 | 修复接收服务后恢复后续新事件；停用、创建之前或未订阅期间的事件不补发。                   |
| 轮换密钥 | 只显示一次新密钥，后续投递立即使用新密钥，没有新旧密钥宽限期。接收端应及时切换；已在途请求可能仍带旧签名。 |
| 删除   | 永久移除端点并放弃未完成投递。已在途请求无法保证撤回；重新接入需创建新端点。                |

3xx 重定向或解析到非公网地址会使端点立即停用。其他持续失败默认经过 24 小时失败窗口后自动停用，该阈值由服务管理员配置；“最多 3 次投递”不表示三次失败就立即停用整个端点。自动停用后先排查 URL、DNS、公网网络、签名配置及响应状态，再重新启用，并通过资源查询补齐业务状态。

轮换前准备接收服务的密钥更新流程。若需要不中断切换，可先创建使用新密钥的端点，接收端分别验签并统一去重，确认新端点正常后删除旧端点。同一资源变更的重复通知仍应按事件 ID 幂等处理。

## 可订阅事件 [#可订阅事件]

当前目录含 38 类事件，按以下资源分组。事件目录列出可订阅能力，事件是否发生仍取决于对应资源操作或执行结果。

| 资源     | 类型                                                                                                                                                 |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| 会话状态   | `session.status_scheduled`、`session.status_run_started`、`session.status_idled`、`session.status_rescheduled`、`session.status_terminated`            |
| 会话与线程  | `session.thread_created`、`session.thread_idled`、`session.thread_terminated`、`session.outcome_evaluation_ended`、`session.updated`、`session.deleted` |
| Vault  | `vault.created`、`vault.archived`、`vault.deleted`                                                                                                   |
| 凭证     | `vault_credential.created`、`vault_credential.archived`、`vault_credential.deleted`、`vault_credential.refresh_failed`（尚无触发点）                         |
| 智能体    | `agent.created`、`agent.updated`、`agent.archived`、`agent.deleted`                                                                                   |
| 部署     | `deployment.created`、`deployment.updated`、`deployment.paused`、`deployment.unpaused`、`deployment.archived`、`deployment.deleted`（尚无触发点）              |
| 计划部署运行 | `deployment_run.started`、`deployment_run.succeeded`、`deployment_run.failed`                                                                        |
| 环境     | `environment.created`、`environment.updated`、`environment.archived`、`environment.deleted`                                                           |
| 持久记忆   | `memory_store.created`、`memory_store.archived`、`memory_store.deleted`                                                                              |

`deployment_run.*` 仅用于计划触发，不由手动运行触发；`succeeded` 表示成功创建并初始化会话，不代表智能体任务最终成功。会话的后续结果需同时订阅相应会话状态并读取事件，详见[定时部署](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13600-agentapi-sessions-and-tasks-scheduled-deployments)。

## Portal 管理接口边界 [#portal-管理接口边界]

Portal 使用以下专用控制面接口，身份由登录会话和 Portal 代理确定。这些路径不接受 MaaS API Key，不是应用直接调用的 CMA API；共享 `/v1` 不提供 Webhook 管理接口。

| 操作       | 方法与路径                                                       |
| -------- | ----------------------------------------------------------- |
| 列表与创建    | `GET` / `POST /portal/v1/webhook_endpoints`                 |
| 详情、更新和删除 | `GET` / `POST` / `DELETE /portal/v1/webhook_endpoints/{id}` |
| 轮换签名密钥   | `POST /portal/v1/webhook_endpoints/{id}/rotate_secret`      |
| 事件目录     | `GET /portal/v1/webhook_event_types`                        |

创建只提交 `url`、可选 `description` 和 `event_types`；更新可提交这些字段及 `status: enabled \| disabled`。服务端限制账户和地域范围，拒绝用户指定 owner 或租户 ID。列表使用 `limit` / `page` 游标；事件目录提供类型、分组、说明和 `emitted` 状态，便于区分历史可订阅项与当前有触发点的项。管理操作通过 Portal 完成，应用接收通知时无需调用这些控制面接口。


# 凭证管理 (/products/agentapi/development_guidelines/agentapi-data-and-integrations/13606-agentapi-data-and-integrations-vaults)



最近更新时间: 2026-10-13 15:31:53

智能体配置决定使用哪些工具，Vault（保管库）决定访问第三方 MCP 服务时使用谁的身份。两者分别配置：同一智能体可以处理多个业务用户的任务，由应用在创建会话时选择对应的 `vault_ids`。

例如，应用为不同业务用户生成协作系统摘要时，应分别保存用户授权，并在每次创建会话前校验授权归属。不要把第三方令牌放进任务消息或系统提示，也不要让客户端直接决定使用哪个 Vault。

在 Portal 中，您可以从会话详情的凭证库入口查看关联的 Vault 名称、ID 和归档状态，并进入凭证库详情。任务详情显示当前配置的凭证库；运行历史则显示该次会话的关联，后续修改任务配置不会改变历史关联 ID。信息暂时不可用时，页面保留 Vault ID 并提供重试。

## 划分调用身份与业务授权 [#划分调用身份与业务授权]

| 配置            | 负责的身份               | 应用需要控制的边界                                                              |
| ------------- | ------------------- | ---------------------------------------------------------------------- |
| MaaS API Key  | 调用 AgentAPI 的账户     | 保留在应用服务端，见[接入准备](/products/agentapi/quick_start/13585-agentapi-access) |
| 智能体的 MCP 配置   | 任务可使用的服务与工具         | 只声明任务需要的服务；声明服务器不代表已经获得第三方授权                                           |
| Vault 中的第三方凭证 | 访问 MCP 服务的业务用户或服务身份 | 维护用户与 Vault 的映射，创建会话前检查归属与权限                                           |

> 账户内的访问范围
>
> Vault 和凭证属于当前账户，账户内有权访问这些资源的 API Key 可以引用它们。`metadata` 中的业务用户 ID 只是标记，不形成用户级访问隔离。应用服务端必须校验客户端发起的任务与允许使用的 Vault，不能将 `vault_ids` 或 `external_user_id` 直接作为授权依据。

## 确定会话的访问范围 [#确定会话的访问范围]

创建会话前，核对三个条件：

1. 服务地址一致。 MCP 凭证通过 `mcp_server_url` 匹配智能体配置的服务地址；没有匹配凭证时，AgentAPI 会尝试匿名连接。
2. 第三方权限满足任务。 摘要查询通常只需读取权限；发布消息等写操作需另行授权。Vault 保存令牌，不会缩小令牌在第三方系统的权限。
3. 授权属于当前任务。 根据应用服务端的用户映射选出 Vault，再将 ID 传入会话；智能体配置可以复用，用户授权不能混用。

一个会话最多引用 50 个 Vault，执行时最多匹配并注入 20 个凭证。多个 Vault 匹配同一 MCP 地址时，`vault_ids` 中第一个匹配的 Vault 优先；应避免用数组顺序掩盖重复授权配置。

![保管库凭证注入 MCP 请求的流程](/docs-assets/products/agentapi/development_guidelines/agentapi-data-and-integrations/13606-agentapi-data-and-integrations-vaults/FpGzsu4EkTrIjHJQheWhGSnjfmBT-caa7331e05ae.webp)

## 配置并使用授权 [#配置并使用授权]

下面的示例按“保存业务用户标识 → 添加第三方令牌 → 创建会话引用”的顺序配置授权。示例中的 Alice 是业务用户标记，不是 AgentAPI 创建的独立安全主体。

### 创建保管库并关联业务用户 [#创建保管库并关联业务用户]

为业务用户或服务身份创建 Vault，保存返回的 ID，并在应用自己的授权记录中关联该 ID。`display_name` 用于识别，`metadata` 用于检索与标记。

cURL

```bash
vault_id=$(curl --request POST "$AGENTAPI_BASE_URL/v1/vaults" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<'EOF' | jq -r '.id'
{
  "display_name": "Alice",
  "metadata": {"external_user_id": "usr_abc123"}
}
EOF
)
echo "$vault_id"  # "vlt_01ABC..."
```

Python

```python
vault = client.beta.vaults.create(
    display_name="Alice",
    metadata={"external_user_id": "usr_abc123"},
)
print(vault.id)  # "vlt_01ABC..."
```

TypeScript

````typescript
const vault = await client.beta.vaults.create({
  display_name: "Alice",
  metadata: { external_user_id: "usr_abc123" },
});
console.log(vault.id); // "vlt_01ABC..."
```csharp
```csharp
var vault = await client.Beta.Vaults.Create(new()
{
    DisplayName = "Alice",
    Metadata = new Dictionary<string, string> { ["external_user_id"] = "usr_abc123" },
});
Console.WriteLine(vault.ID); // "vlt_01ABC..."
````

Go

```go
vault, err := client.Beta.Vaults.New(ctx, anthropic.BetaVaultNewParams{
	DisplayName: "Alice",
	Metadata:    map[string]string{"external_user_id": "usr_abc123"},
})
if err != nil {
	panic(err)
}
fmt.Println(vault.ID) // "vlt_01ABC..."
```

Java

```java
var vault = client.beta().vaults().create(VaultCreateParams.builder()
    .displayName("Alice")
    .metadata(VaultCreateParams.Metadata.builder()
        .putAdditionalProperty("external_user_id", JsonValue.from("usr_abc123"))
        .build())
    .build());
IO.println(vault.id()); // "vlt_01ABC..."
```

PHP

```php
$vault = $client->beta->vaults->create(
    displayName: 'Alice',
    metadata: ['external_user_id' => 'usr_abc123'],
);
echo $vault->id . "\n"; // "vlt_01ABC..."
```

Ruby

```ruby
vault = client.beta.vaults.create(
  display_name: "Alice",
  metadata: {external_user_id: "usr_abc123"}
)
puts vault.id # "vlt_01ABC..."
```

响应返回完整的 Vault 记录：

```json
{
  "type": "vault",
  "id": "vlt_01ABC...",
  "display_name": "Alice",
  "metadata": { "external_user_id": "usr_abc123" },
  "created_at": "2026-03-18T10:00:00Z",
  "updated_at": "2026-03-18T10:00:00Z",
  "archived_at": null
}
```

### 选择第三方鉴权方式 [#选择第三方鉴权方式]

鉴权方式由 MCP 服务决定，不由智能体模型决定：

| MCP 服务接受的授权                      | 凭证类型            | 令牌维护责任                   |
| -------------------------------- | --------------- | ------------------------ |
| 业务用户通过 OAuth 授予的访问令牌             | `mcp_oauth`     | 应用完成授权与刷新，再更新 Vault 中的令牌 |
| 固定 API Key 或个人访问令牌，以 Bearer 方式发送 | `static_bearer` | 应用根据第三方令牌有效期安排轮换         |

两种类型都以 `mcp_server_url` 匹配目标服务。凭证值（`token`、`access_token`、`refresh_token`、`client_secret`）只写入、不在 API 响应中返回；应用应保存凭证 ID，用于后续更新或撤销。

#### 保存 OAuth 授权 [#保存-oauth-授权]

下面的示例保存业务用户的访问令牌及刷新信息。保存 `refresh` 配置不会启动自动刷新：AgentAPI 当前不执行 OAuth 刷新，应用必须在令牌过期后完成刷新并更新凭证。

`refresh.token_endpoint_auth.type` 字段指定令牌刷新请求的认证方式：

* `none`：公共客户端
* `client_secret_basic`：使用客户端密钥的 HTTP Basic 身份验证
* `client_secret_post`：客户端密钥位于 POST 请求体中

cURL

```bash
credential_id=$(curl --fail-with-body -sS "$AGENTAPI_BASE_URL/v1/vaults/$vault_id/credentials" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  --data @- <<'EOF' | jq -r '.id'
{
  "display_name": "Alice's Slack",
  "auth": {
    "type": "mcp_oauth",
    "mcp_server_url": "https://mcp.slack.com/mcp",
    "access_token": "xoxp-...",
    "expires_at": "2099-12-31T23:59:59Z",
    "refresh": {
      "token_endpoint": "https://slack.com/api/oauth.v2.access",
      "client_id": "1234567890.0987654321",
      "scope": "channels:read chat:write",
      "refresh_token": "xoxe-1-...",
      "token_endpoint_auth": {"type": "client_secret_post", "client_secret": "abc123..."}
    }
  }
}
EOF
)
```

Python

```python
credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Alice's Slack",
    auth={
        "type": "mcp_oauth",
        "mcp_server_url": "https://mcp.slack.com/mcp",
        "access_token": "xoxp-...",
        "expires_at": "2099-12-31T23:59:59Z",
        "refresh": {
            "token_endpoint": "https://slack.com/api/oauth.v2.access",
            "client_id": "1234567890.0987654321",
            "scope": "channels:read chat:write",
            "refresh_token": "xoxe-1-...",
            "token_endpoint_auth": {"type": "client_secret_post", "client_secret": "abc123..."},
        },
    },
)
```

TypeScript

````typescript
const credential = await client.beta.vaults.credentials.create(vault.id, {
  display_name: "Alice's Slack",
  auth: {
    type: "mcp_oauth",
    mcp_server_url: "https://mcp.slack.com/mcp",
    access_token: "xoxp-...",
    expires_at: "2099-12-31T23:59:59Z",
    refresh: {
      token_endpoint: "https://slack.com/api/oauth.v2.access",
      client_id: "1234567890.0987654321",
      scope: "channels:read chat:write",
      refresh_token: "xoxe-1-...",
      token_endpoint_auth: {
        type: "client_secret_post",
        client_secret: "abc123...",
      },
    },
  },
});
```csharp
```csharp
var credential = await client.Beta.Vaults.Credentials.Create(vault.ID, new()
{
    DisplayName = "Alice's Slack",
    Auth = new BetaManagedAgentsMcpOAuthCreateParams
    {
        Type = BetaManagedAgentsMcpOAuthCreateParamsType.McpOAuth,
        McpServerUrl = "https://mcp.slack.com/mcp",
        AccessToken = "xoxp-...",
        ExpiresAt = DateTimeOffset.Parse("2099-12-31T23:59:59Z"),
        Refresh = new()
        {
            TokenEndpoint = "https://slack.com/api/oauth.v2.access",
            ClientID = "1234567890.0987654321",
            Scope = "channels:read chat:write",
            RefreshToken = "xoxe-1-...",
            TokenEndpointAuth = new BetaManagedAgentsTokenEndpointAuthPostParam
            {
                Type = BetaManagedAgentsTokenEndpointAuthPostParamType.ClientSecretPost,
                ClientSecret = "abc123...",
            },
        },
    },
});
````

Go

```go
credential, err := client.Beta.Vaults.Credentials.New(ctx, vault.ID, anthropic.BetaVaultCredentialNewParams{
	DisplayName: anthropic.String("Alice's Slack"),
	Auth: anthropic.BetaVaultCredentialNewParamsAuthUnion{
		OfMCPOAuth: &anthropic.BetaManagedAgentsMCPOAuthCreateParams{
			Type:         anthropic.BetaManagedAgentsMCPOAuthCreateParamsTypeMCPOAuth,
			MCPServerURL: "https://mcp.slack.com/mcp",
			AccessToken:  "xoxp-...",
			ExpiresAt:    anthropic.Time(time.Date(2099, time.December, 31, 23, 59, 59, 0, time.UTC)),
			Refresh: anthropic.BetaManagedAgentsMCPOAuthRefreshParams{
				TokenEndpoint: "https://slack.com/api/oauth.v2.access",
				ClientID:      "1234567890.0987654321",
				Scope:         anthropic.String("channels:read chat:write"),
				RefreshToken:  "xoxe-1-...",
				TokenEndpointAuth: anthropic.BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnion{
					OfClientSecretPost: &anthropic.BetaManagedAgentsTokenEndpointAuthPostParam{
						Type:         anthropic.BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost,
						ClientSecret: "abc123...",
					},
				},
			},
		},
	},
})
if err != nil {
	panic(err)
}
```

Java

```java
var credential = client.beta().vaults().credentials().create(vault.id(),
    CredentialCreateParams.builder()
        .displayName("Alice's Slack")
        .auth(BetaManagedAgentsMcpOAuthCreateParams.builder()
            .type(BetaManagedAgentsMcpOAuthCreateParams.Type.MCP_OAUTH)
            .mcpServerUrl("https://mcp.slack.com/mcp")
            .accessToken("xoxp-...")
            .expiresAt(OffsetDateTime.parse("2099-12-31T23:59:59Z"))
            .refresh(BetaManagedAgentsMcpOAuthRefreshParams.builder()
                .tokenEndpoint("https://slack.com/api/oauth.v2.access")
                .clientId("1234567890.0987654321")
                .scope("channels:read chat:write")
                .refreshToken("xoxe-1-...")
                .clientSecretPostTokenEndpointAuth("abc123...")
                .build())
            .build())
        .build());
```

PHP

```php
$credential = $client->beta->vaults->credentials->create(
    vaultID: $vault->id,
    displayName: "Alice's Slack",
    auth: ManagedAgentsMCPOAuthCreateParams::with(
        type: 'mcp_oauth',
        mcpServerURL: 'https://mcp.slack.com/mcp',
        accessToken: 'xoxp-...',
        expiresAt: new DateTimeImmutable('2099-12-31T23:59:59Z'),
        refresh: ManagedAgentsMCPOAuthRefreshParams::with(
            tokenEndpoint: 'https://slack.com/api/oauth.v2.access',
            clientID: '1234567890.0987654321',
            scope: 'channels:read chat:write',
            refreshToken: 'xoxe-1-...',
            tokenEndpointAuth: ManagedAgentsTokenEndpointAuthPostParam::with(
                type: 'client_secret_post',
                clientSecret: 'abc123...',
            ),
        ),
    ),
);
```

Ruby

```ruby
credential = client.beta.vaults.credentials.create(
  vault.id,
  display_name: "Alice's Slack",
  auth: {
    type: "mcp_oauth",
    mcp_server_url: "https://mcp.slack.com/mcp",
    access_token: "xoxp-...",
    expires_at: "2099-12-31T23:59:59Z",
    refresh: {
      token_endpoint: "https://slack.com/api/oauth.v2.access",
      client_id: "1234567890.0987654321",
      scope: "channels:read chat:write",
      refresh_token: "xoxe-1-...",
      token_endpoint_auth: {
        type: "client_secret_post",
        client_secret: "abc123..."
      }
    }
  }
)
```

#### 保存固定 Bearer 令牌 [#保存固定-bearer-令牌]

固定令牌不需要 OAuth 刷新配置。下面的示例将令牌绑定到一个 MCP 地址；如服务地址发生变化，应创建新的凭证，而非只更新令牌值。

cURL

```bash
curl --fail-with-body -sS "$AGENTAPI_BASE_URL/v1/vaults/$vault_id/credentials" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "display_name": "Linear API key",
  "auth": {
    "type": "static_bearer",
    "mcp_server_url": "https://mcp.linear.app/mcp",
    "token": "lin_api_your_linear_key"
  }
}
EOF
```

Python

```python
bearer_credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Linear API key",
    auth={
        "type": "static_bearer",
        "mcp_server_url": "https://mcp.linear.app/mcp",
        "token": "lin_api_your_linear_key",
    },
)
```

TypeScript

````typescript
const bearerCredential = await client.beta.vaults.credentials.create(vault.id, {
  display_name: "Linear API key",
  auth: {
    type: "static_bearer",
    mcp_server_url: "https://mcp.linear.app/mcp",
    token: "lin_api_your_linear_key",
  },
});
```csharp
```csharp
var bearerCredential = await client.Beta.Vaults.Credentials.Create(vault.ID, new()
{
    DisplayName = "Linear API key",
    Auth = new BetaManagedAgentsStaticBearerCreateParams
    {
        Type = BetaManagedAgentsStaticBearerCreateParamsType.StaticBearer,
        McpServerUrl = "https://mcp.linear.app/mcp",
        Token = "lin_api_your_linear_key",
    },
});
````

Go

```go
bearerCredential, err := client.Beta.Vaults.Credentials.New(ctx, vault.ID, anthropic.BetaVaultCredentialNewParams{
	DisplayName: anthropic.String("Linear API key"),
	Auth: anthropic.BetaVaultCredentialNewParamsAuthUnion{
		OfStaticBearer: &anthropic.BetaManagedAgentsStaticBearerCreateParams{
			Type:         anthropic.BetaManagedAgentsStaticBearerCreateParamsTypeStaticBearer,
			MCPServerURL: "https://mcp.linear.app/mcp",
			Token:        "lin_api_your_linear_key",
		},
	},
})
if err != nil {
	panic(err)
}
_ = bearerCredential
```

Java

```java
var bearerCredential = client.beta().vaults().credentials().create(vault.id(),
    CredentialCreateParams.builder()
        .displayName("Linear API key")
        .auth(BetaManagedAgentsStaticBearerCreateParams.builder()
            .type(BetaManagedAgentsStaticBearerCreateParams.Type.STATIC_BEARER)
            .mcpServerUrl("https://mcp.linear.app/mcp")
            .token("lin_api_your_linear_key")
            .build())
        .build());
```

PHP

```php
$bearerCredential = $client->beta->vaults->credentials->create(
    vaultID: $vault->id,
    displayName: 'Linear API key',
    auth: ManagedAgentsStaticBearerCreateParams::with(
        type: 'static_bearer',
        mcpServerURL: 'https://mcp.linear.app/mcp',
        token: 'lin_api_your_linear_key',
    ),
);
```

Ruby

```ruby
bearer_credential = client.beta.vaults.credentials.create(
  vault.id,
  display_name: "Linear API key",
  auth: {
    type: "static_bearer",
    mcp_server_url: "https://mcp.linear.app/mcp",
    token: "lin_api_your_linear_key"
  }
)
```

### 在会话中引用授权 [#在会话中引用授权]

确认业务用户有权使用前面创建的 Vault 后，将其 ID 写入会话的 `vault_ids`。示例为同一业务用户启动协作系统摘要任务：

cURL

```bash
session_id=$(curl --fail-with-body -sS $AGENTAPI_BASE_URL/v1/sessions \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  --data @- <<EOF | jq -r '.id'
{
  "agent": {"type": "agent", "id": "$agent_id", "version": 1},
  "environment_id": "$environment_id",
  "vault_ids": ["$vault_id"],
  "title": "Alice's Slack digest"
}
EOF
)
```

Python

```python
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
    title="Alice's Slack digest",
)
```

TypeScript

````typescript
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  vault_ids: [vault.id],
  title: "Alice's Slack digest",
});
```csharp
```csharp
var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    VaultIds = [vault.ID],
    Title = "Alice's Slack digest",
});
````

Go

```go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfString: anthropic.String(agent.ID),
	},
	EnvironmentID: environment.ID,
	VaultIDs:      []string{vault.ID},
	Title:         anthropic.String("Alice's Slack digest"),
})
if err != nil {
	panic(err)
}
```

Java

```java
var session = client.beta().sessions().create(SessionCreateParams.builder()
    .agent(agent.id())
    .environmentId(environment.id())
    .vaultIds(List.of(vault.id()))
    .title("Alice's Slack digest")
    .build());
```

PHP

```php
$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
    vaultIDs: [$vault->id],
    title: "Alice's Slack digest",
);
```

Ruby

```ruby
session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id,
  vault_ids: [vault.id],
  title: "Alice's Slack digest"
)
```

会话创建成功只说明配置已保存，不能证明第三方鉴权已通过。开始任务后，结合[会话事件](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)核对 MCP 调用结果：

| 现象              | 优先检查                        |
| --------------- | --------------------------- |
| MCP 连接或调用返回鉴权错误 | 服务地址是否匹配，令牌是否过期或已被第三方撤销     |
| 可以读取但无法执行写操作    | 第三方令牌是否具有所需权限，工具配置是否允许该操作   |
| 使用了不符合预期的业务身份   | 应用选择的 Vault 是否正确，是否存在多个匹配凭证 |

## 更新授权并验证生效 [#更新授权并验证生效]

凭证更新分为两类：更换令牌值时更新原凭证；变更服务或 OAuth 客户端时创建新凭证。

| 变更                                                   | 操作          |
| ---------------------------------------------------- | ----------- |
| 密钥值、`display_name`、OAuth 刷新信息                        | 更新原凭证       |
| `mcp_server_url`、`token_endpoint`、`client_id` 等结构性字段 | 归档旧凭证，创建新凭证 |

应用完成 OAuth 刷新或取得新令牌后，使用已保存的凭证 ID 更新。运行中的会话需要异步同步；同步完成后，后续出站请求才使用新值。

cURL

```bash
curl --fail-with-body -sS \
  "$AGENTAPI_BASE_URL/v1/vaults/$vault_id/credentials/$credential_id" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  --data @- <<'EOF' > /dev/null
{
  "auth": {
    "type": "mcp_oauth",
    "access_token": "xoxp-new-...",
    "expires_at": "2099-12-31T23:59:59Z",
    "refresh": {"refresh_token": "xoxe-1-new-..."}
  }
}
EOF
```

Python

```python
client.beta.vaults.credentials.update(
    credential.id,
    vault_id=vault.id,
    auth={
        "type": "mcp_oauth",
        "access_token": "xoxp-new-...",
        "expires_at": "2099-12-31T23:59:59Z",
        "refresh": {"refresh_token": "xoxe-1-new-..."},
    },
)
```

TypeScript

````typescript
await client.beta.vaults.credentials.update(credential.id, {
  vault_id: vault.id,
  auth: {
    type: "mcp_oauth",
    access_token: "xoxp-new-...",
    expires_at: "2099-12-31T23:59:59Z",
    refresh: {
      refresh_token: "xoxe-1-new-...",
    },
  },
});
```csharp
```csharp
await client.Beta.Vaults.Credentials.Update(credential.ID, new()
{
    VaultID = vault.ID,
    Auth = new BetaManagedAgentsMcpOAuthUpdateParams
    {
        Type = BetaManagedAgentsMcpOAuthUpdateParamsType.McpOAuth,
        AccessToken = "xoxp-new-...",
        ExpiresAt = DateTimeOffset.Parse("2099-12-31T23:59:59Z"),
        Refresh = new() { RefreshToken = "xoxe-1-new-..." },
    },
});
````

Go

```go
_, err = client.Beta.Vaults.Credentials.Update(ctx, credential.ID, anthropic.BetaVaultCredentialUpdateParams{
	VaultID: vault.ID,
	Auth: anthropic.BetaVaultCredentialUpdateParamsAuthUnion{
		OfMCPOAuth: &anthropic.BetaManagedAgentsMCPOAuthUpdateParams{
			Type:        anthropic.BetaManagedAgentsMCPOAuthUpdateParamsTypeMCPOAuth,
			AccessToken: anthropic.String("xoxp-new-..."),
			ExpiresAt:   anthropic.Time(time.Date(2099, time.December, 31, 23, 59, 59, 0, time.UTC)),
			Refresh: anthropic.BetaManagedAgentsMCPOAuthRefreshUpdateParams{
				RefreshToken: anthropic.String("xoxe-1-new-..."),
			},
		},
	},
})
if err != nil {
	panic(err)
}
```

Java

```java
client.beta().vaults().credentials().update(credential.id(),
    CredentialUpdateParams.builder()
        .vaultId(vault.id())
        .auth(BetaManagedAgentsMcpOAuthUpdateParams.builder()
            .type(BetaManagedAgentsMcpOAuthUpdateParams.Type.MCP_OAUTH)
            .accessToken("xoxp-new-...")
            .expiresAt(OffsetDateTime.parse("2099-12-31T23:59:59Z"))
            .refresh(BetaManagedAgentsMcpOAuthRefreshUpdateParams.builder()
                .refreshToken("xoxe-1-new-...")
                .build())
            .build())
        .build());
```

PHP

```php
$client->beta->vaults->credentials->update(
    $credential->id,
    vaultID: $vault->id,
    auth: ManagedAgentsMCPOAuthUpdateParams::with(
        type: 'mcp_oauth',
        accessToken: 'xoxp-new-...',
        expiresAt: new DateTimeImmutable('2099-12-31T23:59:59Z'),
        refresh: ManagedAgentsMCPOAuthRefreshUpdateParams::with(refreshToken: 'xoxe-1-new-...'),
    ),
);
```

Ruby

```ruby
client.beta.vaults.credentials.update(
  credential.id,
  vault_id: vault.id,
  auth: {
    type: "mcp_oauth",
    access_token: "xoxp-new-...",
    expires_at: "2099-12-31T23:59:59Z",
    refresh: {refresh_token: "xoxe-1-new-..."}
  }
)
```

### 核对同步与撤销状态 [#核对同步与撤销状态]

凭证轮换会为正在运行的云端沙箱创建异步同步任务。归档或删除 Vault、凭证时，AgentAPI 同样会更新仍可复用的沙箱注入规则。

> 凭证同步
>
> 轮换成功仅表示新密文已保存，运行中的沙箱仍需异步同步。同步重试耗尽时没有可查询的用户事件；请在下一次会话或沙箱连接时验证新凭证，并保存轮换请求的 `X-Trace-ID` 供排障。

下表为 Vault 生命周期的 Webhook 事件，不通过会话 SSE 返回。可在 Portal 的“服务设置 → Webhook”选择订阅，接收服务的验签与可靠处理见 [Webhook 通知](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13605-agentapi-data-and-integrations-webhooks)。未接入 Webhook 时，应用应通过资源查询核对归档或删除状态，再通过第三方服务调用验证凭证可用性。

| 事件                                | 触发条件                                                     |
| --------------------------------- | -------------------------------------------------------- |
| `vault.archived`                  | Vault 已归档。同时会为每个底层凭证发出一个 `vault_credential.archived` 事件。 |
| `vault.deleted`                   | Vault 已删除。同时会为每个底层凭证发出一个 `vault_credential.deleted` 事件。  |
| `vault_credential.archived`       | 凭证已归档，可能是直接归档，也可能是 vault 归档的结果。                          |
| `vault_credential.deleted`        | 凭证已删除，可能是直接删除，也可能是 vault 删除的结果。                          |
| `vault_credential.refresh_failed` | 预留事件类型；AgentAPI 当前不执行 OAuth token 自动刷新，也不会用它报告沙箱同步失败。    |

这些事件用于确认资源状态变化，不等同于第三方在线鉴权校验。AgentAPI 当前不提供 OAuth 在线校验接口，令牌可用性仍需通过实际服务访问确认。

## 停止使用并保留审计记录 [#停止使用并保留审计记录]

业务用户撤销授权后，应用应停止为新会话选择该 Vault 或凭证，并归档或删除相应资源。归档适用于保留非敏感审计记录；删除适用于不再保留资源记录。两种操作都会触发沙箱注入规则更新，但运行中的同步仍是异步的，不能承诺立即撤回已经发出的请求。

* 列出 Vault 或凭证： 分页返回，最新的在前。默认排除已归档记录；传入 `include_archived=true` 可一并返回。
* 归档 Vault： `POST /v1/vaults/{id}/archive`。同时归档其中的凭证并清除密钥，保留记录用于审计。新会话不能再引用该 Vault。
* 归档凭证： `POST /v1/vaults/{id}/credentials/{cred_id}/archive`。清除密钥负载，但保留 `mcp_server_url` 等非敏感描述信息用于审计。
* 删除 Vault 或凭证： 永久删除记录。需要保留审计信息时，请使用归档。

在 Portal 的 Vault 列表中，您可以按名称或 ID 搜索，并选择活跃、已归档或全部状态。搜索会去掉关键词首尾的空白，按字面量包含关系匹配 `display_name` 或 `id`；`%`、`_` 和 `!` 不作为通配符。搜索和状态筛选均在统计总数和分页前完成。

对应的 Portal 接口为 `GET /portal/v1/vaults?page_index=1&q=关键词`。`q` 和 `status` 必须与 `page_index` 一起使用；`status=active` 仅返回活跃 Vault，`status=archived` 仅返回已归档 Vault。查看全部状态时，省略 `status` 并传入 `include_archived=true`，两者不能同时使用。公开接口 `GET /v1/vaults` 不接受 `q` 或 `status`，凭证列表也不支持这两个参数。


# 配置云端环境 (/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)



最近更新时间: 2026-10-13 15:31:59

云端环境（Environment）是一份可复用的沙箱配置，定义智能体执行任务时可用的软件包和出站网络策略。即使引用同一个环境，每个会话也会获得独立的云端沙箱，文件系统状态不会在会话之间共享。

环境创建后可以反复引用；[创建会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)时传入 `environment_id` 即可。运行时和模型配置在[智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)上，环境负责提供执行代码、处理文件和使用工具所需的软件与网络条件。

![云端环境为每个会话提供独立沙箱](/docs-assets/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment/FhSzYsrX726oI4yAFq3M-wtHhMRl-32921928d4b3.webp)

AgentAPI 当前支持两种环境：

* `cloud` 由 AgentAPI 通过七牛 [LAS Sandbox](https://developer-doc.qiniu.com/products/las/13479-sandbox-api-overview) 为每个会话创建独立的云端沙箱；
* `self_hosted` 由自行部署的 worker 提供工作区和执行资源。请参阅 [自托管执行器](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

本页介绍 `type: cloud` 类型的环境。它是使用七牛云端执行能力的默认接入路径。

## 创建环境 [#创建环境]

请先完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)，配置服务地址和 MaaS API Key。以下示例创建一个允许出站互联网访问的云端环境，SDK 示例沿用[SDK 客户端初始化](/products/agentapi/quick_start/13587-agentapi-quickstart)中的 `client`。

cURL

```bash
environment=$(curl --request POST "$AGENTAPI_BASE_URL/v1/environments" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "python-dev",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)
environment_id=$(jq -r '.id' <<< "$environment")

echo "Environment ID: $environment_id"
```

Python

```python
environment = client.beta.environments.create(
    name="python-dev",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},
    },
)

print(f"Environment ID: {environment.id}")
```

TypeScript

````typescript
const environment = await client.beta.environments.create({
  name: "python-dev",
  config: {
    type: "cloud",
    networking: { type: "unrestricted" },
  },
});

console.log(`Environment ID: ${environment.id}`);
```csharp
```csharp
var environment = await client.Beta.Environments.Create(new()
{
    Name = "python-dev",
    Config = new BetaCloudConfigParams
    {
        Networking = new BetaUnrestrictedNetwork(),
    },
});

Console.WriteLine($"Environment ID: {environment.ID}");
````

Go

```go
environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
	Name: "python-dev",
	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
		OfCloud: &anthropic.BetaCloudConfigParams{
			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
				OfUnrestricted: &anthropic.BetaUnrestrictedNetworkParam{},
			},
		},
	},
})
if err != nil {
	panic(err)
}

fmt.Printf("Environment ID: %s\n", environment.ID)
```

Java

```java
var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
    .name("python-dev")
    .config(BetaCloudConfigParams.builder()
        .networking(BetaUnrestrictedNetwork.builder().build())
        .build())
    .build());
IO.println("Environment ID: " + environment.id());
```

PHP

```php
$environment = $client->beta->environments->create(
    name: 'python-dev',
    config: ['type' => 'cloud', 'networking' => ['type' => 'unrestricted']],
);
echo "Environment ID: {$environment->id}\n";
```

Ruby

```ruby
environment = client.beta.environments.create(
  name: "python-dev",
  config: {
    type: "cloud",
    networking: {type: "unrestricted"}
  }
)

puts "Environment ID: #{environment.id}"
```

`name` 用于在 Portal 和列表响应中识别环境，建议使用唯一且能表达用途的名称。保存响应中的 `id`，后续创建会话时需要引用它。

## 配置选项 [#配置选项]

### 预装软件与智能体运行时 [#预装软件与智能体运行时]

七牛云端沙箱已包含常用的语言运行环境、数据库和命令行工具。添加依赖前，请先查看[云端环境参考](/products/agentapi/development_guidelines/agentapi-execution-environments/13609-agentapi-execution-environments-cloud-environments)，确认已有软件和版本。

Python、Node.js 等用于执行任务代码；智能体的 `runtime` 则选择 `claudecode`、`codex` 或 `native` 执行引擎。不同智能体可以共用一份云端环境配置。

### 添加软件包 [#添加软件包]

`packages` 会在创建或更新环境时预装。包管理器配置支持两种写法：

* 字符串数组，例如 `pip: ["pandas==2.2.0"]`。
* 名称到版本的对象，例如 `pip: {"pandas": "2.2.0"}`。

响应统一返回名称到版本的对象；未指定版本时，由包管理器解析版本。

cURL

```bash
environment=$(curl --request POST "$AGENTAPI_BASE_URL/v1/environments" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "data-analysis",
  "config": {
    "type": "cloud",
    "packages": {
      "pip": {"pandas": "", "numpy": "", "scikit-learn": ""},
      "npm": {"express": ""}
    },
    "networking": {"type": "unrestricted"}
  }
}
EOF
)
```

Python

```python
environment = client.beta.environments.create(
    name="data-analysis",
    config={
        "type": "cloud",
        "packages": {
            "pip": ["pandas", "numpy", "scikit-learn"],
            "npm": ["express"],
        },
        "networking": {"type": "unrestricted"},
    },
)
```

TypeScript

````typescript
const environment = await client.beta.environments.create({
  name: "data-analysis",
  config: {
    type: "cloud",
    packages: {
      pip: ["pandas", "numpy", "scikit-learn"],
      npm: ["express"]
    },
    networking: { type: "unrestricted" }
  }
});
```csharp
```csharp
using Anthropic.Models.Beta.Environments;

var environment = await client.Beta.Environments.Create(new()
{
    Name = "data-analysis",
    Config = new BetaCloudConfigParams
    {
        Packages = new()
        {
            Pip = ["pandas", "numpy", "scikit-learn"],
            Npm = ["express"],
        },
        Networking = new BetaUnrestrictedNetwork(),
    },
});
````

Go

```go
environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
	Name: "data-analysis",
	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
		OfCloud: &anthropic.BetaCloudConfigParams{
			Packages: anthropic.BetaPackagesParams{
				Pip: []string{"pandas", "numpy", "scikit-learn"},
				Npm: []string{"express"},
			},
			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
				OfUnrestricted: &anthropic.BetaUnrestrictedNetworkParam{},
			},
		},
	},
})
if err != nil {
	panic(err)
}
_ = environment
```

Java

```java
import com.anthropic.models.beta.environments.*;
import java.util.List;

var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
    .name("data-analysis")
    .config(BetaCloudConfigParams.builder()
        .packages(BetaPackagesParams.builder()
            .pip(List.of("pandas", "numpy", "scikit-learn"))
            .npm(List.of("express"))
            .build())
        .networking(BetaUnrestrictedNetwork.builder().build())
        .build())
    .build());
```

PHP

```php
$environment = $client->beta->environments->create(
    name: 'data-analysis',
    config: [
        'type' => 'cloud',
        'packages' => [
            'pip' => ['pandas', 'numpy', 'scikit-learn'],
            'npm' => ['express'],
        ],
        'networking' => ['type' => 'unrestricted'],
    ],
);
```

Ruby

```ruby
environment = client.beta.environments.create(
  name: "data-analysis",
  config: {
    type: "cloud",
    packages: {
      pip: %w[pandas numpy scikit-learn],
      npm: %w[express]
    },
    networking: {type: "unrestricted"}
  }
)
```

支持的包管理器：

| 字段      | 包管理器           | 示例                                          |
| ------- | -------------- | ------------------------------------------- |
| `apt`   | 系统软件包（apt-get） | `"graphviz"`                                |
| `cargo` | Rust（cargo）    | `"hyperfine@1.18.0"`                        |
| `gem`   | Ruby（gem）      | `"rails:7.1.0"`                             |
| `go`    | Go 模块          | `"golang.org/x/tools/cmd/goimports@latest"` |
| `npm`   | Node.js（npm）   | `"express@4.18.0"`                          |
| `pip`   | Python（pip）    | `"sqlalchemy==2.0.30"`                      |

新安装的 Go 工具放在 `/usr/local/bin`，不依赖会话的 HOME。基础模板需要支持 root 或免密 sudo。已有模板不会自动迁移；若历史工具只在 `/home/user/go/bin`，使用原绝对路径，或在新环境中重新安装。

### 网络 [#网络]

`networking` 控制会话沙箱的出站网络访问：

| 模式             | 行为                                   |
| -------------- | ------------------------------------ |
| `unrestricted` | 允许出站互联网访问，这是默认值。                     |
| `limited`      | 默认拒绝出站访问，仅放行 `allowed_hosts` 中列出的主机。 |

省略 `networking` 时使用默认值 `unrestricted`。仅当需要收紧网络访问时才需显式设置；使用 `limited` 时通过 `allowed_hosts` 声明允许访问的主机：

```json
{
  "type": "cloud",
  "networking": {
    "type": "limited",
    "allowed_hosts": ["mcp.linear.app", "api.github.com"],
    "allow_mcp_servers": true,
    "allow_package_managers": false
  }
}
```

`allow_package_managers` 仅保存并回显，不单独控制包管理器的网络访问。`allow_mcp_servers` 在 `claudecode` 和 `codex` 中不单独控制沙箱网络；Native 显式设置为 `false` 时，会拒绝 MCP 工具接入。该字段为 `true` 或省略时，仍需满足环境的主机白名单。

`limited` 环境中的 MCP 服务和包管理器源应通过 `allowed_hosts` 放行。Native 的 MCP 连接虽然在 AgentAPI 服务端执行，也会检查这份环境配置；环境网络策略不等同于工具权限或第三方授权。

> 模型服务访问
>
> `limited` 环境会自动放行服务端配置的模型服务主机，保障模型调用；这些主机不会加入环境响应中的 `allowed_hosts`。沙箱基础模板所需的 DNS 解析也由服务端放行。环境网络策略不改变智能体权限或 Vault 密钥注入范围。

## 在会话中使用环境 [#在会话中使用环境]

先[创建智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)，再在创建会话时以字符串形式传入环境 ID。下面的 cURL 示例使用智能体页保存的 `AGENT_ID` 和 `AGENT_VERSION`。会话创建成功时尚未执行任务；发送第一条用户消息后，AgentAPI 才会按环境配置准备执行所需的沙箱。

cURL

```bash
session=$(curl --request POST "$AGENTAPI_BASE_URL/v1/sessions" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
  "agent": {"type": "agent", "id": "$AGENT_ID", "version": $AGENT_VERSION},
  "environment_id": "$environment_id"
}
EOF
)
```

Python

```python
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)
```

TypeScript

````typescript
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
});
```csharp
```csharp
var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
});
````

Go

```go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfString: anthropic.String(agent.ID),
	},
	EnvironmentID: environment.ID,
})
if err != nil {
	panic(err)
}
```

Java

```java
var session = client.beta().sessions().create(SessionCreateParams.builder()
    .agent(agent.id())
    .environmentId(environment.id())
    .build());
```

PHP

```php
$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
);
```

Ruby

```ruby
session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id
)
```

## 环境生命周期 [#环境生命周期]

* 环境会一直保留，直到被显式归档或删除。归档后环境变为只读，不能用于创建新会话；已在运行的会话不受影响。
* 每个会话都会获得自己的沙箱实例，即使多个会话引用同一个环境也是如此。会话之间不共享文件系统状态。
* 更新环境不会创建新版本。若需要审计配置变更，请在 `metadata` 或业务系统中记录版本信息。

## 管理环境 [#管理环境]

Portal 的运行环境列表支持按名称或 ID 搜索。关键词会去除首尾空白，按字面量包含关系匹配，并在统计总数和分页前执行。对应接口为 `GET /portal/v1/environments?page_index=1&q=关键词`，`q` 必须与 `page_index` 一起使用；公开的 `GET /v1/environments` 不接受该参数。

cURL

```bash
# 列出环境。page 使用上一次响应中的 next_page 游标。
curl --get "$AGENTAPI_BASE_URL/v1/environments" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --data-urlencode "include_archived=false" \
  --data-urlencode "limit=20"

# 检索特定环境
curl --request GET "$AGENTAPI_BASE_URL/v1/environments/$environment_id" \
  --header "x-api-key: $AGENTAPI_API_KEY"

# 更新环境（只提交需要修改的字段）
curl --request POST "$AGENTAPI_BASE_URL/v1/environments/$environment_id" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data '{"description":"用于数据分析任务的环境"}'

# 归档环境（只读，现有会话继续运行）
curl --request POST "$AGENTAPI_BASE_URL/v1/environments/$environment_id/archive" \
  --header "x-api-key: $AGENTAPI_API_KEY"

# 删除环境（请先确认没有后续会话需要引用它）
curl --request DELETE "$AGENTAPI_BASE_URL/v1/environments/$environment_id" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
# 列出环境
environments = client.beta.environments.list()

# 检索特定环境
env = client.beta.environments.retrieve(environment.id)

# 归档环境（只读，现有会话继续运行）
client.beta.environments.archive(environment.id)

# 删除环境（请先确认没有后续会话需要引用它）
client.beta.environments.delete(environment.id)
```

TypeScript

````typescript
// 列出环境
const environments = await client.beta.environments.list();

// 检索特定环境
const env = await client.beta.environments.retrieve(environment.id);

// 归档环境（只读，现有会话继续运行）
await client.beta.environments.archive(environment.id);

// 删除环境（请先确认没有后续会话需要引用它）
await client.beta.environments.delete(environment.id);
```csharp
```csharp
// 列出环境
var environments = await client.Beta.Environments.List();

// 检索特定环境
var env = await client.Beta.Environments.Retrieve(environment.ID);

// 归档环境（只读，现有会话继续运行）
await client.Beta.Environments.Archive(environment.ID);

// 删除环境（请先确认没有后续会话需要引用它）
await client.Beta.Environments.Delete(environment.ID);
````

Go

```go
// 列出环境
environments, err := client.Beta.Environments.List(ctx, anthropic.BetaEnvironmentListParams{})
// ...

// 检索特定环境
env, err := client.Beta.Environments.Get(ctx, environment.ID, anthropic.BetaEnvironmentGetParams{})
// ...

// 归档环境（只读，现有会话继续运行）
_, err = client.Beta.Environments.Archive(ctx, environment.ID, anthropic.BetaEnvironmentArchiveParams{})
// ...

// 删除环境（请先确认没有后续会话需要引用它）
_, err = client.Beta.Environments.Delete(ctx, environment.ID, anthropic.BetaEnvironmentDeleteParams{})
```

Java

```java
// 列出环境
var environments = client.beta().environments().list();
// 检索特定环境
var env = client.beta().environments().retrieve(environment.id());
// 归档环境（只读，现有会话继续运行）
client.beta().environments().archive(environment.id());
// 删除环境（请先确认没有后续会话需要引用它）
client.beta().environments().delete(environment.id());
```

PHP

```php
// 列出环境
$environments = $client->beta->environments->list();
// 检索特定环境
$env = $client->beta->environments->retrieve($environment->id);
// 归档环境（只读，现有会话继续运行）
$client->beta->environments->archive($environment->id);
// 删除环境（请先确认没有后续会话需要引用它）
$client->beta->environments->delete($environment->id);
```

Ruby

```ruby
# 列出环境
environments = client.beta.environments.list

# 检索特定环境
env = client.beta.environments.retrieve(environment.id)

# 归档环境（只读，现有会话继续运行）
client.beta.environments.archive(environment.id)

# 删除环境（请先确认没有后续会话需要引用它）
client.beta.environments.delete(environment.id)
```

## 后续步骤 [#后续步骤]

* [云端环境参考](/products/agentapi/development_guidelines/agentapi-execution-environments/13609-agentapi-execution-environments-cloud-environments)：查看七牛云端沙箱预装软件和版本。
* [会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)：关联智能体和环境，提交任务输入。
* [文件和产物](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)：为会话挂载输入文件，并下载任务产物。


# 云端沙箱参考 (/products/agentapi/development_guidelines/agentapi-execution-environments/13609-agentapi-execution-environments-cloud-environments)



最近更新时间: 2026-10-13 15:32:00

AgentAPI 的云端环境运行在七牛 LAS Sandbox 上。基础环境版本记录预装软件及默认配置。

使用 `claudecode` 或 `codex` 时，可在对应 Release 的“预装工具版本”中查看 Claude Code、Codex 的版本，并核对任务依赖的软件包。`native` 是 AgentAPI 服务内的运行时，不随沙箱预装；调用文件和命令工具时，仍会使用云端环境的软件与网络配置。运行时选择见[运行时和模型](/products/agentapi/development_guidelines/agentapi-agent-configuration/13589-agentapi-agent-configuration-runtime-and-models)。

创建环境时由平台选择版本，已有环境不会自动升级。额外安装的软件包由环境配置指定。

## 用户身份与目录 [#用户身份与目录]

云端命令、Native Bash 和文件操作统一以 `root` 执行。新会话默认 HOME 为 `/root`、工作目录为 `/workspace`；服务端配置可以覆盖默认值，会话创建后固定目录。

已有会话继续使用保存的目录，不随部署默认值变化。历史记录没有独立目录字段时，服务端从 Turn 日志绝对路径恢复 HOME；无法确定的 HOME 和旧工作目录回退到 `/home/user`。目录是否存在或当前进程的 `$HOME` 不能可靠判断旧布局。历史自定义工作目录需要由运维补录，不能自动推断。

Codex 与 Claude Code 的启动命令保持不变；Claude Code 以 root 使用跳过权限确认模式时，服务端设置 `IS_SANDBOX=1`。root 可以写入 root 所有的仓库，但不能绕过只读挂载或模型认证。自托管 worker 使用其自身配置的目录和身份。

## 基础环境版本 [#基础环境版本]

| Release   | 发布日期       | 环境详情                                                                                                                                                                                                  |
| --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| v20261012 | 2026-10-12 | [查看](/products/agentapi/development_guidelines/agentapi-execution-environments/agentapi-execution-environments-cloud-environments/13610-agentapi-execution-environments-cloud-environments-v20261012) |
| v20261009 | 2026-10-09 | [查看](/products/agentapi/development_guidelines/agentapi-execution-environments/agentapi-execution-environments-cloud-environments/13611-agentapi-execution-environments-cloud-environments-v20261009) |
| v20260929 | 2026-09-29 | [查看](/products/agentapi/development_guidelines/agentapi-execution-environments/agentapi-execution-environments-cloud-environments/13612-agentapi-execution-environments-cloud-environments-v20260929) |
| v20260924 | 2026-09-24 | [查看](/products/agentapi/development_guidelines/agentapi-execution-environments/agentapi-execution-environments-cloud-environments/13613-agentapi-execution-environments-cloud-environments-v20260924) |

## 相关页面 [#相关页面]

* [云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)：配置软件包和网络策略。
* [启动会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)：在指定云端环境中启动会话。


# 自托管执行器 (/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)



最近更新时间: 2026-10-13 15:32:12

自托管环境（`self_hosted`）把文件和命令工具放到自有基础设施执行。AgentAPI 仍负责模型请求、会话状态、事件和工作队列；worker 领取工作项，在本地完成工具调用，再把结果回传给 AgentAPI。

接入前需明确配置与数据边界：

1. 会话使用 `runtime: "native"` 的[智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)，模型仍在智能体配置中选择；自托管只决定工具执行位置。
2. 用户输入、工具参数和工具结果仍会经过 AgentAPI 和模型服务。技能与记忆存储由 AgentAPI 保存，支持这些能力的 worker 会下载副本并按规则同步。网页工具和服务端 MCP 连接由 AgentAPI 执行，不会自动转移到 worker。

完整的数据流、凭证范围和网络边界见[自托管安全责任](/products/agentapi/development_guidelines/agentapi-execution-environments/13615-agentapi-execution-environments-self-hosted-security)。

## 确定执行边界 [#确定执行边界]

|                 | 云端环境                                            | 自托管环境                      |
| --------------- | ----------------------------------------------- | -------------------------- |
| 文件和命令执行位置       | 七牛云端沙箱                                          | 自有基础设施                     |
| 执行环境网络出口        | 云端环境的网络策略                                       | 自有网络策略                     |
| 文件和 GitHub 仓库挂载 | 由 AgentAPI 管理                                   | 自行管理                       |
| 记忆存储            | `claudecode`、`codex` 挂载并在成功执行后写回；`native` 不自动挂载 | 由支持记忆的 SDK worker 下载、挂载和同步 |
| 生命周期            | 由 AgentAPI 管理                                   | 自行管理                       |

自托管适合需要访问内网服务、复用既有执行基础设施，或由应用控制隔离和审计的任务。内网访问应封装为 worker 中的自定义工具；直接配置的远程 MCP 服务仍必须能被 AgentAPI 服务端访问。

| 需求                | 选择                             |
| ----------------- | ------------------------------ |
| 只需要云端执行文件和命令      | 使用云端环境，无需运行 worker             |
| 需要固定主机、私有网络或自有审计  | 使用 `self_hosted`，由 worker 执行工具 |
| 每个会话需要独立文件系统或资源配额 | 由轮询器为每个工作项创建独立沙箱               |
| 多个会话共享一组执行资源      | 使用常驻 worker，按自身调度策略复用主机        |

最小验证路径是：创建 `self_hosted` 环境，启动一个 worker，创建引用该环境的 `native` 会话，发送一条消息，然后从队列统计和会话事件确认工具结果。后文的命令和代码都围绕这条路径展开。

## 配置最小接入条件 [#配置最小接入条件]

> SDK 版本
>
> 本页的 worker 同步行为和运行依赖已核验于 Python SDK 1.12.1、TypeScript SDK 0.132.1、Go SDK 1.79.1 和 `ant` CLI 1.39.1。其他版本的默认值可能不同，升级时需核对所用版本。

先准备一个 `native` 智能体和一台执行主机。暂不使用记忆存储时，无需配置记忆目录：

* 一个使用 `native` 的智能体。 按[创建智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)的示例创建，并将 `runtime` 改为 `native`，保存返回的 ID 和版本。
* 一台 Linux 执行主机，必须提供 `/bin/bash`，worker 不通过 `PATH` 查找 bash。此外，TypeScript SDK 还要求 `PATH` 上有 `unzip` 和 `tar`，以及 Node.js 22 或更高版本；Python 和 Go SDK 用各自标准库解压归档，因此没有这些额外的二进制依赖。
* worker 主机上的 `ant` CLI，或支持 AgentAPI 协议的 SDK（Python、TypeScript 或 Go）。

接入中的三类凭证分别服务于账户操作、领取工作和读取会话资源，不应混用：

| 凭证                | 获取方式                | 使用位置                                                                                                                                                   |
| ----------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 已绑定的 MaaS API Key | Portal 的 API Key 设置 | worker 主机之外的应用，用于创建会话、读取队列统计                                                                                                                           |
| 环境密钥（Worker key）  | Portal 的环境详情页       | worker，用于访问指定环境的工作队列                                                                                                                                   |
| 会话级 `secret`      | 服务端生成，随已认领工作项下发     | 处理该工作项的 worker，用于访问[记忆存储](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted) |

若会话需要记忆存储，启动前还须准备可写的 `/mnt/memory`，见[准备主机](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。采用独立沙箱时，启动器必须把当前工作项的 `secret` 转发给对应实例。

### 创建自托管环境 [#创建自托管环境]

请先完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)。在 [七牛 Portal](https://portal.qiniu.com/agentapi) 的环境页面创建自托管环境，或使用下面的 API。账户级资源操作使用已绑定的 MaaS API Key，客户端初始化见[通过 API 构建](/products/agentapi/quick_start/13587-agentapi-quickstart)。

cURL

```bash
curl -sS --fail-with-body $AGENTAPI_BASE_URL/v1/environments \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "self-hosted",
    "config": {"type": "self_hosted"}
  }'
```

Python

```python
import os
client = anthropic.Anthropic(api_key=os.environ["AGENTAPI_API_KEY"], base_url=os.environ["AGENTAPI_BASE_URL"])

environment = client.beta.environments.create(
    name="self-hosted", config={"type": "self_hosted"}
)
print(environment.id)
```

TypeScript

````typescript
const client = new Anthropic({ apiKey: process.env.AGENTAPI_API_KEY!, baseURL: process.env.AGENTAPI_BASE_URL! });

const environment = await client.beta.environments.create({
  name: "self-hosted",
  config: { type: "self_hosted" }
});
console.log(environment.id);
```csharp
```csharp
using Anthropic.Models.Beta.Environments;

var client = new AnthropicClient(new Anthropic.Core.ClientOptions
{
    ApiKey = System.Environment.GetEnvironmentVariable("AGENTAPI_API_KEY")!,
    BaseUrl = System.Environment.GetEnvironmentVariable("AGENTAPI_BASE_URL")!,
});

var environment = await client.Beta.Environments.Create(
    new EnvironmentCreateParams
    {
        Name = "self-hosted",
        Config = new BetaSelfHostedConfigParams(),
    }
);
Console.WriteLine(environment.ID);
````

Go

```go
client := anthropic.NewClient(
	option.WithoutEnvironmentDefaults(),
	option.WithBaseURL(os.Getenv("AGENTAPI_BASE_URL")),
	option.WithAPIKey(os.Getenv("AGENTAPI_API_KEY")),
)

environment, err := client.Beta.Environments.New(context.Background(), anthropic.BetaEnvironmentNewParams{
	Name: "self-hosted",
	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
		OfSelfHosted: &anthropic.BetaSelfHostedConfigParams{},
	},
})
if err != nil {
	panic(err)
}
fmt.Println(environment.ID)
```

Java

```java
import com.anthropic.models.beta.environments.BetaSelfHostedConfigParams;
import com.anthropic.models.beta.environments.EnvironmentCreateParams;

void main() {
    var client = AnthropicOkHttpClient.builder()
        .apiKey(System.getenv("AGENTAPI_API_KEY"))
        .baseUrl(System.getenv("AGENTAPI_BASE_URL"))
        .build();

    var environment = client.beta().environments().create(
        EnvironmentCreateParams.builder()
            .name("self-hosted")
            .config(BetaSelfHostedConfigParams.builder().build())
            .build()
    );
    IO.println(environment.id());
}
```

PHP

```php
$client = new Anthropic\Client(apiKey: getenv('AGENTAPI_API_KEY'), baseUrl: getenv('AGENTAPI_BASE_URL'));

$environment = $client->beta->environments->create(
    name: 'self-hosted',
    config: ['type' => 'self_hosted'],
);
echo $environment->id, PHP_EOL;
```

Ruby

```ruby
client = Anthropic::Client.new(api_key: ENV.fetch("AGENTAPI_API_KEY"), base_url: ENV.fetch("AGENTAPI_BASE_URL"))

environment = client.beta.environments.create(
  name: "self-hosted",
  config: {type: :self_hosted}
)
puts environment.id
```

### 创建环境密钥 [#创建环境密钥]

在 [七牛 Portal](https://portal.qiniu.com/agentapi) 打开对应自托管环境的详情页，创建连接凭证。一个环境可以同时使用多个凭证，以区分不同 worker；撤销其中一个凭证不会影响其他凭证。密钥明文仅在创建成功后展示一次，之后无法再次获取，请及时保存到 worker 主机。

创建完成后，在 worker 主机上设置环境 ID、环境密钥和服务地址。以下 `ANTHROPIC_*` 名称来自兼容 CLI / SDK 的变量约定，值使用 AgentAPI 的对应配置。`AGENTAPI_BASE_URL` 应与创建环境时的区域一致：

```bash
export ANTHROPIC_ENVIRONMENT_KEY="$worker_key"
export ANTHROPIC_ENVIRONMENT_ID="$AGENTAPI_ENVIRONMENT_ID"
export ANTHROPIC_BASE_URL="$AGENTAPI_BASE_URL"
```

> 说明
>
> 技能包可以包含供智能体直接运行的可执行文件。CLI 和 SDK worker 在解压技能包时，会保留包内记录的可执行权限。自行实现技能下载时，需要保留或设置这些可执行权限。

## 启动验证用 worker [#启动验证用-worker]

首次接入可先让一个进程持续轮询环境队列，通过出站 HTTPS 连接 AgentAPI。只需验证文件和命令工具时可使用 CLI；需要私有工具或记忆同步时使用 SDK worker。验证通过后，再按执行基础设施中的方案配置隔离与回收。

当前服务提供轮询接入；需要按事件唤醒 worker 时，由应用侧启动实例并触发轮询。

### 使用 ant CLI [#使用-ant-cli]

#### 安装 CLI [#安装-cli]

在 worker 主机上运行此命令。

##### Linux / WSL 安装 [#linux--wsl-安装]

对于 Linux 环境，直接下载发布的二进制文件。

```bash
VERSION=1.39.1
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $(uname -m) in
  x86_64) ARCH=amd64 ;;
  aarch64) ARCH=arm64 ;;
esac
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
  | sudo tar -xz -C /usr/local/bin ant
```

可以在 [GitHub 发布页面](https://github.com/anthropics/anthropic-cli/releases)上找到所有版本。

##### macOS 安装 [#macos-安装]

以下命令用于安装 CLI；worker 执行主机仍需满足本页的 Linux 和文件系统要求。

```bash
brew install anthropics/tap/ant
```

#### 启动 CLI worker [#启动-cli-worker]

`ant beta:worker poll` 从环境变量读取 `ANTHROPIC_ENVIRONMENT_KEY` 和 `ANTHROPIC_ENVIRONMENT_ID`，持续领取该环境中的工作。在这个验证方案中，领取和执行发生在同一进程；技能下载及工具文件操作都使用指定工作目录。

```bash
ant beta:worker poll --workdir "/workspace"
```

worker 收到 SIGTERM 或 SIGINT 时会取消调用并释放工作项：它会取消所有进行中的工具调用、发布对应的错误结果，并在停止前释放工作项。

### 使用 SDK worker [#使用-sdk-worker]

SDK 的 `EnvironmentWorker` 封装领取、技能下载、工具执行和结果回传。下面的示例以常驻进程运行，并把退出信号转换为取消操作，使 worker 有机会完成上传和清理；鉴权使用[环境密钥](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

Python

```python
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker

async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key, base_url=os.environ["ANTHROPIC_BASE_URL"]) as client:
        worker = EnvironmentWorker(
            client,
            environment_id=environment_id,
            environment_key=environment_key,
            workdir="/workspace",
        )
        task = asyncio.create_task(worker.run())
        # 取消任务（而非终止进程）可让 worker 停止其
        # 正在处理的工作项，并在退出前上传已更改的内存文件。
        loop = asyncio.get_running_loop()
        for signum in (signal.SIGINT, signal.SIGTERM):
            loop.add_signal_handler(signum, task.cancel)
        with contextlib.suppress(asyncio.CancelledError):
            await task

asyncio.run(main())
```

TypeScript

````typescript
import Anthropic from "@anthropic-ai/sdk";
import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";

const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
const client = new Anthropic({ authToken: environmentKey, baseURL: process.env.ANTHROPIC_BASE_URL! });
const controller = new AbortController();
// 在任一信号上中止可让 worker 上传已更改的内存文件并移除其
// 存储目录，然后进程退出。
process.once("SIGINT", () => controller.abort());
process.once("SIGTERM", () => controller.abort());

await new EnvironmentWorker({
  client,
  environmentId,
  environmentKey,
  workdir: "/workspace",
  signal: controller.signal
}).run();
```csharp
```csharp
// EnvironmentWorker 目前在 C# SDK 中不可用。请参阅 本页的 ant CLI 方式。
````

Go

```go
package main

import (
	"context"
	"log"
	"os"
	"os/signal"
	"syscall"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/lib/environments"
	"github.com/anthropics/anthropic-sdk-go/option"
)

func main() {
	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")

	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	client := anthropic.NewClient(option.WithAuthToken(environmentKey), option.WithBaseURL(os.Getenv("ANTHROPIC_BASE_URL")))

	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
		EnvironmentID:  environmentID,
		EnvironmentKey: environmentKey,
		Workdir:        "/workspace",
	})
	if err := worker.Run(ctx); err != nil {
		log.Fatalf("worker: %v", err)
	}
}

```

Java

```java
// Java SDK 目前不支持 EnvironmentWorker。请参阅 本页的 ant CLI 方式。
```

PHP

```php
// PHP SDK 目前不提供 EnvironmentWorker。请参阅 本页的 ant CLI 方式。
```

Ruby

```ruby
# Ruby SDK 目前不支持 EnvironmentWorker。请参阅 本页的 ant CLI 方式。
```

## 发送任务并核对执行结果 [#发送任务并核对执行结果]

使用已绑定的 MaaS API Key 创建会话，并引用刚创建的环境。`AGENT_ID` 必须来自 `runtime: "native"` 的智能体，不能复用快速开始中的 `claudecode` 智能体。

以下示例把输入文件引用写入 `metadata`。它只向启动器传递信息，不会自动下载文件；首次验证可以省略这项元数据，发送不依赖外部文件的任务。文件、仓库和产物的准备方式见任务工作目录与产物。

cURL

```bash
curl -sS --fail-with-body $AGENTAPI_BASE_URL/v1/sessions \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ANTHROPIC_ENVIRONMENT_ID",
  "metadata": {"input_file": "s3://my-bucket/data.csv"}
}
EOF
```

Python

```python
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)
```

TypeScript

````typescript
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  metadata: { input_file: "s3://my-bucket/data.csv" }
});
```csharp
```csharp
var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    Metadata = new Dictionary<string, string> { ["input_file"] = "s3://my-bucket/data.csv" },
});
````

Go

```go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent:         anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
	EnvironmentID: environment.ID,
	Metadata: map[string]string{
		"input_file": "s3://my-bucket/data.csv",
	},
})
if err != nil {
	panic(err)
}
```

Java

```java
var session = client.beta().sessions().create(SessionCreateParams.builder()
    .agent(agent.id())
    .environmentId(environment.id())
    .metadata(SessionCreateParams.Metadata.builder()
        .putAdditionalProperty("input_file", JsonValue.from("s3://my-bucket/data.csv"))
        .build())
    .build());
```

PHP

```php
$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
    metadata: ['input_file' => 's3://my-bucket/data.csv'],
);
```

Ruby

```ruby
session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id,
  metadata: {input_file: "s3://my-bucket/data.csv"}
)
```

> 说明
>
> 自托管会话接受 `file`、`github_repository` 和 `memory_store` 三种资源。AgentAPI 保存资源声明，worker 或启动器负责下载文件、准备仓库，并在自己的执行环境中挂载资源。记忆的下载、挂载和同步需要支持该能力的 SDK worker，见使用记忆存储。上文的 `metadata` 用于传递由自有启动器解析的资源引用，不会触发 AgentAPI 自动下载。
>
> 以自托管环境为目标的[部署](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13600-agentapi-sessions-and-tasks-scheduled-deployments)遵循相同的规则。

确认智能体已配置任务所需的工具，再按[发送用户消息](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)启动任务。例如，启用文件工具后，请求在工作目录中创建一个文本文件并读取其内容。核对三处结果：

1. 队列统计中存在近期轮询的 worker；若工作积压，检查领取流程。
2. 会话事件中出现工具调用及其结果，而非只停留在已创建会话的状态。
3. worker 的工作目录中存在预期文件；若需要保留产物，由应用另行收集。

创建会话只保存配置，发送消息才会产生工作项。没有 worker 连接时，工作会等待处理。

### 核对队列连接 [#核对队列连接]

打开新的终端，将 `ANTHROPIC_API_KEY` 设置为已绑定的 MaaS API Key。该检查使用账户级 API Key。确认 `workers_polling` 至少为 1：

```bash
ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"
```

如果 `workers_polling` 持续为 0，说明 worker 尚未连接队列。请检查 worker 主机是否已设置 `ANTHROPIC_ENVIRONMENT_KEY` 和 `ANTHROPIC_ENVIRONMENT_ID`。完整的统计响应字段和其他语言示例见[读取队列深度](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

## 从验证进程转为部署实例 [#从验证进程转为部署实例]

验证通过后，先决定工作目录是否需要跨任务复用。常驻模式把执行过程留在同一主机，由应用负责目录、配额和清理；独立沙箱模式把领取与执行分开，由外部轮询器或启动器管理每个工作项的实例。

可以使用[七牛 LAS Sandbox](https://developer-doc.qiniu.com/products/las/13479-sandbox-api-overview) 为每个会话创建短生命周期的容器，也可以使用自有容器或虚拟机。LAS 负责沙箱实例、模板、进程、终端和文件系统；AgentAPI 负责智能体、会话、事件和工作队列。

使用独立实例时，启动器需要完成以下流程：

1. 从 AgentAPI 工作队列领取工作项。
2. 调用 LAS Sandbox API 创建或复用执行实例。
3. 准备 `/workspace`，将会话资源和必要的 `secret` 提供给执行实例。
4. 在实例中运行 worker，回传工具结果。
5. 工作结束后停止并删除沙箱，或按资源策略回收。

LAS Sandbox API 使用区域服务地址和七牛 `X-API-Key`。请根据沙箱所在区域选择服务地址，并参考[沙箱概述](https://developer-doc.qiniu.com/products/las/13479-sandbox-api-overview)获取最新区域、认证和实例管理接口；请勿将 LAS API Key 写入会话的 `metadata` 或 worker 镜像。

### CLI 隔离执行实例 [#cli-隔离执行实例]

需要独立文件系统、资源配额或网络控制时，请为每个会话创建单独的沙箱。下面的镜像安装 `ant`，以 `ant beta:worker run` 为入口；基础镜像必须提供 `/bin/bash`，构建阶段还需要 `curl`。执行实例从环境变量读取会话信息，处理对应工作后退出：

```text
FROM your-base-image
ARG ANT_VERSION=1.39.1
ARG TARGETARCH
RUN ARCH=$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo amd64) && \
    curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \
      | tar -xz -C /usr/local/bin ant
WORKDIR /workspace
VOLUME /workspace
ENTRYPOINT ["ant", "beta:worker", "run"]
```

随后编写启动脚本（spawn script），将会话详情转发到新建沙箱。轮询器通过以下方式向脚本提供信息：

* 通过环境变量注入 `ANTHROPIC_SESSION_ID`、`ANTHROPIC_WORK_ID`、`ANTHROPIC_ENVIRONMENT_ID` 和 `ANTHROPIC_ENVIRONMENT_KEY`。
* 把已认领的工作项以 JSON 形式写入脚本的标准输入，其中包含工作项的每会话 `secret`（前提是 AgentAPI 签发了它）。
* `ANTHROPIC_BASE_URL` 由轮询器传给执行实例。接入 AgentAPI 时必须按上文设置它，确保 worker 连接创建环境所在的服务区域。

示例将主机目录 `/host/outputs` 绑定到沙箱工作目录 `/workspace`，以保留退出后的产物、下载的 `skills/` 及中间文件。自托管不自动收集 `/mnt/session/outputs`，产物应保存在工作目录中，见[沙箱文件系统](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

```bash
#!/bin/bash
# spawn.sh：每个已认领的工作项调用一次
mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID"
exec docker run --rm \
  -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
  -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
  -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \
  your-image
```

`ant beta:worker run` 入口点不会挂载[记忆存储](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。如果环境中的会话附加了记忆存储，请保留轮询器，将会话镜像改为使用 SDK worker，并在启动脚本中将工作项的 `secret` 转发到沙箱。具体方法见[每个会话运行一个沙箱](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

启动指向该脚本的轮询器：

```bash
ant beta:worker poll --on-work ./spawn.sh
```

### 每个会话运行一个沙箱 [#每个会话运行一个沙箱]

当任务需要自定义工具或记忆挂载时，执行实例改用 SDK worker。若多个会话引用同一个记忆存储，独立文件系统还能避免挂载路径冲突，见[准备主机](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。实例之外仍由 `ant beta:worker poll --on-work` 或 SDK 工作轮询器领取工作，见[选择并启动 worker](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

`ant beta:worker run` 不支持记忆挂载。请使用 SDK worker 构建会话镜像，并在入口点中：

1. 创建 `EnvironmentWorker`，调用 `handle_item()`（TypeScript 为 `handleItem`，Go 为 `HandleItem`）。
2. 通过 `ANTHROPIC_*` 变量提供会话、工作和环境标识符。
3. 将工作项的会话级 `secret` 写入 `ANTHROPIC_WORK_SECRET`；也可显式传入 `work_secret`（TypeScript 为 `workSecret`，Go 为 `WorkSecret`）。

Python

```python
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker

async def main() -> None:
    async with AsyncAnthropic(auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"], base_url=os.environ["ANTHROPIC_BASE_URL"]) as client:
        worker = EnvironmentWorker(client, workdir="/workspace")
        # 不带参数时，handle_item() 会读取 spawn 脚本转发的 ANTHROPIC_* 变量，
        # 包括 ANTHROPIC_WORK_SECRET。
        task = asyncio.create_task(worker.handle_item())
        # 在容器停止时取消任务，可让工作进程在退出前上传
        # 已更改的内存文件并移除存储目录。
        loop = asyncio.get_running_loop()
        for signum in (signal.SIGINT, signal.SIGTERM):
            loop.add_signal_handler(signum, task.cancel)
        with contextlib.suppress(asyncio.CancelledError):
            await task

asyncio.run(main())
```

TypeScript

````typescript
import Anthropic from "@anthropic-ai/sdk";
import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";

const client = new Anthropic({ authToken: process.env.ANTHROPIC_ENVIRONMENT_KEY, baseURL: process.env.ANTHROPIC_BASE_URL! });
const controller = new AbortController();
// 在容器停止时中止，可让 worker 在退出前上传已更改的内存
// 文件并移除存储目录。
process.once("SIGTERM", () => controller.abort());
process.once("SIGINT", () => controller.abort());

// 不带参数时，handleItem() 会读取 spawn 脚本转发的 ANTHROPIC_* 变量，
// 包括 ANTHROPIC_WORK_SECRET。
await new EnvironmentWorker({
  client,
  workdir: "/workspace",
  signal: controller.signal
}).handleItem();
```csharp
```csharp
// EnvironmentWorker 目前在 C# SDK 中不可用。
````

Go

```go
package main

import (
	"context"
	"log"
	"os"
	"os/signal"
	"syscall"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/lib/environments"
	"github.com/anthropics/anthropic-sdk-go/option"
)

func main() {
	// 在容器停止时取消 context，可让 worker 在退出前上传
	// 已更改的内存文件并移除存储目录。
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	client := anthropic.NewClient(option.WithAuthToken(os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")), option.WithBaseURL(os.Getenv("ANTHROPIC_BASE_URL")))
	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
		Workdir: "/workspace",
	})
	// 使用零值选项时，HandleItem 会读取 spawn 脚本转发的 ANTHROPIC_* 变量，
	// 包括 ANTHROPIC_WORK_SECRET。
	if err := worker.HandleItem(ctx, environments.HandleItemOptions{}); err != nil {
		log.Fatalf("worker: %v", err)
	}
}

```

Java

```java
// Java SDK 目前暂不提供 EnvironmentWorker。
```

PHP

```php
// PHP SDK 目前暂不支持 EnvironmentWorker。
```

Ruby

```ruby
# Ruby SDK 目前暂不支持 EnvironmentWorker。
```

`ant beta:worker poll --on-work` 不会根据工作项自动设置 `ANTHROPIC_WORK_SECRET`；派生脚本仍会继承父进程的环境变量。启动脚本需要从标准输入中的当前工作项 JSON 读取会话凭证，再传入沙箱：

```bash
#!/bin/bash
# spawn.sh：每个已领取的工作项调用一次
# 已领取的工作项以 JSON 形式通过 stdin 传入。其 secret 是
# 记忆存储端点所需的每会话凭据。
ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')"
export ANTHROPIC_WORK_SECRET
mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID"
exec docker run --rm \
  -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
  -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
  -e ANTHROPIC_WORK_SECRET \
  -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \
  your-sdk-worker-image
```

使用 SDK 工作轮询器领取工作时，也需要将每个工作项的 `secret` 传入对应沙箱。会话凭证仅应提供给执行该会话的沙箱，禁止写入日志。

沙箱镜像还需要可写的 `/mnt/memory`，配置要求见[准备主机](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。每个沙箱仅服务一个会话，使用后即回收，因此不需要清理上次会话遗留的目录，也不需要将记忆目录绑定挂载到主机。worker 会在沙箱退出前将目录内容上传到存储。停止容器时需要满足以下条件：

* 在会话结束前停止容器时，请发送入口点能够转换为取消操作的信号，使 worker 完成上传。配置方法见[准备主机](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。
* 为容器预留足够的上传时间。通过 `docker run` 的 `--stop-timeout` 或编排器的终止宽限期，预留至少 60 秒，并留出本地文件清理时间。

## 任务入队与执行流程 [#任务入队与执行流程]

> 说明
>
> 无论采用哪种执行基础设施，worker 都需通过 AgentAPI 工作队列领取任务、维持租约并回传结果。使用 CLI 或 SDK worker 时，这些操作由客户端实现；使用自定义执行器时，需要自行实现。

向自托管环境中的[会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)发送用户消息后，AgentAPI 将一个工作项加入环境队列。worker 领取工作项，准备工作目录和[技能](/products/agentapi/development_guidelines/agentapi-agent-configuration/13594-agentapi-agent-configuration-skills)，执行工具并回传结果。没有可用 worker 时，工作项会留在队列中，不会自动改用云端环境。

worker 通过轮询领取工作项。可以持续运行 worker，也可以在应用收到任务事件后启动执行实例，再触发轮询。

![自托管执行器数据流：AgentAPI 管理工作队列，worker 在自有基础设施上领取工作、执行工具并回传结果与事件](/docs-assets/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted/FmsxHIiRufs-sCEKzRCS9vMZQIv3-53f1b10ae124.webp)

CLI 和 SDK 均提供 worker 实现。CLI 参数可通过 `ant beta:worker poll --help` 查看，SDK 用法见辅助工具参考。需要自行实现执行器时，请按 [OpenAPI 参考](/products/agentapi/api/13618-agentapi-api-conventions)中的环境工作队列接口实现领取、确认、保活和结果回传。

## 私有工具与 MCP 边界 [#私有工具与-mcp-边界]

AgentAPI 的 MCP 连接由服务端执行，不会进入 worker 的待执行队列。只有需要使用 worker 网络或本地凭证的能力，才应实现为自定义工具，并由 worker 回传 `user.custom_tool_result`。自定义工具的声明和注册见从沙箱提供自定义工具。

## 接入私有业务工具 [#接入私有业务工具]

例如，任务需要查询内网订单系统时，可把查询封装为[自定义工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)。工具声明供模型选择调用，返回结果进入模型上下文；实际请求在 worker 的网络中发起，工具代码负责业务鉴权、参数校验和超时。

接入分成两部分：在智能体上声明可调用的接口，在 worker 中注册同名实现。智能体发出 `agent.custom_tool_use` 后，worker 执行实现并回传 `user.custom_tool_result`。回传使用环境密钥，无需将账户级 MaaS API Key 放入执行实例。

> 说明
>
> `ant` CLI worker 无法注册自定义工具实现。此处使用 SDK worker；独立沙箱的入口应调用 `EnvironmentWorker` 的 `handle_item()`（TypeScript 为 `handleItem`，Go 为 `HandleItem`），替代 `ant beta:worker run`。

### 在智能体上声明工具 [#在智能体上声明工具]

以下声明让模型按订单 ID 调用查询接口。把这个 `custom` 条目加入智能体的 `tools`，并确保 `name` 与 worker 注册名称一致。声明结构见[自定义工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)。

```json
{
  "type": "custom",
  "name": "get_order_status",
  "description": "Look up an order in the internal fulfillment system by order ID.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "description": "The order ID" }
    },
    "required": ["order_id"]
  }
}
```

### 向 worker 注册实现 [#向-worker-注册实现]

worker 的 `tools` 工厂返回本次执行使用的完整工具列表。下面的实现保留内置工具，并加入订单查询工具；工厂用法见[SDK 辅助工具](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)：

Python

```python
import asyncio
import os
from anthropic import AsyncAnthropic, beta_async_tool
from anthropic.lib.environments import EnvironmentWorker
from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401

@beta_async_tool
async def get_order_status(order_id: str) -> str:
    """Look up an order in the internal fulfillment system by order ID."""
    # 在 worker 主机上运行：可调用沙箱能够访问的任何内容。
    return f"Order {order_id}: shipped"

async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key, base_url=os.environ["ANTHROPIC_BASE_URL"]) as client:
        await EnvironmentWorker(
            client,
            environment_id=environment_id,
            environment_key=environment_key,
            workdir="/workspace",
            tools=lambda env: [*beta_agent_toolset_20260401(env), get_order_status],
        ).run()

asyncio.run(main())
```

TypeScript

````typescript
import Anthropic from "@anthropic-ai/sdk";
import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";
import { betaTool } from "@anthropic-ai/sdk/helpers/beta/json-schema";
import { betaAgentToolset20260401 } from "@anthropic-ai/sdk/tools/agent-toolset/node";

const getOrderStatus = betaTool({
  name: "get_order_status",
  description: "Look up an order in the internal fulfillment system by order ID.",
  inputSchema: {
    type: "object",
    properties: { order_id: { type: "string", description: "The order ID" } },
    required: ["order_id"]
  },
  // 在 worker 主机上运行：可调用沙箱能访问的任何内容。
  run: async ({ order_id }) => `Order ${order_id}: shipped`
});

const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
const client = new Anthropic({ authToken: environmentKey, baseURL: process.env.ANTHROPIC_BASE_URL! });
const controller = new AbortController();
process.once("SIGTERM", () => controller.abort());

await new EnvironmentWorker({
  client,
  environmentId,
  environmentKey,
  workdir: "/workspace",
  signal: controller.signal,
  tools: (ctx) => [...betaAgentToolset20260401(ctx), getOrderStatus]
}).run();
```csharp
```csharp
// EnvironmentWorker 目前在 C# SDK 中不可用。
// 如需直接响应自定义工具调用，请参阅会话事件流。
````

Go

```go
package main

import (
	"context"
	"log"
	"os"
	"os/signal"
	"syscall"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/lib/environments"
	"github.com/anthropics/anthropic-sdk-go/option"
	"github.com/anthropics/anthropic-sdk-go/toolrunner"
	"github.com/anthropics/anthropic-sdk-go/tools/agenttoolset"
)

type orderStatusInput struct {
	OrderID string `json:"order_id"`
}

func main() {
	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")

	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	getOrderStatus := toolrunner.NewBetaTool(
		"get_order_status",
		"Look up an order in the internal fulfillment system by order ID.",
		anthropic.BetaToolInputSchemaParam{
			Properties: map[string]any{
				"order_id": map[string]any{"type": "string", "description": "The order ID"},
			},
			Required: []string{"order_id"},
		},
		// 在工作进程主机上运行：可调用沙箱能够访问的任何内容。
		func(ctx context.Context, input orderStatusInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
			return anthropic.BetaToolResultBlockParamContentUnion{
				OfText: &anthropic.BetaTextBlockParam{Text: "Order " + input.OrderID + ": shipped"},
			}, nil
		},
	)

	client := anthropic.NewClient(option.WithAuthToken(environmentKey), option.WithBaseURL(os.Getenv("ANTHROPIC_BASE_URL")))

	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
		EnvironmentID:  environmentID,
		EnvironmentKey: environmentKey,
		Workdir:        "/workspace",
		ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool {
			return append(agenttoolset.BetaAgentToolset20260401(env), getOrderStatus)
		},
	})
	if err := worker.Run(ctx); err != nil {
		log.Fatalf("worker: %v", err)
	}
}

```

Java

```java
// EnvironmentWorker 目前在 Java SDK 中不可用。
// 如需直接响应自定义工具调用，请参阅会话事件流。
```

PHP

```php
// PHP SDK 目前暂不提供 EnvironmentWorker。
// 如需直接响应自定义工具调用，请参阅会话事件流。
```

Ruby

```ruby
# Ruby SDK 目前暂不提供 EnvironmentWorker。
# 如需直接响应自定义工具调用，请参阅会话事件流。
```

worker 只会响应向它注册过的工具。如果一个自定义工具在智能体上声明了、却没向任何 worker 或客户端注册，那么会话会以 `requires_action` 停止原因挂起，直到应用或 worker 回传对应结果；事件流程见 [处理自定义工具调用](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)。

### 将 MCP 服务器包装为自定义工具 [#将-mcp-服务器包装为自定义工具]

如果订单查询等能力已经由内网 MCP 服务提供，无需重写其业务逻辑。让 worker 连接该服务器，把选定工具注册为自定义工具即可。它与直接配置[MCP 连接器](/products/agentapi/development_guidelines/agentapi-agent-configuration/13592-agentapi-agent-configuration-mcp)的差别在连接位置：前者由 worker 发起请求，后者要求 AgentAPI 能访问服务器端点。

这种包装方式无需向 AgentAPI 开放内网服务的入站访问，但工具定义、调用参数和结果仍进入 AgentAPI。调用流程为：

1. 智能体发出一个 `agent.custom_tool_use` 事件。
2. worker 在沙箱内通过已建立的 MCP 会话，将工具调用转发给内部服务器。
3. worker 将服务器响应作为 `user.custom_tool_result` 回传。

SDK 的 MCP 辅助工具将服务器工具转换为 worker 可注册的工具。除 Worker SDK 外，还需安装对应的 MCP SDK：

| 语言         | 安装命令                                            | 需要认证时的传输配置    |
| ---------- | ----------------------------------------------- | ------------- |
| Python     | `pip install "anthropic[mcp]" "mcp>=1.24"`      | `http_client` |
| TypeScript | `npm install @modelcontextprotocol/sdk`         | `requestInit` |
| Go         | `go get github.com/modelcontextprotocol/go-sdk` | `HTTPClient`  |

以下示例连接无需认证的服务器。

### 在智能体上声明服务器的工具 [#在智能体上声明服务器的工具]

先在应用侧取得服务器工具列表，把所需工具的 `name`、`description` 和 `inputSchema` 转为 `custom` 声明，再创建或更新智能体。声明和 worker 注册必须使用相同的工具列表；若服务器分页返回工具，请先取完全部分页，避免模型可以调用而 worker 未注册的工具。

Python

```python
import os

import asyncio
from typing import Any, cast
from anthropic import AsyncAnthropic
from anthropic.types.beta import BetaManagedAgentsCustomToolParams
from mcp import ClientSession, types
# 需要 mcp >= 1.24，该版本将 streamablehttp_client 重命名为 streamable_http_client。
from mcp.client.streamable_http import streamable_http_client

MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"

def to_custom_tool(tool: types.Tool) -> BetaManagedAgentsCustomToolParams:
    # MCP 字段与自定义工具声明一一对应。cast
    # 将 schema 字典原样传递给 SDK 的类型化参数。
    return {
        "type": "custom",
        "name": tool.name,
        "description": tool.description or tool.name,
        "input_schema": cast(Any, tool.inputSchema),
    }

async def main() -> None:
    # 请在创建智能体的应用服务端运行此代码，而不是在工作主机上：
    # 它使用已绑定的 MaaS API Key（AGENTAPI_API_KEY）进行身份验证。
    async with (
        streamable_http_client(MCP_SERVER_URL) as (read, write, _),
        ClientSession(read, write) as mcp_session,
        AsyncAnthropic(api_key=os.environ["AGENTAPI_API_KEY"], base_url=os.environ["AGENTAPI_BASE_URL"]) as client,
    ):
        await mcp_session.initialize()
        listed = await mcp_session.list_tools()
        agent = await client.beta.agents.create(
            name="Internal tools agent",
            model={"id": os.environ["AGENTAPI_MODEL_ID"]},
            tools=[
                {"type": "agent_toolset_20260401"},
                *[to_custom_tool(tool) for tool in listed.tools],
            ],
            extra_body={"runtime": "native"},
        )
        print(agent.id)

asyncio.run(main())
```

TypeScript

````typescript
import Anthropic from "@anthropic-ai/sdk";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp";

// 请在创建智能体的应用服务端运行此代码，而不是在工作主机上：它
// 使用已绑定的 MaaS API Key（AGENTAPI_API_KEY）进行身份验证。
const client = new Anthropic({ apiKey: process.env.AGENTAPI_API_KEY!, baseURL: process.env.AGENTAPI_BASE_URL! });

const mcpClient = new Client({ name: "declare-agent-tools", version: "1.0.0" });
await mcpClient.connect(new StreamableHTTPClientTransport(new URL(MCP_SERVER_URL)));
const { tools } = await mcpClient.listTools();

const agentParams = {
  name: "Internal tools agent",
  model: { id: process.env.AGENTAPI_MODEL_ID! },
  tools: [
    { type: "agent_toolset_20260401" },
    // MCP 字段与自定义工具声明一一对应。
    ...tools.map((tool) => ({
      type: "custom" as const,
      name: tool.name,
      description: tool.description || tool.name,
      input_schema: tool.inputSchema
    }))
  ]
} satisfies Parameters<typeof client.beta.agents.create>[0];
const agent = await client.beta.agents.create(agentParams, {
  body: { ...agentParams, runtime: "native" },
});
console.log(agent.id);

await mcpClient.close();
```csharp
```csharp
// 请参阅 Python、TypeScript 和 Go 选项卡。使用 MCP 客户端列出服务器的工具后，
// 在 C# 中声明自定义工具的方式与之相同。
````

Go

```go
package main

import (
	"os"
	"context"
	"encoding/json"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
	mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
)

const mcpServerURL = "http://mcp.internal.example.com:8000/mcp"

// toCustomTool 将一个 MCP 工具定义映射为一个自定义工具声明。
// 字段一一对应：类型化参数承载 `properties` 和
// `required`，服务器输出的其他所有 JSON Schema 关键字都放入
// ExtraFields，以便声明的 schema 与服务器的 schema 保持一致。
func toCustomTool(tool *mcpsdk.Tool) (anthropic.BetaAgentNewParamsToolUnion, error) {
	raw, err := json.Marshal(tool.InputSchema)
	if err != nil {
		return anthropic.BetaAgentNewParamsToolUnion{}, err
	}
	var schema map[string]any
	if err := json.Unmarshal(raw, &schema); err != nil {
		return anthropic.BetaAgentNewParamsToolUnion{}, err
	}

	inputSchema := anthropic.BetaManagedAgentsCustomToolInputSchemaParam{ExtraFields: map[string]any{}}
	for keyword, value := range schema {
		switch keyword {
		case "type":
			// 该参数类型始终序列化为 "type": "object"。
		case "properties":
			properties, _ := value.(map[string]any)
			inputSchema.Properties = properties
		case "required":
			entries, _ := value.([]any)
			for _, entry := range entries {
				if name, isString := entry.(string); isString {
					inputSchema.Required = append(inputSchema.Required, name)
				}
			}
		default:
			inputSchema.ExtraFields[keyword] = value
		}
	}

	description := tool.Description
	if description == "" {
		description = tool.Name
	}
	return anthropic.BetaAgentNewParamsToolUnion{
		OfCustom: &anthropic.BetaManagedAgentsCustomToolParams{
			Type:        anthropic.BetaManagedAgentsCustomToolParamsTypeCustom,
			Name:        tool.Name,
			Description: description,
			InputSchema: inputSchema,
		},
	}, nil
}

func main() {
	ctx := context.Background()

	// 请在创建智能体的应用服务端运行此程序，而非在工作节点主机上：
	// 它使用已绑定的 MaaS API Key（AGENTAPI_API_KEY）进行身份验证。
	client := anthropic.NewClient(
	option.WithoutEnvironmentDefaults(),
	option.WithBaseURL(os.Getenv("AGENTAPI_BASE_URL")),
	option.WithAPIKey(os.Getenv("AGENTAPI_API_KEY")),
)

	mcpClient := mcpsdk.NewClient(&mcpsdk.Implementation{Name: "declare-agent-tools", Version: "1.0.0"}, nil)
	session, err := mcpClient.Connect(ctx, &mcpsdk.StreamableClientTransport{Endpoint: mcpServerURL}, nil)
	if err != nil {
		log.Fatalf("connect to MCP server: %v", err)
	}
	defer session.Close()

	listed, err := session.ListTools(ctx, nil)
	if err != nil {
		log.Fatalf("list MCP tools: %v", err)
	}

	tools := []anthropic.BetaAgentNewParamsToolUnion{
		{OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
		}},
	}
	for _, tool := range listed.Tools {
		custom, err := toCustomTool(tool)
		if err != nil {
			log.Fatalf("convert MCP tool %s: %v", tool.Name, err)
		}
		tools = append(tools, custom)
	}

	agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
		Name:  "Internal tools agent",
		Model: anthropic.BetaManagedAgentsModelConfigParams{ID: os.Getenv("AGENTAPI_MODEL_ID")},
		Tools: tools,
	}, option.WithJSONSet("runtime", "native"))
	if err != nil {
		log.Fatalf("create agent: %v", err)
	}
	fmt.Println(agent.ID)
}

```

Java

```java
// 请参阅 Python、TypeScript 和 Go 选项卡。使用 MCP 客户端列出服务器的工具后，
// 在 Java 中声明自定义工具的方式与之相同。
```

PHP

```php
// 请参阅 Python、TypeScript 和 Go 选项卡。使用 MCP 客户端列出服务器的工具后，
// 在 PHP 中声明自定义工具的方式与之相同。
```

Ruby

```ruby
# 请参阅 Python、TypeScript 和 Go 选项卡。使用 MCP 客户端列出服务器的工具后，
# 在 Ruby 中声明自定义工具的方式与之相同。
```

### 从 worker 提供工具 [#从-worker-提供工具]

worker 启动时连接同一 MCP 服务器，使用 MCP 辅助工具转换服务器工具，并与内置工具集一起注册。在整个 worker 生命周期内保持该 MCP 会话连接。

Python

```python
import asyncio
import os
from datetime import timedelta
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
# 需要 mcp >= 1.24，该版本将 streamablehttp_client 重命名为 streamable_http_client。
from mcp.client.streamable_http import streamable_http_client

MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"

async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    # 在启动时连接一次 MCP 服务器，并在工作进程的整个生命周期内
    # 保持会话打开。超时设置会将挂起的工具调用转为错误
    # 结果，而不是让调用一直停滞。
    async with (
        streamable_http_client(MCP_SERVER_URL) as (read, write, _),
        ClientSession(read, write, read_timeout_seconds=timedelta(seconds=60)) as mcp_session,
        AsyncAnthropic(auth_token=environment_key, base_url=os.environ["ANTHROPIC_BASE_URL"]) as client,
    ):
        await mcp_session.initialize()
        listed = await mcp_session.list_tools()
        mcp_tools = [async_mcp_tool(tool, mcp_session) for tool in listed.tools]
        await EnvironmentWorker(
            client,
            environment_id=environment_id,
            environment_key=environment_key,
            workdir="/workspace",
            tools=lambda env: [*beta_agent_toolset_20260401(env), *mcp_tools],
        ).run()

asyncio.run(main())
```

TypeScript

````typescript
import Anthropic from "@anthropic-ai/sdk";
import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";
import {
  mcpTools,
  type MCPCallToolResultLike,
  type MCPClientLike
} from "@anthropic-ai/sdk/helpers/beta/mcp";
import { betaAgentToolset20260401 } from "@anthropic-ai/sdk/tools/agent-toolset/node";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp";

const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
const client = new Anthropic({ authToken: environmentKey, baseURL: process.env.ANTHROPIC_BASE_URL! });
const controller = new AbortController();
process.once("SIGTERM", () => controller.abort());

// 在启动时连接一次 MCP 服务器，并在工作进程的整个生命周期内
// 保持连接打开。
const mcpClient = new Client({ name: "sandbox-worker", version: "1.0.0" });
await mcpClient.connect(new StreamableHTTPClientTransport(new URL(MCP_SERVER_URL)));
const { tools } = await mcpClient.listTools();

// MCP SDK 的 callTool 返回类型仍包含 mcpTools 不接受的旧版结果形状；
// 需要收窄类型。待 MCPClientLike 放宽后删除此处理。
const mcpClientForTools: MCPClientLike = {
  callTool: (params) => mcpClient.callTool(params) as Promise<MCPCallToolResultLike>
};

await new EnvironmentWorker({
  client,
  environmentId,
  environmentKey,
  workdir: "/workspace",
  signal: controller.signal,
  tools: (ctx) => [...betaAgentToolset20260401(ctx), ...mcpTools(tools, mcpClientForTools)]
}).run();
```csharp
```csharp
// EnvironmentWorker 目前在 C# SDK 中不可用。
````

Go

```go
package main

import (
	"context"
	"log"
	"os"
	"os/signal"
	"syscall"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/lib/environments"
	"github.com/anthropics/anthropic-sdk-go/mcp"
	"github.com/anthropics/anthropic-sdk-go/option"
	"github.com/anthropics/anthropic-sdk-go/tools/agenttoolset"
	mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
)

const mcpServerURL = "http://mcp.internal.example.com:8000/mcp"

func main() {
	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")

	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	client := anthropic.NewClient(option.WithAuthToken(environmentKey), option.WithBaseURL(os.Getenv("ANTHROPIC_BASE_URL")))

	// 在启动时连接一次 MCP 服务器，并在工作进程的整个生命周期内
	// 保持会话打开。
	mcpClient := mcpsdk.NewClient(&mcpsdk.Implementation{Name: "sandbox-worker", Version: "1.0.0"}, nil)
	session, err := mcpClient.Connect(ctx, &mcpsdk.StreamableClientTransport{Endpoint: mcpServerURL}, nil)
	if err != nil {
		log.Fatalf("connect to MCP server: %v", err)
	}
	defer session.Close()

	listed, err := session.ListTools(ctx, nil)
	if err != nil {
		log.Fatalf("list MCP tools: %v", err)
	}
	mcpTools, err := mcp.NewBetaTools(listed.Tools, session)
	if err != nil {
		log.Fatalf("convert MCP tools: %v", err)
	}

	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
		EnvironmentID:  environmentID,
		EnvironmentKey: environmentKey,
		Workdir:        "/workspace",
		ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool {
			return append(agenttoolset.BetaAgentToolset20260401(env), mcpTools...)
		},
	})
	if err := worker.Run(ctx); err != nil {
		log.Fatalf("worker: %v", err)
	}
}

```

Java

```java
// Java SDK 目前暂不支持 EnvironmentWorker。
```

PHP

```php
// PHP SDK 目前不支持 EnvironmentWorker。
```

Ruby

```ruby
# Ruby SDK 目前不支持 EnvironmentWorker。
```

包装 MCP 服务器时需遵循以下要求：

* 工具列表在启动时确定。 worker 启动时获取一次 MCP 服务器工具列表，不会自动更新正在运行的会话配置。服务器工具发生变更后，请在智能体上重新声明工具，或通过[更新智能体配置](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13598-agentapi-sessions-and-tasks-session-lifecycle)更新空闲会话，并重启 worker。
* 名称和描述。 工具名和描述不能为空。Native 执行时要求工具名长度为 1–64 个字符，以字母或下划线开头，其余字符只能是字母、数字、下划线或连字符；展开后的工具名称不能冲突，包括仅大小写不同的名称。建议避免与内置工具同名或使用 `mcp__` 前缀。
* 工具数量。 智能体配置的 `tools` 最多 64 个条目，每个包装工具或内置工具集各占一个条目；Native 执行时，展开后的工具总数最多 128 个。
* 同名工具处理。 MCP 辅助工具保留服务器原始名称和描述。多个服务器提供同名工具时，为包装工具添加前缀，调用时映射回原名。
* JSON Schema。 `input_schema` 必须是非空对象。Native 执行时会编译并校验 Schema：顶层 `type` 如有设置必须为 `object`，禁止外部 `$ref`，允许以 `#` 开头的本地引用。Schema 最多 256 KiB，嵌套深度最多 64 层。具体模型和 worker 可能有更严格的要求，建议将引用结构内联展开以提高兼容性。
* 错误结果。 MCP 工具错误及无法转换的内容（如音频块、资源链接）均作为错误工具结果返回模型。
* 调用超时。 worker 与 MCP 客户端分别控制超时。在上述已核验版本中，Python worker 的单次工具调用上限为 150 秒，TypeScript 和 Go worker 默认为 120 秒；Go 可通过 `ToolTimeout` 调整。MCP 客户端可能更早超时，建议显式设置其超时，如 Python 的 `read_timeout_seconds`。
* 仅包装可信服务器。 工具名称、描述和结果会进入模型上下文，可能影响其他工具调用，包括 worker 主机上的 `bash`。仅声明自行运营或信任、并授权智能体使用的工具。
* 自定义工具由应用控制权限。 [权限策略](/products/agentapi/development_guidelines/agentapi-agent-configuration/13593-agentapi-agent-configuration-permissions)控制内置工具集和 MCP 工具集。包装后的 MCP 工具属于自定义工具，worker 会执行已注册的调用；审批逻辑应由工具代码实现。

## 准备任务文件并保留产物 [#准备任务文件并保留产物]

自托管环境保存资源声明，不负责替应用准备文件系统。任务文件和 GitHub 仓库需要由 worker 或启动器下载、检出并放到工作目录。可以使用会话的 `resources` 声明 AgentAPI 资源，或使用 `metadata` 传递自有系统的对象存储路径、提交 SHA 等引用。

领取的工作项包含会话 ID。启动器可查询 `GET /v1/sessions/{session_id}`，读取资源声明和元数据，在执行工具前准备目录；普通产物应在实例回收前收集，记忆文件则通过 SDK 同步。目录职责如下：

* `/workspace`： 工具执行和技能下载的系统默认工作目录。CLI 的 `--workdir` 标志默认为当前目录；传入 `--workdir /workspace` 以匹配系统默认值。技能会下载到 `<workdir>/skills/<name>/`。如果使用不同的工作目录，请更新智能体的系统提示，以便智能体能够找到技能文件。
* 输出： 自托管环境不自动收集 `/mnt/session/outputs`。请在系统提示中约定输出路径，并由启动器收集或上传产物；通常可以将工作目录挂载到独立的会话存储目录。
* `/mnt/memory/`： SDK worker 将会话挂载的记忆存储下载到本地，每个存储对应一个目录，路径由该存储的 `mount_path` 决定（例如 `/mnt/memory/user-preferences/`）。这些目录在 worker 认领会话时创建、在会话结束时删除；详见[使用记忆存储](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

## 将跨任务状态写入记忆存储 [#将跨任务状态写入记忆存储]

需要让后续任务读取本次更新时，将[记忆存储](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13603-agentapi-data-and-integrations-memory)加入会话的 `resources`，而不是依赖 worker 工作目录永久保留。每个会话最多附加 8 个存储，声明方式见[将记忆存储附加到会话](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13603-agentapi-data-and-integrations-memory)。自托管会话仍须使用 `native` 智能体。

使用 Python、TypeScript 或 Go SDK 的 `EnvironmentWorker` 下载和同步记忆。常驻进程调用 `run()`，独立执行实例调用 `handle_item()`；两种方式都需为同步留出退出时间。

`ant` CLI worker（`ant beta:worker poll` 和 `ant beta:worker run`）不会挂载记忆存储。需要将 CLI 轮询器与记忆存储结合使用时，请按[每个会话运行一个沙箱](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)在会话沙箱内运行 SDK worker。

### 记忆下载与同步流程 [#记忆下载与同步流程]

记忆同步的验收依据是服务端存储内容，而非模型已完成文件写入。SDK worker 在本地副本和服务端之间执行以下操作：

1. 领取时下载。 用工作项的会话级 `secret` 读取各存储，在 `mount_path` 创建本地目录。路径与云端会话的 `/mnt/memory/` 约定一致，例如 `/mnt/memory/user-preferences/`；系统提示会告知智能体挂载位置。
2. 执行时访问。 worker 将记忆目录加入文件工具的允许根目录，`access: "read_only"` 的目录同时加入只读根目录。智能体通过 `read`、`write`、`edit`、`glob`、`grep` 操作副本。
3. 工具调用后同步。 worker 下载服务端更新、上传本地修改；每个同步间隔（默认 15 秒）最多同步一次，因此写入工具返回成功不代表内容已上传。
4. 结束时上传并清理。 正常结束先进行最终同步，再执行退出上传，两个网络阶段各有 30 秒超时；之后删除本次创建的存储目录。取消工作会跳过完整同步，但仍尝试上传修改并清理目录。

任务结束后，通过记忆 API 核对最终写回内容。其他会话只有在更新上传且自身下载完成后，才能读到新内容。云端沙箱的写回规则见[记忆访问与同步机制](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13603-agentapi-data-and-integrations-memory)。

请保留存储目录中的 `.anthropic-memory-store` 标记文件。标记丢失或变更且目录中仍有文件时，worker 暂停同步，避免误删服务端内容；目录清空时，worker 会重新下载存储内容。

### 准备主机 [#准备主机]

自托管记忆存储要求 worker 主机具备 POSIX 文件系统，主机要求见[准备环境与凭证](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。由于 worker 打开记忆文件时需要 `O_NOFOLLOW`，因此不支持 Windows 主机。建议使用区分大小写的文件系统，避免仅大小写不同的记忆路径发生冲突。

在启动 worker 之前，创建父目录并使其对 worker 运行所用的用户可写：

```bash
sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory
```

请勿预先创建存储的 `mount_path` 目录（例如 `/mnt/memory/user-preferences`）。worker 会自行创建并在会话结束时删除；路径已存在时，会拒绝启动工作。还需满足以下要求：

* 同一文件系统中，同一存储只能由一个会话挂载。 多个会话同时挂载同一存储会使用相同路径。请按[每个会话运行一个沙箱](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)为每个会话配置独立沙箱，以隔离挂载路径。
* 退出时完成上传和清理。 为进程配置取消流程，见退出与目录清理；直接强制终止会遗留目录并丢失尚未上传的内容。

### 选择同步间隔和删除策略 [#选择同步间隔和删除策略]

应用需要分别决定更新延迟和删除策略。以下两个 `EnvironmentWorker` 选项控制这些行为：

* `memory_sync_interval`： 同步间隔，默认 15 秒，最小 5 秒。Python 单位为秒；TypeScript 使用 `memorySyncIntervalMs`，单位为毫秒；Go 使用 `MemorySyncInterval`，类型为 duration。缩短间隔可减少记忆更新延迟，但会增加请求频率。

  Python 的 `None`、TypeScript 的 `null` 或 Go 的负 duration 会关闭记忆下载和同步。仅当所有会话均不附加记忆存储时才应关闭；否则系统提示虽包含存储信息，记忆内容却不可用。

  启用记忆支持后，附加了记忆存储的工作项必须携带会话凭证 `secret`，否则 worker 会拒绝处理该工作项。排查方法见记忆挂载问题。
* `memory_sync_deletions`： 是否将本地删除同步到存储，不影响上传和下载。TypeScript 使用 `memorySyncDeletions`，Go 使用 `MemorySyncDeletions`。

| Python / TypeScript | Go                                            | 行为                                                |
| ------------------- | --------------------------------------------- | ------------------------------------------------- |
| `"enabled"`（默认）     | `environments.MemorySyncDeletionsEnabled`（零值） | 本地文件持续缺失至少 30 秒，后续同步再次确认后删除服务端记忆；正常结束时的最终同步不等待此窗口 |
| `"log_only"`        | `environments.MemorySyncDeletionsLogOnly`     | 同样检查，但仅记录拟删除项；可用于核对删除范围                           |
| `"disabled"`        | `environments.MemorySyncDeletionsDisabled`    | 不删除服务端记忆                                          |

创建 worker 时设置这些选项，可使用 `EnvironmentWorker` 构造函数，或 Python 和 TypeScript 的 `client.beta.environments.work.worker()` 工厂。

以下示例每 10 秒同步一次，并仅记录拟删除的记忆：

Python

```python
worker = EnvironmentWorker(
    client,
    environment_id=environment_id,
    environment_key=environment_key,
    workdir="/workspace",
    memory_sync_interval=10,  # seconds
    memory_sync_deletions="log_only",
)
```

TypeScript

````typescript
const worker = new EnvironmentWorker({
  client,
  environmentId,
  environmentKey,
  workdir: "/workspace",
  memorySyncIntervalMs: 10_000,
  memorySyncDeletions: "log_only"
});
```csharp
```csharp
// EnvironmentWorker 目前在 C# SDK 中不可用。
````

Go

```go
worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
	EnvironmentID:       environmentID,
	EnvironmentKey:      environmentKey,
	Workdir:             "/workspace",
	MemorySyncInterval:  10 * time.Second,
	MemorySyncDeletions: environments.MemorySyncDeletionsLogOnly,
})
```

Java

```java
// Java SDK 目前暂不支持 EnvironmentWorker。
```

PHP

```php
// PHP SDK 目前暂不支持 EnvironmentWorker。
```

Ruby

```ruby
# Ruby SDK 目前不支持 EnvironmentWorker。
```

### 只读存储与冲突 [#只读存储与冲突]

`access: "read_only"` 控制文件工具和记忆上传：`write`、`edit` 拒绝写入，worker 不上传本地修改。它不是整个文件系统的只读挂载；`bash`、自定义工具和本地 MCP 服务仍可能修改副本，随后远程更新会覆盖这些改动。

若需保护执行期间的本地副本，禁用智能体的 `bash`，并移除能够写入该目录的自定义工具。目录仍须允许 worker 写入，以便创建挂载目录和下载内容。

发生同一文件的并发修改时，下一次同步保留服务端版本，覆盖本地并记录警告。此前成功的 `write` 或 `edit` 结果不代表修改最终保留；应用需要在同步后重新读取，再决定是否修改。

## 监控积压、停止工作与回收实例 [#监控积压停止工作与回收实例]

部署验收需要同时检查队列和执行实例：队列反映领取与确认情况，worker 日志和实例状态反映工具执行、上传及清理结果。以下示例由执行环境之外的监控或运维程序调用，使用已绑定的 MaaS API Key。

使用 CLI 或 SDK worker 时，领取和保活由辅助工具处理；应用仍需负责进程健康检查、实例回收，以及上传失败后的排查。

> 说明
>
> 这些端点接受已绑定的 MaaS API Key 或环境密钥。账户级运维调用应从 worker 执行环境之外发起，使用 MaaS API Key。请避免将 `AGENTAPI_API_KEY` 传入智能体可以执行命令的进程环境，以免工具读取账户级凭证。

### 读取队列深度 [#读取队列深度]

用 `work.stats` 区分“没有 worker”“领取后未确认”和“已有任务积压”，再决定检查接入还是扩容：

* `depth`：正在等待被领取的项数。可据此扩容 worker 集群，或在积压时告警。
* `pending`：worker 已领取但尚未确认的工作项数量。worker 辅助工具在处理工作项前会先确认，因此正常运行时该值应接近零；持续非零说明 worker 在领取后尚未完成确认。
* `oldest_queued_at`：队列中最早入队工作项的时间戳，包括等待领取和已领取但未确认的工作项；队列为空时为 `null`。
* `workers_polling`：过去 30 秒内轮询过的 worker 数量。可用于存活告警。

cURL

```bash
curl -sS "$AGENTAPI_BASE_URL/v1/environments/$ANTHROPIC_ENVIRONMENT_ID/work/stats" \
  -H "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
import os

import anthropic

client = anthropic.Anthropic(api_key=os.environ["AGENTAPI_API_KEY"], base_url=os.environ["AGENTAPI_BASE_URL"])

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")
```

TypeScript

````typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ apiKey: process.env.AGENTAPI_API_KEY!, baseURL: process.env.AGENTAPI_BASE_URL! });

const stats = await client.beta.environments.work.stats(process.env.ANTHROPIC_ENVIRONMENT_ID!);

console.log(`depth=${stats.depth} pending=${stats.pending}`);
```csharp
```csharp
using Anthropic;

var client = new AnthropicClient(new Anthropic.Core.ClientOptions
{
    ApiKey = System.Environment.GetEnvironmentVariable("AGENTAPI_API_KEY")!,
    BaseUrl = System.Environment.GetEnvironmentVariable("AGENTAPI_BASE_URL")!,
});

var environmentId = Environment.GetEnvironmentVariable("ANTHROPIC_ENVIRONMENT_ID")!;

var stats = await client.Beta.Environments.Work.Stats(environmentId);

Console.WriteLine($"depth={stats.Depth} pending={stats.Pending}");
````

Go

```go
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient(
	option.WithoutEnvironmentDefaults(),
	option.WithBaseURL(os.Getenv("AGENTAPI_BASE_URL")),
	option.WithAPIKey(os.Getenv("AGENTAPI_API_KEY")),
)
	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")

	stats, err := client.Beta.Environments.Work.Stats(
		context.Background(),
		environmentID,
		anthropic.BetaEnvironmentWorkStatsParams{},
	)
	if err != nil {
		panic(err)
	}

	fmt.Printf("depth=%d pending=%d\n", stats.Depth, stats.Pending)
}
```

Java

```java
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.work.BetaSelfHostedWorkQueueStats;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.builder()
        .apiKey(System.getenv("AGENTAPI_API_KEY"))
        .baseUrl(System.getenv("AGENTAPI_BASE_URL"))
        .build();

    BetaSelfHostedWorkQueueStats stats = client.beta()
        .environments()
        .work()
        .stats(System.getenv("ANTHROPIC_ENVIRONMENT_ID"));

    IO.println("depth=" + stats.depth() + " pending=" + stats.pending());
}
```

PHP

```php
<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv('AGENTAPI_API_KEY'), baseUrl: getenv('AGENTAPI_BASE_URL'));

$stats = $client->beta->environments->work->stats(getenv('ANTHROPIC_ENVIRONMENT_ID'));

printf("depth=%d pending=%d\n", $stats->depth, $stats->pending);
```

Ruby

```ruby
require "anthropic"

client = Anthropic::Client.new(api_key: ENV.fetch("AGENTAPI_API_KEY"), base_url: ENV.fetch("AGENTAPI_BASE_URL"))

stats = client.beta.environments.work.stats(ENV.fetch("ANTHROPIC_ENVIRONMENT_ID"))

puts "depth=#{stats.depth} pending=#{stats.pending}"
```

```text [wrap]
{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}
```

### 停止指定工作项 [#停止指定工作项]

> 停止工作与进程退出
>
> 使用 `work.stop` 请求 worker 停止指定会话的工作。默认情况下，工作项先转为 `stopping`；worker 在下一次租约心跳时检测到停止请求，取消该会话进行中的工具调用并确认关闭，随后工作项转为 `stopped`。需要立即标记停止时，可以在请求体中传入 `force: true`，或在 CLI 中使用 `--force`，将工作项标记为 `stopped`。该强制标记不保证工具进程已经退出；回收执行实例前，还需核对进程停止和资源清理结果。

运维系统需要自行设置 `ANTHROPIC_WORK_ID`，其值为待停止的工作项 ID。可以先通过环境工作项列表查询，具体请求字段见 [OpenAPI 参考](/products/agentapi/api/13618-agentapi-api-conventions)。

cURL

```bash
curl -sS "$AGENTAPI_BASE_URL/v1/environments/$ANTHROPIC_ENVIRONMENT_ID/work/$ANTHROPIC_WORK_ID/stop" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

Python

```python
import os

import anthropic

client = anthropic.Anthropic(api_key=os.environ["AGENTAPI_API_KEY"], base_url=os.environ["AGENTAPI_BASE_URL"])

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)
```

TypeScript

````typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ apiKey: process.env.AGENTAPI_API_KEY!, baseURL: process.env.AGENTAPI_BASE_URL! });

const work = await client.beta.environments.work.stop(process.env.ANTHROPIC_WORK_ID!, {
  environment_id: process.env.ANTHROPIC_ENVIRONMENT_ID!
});

console.log(work.state);
```csharp
```csharp
using Anthropic;

var client = new AnthropicClient(new Anthropic.Core.ClientOptions
{
    ApiKey = System.Environment.GetEnvironmentVariable("AGENTAPI_API_KEY")!,
    BaseUrl = System.Environment.GetEnvironmentVariable("AGENTAPI_BASE_URL")!,
});

var work = await client.Beta.Environments.Work.Stop(
    Environment.GetEnvironmentVariable("ANTHROPIC_WORK_ID")!,
    new()
    {
        EnvironmentID = Environment.GetEnvironmentVariable("ANTHROPIC_ENVIRONMENT_ID")!
    }
);

Console.WriteLine(work.State);
````

Go

```go
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient(
	option.WithoutEnvironmentDefaults(),
	option.WithBaseURL(os.Getenv("AGENTAPI_BASE_URL")),
	option.WithAPIKey(os.Getenv("AGENTAPI_API_KEY")),
)

	work, err := client.Beta.Environments.Work.Stop(
		context.Background(),
		os.Getenv("ANTHROPIC_WORK_ID"),
		anthropic.BetaEnvironmentWorkStopParams{
			EnvironmentID: os.Getenv("ANTHROPIC_ENVIRONMENT_ID"),
		},
	)
	if err != nil {
		panic(err)
	}
	fmt.Println(work.State)
}
```

Java

```java
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.environments.work.BetaSelfHostedWork;
import com.anthropic.models.beta.environments.work.BetaSelfHostedWorkStopRequest;
import com.anthropic.models.beta.environments.work.WorkStopParams;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.builder()
        .apiKey(System.getenv("AGENTAPI_API_KEY"))
        .baseUrl(System.getenv("AGENTAPI_BASE_URL"))
        .build();

    BetaSelfHostedWork work = client.beta().environments().work().stop(
        WorkStopParams.builder()
            .environmentId(System.getenv("ANTHROPIC_ENVIRONMENT_ID"))
            .workId(System.getenv("ANTHROPIC_WORK_ID"))
            .betaSelfHostedWorkStopRequest(BetaSelfHostedWorkStopRequest.builder().build())
            .build()
    );

    IO.println(work.state());
}
```

PHP

```php
<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv('AGENTAPI_API_KEY'), baseUrl: getenv('AGENTAPI_BASE_URL'));

$work = $client->beta->environments->work->stop(
    getenv('ANTHROPIC_WORK_ID'),
    environmentID: getenv('ANTHROPIC_ENVIRONMENT_ID'),
);

echo $work->state . "\n";
```

Ruby

```ruby
require "anthropic"

client = Anthropic::Client.new(api_key: ENV.fetch("AGENTAPI_API_KEY"), base_url: ENV.fetch("AGENTAPI_BASE_URL"))

work = client.beta.environments.work.stop(
  ENV.fetch("ANTHROPIC_WORK_ID"),
  environment_id: ENV.fetch("ANTHROPIC_ENVIRONMENT_ID")
)

puts work.state
```

### 退出与目录清理 [#退出与目录清理]

停止工作项后，还需确认 worker 的上传、目录清理和执行实例退出。`EnvironmentWorker` 不会自动安装信号处理程序，应用必须把退出转换为取消操作：

1. 将 SIGTERM、SIGINT 映射到 SDK 取消机制：Python 取消运行 `run()` 或 `handle_item()` 的任务，TypeScript 中止传给 worker 的 `signal`，Go 取消 context。
2. 独立 worker 进程在信号处理程序中取消；嵌入服务的 worker 在服务关闭钩子中取消，避免接管服务的信号处理。
3. 用 SIGTERM 请求退出，建议在强制终止前至少预留 60 秒，再留出本地文件清理时间。正常结束可能执行两个各有 30 秒超时的网络阶段，此建议不是总退出耗时保证。
4. 核对记忆写回、产物收集和进程退出结果，再回收实例。如果强制终止留下了 `/mnt/memory/` 存储目录，应在下次挂载前删除遗留目录；其中尚未同步的修改将丢失。

### 排查记忆挂载问题 [#排查记忆挂载问题]

记忆故障需检查 worker 日志，不能仅依赖会话错误事件：

* 挂载失败：工作项失败，会话保持空闲，不发出错误事件。
* 后台同步失败：仅记录日志。
* 只读访问拒绝：向智能体返回工具错误，见[只读存储与冲突](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

| 症状                                                                                                            | 原因                                     | 修复方法                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| worker 日志包含 `the work item carried no sessions token`（Go 中为 `ErrSessionMemoryNoToken`），工作项失败。                 | 工作项未提供会话凭证 `secret`，或启动脚本未将它传给执行实例。    | 按每个会话运行一个沙箱传入 `ANTHROPIC_WORK_SECRET`。同一进程领取并处理工作仍出现该错误时，请联系支持团队。                                                                                                                      |
| worker 日志包含 `something already exists at the memory store's path`。                                            | 上一个会话遗留了存储目录，通常是因为 worker 在完成清理前被强制终止。 | 删除日志中指定的遗留目录。其中尚未同步的修改将丢失。                                                                                                                                                             |
| worker 日志包含 `cannot create the memory store's folder` 和 `the worker host must make this mount path writable`。 | worker 运行所用的用户无法在 `/mnt/memory` 下创建目录。 | 创建 `/mnt/memory` 并将其 `chown` 给该用户；请参阅 [准备主机](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。             |
| 在 worker 领取会话后不久，会话处于 `idle` 状态，停止原因为 `requires_action`，且没有错误事件。                                              | 由于前述原因之一，worker 无法挂载记忆存储，因此使工作项失败。     | 在主机上修复原因，然后发送一个 [`user.interrupt`](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events) 事件：会话的工作会再次排队，下一个领取它的 worker 会重试挂载。 |

## SDK 接入方式查询 [#sdk-接入方式查询]

前面的方案分别对应三类 SDK 辅助工具。先确定哪个进程负责领取工作，再选择入口，避免轮询器和执行实例重复管理同一个工作项：

| 应用职责                       | SDK 入口                                          |
| -------------------------- | ----------------------------------------------- |
| 同一进程领取并执行，或执行实例处理一个工作项     | `EnvironmentWorker` 的 `run()` 或 `handle_item()` |
| 外部启动器领取后创建执行实例             | `work.poller()`                                 |
| 应用已领取工作并自行管理生命周期，只需要执行会话工具 | `client.beta.sessions.events.tool_runner()`     |

* `EnvironmentWorker`： 负责轮询、资源准备和工具执行。主要方法与配置项如下：

  * `.run()`：持续运行并处理新领取的会话工作。
  * `.handle_item()`：处理单个已认领工作项后退出。工作、会话和环境标识符可显式传入，或从 `ant beta:worker poll --on-work` 设置的 `ANTHROPIC_*` 变量读取。
  * `memory_sync_interval`（TypeScript 中为 `memorySyncIntervalMs`，Go 中为 `MemorySyncInterval`）和 `memory_sync_deletions`（`memorySyncDeletions`、`MemorySyncDeletions`）：前者控制会话运行期间已附加记忆存储的同步间隔，后者控制是否将本地文件删除同步到服务端存储。单位、默认值及关闭记忆支持的方法见[配置同步](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

* `work.poller()`： 轮询队列并返回已领取的工作项，由应用代码决定如何处理，例如为每个会话启动独立沙箱。它接受以下参数：

  * `drain`：队列为空时是停止轮询，还是继续等待新工作。
  * `block_ms`：单次轮询在返回前等待工作到达的时长（毫秒），取值必须在 1 到 999 之间；辅助工具会自动重新发起下一次轮询。AgentAPI 在省略此参数时使用 999 毫秒长轮询；不提供通过 `0` 或省略参数进行非阻塞检查的公共接口。
  * `reclaim_older_than_ms`：重新领取已被认领、但超过指定毫秒数仍未确认的工作项。
  * `auto_stop`（TypeScript 中为 `autoStop`，Go 中为 `AutoStop`）：是否在处理工作项后自动报告停止。将工作交给 `handle_item()`，或由沙箱内部报告停止时，应设为 `false`，避免重复报告。

* `client.beta.sessions.events.tool_runner()`： 根据会话 ID 和注册工具列表执行该会话的工具调用。适用于已领取工作，并自行管理工作生命周期的场景。

> 说明
>
> 使用 `.handle_item()` 挂载[记忆存储](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)时，还需传入工作项的 `secret`：Python 使用 `work_secret`，TypeScript 使用 `workSecret`，Go 使用 `WorkSecret`，或设置 `ANTHROPIC_WORK_SECRET`。
>
> `ant beta:worker poll --on-work` 不会设置该变量，启动脚本须从标准输入的工作项 JSON 中读取凭证，见[每个会话运行一个沙箱](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

需要自行启动每个会话的执行进程时，例如为每个已认领会话创建沙箱，请使用工作轮询器：

cURL

```bash
# work poller 是一个 SDK 辅助工具（Python、TypeScript、Go），而非原始
# 端点。在 shell 中，请改用 `ant beta:worker poll --on-work`；
# 请参阅 本页的 ant CLI 方式。
```

Python

```python
import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork

SANDBOX_ENV = (
    "ANTHROPIC_ENVIRONMENT_ID",
    "ANTHROPIC_ENVIRONMENT_KEY",
    "ANTHROPIC_WORK_ID",
    "ANTHROPIC_SESSION_ID",
    "ANTHROPIC_WORK_SECRET",
    "ANTHROPIC_BASE_URL",  # forwarded only when set on this host
)

async def launch_container(work: BetaSelfHostedWork) -> None:
    print(f"claimed session {work.data.id}")
    # 请将 `docker run` 替换为实际使用的沙箱启动器。转发环境
    # 密钥（切勿转发账户级 API 密钥）以及工作项的每会话密钥：内部的 worker
    # 需要该密钥来挂载会话的内存存储。
    env = os.environ | {
        "ANTHROPIC_WORK_ID": work.id,
        "ANTHROPIC_SESSION_ID": work.data.id,
        "ANTHROPIC_WORK_SECRET": work.secret or "",
    }
    forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
    launcher = await asyncio.create_subprocess_exec(
        "docker", "run", "--rm", "--detach", *forward, "your-sdk-worker-image", env=env
    )
    await launcher.wait()

async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key, base_url=os.environ["ANTHROPIC_BASE_URL"]) as client:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)

asyncio.run(main())
```

TypeScript

````typescript
import { spawn } from "node:child_process";
import { once } from "node:events";
import Anthropic from "@anthropic-ai/sdk";
import { WorkPoller } from "@anthropic-ai/sdk/helpers/beta/environments";
import type { BetaSelfHostedWork } from "@anthropic-ai/sdk/resources/beta/environments";

const SANDBOX_ENV = [
  "ANTHROPIC_ENVIRONMENT_ID",
  "ANTHROPIC_ENVIRONMENT_KEY",
  "ANTHROPIC_WORK_ID",
  "ANTHROPIC_SESSION_ID",
  "ANTHROPIC_WORK_SECRET",
  "ANTHROPIC_BASE_URL" // forwarded only when set on this host
];

const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
const client = new Anthropic({ authToken: environmentKey, baseURL: process.env.ANTHROPIC_BASE_URL! });

async function launchContainer(work: BetaSelfHostedWork): Promise<void> {
  console.log(`claimed session ${work.data.id}`);
  // 请将 `docker run` 替换为实际使用的沙箱启动器。转发环境
  // 密钥（切勿转发账户级 API 密钥）以及工作项的每会话密钥：
  // 内部的 worker 需要该密钥来挂载会话的内存存储。
  const env = {
    ...process.env,
    ANTHROPIC_WORK_ID: work.id,
    ANTHROPIC_SESSION_ID: work.data.id,
    ANTHROPIC_WORK_SECRET: work.secret ?? ""
  };
  const forward = SANDBOX_ENV.flatMap((name) => ["-e", name]);
  const launcher = spawn(
    "docker",
    ["run", "--rm", "--detach", ...forward, "your-sdk-worker-image"],
    { env, stdio: "inherit" }
  );
  await once(launcher, "close");
}

const poller = new WorkPoller({
  client,
  environmentId,
  environmentKey,
  autoStop: false // the launched sandbox owns the stop call
});

for await (const work of poller) {
  await launchContainer(work);
}
```csharp
```csharp
// C# SDK 目前尚未提供工作轮询辅助工具。
// 如需直接领取工作，请参阅 环境工作队列端点。
````

Go

```go
package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"os/exec"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/lib/environments"
	"github.com/anthropics/anthropic-sdk-go/option"
	"github.com/anthropics/anthropic-sdk-go/packages/param"
)

var sandboxEnv = []string{
	"ANTHROPIC_ENVIRONMENT_ID",
	"ANTHROPIC_ENVIRONMENT_KEY",
	"ANTHROPIC_WORK_ID",
	"ANTHROPIC_SESSION_ID",
	"ANTHROPIC_WORK_SECRET",
	"ANTHROPIC_BASE_URL", // forwarded only when set on this host
}

func launchContainer(ctx context.Context, work *anthropic.BetaSelfHostedWork) error {
	fmt.Printf("claimed session %s\n", work.Data.ID)
	// 请将 `docker run` 替换为实际使用的沙箱启动器。转发环境
	// 密钥（不得转发账户级 API 密钥）以及工作项的每会话密钥：内部的
	// worker 需要该密钥来挂载会话的内存存储。
	args := []string{"run", "--rm", "--detach"}
	for _, name := range sandboxEnv {
		args = append(args, "-e", name)
	}
	launcher := exec.CommandContext(ctx, "docker", append(args, "your-sdk-worker-image")...)
	launcher.Env = append(os.Environ(),
		"ANTHROPIC_WORK_ID="+work.ID,
		"ANTHROPIC_SESSION_ID="+work.Data.ID,
		"ANTHROPIC_WORK_SECRET="+work.Secret,
	)
	launcher.Stdout, launcher.Stderr = os.Stdout, os.Stderr
	return launcher.Run()
}

func main() {
	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")
	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")

	client := anthropic.NewClient(option.WithAuthToken(environmentKey), option.WithBaseURL(os.Getenv("ANTHROPIC_BASE_URL")))

	ctx := context.Background()

	poller := environments.NewWorkPoller(ctx, client, environments.WorkPollerOptions{
		EnvironmentID:  environmentID,
		EnvironmentKey: environmentKey,
		AutoStop:       param.NewOpt(false), // the launched sandbox owns the stop call
	})
	defer poller.Close()

	for work, err := range poller.All() {
		if err != nil {
			log.Fatal(err)
		}
		if err := launchContainer(ctx, work); err != nil {
			log.Fatal(err)
		}
	}
}
```

Java

```java
// Java SDK 目前尚未提供工作轮询辅助工具。
// 如需直接领取工作，请参阅 环境工作队列端点。
```

PHP

```php
// PHP SDK 目前尚未提供工作轮询辅助函数。
// 如需直接领取工作，请参阅 环境工作队列端点。
```

Ruby

```ruby
# Ruby SDK 目前尚未提供工作轮询辅助方法。
# 如需直接领取工作，请参阅 环境工作队列端点。
```

启动沙箱时，必须将已认领工作项的 `secret` 连同会话、工作和环境标识符一起传入，例如通过 `ANTHROPIC_WORK_SECRET` 提供会话凭证，供沙箱内 worker 挂载会话的[记忆存储](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。详见[每个会话运行一个沙箱](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

`AgentToolContext` 是工具调用的执行上下文，定义工作目录和路径策略，并支持下载会话技能。文件工具（`read`、`write`、`edit`、`glob`、`grep`）受以下路径限制：

* 这些工具只能在工作目录、以及 `allowed_roots`（TypeScript 中为 `allowedRoots`，Go 中为 `AllowedRoots`）列出的目录范围内操作。
* `write` 和 `edit` 还会额外拒绝 `read_only_roots`（`readOnlyRoots`、`ReadOnlyRoots`）下的路径。
* `EnvironmentWorker` 会自动将会话的记忆存储目录加入这些列表。

这些路径限制只作用于文件工具，不限制 `bash`，也不能替代沙箱隔离。`beta_agent_toolset_20260401(env)` 接收 `AgentToolContext`，返回 `bash`、`read`、`write`、`edit`、`glob`、`grep` 的实现。`native` 的 `web_fetch` 和 `web_search` 由 AgentAPI 执行，不会进入 worker 的工具队列。

使用 `EnvironmentWorker`： worker 自动管理工具上下文和内置工具实例。需要加入自定义工具时，传入 `tools` 工厂返回完整工具列表：

Python

```python
EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])
```

TypeScript

````typescript
new EnvironmentWorker({
  client,
  environmentId,
  environmentKey,
  tools: (ctx) => [betaBashTool(ctx), myCustomTool]
});
```csharp
```csharp
// EnvironmentWorker 目前在 C# SDK 中不可用。
// 如需直接响应自定义工具调用，请参阅会话事件流。
````

Go

```go
worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
	EnvironmentID:  environmentID,
	EnvironmentKey: environmentKey,
	ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool {
		return []anthropic.BetaTool{agenttoolset.BetaBashTool(env), myCustomTool}
	},
})
```

Java

```java
// Java SDK 目前不提供 EnvironmentWorker。
// 如需直接响应自定义工具调用，请参阅会话事件流。
```

PHP

```php
// PHP SDK 目前尚不支持 EnvironmentWorker。
// 如需直接响应自定义工具调用，请参阅会话事件流。
```

Ruby

```ruby
# Ruby SDK 目前暂不提供 EnvironmentWorker。
# 如需直接响应自定义工具调用，请参阅会话事件流。
```

使用 `work.poller()` 和 `tool_runner()`： 将工具列表作为 `tools` 传递给 `client.beta.sessions.events.tool_runner()`。若要构建该列表，请自行设置 `AgentToolContext` 并调用 `beta_agent_toolset_20260401(env)`：

Python

```python
from anthropic.lib.tools.agent_toolset import (
    AgentToolContext,
    beta_agent_toolset_20260401,
)

async with AgentToolContext(
    workdir="/workspace", client=client, session_id=work.data.id
) as env:
    # skills 已下载到 /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)
```

TypeScript

````typescript
import {
  setupSkills,
  betaAgentToolset20260401
} from "@anthropic-ai/sdk/tools/agent-toolset/node";

const ctx = { workdir: "/workspace", client, sessionId: work.data.id };
await setupSkills(ctx);
const tools = betaAgentToolset20260401(ctx);
```csharp
```csharp
// AgentToolContext 目前在 C# SDK 中不可用。
````

Go

```go
env := &agenttoolset.AgentToolContext{Workdir: "/workspace"}
if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil {
	panic(err)
}
// skills 已下载到 /workspace/skills/<name>/
tools := agenttoolset.BetaAgentToolset20260401(env)
```

Java

```java
// AgentToolContext 目前在 Java SDK 中不可用。
```

PHP

```php
// PHP SDK 目前不支持 AgentToolContext。
```

Ruby

```ruby
# Ruby SDK 目前不支持 AgentToolContext。
```

## 后续步骤 [#后续步骤]

* [自托管安全责任](/products/agentapi/development_guidelines/agentapi-execution-environments/13615-agentapi-execution-environments-self-hosted-security)：核对数据流、凭证和执行隔离。
* [会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)：创建任务并发送输入。
* [OpenAPI 参考](/products/agentapi/api/13618-agentapi-api-conventions)：查看环境工作队列的请求与响应字段。


# 自托管安全责任 (/products/agentapi/development_guidelines/agentapi-execution-environments/13615-agentapi-execution-environments-self-hosted-security)



最近更新时间: 2026-10-13 15:32:15

自托管仅将文件操作和命令执行交给自托管 worker，会话事件和模型调用仍由 AgentAPI 管理。请核对数据流、凭证和执行隔离；自托管不保证数据不出网。

## 确认数据流与访问范围 [#确认数据流与访问范围]

用户消息、工具定义、工具参数和工具结果会进入 AgentAPI，并按模型调用需要传给模型服务。文件在 worker 上处理时，读出的内容也可能通过工具结果进入模型上下文。请根据业务的数据要求控制输入和工具输出。

`native` 的网页工具和直接配置的 MCP 连接由 AgentAPI 执行。仅在内部网络可访问的服务，应通过 worker 中的自定义工具访问，并回传必要的结果；这些工具仍需自行校验权限。执行路径见[自托管执行器](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

## 分离三类凭证 [#分离三类凭证]

| 凭证                | 用途                     | 保存与传递                                             |
| ----------------- | ---------------------- | ------------------------------------------------- |
| 已绑定的 MaaS API Key | 账户级 API 调用，例如创建会话与资源管理 | 保留在应用服务端或运维系统，避免传入智能体可执行命令的进程环境。                  |
| 环境密钥（Worker key）  | 轮询指定环境的工作队列并回传结果       | 通过密钥管理系统提供给 worker，避免写入镜像或日志；疑似泄露时在 Portal 撤销并轮换。 |
| 工作项的会话凭证 `secret` | 访问当前会话获准使用的记忆等资源       | 只传给处理该会话的执行实例，避免存入镜像、共享卷或日志。                      |

CLI 和兼容 SDK 使用 `ANTHROPIC_ENVIRONMENT_KEY`、`ANTHROPIC_WORK_SECRET` 等变量名。这些名称来自客户端约定，其值应为 AgentAPI 返回的对应凭证。记忆访问不能用环境密钥代替会话凭证，见[使用记忆存储](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

请监测凭证异常使用并及时轮换。撤销环境密钥在 worker 的后续请求中生效。

## 隔离执行环境 [#隔离执行环境]

工具以 worker 进程的权限运行。请根据任务的信任边界分离环境、执行实例、工作目录和网络权限，避免不受信任的代码读取其他会话的文件或凭证。

* 镜像与进程权限：验证镜像来源，移除不需要的 Linux capabilities，以非 root 用户运行；只读根文件系统需为工作目录等必要路径保留可写空间。AgentAPI 不验证镜像或 worker 构建。
* 网络出口：通过 VPC、防火墙或沙箱网络策略限制 worker 访问的服务。环境中的云端网络配置不能替代自有基础设施上的出站控制。
* 文件挂载：只提供任务所需目录，避免挂载宿主机凭证或其他会话的数据。多个会话使用同一个记忆存储时，为每个会话提供独立文件系统。
* 工具审批：在自定义工具实现中校验参数、业务身份和操作权限。AgentAPI 的工具权限策略不能替代这些校验。

## 保护记忆副本 [#保护记忆副本]

SDK worker 在 `/mnt/memory/` 下维护并同步记忆副本，正常退出时清理目录。强制终止可能留下目录及未同步内容，需由业务系统清理并限制访问。

`read_only` 禁止文件工具写入及记忆写回，但不使本地目录只读。`bash` 或可写文件的自定义工具仍可能修改副本，影响后续读取。

如果必须保证本地视图不被任务修改，请禁用 `bash`，限制其他工具的写入能力，并配置执行环境的访问控制。准备目录与同步策略见[记忆存储接入](/products/agentapi/development_guidelines/agentapi-execution-environments/13614-agentapi-execution-environments-self-hosted)。

## 管理日志与数据清理 [#管理日志与数据清理]

会话内容和工具结果可能留存在 worker 日志、工作目录和监控系统中。需要按业务要求脱敏、限制访问并设置保留期限。AgentAPI 中的归档、删除或历史脱敏不会自动清除自有基础设施上的副本。

停止 worker 时，应先取消正在处理的工作，为记忆上传和目录清理留出时间，再回收执行实例。强制停止工作项只改变服务端状态，不能保证宿主机进程已经退出；请同时检查基础设施上的实际进程与资源。


# 创建会话 (/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)



最近更新时间: 2026-10-13 15:31:33

会话（Session）保存一个任务的输入、智能体输出、工具调用和交互历史。创建时引用[智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)与[云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)，并固定智能体版本；发送用户事件后才开始执行。

![会话消息与事件流](/docs-assets/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session/FqtI0KwhVzMFwEnlT0HhD74hSVSv-628ee27bb049.webp)

## 任务与执行轮次 [#任务与执行轮次]

数据分析任务可以在同一会话中提交数据、补充统计口径和修订报告，共用历史与文件；无关任务应创建新会话。新会话以 `idle` 状态开始，首次输入才准备云端沙箱。

会话状态与恢复边界见[会话操作](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13598-agentapi-sessions-and-tasks-session-lifecycle)，本轮结果按[停止原因](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)判断。

## 创建会话 [#创建会话]

创建会话必须提供 `agent` 和 `environment_id`。智能体是版本化资源；建议明确传入版本对象，使同一任务始终使用可追溯的智能体配置。会话使用的 `runtime` 继承自该智能体版本，请在[定义智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)时选择 `claudecode`、`codex` 或 `native`，不要把 `runtime` 作为会话字段传入。

开始前，请完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)，并保存创建智能体和云端环境时返回的 ID。以下 SDK 示例沿用[SDK 客户端初始化](/products/agentapi/quick_start/13587-agentapi-quickstart)中的 `client`。以下示例仅传入智能体 ID：会话固定创建时的最新版本，后续智能体更新不会改变会话配置。

cURL

```bash
session=$(curl --request POST "$AGENTAPI_BASE_URL/v1/sessions" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID"
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")
```

Python

```python
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)
```

TypeScript

````typescript
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id
});
```csharp
```csharp
var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
});
````

Go

```go
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfString: anthropic.String(agent.ID),
	},
	EnvironmentID: environment.ID,
})
if err != nil {
	panic(err)
}
```

Java

```java
var session = client.beta().sessions().create(SessionCreateParams.builder()
    .agent(agent.id())
    .environmentId(environment.id())
    .build());
```

PHP

```php
$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
);
```

Ruby

```ruby
session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id
)
```

## 发送消息启动执行 [#发送消息启动执行]

会话创建后，向 `POST /v1/sessions/{id}/events` 提交 `user.message` 才会启动执行。结构化输入使用 `input.parts`；HTTP 与 SDK 的发送方式见[提交任务输入](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)，进度通过[事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)读取。

## 配置会话的资源与行为 [#配置会话的资源与行为]

### 任务信息和资源 [#任务信息和资源]

创建请求还可以包含以下信息：

* `title`：便于在 Portal 和列表中识别任务的标题。
* `metadata`：字符串键值对，用于关联业务 ID、任务来源等信息。
* `resources`：挂载[文件](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)、[GitHub 仓库](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13604-agentapi-data-and-integrations-github)或[记忆存储](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13603-agentapi-data-and-integrations-memory)。单个会话最多可以添加 500 个资源，其中记忆存储最多 8 个。
* `vault_ids`：为需要认证的 MCP 服务关联凭证，详见MCP 身份验证。

GitHub 仓库需要沙箱的 Git 能力。`claudecode`、`codex` 支持这类资源；`native` 在启用沙箱执行工具时也支持，并会在首个模型请求前异步准备沙箱，模型调用沙箱工具时等待沙箱就绪。

Portal 会话详情顶部的凭证库入口显示关联数量。点击后，您可以查看各凭证库的名称、ID 和归档状态，并进入[凭证库](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13606-agentapi-data-and-integrations-vaults)详情；没有关联时显示“未关联凭证库”。

### 固定智能体版本 [#固定智能体版本]

要将会话固定到特定的智能体版本，请传入一个对象，以控制执行版本并分阶段发布新版本。

cURL

```bash
pinned_session=$(curl --request POST "$AGENTAPI_BASE_URL/v1/sessions" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
  "agent": {"type": "agent", "id": "$AGENT_ID", "version": 1},
  "environment_id": "$ENVIRONMENT_ID"
}
EOF
)
PINNED_SESSION_ID=$(jq -r '.id' <<< "$pinned_session")
```

Python

```python
pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)
```

TypeScript

````typescript
const pinnedSession = await client.beta.sessions.create({
  agent: { type: "agent", id: agent.id, version: 1 },
  environment_id: environment.id
});
```csharp
```csharp
var pinnedSession = await client.Beta.Sessions.Create(new()
{
    Agent = new BetaManagedAgentsAgentParams
    {
        Type = BetaManagedAgentsAgentParamsType.Agent,
        ID = agent.ID,
        Version = 1,
    },
    EnvironmentID = environment.ID,
});
````

Go

```go
pinnedSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
			Type:    anthropic.BetaManagedAgentsAgentParamsTypeAgent,
			ID:      agent.ID,
			Version: anthropic.Int(1),
		},
	},
	EnvironmentID: environment.ID,
})
if err != nil {
	panic(err)
}
```

Java

```java
var pinnedSession = client.beta().sessions().create(SessionCreateParams.builder()
    .agent(BetaManagedAgentsAgentParams.builder()
        .type(BetaManagedAgentsAgentParams.Type.AGENT)
        .id(agent.id())
        .version(1)
        .build())
    .environmentId(environment.id())
    .build());
```

PHP

```php
$pinnedSession = $client->beta->sessions->create(
    agent: ['type' => 'agent', 'id' => $agent->id, 'version' => 1],
    environmentID: $environment->id,
);
```

Ruby

```ruby
pinned_session = client.beta.sessions.create(
  agent: {type: :agent, id: agent.id, version: 1},
  environment_id: environment.id
)
```

### 为会话覆盖智能体配置 [#为会话覆盖智能体配置]

创建会话时，可以使用 `agent_with_overrides` 只为当前会话覆盖智能体配置，而不修改智能体，也不会创建新的智能体版本。传入智能体的 `id` 和可选的 `version`（省略 `version` 时使用最新版本），并可覆盖 `model`、`system`、`tools`、`mcp_servers`、`skills` 中的一项或多项。

| 请求内容           | 会话使用的配置                                        |
| -------------- | ---------------------------------------------- |
| 省略某个覆盖字段       | 继承所固定的智能体版本。                                   |
| 提交字段值          | 整体替换对应字段，不与基础配置合并。                             |
| `system: null` | 清空系统提示。                                        |
| 列表字段为空数组       | 清空对应的工具、MCP 服务器或技能列表。                          |
| 提交 `model` 对象  | 使用新模型对象；显式提供的 `effort` 会生效，省略时不继承基础配置的 effort。 |

例如，`"model": {"id": "your-model-id", "effort": {"type": "high"}}` 会为这次会话设置模型和思考强度；只提供 `id` 则使用该模型的默认强度。请从[七牛 MaaS 模型管理页](https://portal.qiniu.com/ai-inference/model)获取可用的模型 ID。

会话仍会固定一个智能体版本。`runtime` 和 `agentapi_options` 从该版本继承，会话覆盖不能改变它们；因此 `thinking` 和 `system_prompt_mode` 也保持该版本的设置。

如需调整这些配置，请更新智能体并创建新会话。用法见[思考配置](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)和[系统提示词放置方式](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)。

创建响应的 `agent` 是覆盖后的配置快照，`id` 和 `version` 仍指向原智能体版本。快照不回显思考开关和系统提示词放置方式；请通过 `id` 和 `version` 查询对应版本。

cURL

```bash
override_session=$(curl --request POST "$AGENTAPI_BASE_URL/v1/sessions" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
  "agent": {
    "type": "agent_with_overrides",
    "id": "$AGENT_ID",
    "version": 1,
    "model": {"id": "$AGENTAPI_MODEL_ID"}
  },
  "environment_id": "$ENVIRONMENT_ID"
}
EOF
)
OVERRIDE_SESSION_ID=$(jq -r '.id' <<< "$override_session")
```

Python

```python
override_session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        "version": 1,
        "model": {"id": "gpt-5.6-sol"},
    },
    environment_id=environment.id,
)
```

TypeScript

````typescript
const overrideSession = await client.beta.sessions.create({
  agent: {
    type: "agent_with_overrides",
    id: agent.id,
    version: 1,
    model: { id: "gpt-5.6-sol" }
  },
  environment_id: environment.id
});
```csharp
```csharp
var overrideSession = await client.Beta.Sessions.Create(new()
{
    Agent = new BetaManagedAgentsAgentWithOverridesParams
    {
        Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
        ID = agent.ID,
        Version = 1,
        Model = new BetaManagedAgentsModelConfigParams { ID = "gpt-5.6-sol" },
    },
    EnvironmentID = environment.ID,
});
````

Go

```go
overrideSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
			Type:    anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
			ID:      agent.ID,
			Version: anthropic.Int(1),
			Model: anthropic.BetaManagedAgentsModelConfigParams{
				ID: "gpt-5.6-sol",
			},
		},
	},
	EnvironmentID: environment.ID,
})
if err != nil {
	panic(err)
}
```

Java

```java
var overrideSession = client.beta().sessions().create(
    SessionCreateParams.builder()
        .agent(BetaManagedAgentsAgentWithOverridesParams.builder()
            .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
            .id(agent.id())
            .version(1)
            .model(BetaManagedAgentsModelConfigParams.builder()
                .id("gpt-5.6-sol")
                .build())
            .build())
        .environmentId(environment.id())
        .build()
);
```

PHP

```php
$overrideSession = $client->beta->sessions->create(
    agent: BetaManagedAgentsAgentWithOverridesParams::with(
        type: 'agent_with_overrides',
        id: $agent->id,
        version: 1,
        model: ['id' => 'gpt-5.6-sol'],
    ),
    environmentID: $environment->id,
);
```

Ruby

```ruby
override_session = client.beta.sessions.create(
  agent: Anthropic::Beta::BetaManagedAgentsAgentWithOverridesParams.new(
    type: :agent_with_overrides,
    id: agent.id,
    version: 1,
    model: {id: "gpt-5.6-sol"}
  ),
  environment_id: environment.id
)
```

## MCP 身份验证 [#mcp-身份验证]

创建会话时通过 `vault_ids` 引用凭证。一个会话最多引用 50 个 Vault，执行时最多匹配并注入 20 个凭证。Vault 创建与凭证匹配规则见[凭证管理](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13606-agentapi-data-and-integrations-vaults)，会话接入示例见[MCP 身份验证](/products/agentapi/development_guidelines/agentapi-agent-configuration/13592-agentapi-agent-configuration-mcp)。

## 后续步骤 [#后续步骤]

* [会话操作](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13598-agentapi-sessions-and-tasks-session-lifecycle)：检索、列出、更新、归档和删除会话。
* [事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)：订阅响应，处理中断、工具结果和工具确认。
* [定时部署](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13600-agentapi-sessions-and-tasks-scheduled-deployments)：按 cron 周期运行智能体并查看执行历史。


# 事件和事件流 (/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)



最近更新时间: 2026-10-13 15:31:35

应用提交任务后，需要持续接收回答、工具调用和状态变化，才能判断云端执行的结果。AgentAPI 将这些记录保存在会话中，应用可以通过 SSE 实时消费，也可以查询历史。

涉及通知、写库或其他外部副作用时，应用应在自己的事务中同时记录业务状态和消费进度，并为可重试操作设置业务幂等键。

无需持续保持 SSE 连接的资源变更或会话状态通知，可在 Portal 配置 [Webhook](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13605-agentapi-data-and-integrations-webhooks)。Webhook 不转发所有会话事件；收到通知后仍需读取停止原因、回答和产物，不能把会话空闲视为任务成功。

## 执行结果判断 [#执行结果判断]

应用收到 `agent.message` 时可以展示回答；收到 `session.status_idle` 时，才知道本轮已停止。停止不一定代表任务完成，需要根据 `stop_reason` 决定下一步：

| 停止原因                | 应用的下一步                                         |
| ------------------- | ---------------------------------------------- |
| `end_turn`          | 检查最终回答和任务产物，确认满足业务要求。                          |
| `requires_action`   | 按 `stop_reason.event_ids` 找到阻塞事件，处理自定义工具或工具确认。 |
| `interrupted`       | 记录中断，检查已完成的操作；中断不会撤销外部修改。                      |
| `budget_reached`    | 检查预算和部分产物，再决定是否继续。                             |
| `retries_exhausted` | 读取错误信息，解决问题后再发送输入。                             |

> 状态与停止原因
>
> `native` 的人工中断也使用 `end_turn`，需结合 `user.interrupt` 事件判断。`session.error` 本身不代表会话已终止，应继续检查后续状态；进入 `terminated` 的会话不能继续接收任务输入。

## 建立事件消费循环 [#建立事件消费循环]

### 事件接入方式 [#事件接入方式]

创建[会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)后，保存会话 ID，并用它完成以下操作。请求路径均以 `/v1/sessions/{id}` 为前缀。

| 操作     | 请求方法与路径后缀            | 使用场景                                        |
| ------ | -------------------- | ------------------------------------------- |
| 发送事件   | `POST /events`       | 提交用户消息、中断、工具结果或确认。请求返回表示事件已接收，任务结果需从后续事件读取。 |
| 订阅事件流  | `GET /events/stream` | 通过 SSE 展示执行进度。连接先回放历史，再推送实时事件。              |
| 读取事件历史 | `GET /events`        | 分页读取已保存的记录，用于查询、审计或恢复应用状态。                  |

消费循环应先订阅事件流，再发送用户消息，并持续处理回答和状态变化。应用重启或连接中断后，按回放和去重恢复消费。

### 订阅回答和执行进度 [#订阅回答和执行进度]

消费端先打开 SSE 连接，再提交输入。事件流按顺序回放历史并继续推送新事件；收到 `session.status_idle` 后，连接仍保持打开，应用根据执行结果决定后续操作。

完整的 `agent.message` 用于展示回答。若 Native 应用需要提前展示生成中的文字，应在发送输入前订阅增量预览；这类预览不写入历史，重连后不能补回。

Native 会话可通过 `event_deltas[]=agent.message` 订阅当前模型请求的文本预览，其他运行时忽略此参数：

* 正常结束：依次收到 `event_start`、若干 `event_delta` 和同一 ID 的完整 `agent.message`。
* 请求失败或中断：不返回完整消息，以 `span.model_request_end` 结束预览。
* 增量仅对当前连接有效，不写入历史，按模型输出尽力推送，不保证逐字符或逐 token。

例如，客户端可能收到以下 SSE 帧（`event_delta` 的数量和每段文本长度由模型服务决定）：

```text
event: event_start
data: {"type":"event_start","event":{"type":"agent.message","id":"evt_..."}}

event: event_delta
data: {"type":"event_delta","event_id":"evt_...","delta":{"type":"content_delta","index":0,"content":{"type":"text","text":"你"}}}

event: event_delta
data: {"type":"event_delta","event_id":"evt_...","delta":{"type":"content_delta","index":0,"content":{"type":"text","text":"好"}}}

event: agent.message
data: {"type":"agent.message","id":"evt_...","content":[{"type":"text","text":"你好"}]}
```

> 单轮示例的适用范围
>
> 下面的示例用于新建会话的一轮执行，在收到 `session.status_idle` 或错误时退出。已有会话的流会先回放历史，其中的旧 `idle` 不代表新一轮已经结束。持续运行的应用应使用回放和去重示例，并按停止原因处理工具等待和错误，不能仅凭 `idle` 判定任务成功。

cURL

```bash
# 先打开流，再发送用户消息
exec {stream}< <(
  curl --fail-with-body -sS -N \
    "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events/stream?event_deltas%5B%5D=agent.message" \
    -H "x-api-key: $AGENTAPI_API_KEY" \
    -H "content-type: application/json" \
    -H "accept: text/event-stream"
)

curl --fail-with-body -sS \
  "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  -d @- >/dev/null <<'EOF'
{
  "events": [
    {
      "type": "user.message",
      "input": {"parts": [{"type": "text", "text": "Summarize the repo README"}]}
    }
  ]
}
EOF

while IFS= read -r -u "$stream" event_line; do
  [[ $event_line == data:* ]] || continue
  event_json=${event_line#data: }
  case $(jq -r '.type' <<<"$event_json") in
    agent.message)
      jq -j '.content[] | select(.type == "text") | .text' <<<"$event_json"
      ;;
    session.status_idle)
      break
      ;;
    session.error)
      printf '\n[Error: %s]\n' "$(jq -r '.error.message // "unknown"' <<<"$event_json")"
      break
      ;;
  esac
done
exec {stream}<&-
```

Python

```python
# 先打开流，再发送用户消息
with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Summarize the repo README"}],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.status_idle":
                break
            case "session.error":
                error_message = event.error.message if event.error else "unknown"
                print(f"\n[Error: {error_message}]")
                break
```

TypeScript

````typescript
// 先打开流，再发送用户消息
const stream = await client.beta.sessions.events.stream(session.id);
await client.beta.sessions.events.send(session.id, {
  events: [
    {
      type: "user.message",
      content: [{ type: "text", text: "Summarize the repo README" }]
    }
  ]
});

for await (const event of stream) {
  if (event.type === "agent.message") {
    for (const block of event.content) {
      if (block.type === "text") {
        process.stdout.write(block.text);
      }
    }
  } else if (event.type === "session.status_idle") {
    break;
  } else if (event.type === "session.error") {
    console.log(`\n[Error: ${event.error?.message ?? "unknown"}]`);
    break;
  }
}
```csharp
```csharp
// 先打开流，然后再发送用户消息
using var stream = await client.Beta.Sessions.Events.WithRawResponse.StreamStreaming(session.ID);
await client.Beta.Sessions.Events.Send(session.ID, new()
{
    Events =
    [
        new BetaManagedAgentsUserMessageEventParams
        {
            Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
            Content =
            [
                new BetaManagedAgentsTextBlock
                {
                    Type = BetaManagedAgentsTextBlockType.Text,
                    Text = "Summarize the repo README",
                },
            ],
        },
    ],
});

await foreach (var streamEvent in stream.Enumerate())
{
    if (streamEvent.Value is BetaManagedAgentsAgentMessageEvent message)
    {
        foreach (var block in message.Content)
        {
            Console.Write(block.Text);
        }
    }
    else if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent)
    {
        break;
    }
    else if (streamEvent.Value is BetaManagedAgentsSessionErrorEvent error)
    {
        Console.WriteLine($"\n[Error: {error.Error?.Message ?? "unknown"}]");
        break;
    }
}
````

Go

```go
	// 先打开流，然后发送用户消息
	stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
	defer stream.Close()

	if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
		Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
			OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
				Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
				Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
					OfText: &anthropic.BetaManagedAgentsTextBlockParam{
						Type: anthropic.BetaManagedAgentsTextBlockTypeText,
						Text: "Summarize the repo README",
					},
				}},
			},
		}},
	}); err != nil {
		panic(err)
	}

events:
	for stream.Next() {
		switch event := stream.Current().AsAny().(type) {
		case anthropic.BetaManagedAgentsAgentMessageEvent:
			// 具体类型列表：BetaManagedAgentsTextBlock
			for _, block := range event.Content {
				fmt.Print(block.Text)
			}
		case anthropic.BetaManagedAgentsSessionStatusIdleEvent:
			break events
		case anthropic.BetaManagedAgentsSessionErrorEvent:
			fmt.Printf("\n[Error: %s]\n", cmp.Or(event.Error.Message, "unknown"))
			break events
		}
	}
	if err := stream.Err(); err != nil {
		panic(err)
	}
```

Java

```java
// 先打开流，然后发送用户消息
try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
    client.beta().sessions().events().send(
        session.id(),
        EventSendParams.builder()
            .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
                .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
                .addTextContent("Summarize the repo README")
                .build())
            .build()
    );

    Iterable<BetaManagedAgentsStreamSessionEvents> events = stream.stream()::iterator;
    for (var event : events) {
        if (event.isAgentMessage()) {
            event.asAgentMessage().content().forEach(block -> block.text().ifPresent(textBlock -> IO.print(textBlock.text())));
        } else if (event.isSessionStatusIdle()) {
            break;
        } else if (event.isSessionError()) {
            // `message` 字段在所有错误变体中都存在；从原始 JSON 中读取它。
            var errorMessage =
                event.asSessionError().error()._json().orElse(null) instanceof JsonObject json
                    ? json.values().get("message").asStringOrThrow()
                    : "unknown";
            IO.println("\n[Error: " + errorMessage + "]");
            break;
        }
    }
}
```

PHP

```php
// 先打开流，再发送用户消息
$stream = $client->beta->sessions->events->streamStream($session->id);
$client->beta->sessions->events->send(
    $session->id,
    events: [
        [
            'type' => 'user.message',
            'content' => [['type' => 'text', 'text' => 'Summarize the repo README']],
        ],
    ],
);

foreach ($stream as $event) {
    match ($event->type) {
        'agent.message' => array_walk(
            $event->content,
            static fn ($block) => $block->type === 'text' ? print($block->text) : null,
        ),
        'session.error' => printf("\n[Error: %s]", $event->error?->message ?? 'unknown'),
        default => null,
    };
    if ($event->type === 'session.status_idle' || $event->type === 'session.error') {
        break;
    }
}
$stream->close();
```

Ruby

```ruby
# 先打开流，再发送用户消息
stream = client.beta.sessions.events.stream_events(session.id)

client.beta.sessions.events.send_(
  session.id,
  events: [{
    type: "user.message",
    content: [{type: "text", text: "Summarize the repo README"}]
  }]
)

stream.each do |event|
  case event.type
  in :"agent.message"
    event.content.each { print it.text }
  in :"session.status_idle"
    break
  in :"session.error"
    puts "\n[Error: #{event.error&.message || "unknown"}]"
    break
  else
    # 忽略其他事件类型
  end
end
```

### 提交任务输入 [#提交任务输入]

订阅建立后，发送 `user.message` 启动执行。下面提交文件性能分析任务；请求返回仅表示输入已接收，回答和执行结果仍需从事件流读取。

cURL

```bash
curl --fail-with-body -sS "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "events": [
    {
      "type": "user.message",
      "input": {"parts": [
        {"type": "text", "text": "Analyze the performance of the sort function in utils.py"}
      ]}
    }
  ]
}
EOF
```

Python

```python
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {
                    "type": "text",
                    "text": "Analyze the performance of the sort function in utils.py",
                },
            ],
        },
    ],
)
```

TypeScript

````typescript
await client.beta.sessions.events.send(session.id, {
  events: [
    {
      type: "user.message",
      content: [
        {
          type: "text",
          text: "Analyze the performance of the sort function in utils.py",
        },
      ],
    },
  ],
});
```csharp
```csharp
await client.Beta.Sessions.Events.Send(session.ID, new()
{
    Events =
    [
        new BetaManagedAgentsUserMessageEventParams
        {
            Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
            Content =
            [
                new BetaManagedAgentsTextBlock
                {
                    Type = BetaManagedAgentsTextBlockType.Text,
                    Text = "Analyze the performance of the sort function in utils.py",
                },
            ],
        },
    ],
});
````

Go

```go
if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
					Text: "Analyze the performance of the sort function in utils.py",
				},
			}},
		},
	}},
}); err != nil {
	panic(err)
}
```

Java

```java
client.beta().sessions().events().send(
    session.id(),
    EventSendParams.builder()
        .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
            .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
            .addTextContent("Analyze the performance of the sort function in utils.py")
            .build())
        .build());
```

PHP

```php
$client->beta->sessions->events->send(
    $session->id,
    events: [
        [
            'type' => 'user.message',
            'content' => [
                [
                    'type' => 'text',
                    'text' => 'Analyze the performance of the sort function in utils.py',
                ],
            ],
        ],
    ],
);
```

Ruby

```ruby
client.beta.sessions.events.send_(
  session.id,
  events: [
    {
      type: "user.message",
      content: [
        {
          type: "text",
          text: "Analyze the performance of the sort function in utils.py"
        }
      ]
    }
  ]
)
```

## 恢复事件消费 [#恢复事件消费]

页面刷新、网络断开或应用重启后，重新订阅同一个会话。服务端会回放历史，应用需要保存已处理的事件 ID，避免重复展示回答或重复触发业务处理：

1. 打开一个新流。
2. 依次消费服务端先回放的历史事件和随后到达的实时事件。
3. 对每个事件按 ID 去重，再交给业务逻辑；不要仅因回放历史中的 `session.status_idle` 而关闭连接。

下面的 `loadSeenEventIds`、`persistSeenEventId`（以及其他语言的对应函数）需由应用实现。示例持续消费回放和实时事件；页面关闭、会话终止或其他业务条件满足时，由应用关闭连接。

> 业务处理与消费进度
>
> 下面的展示去重示例在处理前记录 ID，崩溃时可能遗漏展示。涉及通知、写库或其他副作用时，应在应用自己的事务中同时提交业务状态、消费进度和待发送通知，并使用业务幂等键处理重试。

cURL

```bash
exec {stream}< <(
  curl --fail-with-body -sS -N \
    "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events/stream" \
    -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  -H "accept: text/event-stream"
)

# 从应用自己的持久化状态加载已经交给业务逻辑的事件 ID。
declare -A seen_event_ids

# SSE 会先回放历史，再继续推送实时事件。
while IFS= read -r -u "$stream" event_line; do
  [[ $event_line == data:* ]] || continue
  event_json=${event_line#data: }
  event_id=$(jq -r '.id' <<<"$event_json")
  [[ -n ${seen_event_ids[$event_id]+seen} ]] && continue
  seen_event_ids[$event_id]=1
  case $(jq -r '.type' <<<"$event_json") in
    agent.message)
      jq -j '.content[] | select(.type == "text") | .text' <<<"$event_json"
      ;;
    session.status_idle)
      # 历史事件中的 idle 不代表新一轮已完成；连接继续等待。
      ;;
  esac
done
exec {stream}<&-
```

Python

```python
seen_event_ids = load_seen_event_ids(session.id)  # 从应用存储恢复
with client.beta.sessions.events.stream(session.id) as stream:
    # 服务端会先回放历史，然后继续推送实时事件。
    for event in stream:
        if event.id in seen_event_ids:
            continue
        seen_event_ids.add(event.id)
        persist_seen_event_id(session.id, event.id)
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
```

TypeScript

````typescript
const seenEventIds = await loadSeenEventIds(session.id); // 应用自己的持久化状态
const stream = await client.beta.sessions.events.stream(session.id);

// 服务端会先回放历史，然后继续推送实时事件。
for await (const event of stream) {
  if (seenEventIds.has(event.id)) continue;
  seenEventIds.add(event.id);
  await persistSeenEventId(session.id, event.id);
  if (event.type === "agent.message") {
    for (const block of event.content) {
      if (block.type === "text") {
        process.stdout.write(block.text);
      }
    }
  }
}
```csharp
```csharp
using var stream = await client.Beta.Sessions.Events.WithRawResponse.StreamStreaming(session.ID);

// 从应用自己的持久化状态加载已处理的事件 ID。
HashSet<string> seenEventIds = await LoadSeenEventIds(session.ID);

// 服务端会先回放历史，然后继续推送实时事件。
await foreach (var streamEvent in stream.Enumerate())
{
    if (!seenEventIds.Add(streamEvent.ID))
    {
        continue;
    }
    await PersistSeenEventId(session.ID, streamEvent.ID);
    if (streamEvent.Value is BetaManagedAgentsAgentMessageEvent message)
    {
        foreach (var block in message.Content)
        {
            Console.Write(block.Text);
        }
    }
}
````

Go

```go
	stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
	defer stream.Close()

	// 从应用自己的持久化状态加载已处理的事件 ID。
	seenEventIDs := loadSeenEventIDs(session.ID)

	// 服务端会先回放历史，然后继续推送实时事件。
	for stream.Next() {
		event := stream.Current()
		if _, seen := seenEventIDs[event.ID]; seen {
			continue
		}
		seenEventIDs[event.ID] = struct{}{}
		persistSeenEventID(session.ID, event.ID)
		switch event := event.AsAny().(type) {
		case anthropic.BetaManagedAgentsAgentMessageEvent:
			// 具体类型列表：BetaManagedAgentsTextBlock
			for _, block := range event.Content {
				fmt.Print(block.Text)
			}
		}
	}
	if err := stream.Err(); err != nil {
		panic(err)
	}
```

Java

```java
try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
    // 从应用自己的持久化状态加载已处理的事件 ID。
    var seenEventIds = loadSeenEventIds(session.id());

    // 服务端会先回放历史，然后继续推送实时事件。
    stream.stream()
        .filter(event -> event._json().orElseThrow() instanceof JsonObject json
            && seenEventIds.add(json.values().get("id").asStringOrThrow()))
        .filter(BetaManagedAgentsStreamSessionEvents::isAgentMessage)
        .forEach(event -> event.asAgentMessage().content()
            .forEach(block -> block.text().ifPresent(textBlock -> IO.print(textBlock.text()))));
}
```

PHP

```php
$stream = $client->beta->sessions->events->streamStream($session->id);

// 从应用自己的持久化状态加载已处理的事件 ID。
$seenEventIds = loadSeenEventIds($session->id);

// 服务端会先回放历史，然后继续推送实时事件。
foreach ($stream as $event) {
    if (isset($seenEventIds[$event->id])) {
        continue;
    }
    $seenEventIds[$event->id] = true;
    persistSeenEventId($session->id, $event->id);
    match ($event->type) {
        'agent.message' => array_walk(
            $event->content,
            static fn ($block) => $block->type === 'text' ? print($block->text) : null,
        ),
        default => null,
    };
}
$stream->close();
```

Ruby

```ruby
stream = client.beta.sessions.events.stream_events(session.id)

# 从应用自己的持久化状态加载已处理的事件 ID。
seen_event_ids = load_seen_event_ids(session.id)

# 服务端会先回放历史，然后继续推送实时事件。
stream.each do |event|
  next unless seen_event_ids.add?(event.id)
  persist_seen_event_id(session.id, event.id)
  case event.type
  in :"agent.message"
    event.content.each { print it.text }
  else
    # 忽略其他事件类型
  end
end
```

### 查询历史事件 [#查询历史事件]

需要重建对话记录或排查已结束的任务时，使用事件列表接口。列表默认分页：以下 cURL 示例持续读取 `next_page`，直到取完历史；SDK 应使用自动分页迭代器，或将 `next_page` 作为下一次请求的 `page` 参数。

cURL

```bash
page=""
while :; do
  url="$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events"
  [[ -z "$page" ]] || url+="?page=$(printf '%s' "$page" | jq -sRr @uri)"
  response=$(curl --fail-with-body -sS "$url" \
    -H "x-api-key: $AGENTAPI_API_KEY" \
    -H "content-type: application/json")
  jq -r '.data[] | "[\(.type)] \(.processed_at)"' <<<"$response"
  page=$(jq -r '.next_page // empty' <<<"$response")
  [[ -n "$page" ]] || break
done
```

Python

```python
events = client.beta.sessions.events.list(session.id)
for event in events.data:
    print(f"[{event.type}] {event.processed_at}")
```

TypeScript

````typescript
const events = await client.beta.sessions.events.list(session.id);
for (const event of events.data) {
  console.log(`[${event.type}] ${event.processed_at}`);
}
```csharp
```csharp
var events = await client.Beta.Sessions.Events.List(session.ID);
foreach (var sessionEvent in events.Items)
{
    Console.WriteLine($"[{sessionEvent.Json.GetProperty("type").GetString()}] {sessionEvent.ProcessedAt}");
}
````

Go

```go
events, err := client.Beta.Sessions.Events.List(ctx, session.ID, anthropic.BetaSessionEventListParams{})
if err != nil {
	panic(err)
}
for _, event := range events.Data {
	fmt.Printf("[%s] %s\n", event.Type, event.ProcessedAt)
}
```

Java

```java
var events = client.beta().sessions().events().list(session.id());
for (var event : events.data()) {
    var eventJson = event._json().orElseThrow().convert(JsonNode.class);
    var processedAt = eventJson.path("processed_at");
    IO.println("[" + eventJson.get("type").asText() + "] "
        + (processedAt.isTextual() ? processedAt.asText() : "null"));
}
```

PHP

```php
$events = $client->beta->sessions->events->list($session->id);
foreach ($events->data as $event) {
    $processedAt = ($event->processedAt ?? null)?->format(DATE_RFC3339) ?? 'null';
    echo "[{$event->type}] {$processedAt}\n";
}
```

Ruby

```ruby
events = client.beta.sessions.events.list(session.id)
events.data.each { puts "[#{it.type}] #{it.processed_at}" }
```

上述 SDK 片段仅展示当前页响应。读取全部历史时，需要继续按 `next_page` 分页请求；单次 `list` 调用不保证返回完整记录。

传入 `types` 过滤器，即可只返回指定类型的事件：

cURL

```bash
curl --fail-with-body -sS "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events?types[]=agent.tool_use&types[]=agent.tool_result" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  | jq -r '.data[] | "[\(.type)] \(.processed_at)"'
```

Python

```python
events = client.beta.sessions.events.list(
    session.id,
    types=["agent.tool_use", "agent.tool_result"],
)
for event in events.data:
    print(f"[{event.type}] {event.processed_at}")
```

TypeScript

````typescript
const events = await client.beta.sessions.events.list(session.id, {
  types: ["agent.tool_use", "agent.tool_result"],
});
for (const event of events.data) {
  console.log(`[${event.type}] ${event.processed_at}`);
}
```csharp
```csharp
var events = await client.Beta.Sessions.Events.List(session.ID, new()
{
    Types = ["agent.tool_use", "agent.tool_result"],
});
foreach (var sessionEvent in events.Items)
{
    Console.WriteLine($"[{sessionEvent.Json.GetProperty("type").GetString()}] {sessionEvent.ProcessedAt}");
}
````

Go

```go
events, err := client.Beta.Sessions.Events.List(ctx, session.ID, anthropic.BetaSessionEventListParams{
	Types: []string{"agent.tool_use", "agent.tool_result"},
})
if err != nil {
	panic(err)
}
for _, event := range events.Data {
	fmt.Printf("[%s] %s\n", event.Type, event.ProcessedAt)
}
```

Java

```java
var events = client.beta().sessions().events().list(
    session.id(),
    EventListParams.builder()
        .addType("agent.tool_use")
        .addType("agent.tool_result")
        .build());
for (var event : events.data()) {
    event.agentToolUse().ifPresent(toolUse ->
        IO.println("[" + toolUse.type() + "] " + toolUse.processedAt()));
    event.agentToolResult().ifPresent(toolResult ->
        IO.println("[" + toolResult.type() + "] " + toolResult.processedAt()));
}
```

PHP

```php
// 在 PHP 中，通过 EventListParams 传入需要的事件类型。
```

Ruby

```ruby
events = client.beta.sessions.events.list(
  session.id,
  types: ["agent.tool_use", "agent.tool_result"]
)
events.data.each { puts "[#{it.type}] #{it.processed_at}" }
```

## 调整执行中的任务 [#调整执行中的任务]

任务目标发生变化时，先用 `user.interrupt` 停止当前执行，再提交新要求。以下示例将文件分析改为修复指定位置的问题，合并发送中断和新消息的方式仅适用于 AgentAPI 托管的 `native`；其他运行时按下方警告分两步发送。

cURL

```bash
# 智能体当前正在分析文件...
# 用新的指令中断：
curl --fail-with-body -sS "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "events": [
    {"type": "user.interrupt"},
    {
      "type": "user.message",
      "input": {"parts": [
        {"type": "text", "text": "Instead, focus on fixing the bug in line 42."}
      ]}
    }
  ]
}
EOF
```

Python

```python
# 智能体当前正在分析文件...
# 用新的指令中断：
client.beta.sessions.events.send(
    session.id,
    events=[
        {"type": "user.interrupt"},
        {
            "type": "user.message",
            "content": [
                {
                    "type": "text",
                    "text": "Instead, focus on fixing the bug in line 42.",
                },
            ],
        },
    ],
)
```

TypeScript

````typescript
// 智能体当前正在分析文件……
// 用新的指令中断：
await client.beta.sessions.events.send(session.id, {
  events: [
    { type: "user.interrupt" },
    {
      type: "user.message",
      content: [
        {
          type: "text",
          text: "Instead, focus on fixing the bug in line 42.",
        },
      ],
    },
  ],
});
```csharp
```csharp
// 智能体当前正在分析文件...
// 用新的指令进行中断：
await client.Beta.Sessions.Events.Send(session.ID, new()
{
    Events =
    [
        new BetaManagedAgentsUserInterruptEventParams
        {
            Type = BetaManagedAgentsUserInterruptEventParamsType.UserInterrupt,
        },
        new BetaManagedAgentsUserMessageEventParams
        {
            Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
            Content =
            [
                new BetaManagedAgentsTextBlock
                {
                    Type = BetaManagedAgentsTextBlockType.Text,
                    Text = "Instead, focus on fixing the bug in line 42.",
                },
            ],
        },
    ],
});
````

Go

```go
// 智能体当前正在分析文件...
// 以新的指示中断：
if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
	Events: []anthropic.BetaManagedAgentsEventParamsUnion{
		{
			OfUserInterrupt: &anthropic.BetaManagedAgentsUserInterruptEventParams{
				Type: anthropic.BetaManagedAgentsUserInterruptEventParamsTypeUserInterrupt,
			},
		},
		{
			OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
				Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
				Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
					OfText: &anthropic.BetaManagedAgentsTextBlockParam{
						Type: anthropic.BetaManagedAgentsTextBlockTypeText,
						Text: "Instead, focus on fixing the bug in line 42.",
					},
				}},
			},
		},
	},
}); err != nil {
	panic(err)
}
```

Java

```java
// 智能体当前正在分析文件……
// 以新的指示进行中断：
client.beta().sessions().events().send(
    session.id(),
    EventSendParams.builder()
        .addEvent(BetaManagedAgentsUserInterruptEventParams.builder()
            .type(BetaManagedAgentsUserInterruptEventParams.Type.USER_INTERRUPT)
            .build())
        .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
            .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
            .addTextContent("Instead, focus on fixing the bug in line 42.")
            .build())
        .build());
```

PHP

```php
// 智能体当前正在分析文件……
// 用新的指示中断：
$client->beta->sessions->events->send(
    $session->id,
    events: [
        ['type' => 'user.interrupt'],
        [
            'type' => 'user.message',
            'content' => [
                [
                    'type' => 'text',
                    'text' => 'Instead, focus on fixing the bug in line 42.',
                ],
            ],
        ],
    ],
);
```

Ruby

```ruby
# 智能体当前正在分析一个文件……
# 用新的指令中断：
client.beta.sessions.events.send_(
  session.id,
  events: [
    {type: "user.interrupt"},
    {
      type: "user.message",
      content: [
        {type: "text", text: "Instead, focus on fixing the bug in line 42."}
      ]
    }
  ]
)
```

请求在事件入队后立即返回。在智能体处理中断之前，中断事件的 `processed_at` 为 `null`。中断的生效时机取决于当前执行阶段：

* 如果模型正在生成响应，响应会立即停止。
* 如果有工具调用正在运行，中断可能延迟生效，在此之前会话保持 `running` 状态。

> 运行中的消息与中断
>
> 会话处于 `running` 时，各运行时的处理方式不同：
>
> * AgentAPI 托管的 `native`：可在同一请求提交 `user.interrupt` + `user.message`，事件按序入队执行。此保证不适用于自托管外部 worker。
> * `claudecode` 和 `codex`：发送 `user.message` 会返回 `409`（agent busy）。请先发送 `user.interrupt`，等待 `idle` 后再发送新消息。
>
> 中断不会回滚已完成的工具操作或外部副作用。

被中断的执行以 `session.status_idle` 结束。`stop_reason.type` 在 `native` 中为 `end_turn`，与正常结束相同；在 `claudecode` 和 `codex` 中为 `interrupted`。请结合事件流中的 `user.interrupt` 判断中断。随后发送 `user.message` 可启动下一轮执行。

### 在原会话中继续任务 [#在原会话中继续任务]

文件分析或修改结束后，可以在原会话提交测试要求。处于 `idle` 的会话仍能接收 `user.message`，AgentAPI 会尽量复用可用的运行时上下文。

> 上下文与产物保存
>
> `claudecode` 或 `codex` 的云端沙箱失效后，会话随之终止，需要新建会话。运行时上下文不保证长期留存；需要保存的产物应写入 `/mnt/session/outputs/`，再通过 [Files API](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files) 下载。

![CLI 会话状态生命周期：running 停止本轮后进入 idle，可发送后续输入继续执行；claudecode 和 codex 的原沙箱丢失后进入 terminated](/docs-assets/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events/FgB2gdmBcB04Gec6FGDADZXjutmN-3cc5db973469.webp)

向空闲会话发送 `user.message` 事件可启动下一轮执行：

cURL

```bash
# 在生产环境中，请传入待恢复会话的已存储 ID。
curl --fail-with-body -sS "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "events": [
    {
      "type": "user.message",
      "input": {"parts": [
        {"type": "text", "text": "Now run the tests against the changes you made earlier."}
      ]}
    }
  ]
}
EOF
```

Python

```python
# 通过发送新的 user.message 事件来恢复先前创建的会话。
# 在生产环境中，传入待恢复会话的已存储 ID。
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {
                    "type": "text",
                    "text": "Now run the tests against the changes you made earlier.",
                },
            ],
        },
    ],
)
```

TypeScript

````typescript
// 通过向先前创建的会话发送新的用户事件来恢复该会话。
// 在生产环境中，请传入待恢复会话的已存储 ID。
await client.beta.sessions.events.send(session.id, {
  events: [
    {
      type: "user.message",
      content: [
        {
          type: "text",
          text: "Now run the tests against the changes you made earlier.",
        },
      ],
    },
  ],
});
```csharp
```csharp
// 通过 ID 恢复先前创建的会话。在生产环境中，请传入
// 创建会话时存储的会话 ID。
await client.Beta.Sessions.Events.Send(session.ID, new()
{
    Events =
    [
        new BetaManagedAgentsUserMessageEventParams
        {
            Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
            Content =
            [
                new BetaManagedAgentsTextBlock
                {
                    Type = BetaManagedAgentsTextBlockType.Text,
                    Text = "Now run the tests against the changes you made earlier.",
                },
            ],
        },
    ],
});
````

Go

```go
// 恢复先前创建的会话：向其发送新的 user.message
// 事件。在生产环境中，请传入要恢复的会话的已存储 ID。
if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
					Text: "Now run the tests against the changes you made earlier.",
				},
			}},
		},
	}},
}); err != nil {
	panic(err)
}
```

Java

```java
// 通过 ID 恢复先前创建的会话。在生产环境中，请传入
// 创建会话时存储的会话 ID。
client.beta().sessions().events().send(
    session.id(),
    EventSendParams.builder()
        .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
            .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
            .addTextContent("Now run the tests against the changes you made earlier.")
            .build())
        .build());
```

PHP

```php
// 通过发送新的 user.message 事件来恢复先前创建的会话。
// 在生产环境中，请传入创建会话时存储的会话 ID。
$client->beta->sessions->events->send(
    $session->id,
    events: [
        [
            'type' => 'user.message',
            'content' => [
                [
                    'type' => 'text',
                    'text' => 'Now run the tests against the changes you made earlier.',
                ],
            ],
        ],
    ],
);
```

Ruby

```ruby
# 恢复会话只需向其发送下一个事件。在生产环境中，
# 请传入创建会话时存储的会话 ID。
client.beta.sessions.events.send_(
  session.id,
  events: [
    {
      type: "user.message",
      content: [
        {type: "text", text: "Now run the tests against the changes you made earlier."}
      ]
    }
  ]
)
```

## 完成需要应用处理的操作 [#完成需要应用处理的操作]

`requires_action` 表示本轮等待应用参与。先读取阻塞事件，区分是业务系统执行工具，还是批准云端工具调用，再发送对应结果。观察工具事件和执行工具是两种职责，不能将所有 `agent.tool_use` 都交给应用重复执行。

### 处理自定义工具调用 [#处理自定义工具调用]

例如，任务需要通过业务系统查询数据时，可将查询声明为[自定义工具](/products/agentapi/development_guidelines/agentapi-agent-configuration/13591-agentapi-agent-configuration-tools)。应用保存 `agent.custom_tool_use` 的事件 ID、工具名称和输入；会话以 `requires_action` 停止后，按 `stop_reason.event_ids` 逐个处理：

1. 从已接收事件中找到对应调用，在业务系统中执行工具。
2. 发送 `user.custom_tool_result`，将调用事件 ID 填入 `custom_tool_use_id`，并附上结果。
3. 全部阻塞事件处理完后，继续消费回到 `running` 的会话。

cURL

```bash
exec {stream_fd}< <(curl --fail-with-body -sS -N \
  "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events/stream" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  -H "accept: text/event-stream")

while IFS= read -r -u "$stream_fd" line; do
  [[ $line == data:* ]] || continue
  event_json="${line#data: }"
  stop_reason=$(jq -r 'select(.type == "session.status_idle") | .stop_reason.type // empty' <<<"$event_json")
  case "$stop_reason" in
    requires_action)
      while IFS= read -r event_id; do
        # 执行该工具并将结果发回
        result=$(call_tool "$event_id")
        jq -n --arg id "$event_id" --arg result "$result" \
          '{events: [{type: "user.custom_tool_result", custom_tool_use_id: $id, content: [{type: "text", text: $result}]}]}' |
          curl --fail-with-body -sS \
            "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events" \
            -H "x-api-key: $AGENTAPI_API_KEY" \
            -H "content-type: application/json" \
            -d @-
      done < <(jq -r '.stop_reason.event_ids[]' <<<"$event_json")
      ;;
    end_turn)
      break
      ;;
  esac
done
exec {stream_fd}<&-
```

Python

```python
with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop_reason := event.stop_reason):
            match stop_reason.type:
                case "requires_action":
                    for event_id in stop_reason.event_ids:
                        # 查找自定义工具使用事件并执行它
                        tool_event = events_by_id[event_id]
                        result = call_tool(tool_event.name, tool_event.input)

                        # 将结果发送回去
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.custom_tool_result",
                                    "custom_tool_use_id": event_id,
                                    "content": [{"type": "text", "text": result}],
                                },
                            ],
                        )
                case "end_turn":
                    break
```

TypeScript

````typescript
const stream = await client.beta.sessions.events.stream(session.id);

for await (const event of stream) {
  if (event.type !== "session.status_idle") continue;
  if (event.stop_reason.type === "end_turn") break;
  if (event.stop_reason.type !== "requires_action") continue;

  for (const eventId of event.stop_reason.event_ids) {
    // 查找该自定义工具使用事件并执行它
    const toolEvent = eventsById.get(eventId);
    if (!toolEvent) continue;
    const result = await callTool(toolEvent.name, toolEvent.input);

    // 将结果发送回去
    await client.beta.sessions.events.send(session.id, {
      events: [
        {
          type: "user.custom_tool_result",
          custom_tool_use_id: eventId,
          content: [{ type: "text", text: result }],
        },
      ],
    });
  }
}
```csharp
```csharp
await foreach (var streamEvent in client.Beta.Sessions.Events.StreamStreaming(session.ID))
{
    if (streamEvent.Value is not BetaManagedAgentsSessionStatusIdleEvent idle) continue;

    if (idle.StopReason?.Value is BetaManagedAgentsSessionRequiresAction requiresAction)
    {
        foreach (var eventId in requiresAction.EventIds)
        {
            // 查找自定义工具使用事件并执行它
            var toolEvent = eventsById[eventId];
            var result = await CallTool(toolEvent.Name, toolEvent.Input);

            // 将结果发送回去
            await client.Beta.Sessions.Events.Send(session.ID, new()
            {
                Events =
                [
                    new BetaManagedAgentsUserCustomToolResultEventParams
                    {
                        Type = BetaManagedAgentsUserCustomToolResultEventParamsType.UserCustomToolResult,
                        CustomToolUseID = eventId,
                        Content =
                        [
                            new BetaManagedAgentsTextBlock
                            {
                                Type = BetaManagedAgentsTextBlockType.Text,
                                Text = result,
                            },
                        ],
                    },
                ],
            });
        }
    }
    else if (idle.StopReason?.Value is BetaManagedAgentsSessionEndTurn)
    {
        break;
    }
}
````

Go

```go
	stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
	defer stream.Close()

loop:
	for stream.Next() {
		event, ok := stream.Current().AsAny().(anthropic.BetaManagedAgentsSessionStatusIdleEvent)
		if !ok {
			continue
		}
		switch stopReason := event.StopReason.AsAny().(type) {
		case anthropic.BetaManagedAgentsSessionRequiresAction:
			for _, eventID := range stopReason.EventIDs {
				// 查找自定义工具使用事件并执行它
				toolEvent := eventsByID[eventID]
				result := callTool(toolEvent.Name, toolEvent.Input)
				// 将结果发送回去
				if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
					Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
						OfUserCustomToolResult: &anthropic.BetaManagedAgentsUserCustomToolResultEventParams{
							Type:            anthropic.BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult,
							CustomToolUseID: eventID,
							Content: []anthropic.BetaManagedAgentsUserCustomToolResultEventParamsContentUnion{{
								OfText: &anthropic.BetaManagedAgentsTextBlockParam{
									Type: anthropic.BetaManagedAgentsTextBlockTypeText,
									Text: result,
								},
							}},
						},
					}},
				}); err != nil {
					panic(err)
				}
			}
		case anthropic.BetaManagedAgentsSessionEndTurn:
			break loop
		}
	}
	if err := stream.Err(); err != nil {
		panic(err)
	}
```

Java

```java
try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
    stream.stream()
        .filter(BetaManagedAgentsStreamSessionEvents::isSessionStatusIdle)
        .map(idleEvent -> idleEvent.asSessionStatusIdle().stopReason())
        .takeWhile(stopReason -> !stopReason.isEndTurn())
        .filter(stopReason -> stopReason.isRequiresAction())
        .flatMap(stopReason -> stopReason.asRequiresAction().eventIds().stream())
        .forEach(eventId -> {
            // 查找自定义工具使用事件并执行它
            var toolEvent = eventsById.get(eventId);
            var result = callTool(toolEvent.name(), toolEvent.input());

            // 将结果发送回去
            client.beta().sessions().events().send(
                session.id(),
                EventSendParams.builder()
                    .addEvent(BetaManagedAgentsUserCustomToolResultEventParams.builder()
                        .type(BetaManagedAgentsUserCustomToolResultEventParams.Type.USER_CUSTOM_TOOL_RESULT)
                        .customToolUseId(eventId)
                        .addTextContent(result)
                        .build())
                    .build());
        });
}
```

PHP

```php
$stream = $client->beta->sessions->events->streamStream($session->id);

foreach ($stream as $event) {
    if ($event->type === 'session.status_idle' && $event->stopReason) {
        if ($event->stopReason->type === 'requires_action') {
            foreach ($event->stopReason->eventIDs as $eventId) {
                // 查找自定义工具使用事件并执行它
                $toolEvent = $eventsById[$eventId];
                $result = callTool($toolEvent->name, $toolEvent->input);

                // 将结果发送回去
                $client->beta->sessions->events->send(
                    $session->id,
                    events: [
                        [
                            'type' => 'user.custom_tool_result',
                            'custom_tool_use_id' => $eventId,
                            'content' => [['type' => 'text', 'text' => $result]],
                        ],
                    ],
                );
            }
        } elseif ($event->stopReason->type === 'end_turn') {
            break;
        }
    }
}
```

Ruby

```ruby
client.beta.sessions.events.stream_events(session.id).each do |event|
  case event
  in {type: :"session.status_idle", stop_reason: {type: :requires_action, event_ids:}}
    event_ids.each do |event_id|
      # 查找自定义工具使用事件并执行它
      tool_event = events_by_id[event_id]
      result = call_tool.call(tool_event.name, tool_event.input)
      # 将结果发送回去
      client.beta.sessions.events.send_(
        session.id,
        events: [
          {
            type: "user.custom_tool_result",
            custom_tool_use_id: event_id,
            content: [{type: "text", text: result}]
          }
        ]
      )
    end
  in {type: :"session.status_idle", stop_reason: {type: :end_turn}}
    break
  else
  end
end
```

### 工具确认 [#工具确认]

当[权限策略](/products/agentapi/development_guidelines/agentapi-agent-configuration/13593-agentapi-agent-configuration-permissions)要求确认时，应用负责审批，工具仍由云端执行。收到 `agent.tool_use` 或 `agent.mcp_tool_use` 后，会话以 `requires_action` 停止；应用按 `stop_reason.event_ids` 提取调用，展示工具及参数供审批。

为每个阻塞事件发送 `user.tool_confirmation`：`tool_use_id` 填调用事件 ID，`result` 填 `"allow"` 或 `"deny"`，拒绝时可附 `deny_message`。所有阻塞事件处理完后，会话回到 `running`。下面示例展示批准请求的发送方式；业务应用应在审批完成后发送。

cURL

```bash
exec {stream_fd}< <(curl --fail-with-body -sS -N \
  "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events/stream" \
  -H "x-api-key: $AGENTAPI_API_KEY" \
  -H "content-type: application/json" \
  -H "accept: text/event-stream")

while IFS= read -r -u "$stream_fd" line; do
  [[ $line == data:* ]] || continue
  event_json="${line#data: }"
  stop_reason=$(jq -r 'select(.type == "session.status_idle") | .stop_reason.type // empty' <<<"$event_json")
  case "$stop_reason" in
    requires_action)
      while IFS= read -r event_id; do
        # 批准待处理的工具调用
        jq -n --arg id "$event_id" \
          '{events: [{type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}]}' |
          curl --fail-with-body -sS \
            "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/events" \
            -H "x-api-key: $AGENTAPI_API_KEY" \
            -H "content-type: application/json" \
            -d @-
      done < <(jq -r '.stop_reason.event_ids[]' <<<"$event_json")
      ;;
    end_turn)
      break
      ;;
  esac
done
exec {stream_fd}<&-
```

Python

```python
with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop_reason := event.stop_reason):
            match stop_reason.type:
                case "requires_action":
                    for event_id in stop_reason.event_ids:
                        # 批准待处理的工具调用
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.tool_confirmation",
                                    "tool_use_id": event_id,
                                    "result": "allow",
                                },
                            ],
                        )
                case "end_turn":
                    break
```

TypeScript

````typescript
const stream = await client.beta.sessions.events.stream(session.id);

for await (const event of stream) {
  if (event.type !== "session.status_idle") continue;
  if (event.stop_reason.type === "end_turn") break;
  if (event.stop_reason.type !== "requires_action") continue;

  for (const eventId of event.stop_reason.event_ids) {
    // 批准待处理的工具调用
    await client.beta.sessions.events.send(session.id, {
      events: [
        {
          type: "user.tool_confirmation",
          tool_use_id: eventId,
          result: "allow",
        },
      ],
    });
  }
}
```csharp
```csharp
await foreach (var streamEvent in client.Beta.Sessions.Events.StreamStreaming(session.ID))
{
    if (streamEvent.Value is not BetaManagedAgentsSessionStatusIdleEvent idle) continue;

    if (idle.StopReason?.Value is BetaManagedAgentsSessionRequiresAction requiresAction)
    {
        foreach (var eventId in requiresAction.EventIds)
        {
            // 批准待处理的工具调用
            await client.Beta.Sessions.Events.Send(session.ID, new()
            {
                Events =
                [
                    new BetaManagedAgentsUserToolConfirmationEventParams
                    {
                        Type = BetaManagedAgentsUserToolConfirmationEventParamsType.UserToolConfirmation,
                        ToolUseID = eventId,
                        Result = BetaManagedAgentsUserToolConfirmationEventParamsResult.Allow,
                    },
                ],
            });
        }
    }
    else if (idle.StopReason?.Value is BetaManagedAgentsSessionEndTurn)
    {
        break;
    }
}
````

Go

```go
	stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
	defer stream.Close()

loop:
	for stream.Next() {
		event, ok := stream.Current().AsAny().(anthropic.BetaManagedAgentsSessionStatusIdleEvent)
		if !ok {
			continue
		}
		switch stopReason := event.StopReason.AsAny().(type) {
		case anthropic.BetaManagedAgentsSessionRequiresAction:
			for _, eventID := range stopReason.EventIDs {
				// 批准待处理的工具调用
				if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
					Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
						OfUserToolConfirmation: &anthropic.BetaManagedAgentsUserToolConfirmationEventParams{
							Type:      anthropic.BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation,
							ToolUseID: eventID,
							Result:    anthropic.BetaManagedAgentsUserToolConfirmationEventParamsResultAllow,
						},
					}},
				}); err != nil {
					panic(err)
				}
			}
		case anthropic.BetaManagedAgentsSessionEndTurn:
			break loop
		}
	}
	if err := stream.Err(); err != nil {
		panic(err)
	}
```

Java

```java
try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
    stream.stream()
        .filter(BetaManagedAgentsStreamSessionEvents::isSessionStatusIdle)
        .map(idleEvent -> idleEvent.asSessionStatusIdle().stopReason())
        .takeWhile(stopReason -> !stopReason.isEndTurn())
        .filter(stopReason -> stopReason.isRequiresAction())
        .flatMap(stopReason -> stopReason.asRequiresAction().eventIds().stream())
        // 批准每个待处理的工具调用
        .forEach(toolUseId -> client.beta().sessions().events().send(
            session.id(),
            EventSendParams.builder()
                .addEvent(BetaManagedAgentsUserToolConfirmationEventParams.builder()
                    .type(BetaManagedAgentsUserToolConfirmationEventParams.Type.USER_TOOL_CONFIRMATION)
                    .toolUseId(toolUseId)
                    .result(BetaManagedAgentsUserToolConfirmationEventParams.Result.ALLOW)
                    .build())
                .build()));
}
```

PHP

```php
$stream = $client->beta->sessions->events->streamStream($session->id);

foreach ($stream as $event) {
    if ($event->type === 'session.status_idle' && $event->stopReason) {
        if ($event->stopReason->type === 'requires_action') {
            foreach ($event->stopReason->eventIDs as $eventId) {
                // 批准待处理的工具调用
                $client->beta->sessions->events->send(
                    $session->id,
                    events: [
                        [
                            'type' => 'user.tool_confirmation',
                            'tool_use_id' => $eventId,
                            'result' => 'allow',
                        ],
                    ],
                );
            }
        } elseif ($event->stopReason->type === 'end_turn') {
            break;
        }
    }
}
```

Ruby

```ruby
client.beta.sessions.events.stream_events(session.id).each do |event|
  case event
  in {type: :"session.status_idle", stop_reason: {type: :requires_action, event_ids:}}
    event_ids.each do |event_id|
      # 批准待处理的工具调用
      client.beta.sessions.events.send_(
        session.id,
        events: [
          {type: "user.tool_confirmation", tool_use_id: event_id, result: "allow"}
        ]
      )
    end
  in {type: :"session.status_idle", stop_reason: {type: :end_turn}}
    break
  else
  end
end
```

## 核对用量与排查异常 [#核对用量与排查异常]

用量与时长用于观察执行成本。

### 核对模型用量与执行时长 [#核对模型用量与执行时长]

会话通过 `stats` 返回时长，通过 `usage` 返回所有轮次的累计模型用量。会话进入 `idle` 后，查询可获取基于已提交事件计算的最新汇总；运行时报告的用量明细见 `span.model_request_end`。

```json
{
  "id": "ses_01...",
  "status": "idle",
  "usage": {
    "input_tokens": 2400,
    "output_tokens": 350,
    "cache_read_input_tokens": 1800
  },
  "stats": {
    "active_seconds": 342.5,
    "duration_seconds": 401.2
  }
}
```

读取响应时，请区分用量与时长：

* `usage`：累计用量，可能包含 `input_tokens`、`output_tokens`、`cache_read_input_tokens`、`cache_creation` 和 `server_tool_use`；不包含 `active_seconds`。缺失或有歧义的计数按未知处理，不应视为零。
* `stats.active_seconds`：累计执行时间。
* `stats.duration_seconds`：从创建到当前的经过时间，会话终止后冻结。
* `span.model_request_end.model_usage`：Native 中表示单次模型请求用量；CLI 运行时可能报告整次执行或线程累计用量，不能按单次请求直接累加。字段由运行时和模型决定，可能包含 `input_tokens`、`output_tokens` 或缓存用量。

计数至少上报一次后才会出现，客户端需兼容缺失和额外字段。完整结构见 [API 通用约定](/products/agentapi/api/13618-agentapi-api-conventions)。

### 在 Portal 定位执行问题 [#在-portal-定位执行问题]

在 Portal 会话详情的“轨迹”中检查事件和停止原因，需要完整记录时通过“Raw JSONL”导出。界面使用说明见[在 Portal 中构建](/products/agentapi/quick_start/13586-agentapi-portal)。

## 事件字段与消费职责 [#事件字段与消费职责]

实现分发逻辑时，按事件的用途选择处理方式。应用发送用户事件；AgentAPI 返回回答、工具调用、执行阶段（Span）和会话状态。

![事件双向流动：用户事件从应用上行进入会话，会话事件、执行阶段事件（Span）和智能体事件从会话下行返回应用](/docs-assets/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events/FuHJB0aM8PDf93dTXniwnqCARMVf-4d4d8d0ec5f6.webp)

| 消费目的   | 事件                                                                         | 应用职责                                                 |
| ------ | -------------------------------------------------------------------------- | ---------------------------------------------------- |
| 展示回答   | `agent.message`                                                            | 提取回答内容；Native 增量预览另按 `event_start`、`event_delta` 处理。 |
| 观察云端工具 | `agent.tool_use`、`agent.mcp_tool_use`                                      | 展示调用过程，按权限策略处理确认。                                    |
| 执行业务工具 | `agent.custom_tool_use`                                                    | 保存调用，按阻塞事件 ID 回传结果。                                  |
| 更新任务状态 | `session.status_running`、`session.status_idle`、`session.status_terminated` | 展示执行状态；停止时检查原因，终止后停止提交输入。                            |
| 排查模型请求 | `span.model_request_start`、`span.model_request_end`                        | 关联请求阶段，检查运行时报告的用量。                                   |
| 记录错误   | `session.error`                                                            | 保存错误信息，继续检查后续状态。                                     |

持久化事件类型遵循 `{domain}.{action}` 命名约定；仅供流预览的 `event_start`、`event_delta` 例外。完整目录见[事件类型](/products/agentapi/api/13618-agentapi-api-conventions)。

持久化事件包含 `id`、`type`、`session_id`、`sequence_number` 和 `processed_at`。排队中的用户输入在接收响应中可能返回 `processed_at: null`；执行时，事件列表和事件流中的对应事件会带上处理时间。不要依赖事件包含 `created_at`。


# 会话操作 (/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13598-agentapi-sessions-and-tasks-session-lifecycle)



最近更新时间: 2026-10-13 15:31:37

一次云端任务结束后，会话仍可保留历史并继续接收输入。将 AgentAPI 接入业务系统时，需要根据会话状态决定何时继续任务、修改配置、停止执行，以及保留或清理产物。

本页从已创建的会话开始，说明读取、更新、归档和删除操作。创建会话与发送首条消息见[会话](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)，SDK 客户端初始化见[通过 API 构建](/products/agentapi/quick_start/13587-agentapi-quickstart)。

## 选择生命周期操作 [#选择生命周期操作]

| 业务目标           | 操作                         | 对已有记录的影响                           |
| -------------- | -------------------------- | ---------------------------------- |
| 在同一任务中补充要求     | 发送 `user.message`          | 保留会话历史，继续使用现有会话。                   |
| 停止当前执行，之后继续    | 发送 `user.interrupt`，观察返回事件 | 保留历史；已经发生的工具副作用不会回滚。               |
| 修改标题、业务标识或工具配置 | 更新会话                       | 工具与 MCP 配置要求会话处于 `idle`；不会更新底层智能体。 |
| 停用会话并保留历史      | 归档会话                       | 停止执行并拒绝新事件；保留历史与文件对象。              |
| 永久清理任务记录和产物    | 删除会话                       | 删除会话、事件和会话作用域文件；请先下载产物。            |

## 会话状态 [#会话状态]

会话状态描述执行进度，不等同于业务任务是否成功。请结合下表、状态事件的停止原因和任务产物判断执行结果。

| 状态             | 描述                                                                                        |
| -------------- | ----------------------------------------------------------------------------------------- |
| `idle`         | 智能体正在等待输入，包括用户消息或工具确认。通过 `POST /v1/sessions` 创建的会话以 `idle` 状态开始，需再发送 `user.message` 才会执行。 |
| `running`      | 智能体正在主动执行。                                                                                |
| `rescheduling` | 发生了瞬时错误，正在自动重试。                                                                           |
| `terminated`   | 会话已结束，原因可能是发生了不可恢复的错误，或者会话已被归档。完成工作的会话会进入 `idle` 状态，而不是 `terminated`。                     |

![会话状态流转](/docs-assets/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13598-agentapi-sessions-and-tasks-session-lifecycle/FvjBfGeLZrEi8enFCVEtuaN3SfYW-b0dddb5590fe.webp)

接收到 `session.status_idle` 时，还需按[停止原因](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)判断本轮结果；断线后按[事件恢复流程](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)继续观察同一会话。

## 云端环境的运行与暂停 [#云端环境的运行与暂停]

会话进入 `idle` 后，AgentAPI 会记录一次 `pause_pending`，生命周期管理器每 90–150 秒处理这些待暂停 context。暂停保留沙箱中的文件和运行时上下文。收到下一轮输入后，AgentAPI 清除待暂停或已暂停状态，按需恢复同一沙箱，并重新设置完整的运行时长。

暂停成功、或 provider 返回 `409`/`404` 表示沙箱已经暂停时，状态会持久化为 `paused`。这个状态在实例之间共享，服务重启后仍然有效；只有暂停失败才会保留待重试状态。

沙箱每次创建或恢复时设置运行时长，执行中不再定时续期。服务端的沙箱运行时长和 CLI 命令执行上限默认均为 1 小时。需要 12 小时等更长时限时，应在部署配置中显式设置，且沙箱服务必须支持相应上限。这两项限制互相独立：命令达到执行上限时，即使沙箱仍可用，AgentAPI 也会停止命令；沙箱寿命先开始计时，两项配置相同时，沙箱可能先到期。需要为命令退出和产物收集留出时间的部署，应将命令上限设得短于沙箱运行时长。

`native` 的模型请求和工具调用还受各自的执行预算限制。会话历史的保留不保证原沙箱能够恢复。对于 `claudecode` 和 `codex`，如果原沙箱已经丢失，会话会终止；请创建新会话并提供继续任务所需材料，AgentAPI 不会仅凭事件历史重建替代沙箱。延长沙箱运行时长不会改变这一限制。

## 检索会话 [#检索会话]

使用会话 ID 读取当前配置与状态。需要判断一次具体执行为何结束时，应同时读取事件中的停止原因和错误；会话查询返回的是当前快照。

cURL

```bash
retrieved=$(curl --request GET --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID" \
  --header "x-api-key: $AGENTAPI_API_KEY")
echo "Status: $(jq -r '.status' <<< "$retrieved")"
```

Python

```python
retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")
```

TypeScript

````typescript
const retrieved = await client.beta.sessions.retrieve(session.id);
console.log(`Status: ${retrieved.status}`);
```csharp
```csharp
var retrieved = await client.Beta.Sessions.Retrieve(session.ID);
Console.WriteLine($"Status: {retrieved.Status.Raw()}");
````

Go

```go
retrieved, err := client.Beta.Sessions.Get(ctx, session.ID, anthropic.BetaSessionGetParams{})
if err != nil {
	panic(err)
}
fmt.Printf("Status: %s\n", retrieved.Status)
```

Java

```java
var retrieved = client.beta().sessions().retrieve(session.id());
IO.println("Status: " + retrieved.status());
```

PHP

```php
$retrieved = $client->beta->sessions->retrieve($session->id);
echo "Status: {$retrieved->status}\n";
```

Ruby

```ruby
retrieved = client.beta.sessions.retrieve(session.id)
puts "Status: #{retrieved.status}"
```

## 列出会话 [#列出会话]

`GET /v1/sessions` 的结果是分页的。使用 `limit` 查询参数控制页面大小。每个响应都包含一个 `next_page` 游标；在下一次请求中将其作为 `page` 参数传递即可获取下一页。当没有更多结果时，`next_page` 为 `null`。

分页时，将响应中的 `next_page` 原样传入下一次请求的 `page`，不要解析或修改游标；`next_page` 为 `null` 时结束。可另行设置 `limit` 和筛选条件；当前 `/v1/sessions` 不支持 `prev_page` 或 `order`。

列表默认排除归档会话。可以按 `agent_id`、`memory_store_id`、`status` 和 `created_at[gte]`/`created_at[lte]` 筛选；需要查询归档历史时使用 `include_archived=true`。保留同一组筛选条件，再用返回的游标获取下一页。

cURL

```bash
first_page=$(curl --request GET --fail-with-body --silent --show-error \
  "$AGENTAPI_BASE_URL/v1/sessions?agent_id=$AGENT_ID&limit=1" \
  --header "x-api-key: $AGENTAPI_API_KEY")
jq '{data: [.data[] | {id, status}], next_page}' <<< "$first_page"

next_cursor=$(jq -r '.next_page' <<< "$first_page")
second_page=$(curl --request GET --fail-with-body --silent --show-error \
  "$AGENTAPI_BASE_URL/v1/sessions?agent_id=$AGENT_ID&limit=1&page=$next_cursor" \
  --header "x-api-key: $AGENTAPI_API_KEY")
jq '{data: [.data[] | {id, status}], next_page}' <<< "$second_page"
```

Python

```python
# 将 `limit` 设得较低，使结果跨越多页。
first_page = client.beta.sessions.list(limit=1, agent_id=agent.id)
# 最后一页的 `next_page` 为 None。
print(f"next_page: {first_page.next_page}")

# 将 `next_page` 作为 `page` 传回以获取下一页。
second_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=first_page.next_page
)
for listed_session in second_page.data:
    print(f"{listed_session.id}: {listed_session.status}")
# 继续读取时，重复将 second_page.next_page 传给 page，直到它变为 None。
```

TypeScript

````typescript
const firstPage = await client.beta.sessions.list({ limit: 1, agent_id: agent.id });
// 当存在更多会话时会设置 next_page。
console.log(`next_page: ${firstPage.next_page}`);

// 将 next_page 作为 `page` 游标传入以获取第二页。
const secondPage = await client.beta.sessions.list({
  limit: 1,
  agent_id: agent.id,
  page: firstPage.next_page
});
for (const listedSession of secondPage.data) {
  console.log(`Page 2 has ${listedSession.id}: ${listedSession.status}`);
}
// 继续读取时，将 secondPage.next_page 传给 page，直到它为 null。
```csharp
```csharp
// `List` 返回当前页条目；需要继续读取时，请使用响应中的 next_page。
using var page1Response = await client.Beta.Sessions.WithRawResponse.List(
    new SessionListParams { Limit = 1, AgentID = agent.ID }
);
var page1 = await page1Response.Deserialize<SessionListPageResponse>();
Console.WriteLine($"next_page: {page1.NextPage ?? "null"}");

// 前进：将第 1 页的 `next_page` 作为 `page` 游标传入。
using var page2Response = await client.Beta.Sessions.WithRawResponse.List(
    new SessionListParams { Limit = 1, AgentID = agent.ID, Page = page1.NextPage }
);
var page2 = await page2Response.Deserialize<SessionListPageResponse>();
foreach (var listedSession in page2.Data ?? [])
{
    Console.WriteLine($"Page 2: {listedSession.ID}: {listedSession.Status.Raw()}");
}

// 继续读取时，将 page2.NextPage 传给 Page，直到它为空。
````

Go

```go
// 第 1 页：响应中的 NextPage 指向下一页。
firstPage, err := client.Beta.Sessions.List(ctx, anthropic.BetaSessionListParams{
	AgentID: anthropic.String(agent.ID),
	Limit:   anthropic.Int(1),
})
if err != nil {
	panic(err)
}
fmt.Printf("Page 1 next_page: %q\n", firstPage.NextPage)

// 前进：将 next_page 作为 Page 游标传入以获取第 2 页。
secondPage, err := client.Beta.Sessions.List(ctx, anthropic.BetaSessionListParams{
	AgentID: anthropic.String(agent.ID),
	Limit:   anthropic.Int(1),
	Page:    anthropic.String(firstPage.NextPage),
})
if err != nil {
	panic(err)
}
for _, listedSession := range secondPage.Data {
	fmt.Printf("Page 2: %s: %s\n", listedSession.ID, listedSession.Status)
}

// 继续读取时，将 secondPage.NextPage 传给 Page，直到它为空。
```

Java

```java
var params = SessionListParams.builder()
    .agentId(agent.id())
    .limit(1)
    .build();
var firstPage = client.beta().sessions().list(params);
for (var listedSession : firstPage.data()) {
    IO.println(listedSession.id() + ": " + listedSession.status());
}
// next_page 指向第 2 页；最后一页没有 next_page。
IO.println("next_page: " + firstPage.response().nextPage());

// 通过将 next_page 作为页面游标传入来前进。
var nextCursor = firstPage.response().nextPage().orElseThrow();
var secondPage = client.beta().sessions().list(params.toBuilder().page(nextCursor).build());

// 继续读取时，将 secondPage.response().nextPage() 传给 page，直到 Optional 为空。
```

PHP

```php
// 第 1 页：nextPage 指向下一页。
$firstPage = $client->beta->sessions->list(agentID: $agent->id, limit: 1);
echo 'Page 1 next_page: ' . ($firstPage->nextPage ?? 'null') . "\n";

// 前进：将 nextPage 作为 `page` 游标传回以获取第 2 页。
$secondPage = $client->beta->sessions->list(
    agentID: $agent->id,
    limit: 1,
    page: $firstPage->nextPage,
);
foreach ($secondPage->getItems() as $listedSession) {
    echo "Page 2: {$listedSession->id}: {$listedSession->status}\n";
}

// 继续读取时，将 secondPage->nextPage 传给 page，直到它为空。
```

Ruby

```ruby
first_page = client.beta.sessions.list(agent_id: agent.id, limit: 1)
first_page.data.each do |listed_session|
  puts "#{listed_session.id}: #{listed_session.status}"
end

# `next_page_` 是下一页游标；当它为 nil 时表示已经读完。
puts "next_page: #{first_page.next_page_.inspect}"

# 将 `next_page_` 作为 `page` 传回，即可继续向后读取。
second_page = client.beta.sessions.list(
  agent_id: agent.id,
  limit: 1,
  page: first_page.next_page_
)
# 继续读取时，重复传入 second_page.next_page_，直到它为 nil。
```

## 更新会话 [#更新会话]

`POST /v1/sessions/{id}` 用于更新会话的 `title`、`metadata`，以及在会话处于 `idle` 状态时更新智能体的 `tools` 和 `mcp_servers`。请求体接受以下字段：

* `title`：会话标题（字符串），会覆盖现有标题。
* `metadata`：键值对，按键合并到现有元数据上；将某个键的值设为 `null` 可删除该键。
* `agent`：包含 `tools` 和/或 `mcp_servers` 的对象，对提供的字段做整体替换（提供的数组即为新值；如需保留原有条目，请先 `GET` 会话，修改数组后再提交）。这两项的更新是会话本地的，不会回写到底层智能体。

请求体中出现 `environment_id` 或 `resources` 字段会被服务端拒绝并返回 `400`（`<字段> is not supported by this endpoint`）。`agent` 中若包含 `model`、`system`、`skills` 等不可更新字段，会返回 `400`（`agent.<字段> cannot be updated after session creation`）。

> 部分智能体配置在会话创建后不可更改
>
> 会话创建后的配置限制如下：
>
> * `model`、`system`、`skills` 不可更改。需要不同配置时，请在创建会话时使用[智能体配置覆盖](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13596-agentapi-sessions-and-tasks-session)，同时也可覆盖 `tools` 和 `mcp_servers`。
> * `tools` 和 `mcp_servers` 只能在 `idle` 状态更新，否则返回 `409`（`session must be idle to update agent configuration`）。运行中的会话可先发送 [`user.interrupt` 事件](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)，等待 `idle` 后再更新。
> * 模型支持时，可发送 [`system.message` 事件](/products/agentapi/api/13618-agentapi-api-conventions)追加系统级指导。

cURL

```bash
curl --request POST --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" \
  --data @- <<EOF
{
  "title": "重构登录流程",
  "metadata": {"ticket": "ENG-1234"}
}
EOF
```

Python

```python
client.beta.sessions.update(
    session.id,
    title="重构登录流程",
    metadata={"ticket": "ENG-1234"},
)
```

TypeScript

```typescript
await client.beta.sessions.update(session.id, {
  title: "重构登录流程",
  metadata: { ticket: "ENG-1234" }
});
```

## 归档会话 [#归档会话]

归档会话可阻止发送新事件，同时保留其历史记录。归档后，`status` 变为 `terminated`，AgentAPI 会取消排队任务并请求停止正在执行的任务。若需要在归档前确认当前执行已经停止，请先发送一个 [`user.interrupt` 事件](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)并等待会话变为 `idle`。

归档不会回滚已经执行的工具操作。需要再次开展工作时，请创建新会话；查询归档历史时，在会话列表中使用 `include_archived=true`。

cURL

```bash
curl --fail-with-body --silent --show-error --request POST "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID/archive" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
client.beta.sessions.archive(session.id)
```

TypeScript

````typescript
await client.beta.sessions.archive(session.id);
```csharp
```csharp
await client.Beta.Sessions.Archive(session.ID);
````

Go

```go
_, err = client.Beta.Sessions.Archive(ctx, session.ID, anthropic.BetaSessionArchiveParams{})
if err != nil {
	panic(err)
}
```

Java

```java
client.beta().sessions().archive(session.id());
```

PHP

```php
$client->beta->sessions->archive($session->id);
```

Ruby

```ruby
client.beta.sessions.archive(session.id)
```

## 删除会话 [#删除会话]

删除后无法再通过 API 检索或继续使用该会话，并清理以下内容：

* 会话事件。
* 会话生成的输出文件，以及挂载到会话的文件副本。归档会话不会清理这些文件。

记忆存储、保管库、技能、环境、智能体和独立上传文件不受影响。

删除前，请先下载需要保留的文件。最后一轮输出可能晚于会话进入 `idle` 才出现在[会话的文件列表](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)中，请确认文件已全部列出。需要停止当前执行时，先发送 [`user.interrupt` 事件](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)，等待 `idle` 后再删除。删除接口不保证立即销毁关联沙箱；自托管进程的停止和本地文件清理由执行器负责。

cURL

```bash
curl --fail-with-body --silent --show-error --request DELETE "$AGENTAPI_BASE_URL/v1/sessions/$SESSION_ID" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
client.beta.sessions.delete(session.id)
```

TypeScript

````typescript
await client.beta.sessions.delete(session.id);
```csharp
```csharp
await client.Beta.Sessions.Delete(session.ID);
````

Go

```go
_, err = client.Beta.Sessions.Delete(ctx, session.ID, anthropic.BetaSessionDeleteParams{})
if err != nil {
	panic(err)
}
```

Java

```java
client.beta().sessions().delete(session.id());
```

PHP

```php
$client->beta->sessions->delete($session->id);
```

Ruby

```ruby
client.beta.sessions.delete(session.id)
```


# 定义结果 (/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13599-agentapi-sessions-and-tasks-outcomes)



最近更新时间: 2026-10-13 15:31:39

结果（Outcome）为会话定义交付目标与评分标准，适合需要生成、检查并反复修改产物的任务。例如，让智能体生成一份数据质量检查方案，再逐项检查方案是否包含检查方法和处理建议。

发送 `user.define_outcome` 后，AgentAPI 会运行智能体并配置一个评分器（grader），根据评分标准（rubric）检查产物。评分器与主智能体使用独立的上下文，在同一个会话沙箱中检查输出文件。

评分器说明各项标准是否通过，智能体根据反馈继续修改。

迭代会在满足标准、达到次数上限、评估失败或被中断时停止。`max_iterations` 默认是 3，可设置为 1–20；它限制执行与评估的轮数，不是“保证达标”的承诺。

![面向结果的迭代循环](/docs-assets/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13599-agentapi-sessions-and-tasks-outcomes/FqHjk8KUZqZW4lBDhuj11rgR_ViT-3ddcd4de727e.webp)

## 接入结果任务 [#接入结果任务]

1. 创建[智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)与[云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)，确保运行时能生成并读取任务需要的文件。
2. 编写评分标准，作为文本发送，或上传文件后引用其 ID。
3. 创建会话，发送 `user.define_outcome`，设置交付目标和迭代上限。
4. 消费事件，按 `outcome_id` 跟踪评估；区分需要继续修改的 `needs_revision` 与最终结果。
5. 确认最终结果，列出并下载预期交付物，再进行业务侧验收。

本页示例生成 Markdown 格式的数据质量检查方案。已有输入材料时，可在创建会话时挂载[文件](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)或[仓库](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13604-agentapi-data-and-integrations-github)。

## 创建评分标准 [#创建评分标准]

评分标准是必填的 Markdown 文本，用于说明每一项通过条件。结果描述说明交付目标，评分标准定义交付物的验收条件；两者应对应同一个目标。

评分标准编写建议

评分标准应包含明确、可验证的条目，例如“CSV 包含数值类型的价格列”。避免使用“数据质量良好”等缺少验收条件的描述。评分器会逐条独立评分，含糊的标准可能导致评分结果不稳定。

如果尚未制定评分标准，可以提供一个符合预期的产物示例，由智能体分析其满足的可验证条件，再将这些条件整理成评分标准。

示例评分标准：

```markdown
# 数据质量方案评分标准

## 检查范围
- 覆盖缺失值、重复记录和字段类型三类问题
- 每类问题都说明检测方法和处理建议

## 输出质量
- 交付一份名为 report.md 的 Markdown 文档
- 文档包含检查步骤、示例和适用限制
```

将评分标准作为内联文本传递给 `user.define_outcome`（参见创建带有结果的会话），或通过 Files API 上传，以便在多个会话中重复使用。

请先完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)，从[七牛 MaaS 模型管理页](https://portal.qiniu.com/ai-inference/model)选择模型并设置 `AGENTAPI_MODEL_ID`。创建智能体时显式设置 `runtime`；会话继承该运行时。本页 SDK 示例配置 AgentAPI 服务地址与 MaaS API Key。

若使用 cURL 上传评分文件，请先把上面的评分标准写入本地 `/tmp/rubric.md`。以下 SDK 示例会创建该文件并上传；使用内联评分标准时，可跳过上传步骤。

cURL

```bash
rubric=$(curl --request POST --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/files" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --form "file=@/tmp/rubric.md")
rubric_id=$(jq -er '.id' <<<"$rubric")
printf 'Uploaded rubric: %s\n' "$rubric_id"
```

Python

```python
import os
from pathlib import Path

from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["AGENTAPI_API_KEY"],
    base_url=os.environ["AGENTAPI_BASE_URL"],
)

RUBRIC = """# 数据质量方案评分标准

## 检查范围
- 覆盖缺失值、重复记录和字段类型三类问题
- 每类问题都说明检测方法和处理建议

## 输出质量
- 交付一份名为 report.md 的 Markdown 文档
- 文档包含检查步骤、示例和适用限制
"""
Path("/tmp/rubric.md").write_text(RUBRIC)

rubric = client.beta.files.upload(file=Path("/tmp/rubric.md"))
print(f"Uploaded rubric: {rubric.id}")
```

TypeScript

````typescript
import { writeFile, readFile } from "node:fs/promises";

import Anthropic from "@anthropic-ai/sdk";
import { toFile } from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.AGENTAPI_API_KEY,
  baseURL: process.env.AGENTAPI_BASE_URL,
});

const RUBRIC = `# 数据质量方案评分标准

## 检查范围
- 覆盖缺失值、重复记录和字段类型三类问题
- 每类问题都说明检测方法和处理建议

## 输出质量
- 交付一份名为 report.md 的 Markdown 文档
- 文档包含检查步骤、示例和适用限制
`;
await writeFile("/tmp/rubric.md", RUBRIC);

const rubric = await client.beta.files.upload({
  file: await toFile(await readFile("/tmp/rubric.md"), "rubric.md"),
});
console.log(`Uploaded rubric: ${rubric.id}`);
```csharp
```csharp
using Anthropic;
using Anthropic.Core;
using Anthropic.Models.Beta.Agents;
using Anthropic.Models.Beta.Environments;
using Anthropic.Models.Beta.Sessions;
using Anthropic.Models.Beta.Sessions.Events;
using Anthropic.Models.Files;

var client = new AnthropicClient(new ClientOptions
{
    ApiKey = Environment.GetEnvironmentVariable("AGENTAPI_API_KEY")
        ?? throw new InvalidOperationException("AGENTAPI_API_KEY is required"),
    BaseUrl = Environment.GetEnvironmentVariable("AGENTAPI_BASE_URL")
        ?? throw new InvalidOperationException("AGENTAPI_BASE_URL is required"),
});

const string Rubric = """
    # 数据质量方案评分标准

    ## 检查范围
    - 覆盖缺失值、重复记录和字段类型三类问题
    - 每类问题都说明检测方法和处理建议

    ## 输出质量
    - 交付一份名为 report.md 的 Markdown 文档
    - 文档包含检查步骤、示例和适用限制
    """;
await File.WriteAllTextAsync("/tmp/rubric.md", Rubric);

var rubric = await client.Beta.Files.Upload(new()
{
    File = File.OpenRead("/tmp/rubric.md"),
});
Console.WriteLine($"Uploaded rubric: {rubric.ID}");
````

Go

```go
package main

import (
	"context"
	"fmt"
	"io"
	"os"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/option"
)

const rubric = `# 数据质量方案评分标准

## 检查范围
- 覆盖缺失值、重复记录和字段类型三类问题
- 每类问题都说明检测方法和处理建议

## 输出质量
- 交付一份名为 report.md 的 Markdown 文档
- 文档包含检查步骤、示例和适用限制
`

func main() {
	ctx := context.Background()
	client := anthropic.NewClient(
		option.WithoutEnvironmentDefaults(),
		option.WithBaseURL(os.Getenv("AGENTAPI_BASE_URL")),
		option.WithAPIKey(os.Getenv("AGENTAPI_API_KEY")),
	)

	if err := os.WriteFile("/tmp/rubric.md", []byte(rubric), 0o644); err != nil {
		panic(err)
	}

	f, err := os.Open("/tmp/rubric.md")
	if err != nil {
		panic(err)
	}
	defer f.Close()

	uploaded, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
		File: anthropic.File(f, "rubric.md", "text/markdown"),
	})
	if err != nil {
		panic(err)
	}
	fmt.Printf("Uploaded rubric: %s\n", uploaded.ID)
}
```

Java

```java
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.http.HttpResponse;
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.agents.AgentCreateParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsAgentToolset20260401Params;
import com.anthropic.models.beta.agents.BetaManagedAgentsModel;
import com.anthropic.models.beta.environments.BetaCloudConfigParams;
import com.anthropic.models.beta.environments.EnvironmentCreateParams;
import com.anthropic.models.beta.files.FileListParams;
import com.anthropic.models.beta.sessions.SessionCreateParams;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsTextRubricParams;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserDefineOutcomeEventParams;
import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserInterruptEventParams;
import com.anthropic.models.beta.sessions.events.EventSendParams;
import com.anthropic.models.files.FileUploadParams;

import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;

void main() throws Exception {
    var client = AnthropicOkHttpClient.builder()
        .apiKey(System.getenv("AGENTAPI_API_KEY"))
        .baseUrl(System.getenv("AGENTAPI_BASE_URL"))
        .build();

    var RUBRIC = """
        # 数据质量方案评分标准

        ## 检查范围
        - 覆盖缺失值、重复记录和字段类型三类问题
        - 每类问题都说明检测方法和处理建议

        ## 输出质量
        - 交付一份名为 report.md 的 Markdown 文档
        - 文档包含检查步骤、示例和适用限制
        """;
    Files.writeString(Path.of("/tmp/rubric.md"), RUBRIC);

    var rubric = client.beta().files().upload(
        FileUploadParams.builder()
            .file(Path.of("/tmp/rubric.md"))
            .build());
    IO.println("Uploaded rubric: " + rubric.id());
}
```

PHP

```php
use Anthropic\Client;
use Anthropic\Core\FileParam;

$client = new Client(
    apiKey: getenv('AGENTAPI_API_KEY') ?:
        throw new RuntimeException('AGENTAPI_API_KEY is required'),
    baseUrl: getenv('AGENTAPI_BASE_URL') ?:
        throw new RuntimeException('AGENTAPI_BASE_URL is required'),
);

$rubricText = <<<'MD'
# 数据质量方案评分标准

## 检查范围
- 覆盖缺失值、重复记录和字段类型三类问题
- 每类问题都说明检测方法和处理建议

## 输出质量
- 交付一份名为 report.md 的 Markdown 文档
- 文档包含检查步骤、示例和适用限制
MD;
file_put_contents('/tmp/rubric.md', $rubricText);

$rubric = $client->beta->files->upload(
    file: FileParam::fromResource(fopen('/tmp/rubric.md', 'r'), contentType: 'text/markdown'),
);
echo "Uploaded rubric: {$rubric->id}\n";
```

Ruby

```ruby
require "anthropic"
require "pathname"

client = Anthropic::Client.new(
  api_key: ENV.fetch("AGENTAPI_API_KEY"),
  base_url: ENV.fetch("AGENTAPI_BASE_URL")
)

RUBRIC = <<~MD
  # 数据质量方案评分标准

  ## 检查范围
  - 覆盖缺失值、重复记录和字段类型三类问题
  - 每类问题都说明检测方法和处理建议

  ## 输出质量
  - 交付一份名为 report.md 的 Markdown 文档
  - 文档包含检查步骤、示例和适用限制
MD
File.write("/tmp/rubric.md", RUBRIC)

rubric = client.beta.files.upload(file: Pathname.new("/tmp/rubric.md"))
puts "Uploaded rubric: #{rubric.id}"
```

## 创建带有结果的会话 [#创建带有结果的会话]

以下示例使用已创建的智能体和云端环境，先创建会话，再发送 `user.define_outcome`。该事件本身会启动任务，不需要额外发送 `user.message`。智能体应已启用内置工具集，支持写入方案文件与读取评分器反馈；完整创建示例见[智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)。

cURL

```bash
# 创建会话
session=$(curl --request POST --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/sessions" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" --data @- <<EOF
{
  "agent": {"type": "agent", "id": "$agent_id", "version": 1},
  "environment_id": "$environment_id",
  "title": "数据质量检查方案"
}
EOF
)
session_id=$(jq -r '.id' <<<"$session")

# 定义结果，智能体收到后即开始工作
curl --request POST --fail-with-body --silent --show-error "$AGENTAPI_BASE_URL/v1/sessions/$session_id/events" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --header "content-type: application/json" --data @- >/dev/null <<EOF
{
  "events": [
    {
      "type": "user.define_outcome",
      "description": "生成一份名为 report.md 的 Markdown 数据质量检查方案，说明如何检测和处理缺失值、重复记录及字段类型问题，并列出示例和适用限制。",
      "rubric": {"type": "file", "file_id": "$rubric_id"},
      "max_iterations": 5
    }
  ]
}
EOF
# 或："rubric": {"type": "text", "content": "- 覆盖缺失值、重复记录和字段类型\n- 每类问题说明检测方法和处理建议\n- 交付 report.md，包含检查步骤、示例和适用限制"}
# "max_iterations" 为可选项；默认 3，最大 20
```

Python

```python
# 创建会话
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="数据质量检查方案",
)

# 定义结果，智能体收到后即开始工作
client.beta.sessions.events.send(
    session_id=session.id,
    events=[
        {
            "type": "user.define_outcome",
            "description": "生成一份名为 report.md 的 Markdown 数据质量检查方案，说明如何检测和处理缺失值、重复记录及字段类型问题，并列出示例和适用限制。",
            "rubric": {"type": "text", "content": RUBRIC},
            # 或："rubric": {"type": "file", "file_id": rubric.id},
            "max_iterations": 5,  # optional; default 3, max 20
        }
    ],
)
```

TypeScript

````typescript
// 创建会话
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  title: "数据质量检查方案",
});

// 定义结果，智能体收到后即开始工作
await client.beta.sessions.events.send(session.id, {
  events: [
    {
      type: "user.define_outcome",
      description: "生成一份名为 report.md 的 Markdown 数据质量检查方案，说明如何检测和处理缺失值、重复记录及字段类型问题，并列出示例和适用限制。",
      rubric: { type: "text", content: RUBRIC },
      // 或：rubric: { type: "file", file_id: rubric.id },
      max_iterations: 5, // optional; default 3, max 20
    },
  ],
});
```csharp
```csharp
// 创建会话
var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    Title = "数据质量检查方案",
});

// 定义结果，智能体收到后即开始工作
await client.Beta.Sessions.Events.Send(session.ID, new()
{
    Events =
    [
        new BetaManagedAgentsUserDefineOutcomeEventParams
        {
            Type = BetaManagedAgentsUserDefineOutcomeEventParamsType.UserDefineOutcome,
            Description = "生成一份名为 report.md 的 Markdown 数据质量检查方案，说明如何检测和处理缺失值、重复记录及字段类型问题，并列出示例和适用限制。",
            Rubric = new BetaManagedAgentsTextRubricParams
            {
                Type = BetaManagedAgentsTextRubricParamsType.Text,
                Content = Rubric,
            },
            // 或：Rubric = new BetaManagedAgentsFileRubricParams
            //     { Type = BetaManagedAgentsFileRubricParamsType.File, FileID = rubric.ID },
            MaxIterations = 5, // optional; default 3, max 20
        },
    ],
});
````

Go

```go
// 创建会话
session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfString: anthropic.String(agent.ID),
	},
	EnvironmentID: environment.ID,
	Title:         anthropic.String("数据质量检查方案"),
})
if err != nil {
	panic(err)
}

// 定义结果，智能体收到后即开始工作
_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
		OfUserDefineOutcome: &anthropic.BetaManagedAgentsUserDefineOutcomeEventParams{
			Type:        anthropic.BetaManagedAgentsUserDefineOutcomeEventParamsTypeUserDefineOutcome,
			Description: "生成一份名为 report.md 的 Markdown 数据质量检查方案，说明如何检测和处理缺失值、重复记录及字段类型问题，并列出示例和适用限制。",
			Rubric: anthropic.BetaManagedAgentsUserDefineOutcomeEventParamsRubricUnion{
				OfText: &anthropic.BetaManagedAgentsTextRubricParams{
					Type:    anthropic.BetaManagedAgentsTextRubricParamsTypeText,
					Content: rubric,
				},
			},
			// 或：OfFile: &anthropic.BetaManagedAgentsFileRubricParams{
			//     Type: anthropic.BetaManagedAgentsFileRubricParamsTypeFile, FileID: uploaded.ID},
			MaxIterations: anthropic.Int(5), // optional; default 3, max 20
		},
	}},
})
if err != nil {
	panic(err)
}
```

Java

```java
// 创建会话
var session = client.beta().sessions().create(
    SessionCreateParams.builder()
        .agent(agent.id())
        .environmentId(environment.id())
        .title("数据质量检查方案")
        .build());

// 定义结果，智能体收到后即开始工作
client.beta().sessions().events().send(
    session.id(),
    EventSendParams.builder()
        .addEvent(BetaManagedAgentsUserDefineOutcomeEventParams.builder()
            .type(BetaManagedAgentsUserDefineOutcomeEventParams.Type.USER_DEFINE_OUTCOME)
            .description("生成一份名为 report.md 的 Markdown 数据质量检查方案，说明如何检测和处理缺失值、重复记录及字段类型问题，并列出示例和适用限制。")
            .rubric(BetaManagedAgentsTextRubricParams.builder()
                .type(BetaManagedAgentsTextRubricParams.Type.TEXT)
                .content(RUBRIC)
                .build())
            // 或：.rubric(BetaManagedAgentsFileRubricParams.builder()
            //     .type(BetaManagedAgentsFileRubricParams.Type.FILE).fileId(rubric.id()).build())
            .maxIterations(5) // optional; default 3, max 20
            .build())
        .build());
```

PHP

```php
// 创建会话
$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
    title: '数据质量检查方案',
);

// 定义结果，智能体收到后即开始工作
$client->beta->sessions->events->send(
    $session->id,
    events: [
        [
            'type' => 'user.define_outcome',
            'description' => '生成一份名为 report.md 的 Markdown 数据质量检查方案，说明如何检测和处理缺失值、重复记录及字段类型问题，并列出示例和适用限制。',
            'rubric' => ['type' => 'text', 'content' => $rubricText],
            // 或：'rubric' => ['type' => 'file', 'file_id' => $rubric->id],
            'max_iterations' => 5, // optional; default 3, max 20
        ],
    ],
);
```

Ruby

```ruby
# 创建会话
session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id,
  title: "数据质量检查方案"
)

# 定义结果，智能体收到后即开始工作
client.beta.sessions.events.send_(
  session.id,
  events: [
    {
      type: "user.define_outcome",
      description: "生成一份名为 report.md 的 Markdown 数据质量检查方案，说明如何检测和处理缺失值、重复记录及字段类型问题，并列出示例和适用限制。",
      rubric: {type: "text", content: RUBRIC},
      # 或：rubric: {type: "file", file_id: rubric.id},
      max_iterations: 5 # optional; default 3, max 20
    }
  ]
)
```

> 说明
>
> `POST /v1/sessions` 不接受 `initial_events`，需创建会话后再发送 `user.define_outcome`。需要创建时启动结果任务，可在[定时部署](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13600-agentapi-sessions-and-tasks-scheduled-deployments)的 `initial_events` 中配置该事件。

## 结果事件 [#结果事件]

结果任务的生成、工具调用与评估进度都通过同一条[事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)返回。应用应按 `outcome_id` 关联评估事件，并保存事件游标以便重连。

* `agent.*` 事件（例如消息和工具调用）记录任务执行进度。
* `span.outcome_evaluation_*` 事件仅针对面向结果的会话发出，显示迭代循环的次数和评分器的反馈过程。
* 也可以向面向结果的会话发送 `user.message` [事件](/products/agentapi/api/13618-agentapi-api-conventions)，在执行过程中补充要求。即使不发送额外消息，智能体也会持续迭代，直到满足标准或达到最大迭代次数。
* `user.interrupt` 事件会暂停当前结果的工作，并将 `span.outcome_evaluation_end.result` 标记为 `interrupted`，允许启动一个新的结果。
* 最终结果评估完成后，会话既可以作为对话式会话继续，也可以启动一个新的结果。会话会保留先前结果的历史记录。

### 结果定义事件 [#结果定义事件]

> 说明
>
> 一个会话同时只能执行一个结果任务。执行多个结果任务时，请在前一个任务的终止 `span.outcome_evaluation_end` 事件之后发送新的 `user.define_outcome` 事件。

发送结果定义事件可启动结果任务。AgentAPI 接收后会返回该事件，并包含 `processed_at` 时间戳和 `outcome_id`。

```json
{
  "type": "user.define_outcome",
  "description": "生成一份名为 report.md 的 Markdown 数据质量检查方案，说明如何检测和处理缺失值、重复记录及字段类型问题，并列出示例和适用限制。",
  "rubric": { "type": "file", "file_id": "file_01..." },
  "max_iterations": 5
}
```

### 结果评估开始 [#结果评估开始]

当评分器开始评估某一轮迭代时，会发出该事件。`iteration` 字段是从 0 开始计数的修订计数器：`0` 表示第一次评估，`1` 表示第一次修订后的重新评估，依此类推。

```json
{
  "type": "span.outcome_evaluation_start",
  "id": "evt_01def...",
  "outcome_id": "outc_01a...",
  "iteration": 0,
  "processed_at": "2026-03-25T14:01:45Z"
}
```

### 结果评估进行中 [#结果评估进行中]

该事件表示评分器正在工作，不包含评分器的内部推理。应用可以据此更新评估进度，具体反馈由评估结束事件返回。

```json
{
  "type": "span.outcome_evaluation_ongoing",
  "id": "evt_01ghi...",
  "outcome_id": "outc_01a...",
  "iteration": 0,
  "processed_at": "2026-03-25T14:02:10Z"
}
```

### 结果评估结束 [#结果评估结束]

评分器完成某一轮评估后发出，包括评估过程中发生失败或中断。若执行在评估开始前失败或中断，不会产生这一轮的评估结束事件；此时应结合会话状态、停止原因和错误事件判断。

`result` 字段表示评估结果，并决定后续执行行为。

| Result                   | 下一步                                                        |
| ------------------------ | ---------------------------------------------------------- |
| `satisfied`              | 会话转换为 `idle`。                                              |
| `needs_revision`         | 智能体开始一个新的迭代周期。                                             |
| `max_iterations_reached` | 已用完允许的轮数，仍未达标；结束评估并回到 `idle`。请检查反馈和当前产物，再决定是否调整目标或评分标准。    |
| `failed`                 | 评估未能完成，例如评分标准无法读取、评分器出错或返回了失败结果。请结合 `explanation` 和错误事件排查。 |
| `interrupted`            | 评估过程中被中断。评估开始前发生的中断应通过会话状态和停止原因判断。                         |

```json
{
  "type": "span.outcome_evaluation_end",
  "id": "evt_01jkl...",
  "outcome_evaluation_start_id": "evt_01def...",
  "outcome_id": "outc_01a...",
  "result": "satisfied",
  "explanation": "方案覆盖三类数据问题，包含检测方法、处理建议、示例和适用限制，report.md 已生成。",
  "iteration": 0,
  "usage": {
    "input_tokens": 2400,
    "output_tokens": 350,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 1800
  },
  "processed_at": "2026-03-25T14:03:00Z"
}
```

## 检查结果状态 [#检查结果状态]

可以在[事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)中监听 `span.outcome_evaluation_end`，或者轮询 `GET /v1/sessions/{session_id}` 并读取 `outcome_evaluations[].result`。结果执行期间为 `running`；结束后可能为 `satisfied`、`max_iterations_reached`、`failed` 或 `interrupted`：

`needs_revision` 只表示本轮评估要求修改，任务会继续执行。会话进入 `idle` 也不代表结果已经达标；请确认目标 `outcome_id` 的最终 `result`。达到上限或失败后，保留反馈与产物用于排查，需要再次评估时重新发送结果定义。

cURL

```bash
session=$(curl --fail-with-body --silent --show-error --request GET "$AGENTAPI_BASE_URL/v1/sessions/$session_id" \
  --header "x-api-key: $AGENTAPI_API_KEY")

jq -r '.outcome_evaluations[] | "\(.outcome_id): \(.result)"' <<<"$session"
# outc_01a...: satisfied
```

Python

```python
session = client.beta.sessions.retrieve(session.id)

for outcome in session.outcome_evaluations:
    print(f"{outcome.outcome_id}: {outcome.result}")
    # outc_01a...: satisfied
```

TypeScript

````typescript
const retrieved = await client.beta.sessions.retrieve(session.id);

for (const outcome of retrieved.outcome_evaluations) {
  console.log(`${outcome.outcome_id}: ${outcome.result}`);
  // outc_01a...: satisfied
}
```csharp
```csharp
session = await client.Beta.Sessions.Retrieve(session.ID);

foreach (var outcome in session.OutcomeEvaluations)
{
    Console.WriteLine($"{outcome.OutcomeID}: {outcome.Result}");
    // outc_01a...: satisfied
}
````

Go

```go
session, err = client.Beta.Sessions.Get(ctx, session.ID, anthropic.BetaSessionGetParams{})
if err != nil {
	panic(err)
}

for _, outcome := range session.OutcomeEvaluations {
	fmt.Printf("%s: %s\n", outcome.OutcomeID, outcome.Result)
	// outc_01a...: satisfied
}
```

Java

```java
var retrieved = client.beta().sessions().retrieve(session.id());

for (var outcome : retrieved.outcomeEvaluations()) {
    IO.println(outcome.outcomeId() + ": " + outcome.result());
    // outc_01a...: satisfied
}
```

PHP

```php
$session = $client->beta->sessions->retrieve($session->id);

foreach ($session->outcomeEvaluations as $outcome) {
    echo "{$outcome->outcomeID}: {$outcome->result}\n";
    // outc_01a...: satisfied
}
```

Ruby

```ruby
session = client.beta.sessions.retrieve(session.id)

session.outcome_evaluations.each do |outcome|
  puts "#{outcome.outcome_id}: #{outcome.result}"
  # outc_01a...: satisfied
end
```

## 检索交付物 [#检索交付物]

> 生成可下载的交付物
>
> 云端环境默认引导智能体将最终文件写入 `/mnt/session/outputs/`，普通会话与 Outcome 均适用，无需在提示词中重复说明。自托管 worker 不注入此指引。

智能体会把输出文件写入沙箱内的 `/mnt/session/outputs/`。按以下两步取回这些文件：

1. 通过 [Files API](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files) 列出文件，以会话 ID 作为 `scope_id`。
2. 按文件 ID 逐个下载。

AgentAPI 在执行结束后收集文件，可能比会话进入空闲状态晚几秒。若预期文件尚未列出，请稍后重查；列出后即可下载。

cURL

```bash
# 列出此会话生成的文件
files=$(curl --fail-with-body --silent --show-error --request GET "$AGENTAPI_BASE_URL/v1/files?scope_id=$session_id" \
  --header "x-api-key: $AGENTAPI_API_KEY")
jq -r '.data[] | "\(.id) \(.filename)"' <<<"$files"

# 下载文件
file_id=$(jq -r '.data[0].id // empty' <<<"$files")
if [[ -n $file_id ]]; then
  curl --fail-with-body --silent --show-error --request GET "$AGENTAPI_BASE_URL/v1/files/$file_id/content" \
    --header "x-api-key: $AGENTAPI_API_KEY" \
    --output /tmp/report.md
fi
```

Python

```python
# 列出此会话生成的文件
files = client.beta.files.list(scope_id=session.id)
for file in files:
    print(file.id, file.filename)

# 下载文件
if files.data:
    content = client.beta.files.download(files.data[0].id)
    content.write_to_file("/tmp/report.md")
```

TypeScript

````typescript
// 列出此会话生成的文件
const files = await client.beta.files.list({
  scope_id: session.id,
});
for (const file of files.data) {
  console.log(file.id, file.filename);
}

// 下载文件
if (files.data.length > 0) {
  const content = await client.beta.files.download(files.data[0].id);
  await writeFile("/tmp/report.md", new Uint8Array(await content.arrayBuffer()));
}
```csharp
```csharp
// 列出此会话生成的文件
var files = await client.Beta.Files.List(new()
{
    ScopeID = session.ID,
});
foreach (var file in files.Items)
{
    Console.WriteLine($"{file.ID} {file.Filename}");
}

// 下载文件
if (files.Items.Count > 0)
{
    using var download = await client.Beta.Files.Download(files.Items[0].ID);
    await using var output = File.Create("/tmp/report.md");
    await (await download.ReadAsStream()).CopyToAsync(output);
}
````

Go

```go
// 列出此会话生成的文件
files, err := client.Beta.Files.List(ctx, anthropic.BetaFileListParams{
	ScopeID: anthropic.String(session.ID),
})
if err != nil {
	panic(err)
}
for _, file := range files.Data {
	fmt.Println(file.ID, file.Filename)
}

// 下载文件
if len(files.Data) > 0 {
	resp, err := client.Beta.Files.Download(ctx, files.Data[0].ID)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, err := os.Create("/tmp/report.md")
	if err != nil {
		panic(err)
	}
	defer out.Close()
	if _, err := io.Copy(out, resp.Body); err != nil {
		panic(err)
	}
}
```

Java

```java
// 列出此会话生成的文件
var files = client.beta().files().list(
    FileListParams.builder()
        .scopeId(session.id())
        .build());
for (var file : files.data()) {
    IO.println(file.id() + " " + file.filename());
}

// 下载文件
if (!files.data().isEmpty()) {
    try (HttpResponse response = client.beta().files().download(files.data().getFirst().id())) {
        try (InputStream body = response.body()) {
            Files.copy(body, Path.of("/tmp/report.md"), StandardCopyOption.REPLACE_EXISTING);
        }
    }
}
```

PHP

```php
// 列出此会话生成的文件
$files = $client->beta->files->list(scopeID: $session->id);
foreach ($files->getItems() as $file) {
    echo "{$file->id} {$file->filename}\n";
}

// 下载文件
if (count($files->getItems()) > 0) {
    $content = $client->beta->files->download($files->getItems()[0]->id);
    file_put_contents('/tmp/report.md', $content);
}
```

Ruby

```ruby
# 列出此会话生成的文件
files = client.beta.files.list(scope_id: session.id)
files.data.each { |file| puts "#{file.id} #{file.filename}" }

# 下载文件
if (first = files.data.first)
  content = client.beta.files.download(first.id)
  File.binwrite("/tmp/report.md", content.read)
end
```

## 后续步骤 [#后续步骤]

* [凭证管理](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13606-agentapi-data-and-integrations-vaults)：在创建会话时注册每个用户的凭据。

* [事件和事件流](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13597-agentapi-sessions-and-tasks-events)：发送事件、流式传输响应，并在执行过程中中断执行或补充任务要求。

* [附加和下载文件](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)：上传文件并挂载到会话沙箱中，供智能体读取和处理。


# 定时部署 (/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13600-agentapi-sessions-and-tasks-scheduled-deployments)



最近更新时间: 2026-10-13 15:31:41

定时部署（scheduled deployment）让智能体按固定时间自动创建会话并执行任务。可以使用 Deployments API 创建、运行、暂停、恢复和归档部署。

部署保存任务模板，每次触发生成部署运行记录并创建新会话。需要跨次保留信息时，请在模板中附加[记忆存储](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13603-agentapi-data-and-integrations-memory)。

![定时部署的会话触发流程](/docs-assets/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13600-agentapi-sessions-and-tasks-scheduled-deployments/FjsLuFtxiSwvs5cnqd2zmYBS9EQx-f262c1993561.webp)

## 接入定时任务 [#接入定时任务]

1. 完成[接入准备](/products/agentapi/quick_start/13585-agentapi-access)，创建[智能体](/products/agentapi/development_guidelines/agentapi-agent-configuration/13590-agentapi-agent-configuration-agent)和[云端环境](/products/agentapi/development_guidelines/agentapi-execution-environments/13608-agentapi-execution-environments-environment)。智能体显式配置 `runtime`，部署创建的会话继承该运行时。
2. 准备每次执行需要的输入、文件、仓库和 Vault；这些配置保存在部署模板中。
3. 创建部署，核对 cron、时区及 `upcoming_runs_at`。
4. 手动运行一次，使用返回的 `session_id` 查看事件并核对产物。
5. 定时运行后，同时监控部署运行错误和会话执行结果；修复自动暂停的原因后再恢复计划。

以下示例沿用[SDK 客户端初始化](/products/agentapi/quick_start/13587-agentapi-quickstart)中的 `client`，并使用已经创建的智能体和云端环境。智能体所用模型应从[七牛 MaaS 模型管理页](https://portal.qiniu.com/ai-inference/model)选择。首次接入时可先省略 `schedule`，完成手动验证后再更新计划。

## 创建定时部署 [#创建定时部署]

创建部署时，需要指定智能体、云端环境、初始事件和计划。部署保存这些配置，每次触发都会创建一个新的会话。

Portal 任务详情会展示当前配置关联的凭证库。您也可以在运行历史中查看该次会话关联的凭证库；这里使用历史会话的 `vault_ids`，后续修改部署不会改变这些关联 ID。尚未创建会话的运行会显示“未创建 Session”；已删除或暂时无法访问的会话会显示加载错误，您可以重试。

部署会固定智能体版本：`agent` 可传 ID 字符串（保存时解析版本），或带 `version` 的引用。更新智能体后，需另行更新部署的 `agent` 引用。请将 cURL 示例中的版本 `1` 替换为要发布的版本。

任务依赖输入文件、仓库或外部服务时，在模板中设置 `resources` 和 `vault_ids`。这些资源会在每次创建会话时重新校验；令牌保存在 Vault 中，仓库挂载凭证按[访问 GitHub](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13604-agentapi-data-and-integrations-github)配置。

* `initial_events` 至少包含一个 `user.message` 或 `user.define_outcome` 事件，用于启动会话。
* `schedule` 使用分钟级 cron 表达式和 IANA 时区；省略 `schedule` 时，只能手动运行部署。

以下示例创建每周项目检查任务。各语言 SDK 用 `content` 构造兼容类型，再通过原始请求体选项将 `initial_events` 替换为 AgentAPI 的规范字段 `input.parts`。

cURL

```bash
DEPLOYMENT_ID=$(
  curl --fail-with-body --silent --show-error --request POST "$AGENTAPI_BASE_URL/v1/deployments" \
    --header "x-api-key: $AGENTAPI_API_KEY" \
    --header "content-type: application/json" \
    --data @- <<EOF | jq -er '.id'
{
  "name": "每周项目检查",
  "agent": {"type": "agent", "id": "$AGENT_ID", "version": 1},
  "environment_id": "$ENVIRONMENT_ID",
  "initial_events": [
    {"type": "user.message", "input": {"parts": [{"type": "text", "text": "检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。"}]}}
  ],
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York"
  }
}
EOF
)
```

Python

```python
deployment = client.beta.deployments.create(
    name="每周项目检查",
    agent=agent.id,
    environment_id=environment.id,
    initial_events=[
        {
            "type": "user.message",
            "content": [{"type": "text", "text": "检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。"}],
        },
    ],
    schedule={
        "type": "cron",
        "expression": "0 20 * * 5",
        "timezone": "America/New_York",
    },
    extra_body={
        "initial_events": [{
            "type": "user.message",
            "input": {"parts": [{"type": "text", "text": "检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。"}]},
        }],
    },
)
```

TypeScript

````typescript
const params = {
  name: "每周项目检查",
  agent: agent.id,
  environment_id: environment.id,
  initial_events: [
    {
      type: "user.message",
      content: [{ type: "text", text: "检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。" }],
    },
  ],
  schedule: {
    type: "cron",
    expression: "0 20 * * 5",
    timezone: "America/New_York",
  },
} satisfies Parameters<typeof client.beta.deployments.create>[0];
const deployment = await client.beta.deployments.create(params, {
  body: {
    ...params,
    initial_events: [{
      type: "user.message",
      input: { parts: [{ type: "text", text: "检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。" }] },
    }],
  },
});
```csharp
```csharp
using System.Linq;
using System.Text.Json;
using Anthropic.Models.Beta.Deployments;
using Anthropic.Models.Beta.Sessions.Events;

var parameters = new DeploymentCreateParams
{
    Name = "每周项目检查",
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    InitialEvents =
    [
        new BetaManagedAgentsUserMessageEventParams
        {
            Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
            Content =
            [
                new BetaManagedAgentsTextBlock
                {
                    Type = BetaManagedAgentsTextBlockType.Text,
                    Text = "检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。",
                },
            ],
        },
    ],
    Schedule = new BetaManagedAgentsScheduleParams
    {
        Type = BetaManagedAgentsScheduleParamsType.Cron,
        Expression = "0 20 * * 5",
        Timezone = "America/New_York",
    },
};
var body = parameters.RawBodyData.ToDictionary(entry => entry.Key, entry => entry.Value);
body["initial_events"] = JsonSerializer.SerializeToElement(new[] {
    new {
        type = "user.message",
        input = new { parts = new[] { new { type = "text", text = "检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。" } } },
    },
});
parameters = DeploymentCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body);
var deployment = await client.Beta.Deployments.Create(parameters);
````

Go

```go
import "github.com/anthropics/anthropic-sdk-go/option"

deployment, err := client.Beta.Deployments.New(ctx, anthropic.BetaDeploymentNewParams{
	Name:          "每周项目检查",
	Agent:         anthropic.BetaDeploymentNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
	EnvironmentID: environment.ID,
	InitialEvents: []anthropic.BetaManagedAgentsDeploymentInitialEventParamsUnion{{
		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
					Text: "检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。",
				},
			}},
		},
	}},
	Schedule: anthropic.BetaManagedAgentsScheduleParams{
		Type:       anthropic.BetaManagedAgentsScheduleParamsTypeCron,
		Expression: "0 20 * * 5",
		Timezone:   "America/New_York",
	},
}, option.WithJSONSet("initial_events", []map[string]any{{
    "type": "user.message",
    "input": map[string]any{
        "parts": []map[string]string{{"type": "text", "text": "检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。"}},
    },
}}))
if err != nil {
	panic(err)
}
```

Java

```java
import com.anthropic.core.JsonValue;
import java.util.List;
import java.util.Map;

var deployment = client.beta().deployments().create(
    DeploymentCreateParams.builder()
        .name("每周项目检查")
        .agent(agent.id())
        .environmentId(environment.id())
        .addInitialEvent(
            BetaManagedAgentsUserMessageEventParams.builder()
                .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
                .addTextContent("检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。")
                .build()
        )
        .schedule(
            BetaManagedAgentsScheduleParams.builder()
                .type(BetaManagedAgentsScheduleParams.Type.CRON)
                .expression("0 20 * * 5")
                .timezone("America/New_York")
                .build()
        )
        .putAdditionalBodyProperty("initial_events", JsonValue.from(List.of(Map.of(
            "type", "user.message",
            "input", Map.of("parts", List.of(Map.of("type", "text", "text", "检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。")))
        ))))
        .build()
);
```

PHP

```php
$deployment = $client->beta->deployments->create(
    name: '每周项目检查',
    agent: $agent->id,
    environmentID: $environment->id,
    initialEvents: [
        [
            'type' => 'user.message',
            'content' => [['type' => 'text', 'text' => '检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。']],
        ],
    ],
    schedule: [
        'type' => 'cron',
        'expression' => '0 20 * * 5',
        'timezone' => 'America/New_York',
    ],
    requestOptions: ['extraBodyParams' => [
        'initial_events' => [[
            'type' => 'user.message',
            'input' => ['parts' => [['type' => 'text', 'text' => '检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。']]],
        ]],
    ]],
);
```

Ruby

```ruby
deployment = client.beta.deployments.create(
  name: "每周项目检查",
  agent: agent.id,
  environment_id: environment.id,
  initial_events: [
    {
      type: "user.message",
      content: [{type: "text", text: "检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。"}]
    }
  ],
  schedule: {
    type: "cron",
    expression: "0 20 * * 5",
    timezone: "America/New_York"
  },
  request_options: {
    extra_body: {
      initial_events: [{
        type: "user.message",
        input: {parts: [{type: "text", text: "检查本周项目变更，汇总风险与待办事项，并生成 Markdown 报告。"}]}
      }]
    }
  }
)
```

响应中的部署对象通过 `schedule.upcoming_runs_at` 字段返回后续触发时间，可用于核对计划设置。

```json
{
  "id": "depl_01xyz",
  "status": "active",
  "paused_reason": null,
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York",
    "last_run_at": null,
    "upcoming_runs_at": [
      "2026-05-09T00:00:00Z",
      "2026-05-16T00:00:00Z",
      "2026-05-23T00:00:00Z"
    ]
  }
}
```

计划时间不含抖动（jitter）。为分散负载，调度器会在计划时间后增加 5 秒至 9 分钟的延迟，其上限按运行间隔的 15% 计算，再限制在该范围内。实际触发还可能受调度器处理延迟影响。

当前服务对每个账户的未归档定时部署数量限制为 1,000 个。达到上限后，创建定时部署或为现有部署新增计划会返回 `400`。

本页展示定时部署的常用参数和响应；通用认证、分页和错误约定请参阅 [API 通用约定](/products/agentapi/api/13618-agentapi-api-conventions)。

### Cron 和时区语义 [#cron-和时区语义]

* 表达式： 标准 POSIX cron（`minute hour day-of-month month day-of-week`）。
* 时区： IANA 时区标识符（例如 `"America/Los_Angeles"`）。
* 夏令时（DST）： Cron 计划使用字面挂钟时间匹配，因此 `America/New_York` 时区中的 `"0 20 * * *"` 会在当地时间晚上 8:00 触发，无论当前生效的是 EST 还是 EDT。

> 说明
>
> 在夏令时开始（时钟拨快）当天不存在的挂钟时间（例如凌晨 2 点）不会被触发。在夏令时结束（时钟拨慢）当天出现两次的挂钟时间会触发两次。如果无法接受遗漏或重复执行，请将计划安排在当地时间凌晨 1–3 点窗口之外，或使用 UTC。

## 触发手动运行 [#触发手动运行]

要在计划之外运行部署，请调用部署的 `run` 端点。这会立即创建一个会话，并写入一条 `trigger_context.type: "manual"` 的部署运行记录，适合在启用计划前测试部署。

cURL

```bash
curl --fail-with-body --silent --show-error --request POST "$AGENTAPI_BASE_URL/v1/deployments/$DEPLOYMENT_ID/run" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
run = client.beta.deployments.run(deployment.id)
```

TypeScript

````typescript
const run = await client.beta.deployments.run(deployment.id);
```csharp
```csharp
var manualRun = await client.Beta.Deployments.Run(deployment.ID);
````

Go

```go
manualRun, err := client.Beta.Deployments.Run(ctx, deployment.ID, anthropic.BetaDeploymentRunParams{})
if err != nil {
	panic(err)
}
```

Java

```java
var run = client.beta().deployments().run(deployment.id());
```

PHP

```php
$run = $client->beta->deployments->run($deployment->id);
```

Ruby

```ruby
run = client.beta.deployments.run(deployment.id)
```

## 部署运行 [#部署运行]

> 部署运行与任务结果
>
> 部署运行（deployment run）记录会话创建和初始事件提交的结果，包括环境已归档、资源不可用或初始事件被拒绝等错误。运行成功不代表任务已经完成；任务是否成功，需用返回的 `session_id` 查询会话和事件。

> 防止重复执行
>
> 调度采用“至少一次”语义，不能保证 exactly-once；超时、重启或恢复后可能重复触发。写入、发消息、创建工单等操作应在业务侧去重：可组合 `deployment_id` 与 `trigger_context.scheduled_at` 作为幂等键，在执行前检查是否已处理。

按如下方式列出某个部署的所有部署运行：

cURL

```bash
curl --fail-with-body --silent --show-error --get "$AGENTAPI_BASE_URL/v1/deployment_runs" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --data-urlencode "deployment_id=$DEPLOYMENT_ID"
```

Python

```python
for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
):
    print(run.created_at, run.session_id or run.error.type)
```

TypeScript

````typescript
for await (const run of client.beta.deploymentRuns.list({
  deployment_id: deployment.id,
})) {
  console.log(run.created_at, run.session_id ?? run.error?.type);
}
```csharp
```csharp
var runs = await client.Beta.DeploymentRuns.List(
    new() { DeploymentID = deployment.ID }
);
await foreach (var run in runs.Paginate())
{
    // Error 联合类型直接暴露 .Message；在添加通用 .Type 访问器之前，
    // 判别器需从 .Json 中读取。
    var outcome = run.SessionID ?? run.Error!.Json.GetProperty("type").GetString();
    Console.WriteLine($"{run.CreatedAt} {outcome}");
}
````

Go

```go
runs := client.Beta.DeploymentRuns.ListAutoPaging(ctx, anthropic.BetaDeploymentRunListParams{
	DeploymentID: anthropic.String(deployment.ID),
})
for runs.Next() {
	run := runs.Current()
	if run.SessionID != "" {
		fmt.Println(run.CreatedAt.Format(time.RFC3339), run.SessionID)
	} else {
		fmt.Println(run.CreatedAt.Format(time.RFC3339), run.Error.Type)
	}
}
if err := runs.Err(); err != nil {
	panic(err)
}
```

Java

```java
for (var run : client.beta().deploymentRuns().list(
        DeploymentRunListParams.builder()
            .deploymentId(deployment.id())
            .build()).autoPager()) {
    // Error 联合类型尚未暴露通用的 .type()/.message()
    // 访问器；.toString() 包含两者。
    IO.println(run.createdAt() + " "
        + run.sessionId().orElseGet(() -> run.error().orElseThrow().toString()));
}
```

PHP

```php
foreach ($client->beta->deploymentRuns->list(
    deploymentID: $deployment->id,
)->pagingEachItem() as $run) {
    $outcome = $run->sessionID ?? $run->error->type;
    echo "{$run->createdAt->format(DATE_ATOM)} {$outcome}\n";
}
```

Ruby

```ruby
client.beta.deployment_runs.list(
  deployment_id: deployment.id
).auto_paging_each do
  puts "#{it.created_at} #{it.session_id || it.error.type}"
end
```

还可以筛选出带有错误的部署运行：

cURL

```bash
curl --fail-with-body --silent --show-error --get "$AGENTAPI_BASE_URL/v1/deployment_runs" \
  --header "x-api-key: $AGENTAPI_API_KEY" \
  --data-urlencode "deployment_id=$DEPLOYMENT_ID" \
  --data-urlencode "has_error=true"
```

Python

```python
for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
    has_error=True,
):
    print(run.created_at, run.error.type, run.error.message)
```

TypeScript

````typescript
for await (const run of client.beta.deploymentRuns.list({
  deployment_id: deployment.id,
  has_error: true,
})) {
  console.log(run.created_at, run.error?.type, run.error?.message);
}
```csharp
```csharp
var failedRuns = await client.Beta.DeploymentRuns.List(
    new() { DeploymentID = deployment.ID, HasError = true }
);
await foreach (var failedRun in failedRuns.Paginate())
{
    var error = failedRun.Error!;
    var errorType = error.Json.GetProperty("type").GetString();
    Console.WriteLine($"{failedRun.CreatedAt} {errorType} {error.Message}");
}
````

Go

```go
failedRuns := client.Beta.DeploymentRuns.ListAutoPaging(ctx, anthropic.BetaDeploymentRunListParams{
	DeploymentID: anthropic.String(deployment.ID),
	HasError:     anthropic.Bool(true),
})
for failedRuns.Next() {
	failedRun := failedRuns.Current()
	fmt.Println(failedRun.CreatedAt.Format(time.RFC3339), failedRun.Error.Type, failedRun.Error.Message)
}
if err := failedRuns.Err(); err != nil {
	panic(err)
}
```

Java

```java
for (var run : client.beta().deploymentRuns().list(
        DeploymentRunListParams.builder()
            .deploymentId(deployment.id())
            .hasError(true)
            .build()).autoPager()) {
    IO.println(run.createdAt() + " " + run.error().orElseThrow());
}
```

PHP

```php
foreach ($client->beta->deploymentRuns->list(
    deploymentID: $deployment->id,
    hasError: true,
)->pagingEachItem() as $run) {
    echo "{$run->createdAt->format(DATE_ATOM)} {$run->error->type} {$run->error->message}\n";
}
```

Ruby

```ruby
client.beta.deployment_runs.list(
  deployment_id: deployment.id,
  has_error: true
).auto_paging_each do
  puts "#{it.created_at} #{it.error.type} #{it.error.message}"
end
```

失败的运行包含一个 `error`，其 `type` 描述了会话创建被拒绝的原因（例如 `environment_archived_error`、`agent_archived_error` 或 `session_rate_limited_error`）。

```json
{
  "type": "deployment_run",
  "id": "drun_01abc124",
  "deployment_id": "depl_01xyz",
  "trigger_context": { "type": "schedule", "scheduled_at": "2026-05-09T00:00:00Z" },
  "session_id": null,
  "error": {
    "type": "environment_archived_error",
    "message": "environment `env_01abc` is archived"
  },
  "agent": { "type": "agent", "id": "agt_01ghi789", "version": 3 },
  "created_at": "2026-05-09T00:00:01Z"
}
```

## 管理部署生命周期 [#管理部署生命周期]

* 列出部署：`GET /v1/deployments`。
* 查看部署：`GET /v1/deployments/{deployment_id}`。
* 更新部署：`POST /v1/deployments/{deployment_id}`。请求中的 `resources`、`vault_ids`、`initial_events` 整体替换原值；`"schedule": null` 清除计划。

暂停（Pause）会停止后续定时触发；已创建且正在运行的会话会继续执行。暂停期间仍允许通过 `run` 端点手动运行。暂停会将 `paused_reason` 设置为 `{"type": "manual"}`；取消暂停会将其清除。

cURL

```bash
curl --fail-with-body --silent --show-error --request POST "$AGENTAPI_BASE_URL/v1/deployments/$DEPLOYMENT_ID/pause" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
client.beta.deployments.pause(deployment.id)
```

TypeScript

````typescript
await client.beta.deployments.pause(deployment.id);
```csharp
```csharp
await client.Beta.Deployments.Pause(deployment.ID);
````

Go

```go
if _, err := client.Beta.Deployments.Pause(ctx, deployment.ID, anthropic.BetaDeploymentPauseParams{}); err != nil {
	panic(err)
}
```

Java

```java
client.beta().deployments().pause(deployment.id());
```

PHP

```php
$client->beta->deployments->pause($deployment->id);
```

Ruby

```ruby
client.beta.deployments.pause(deployment.id)
```

取消暂停（Unpause）会从下一个计划时间点恢复计划。错过的触发不会被补执行。

cURL

```bash
curl --fail-with-body --silent --show-error --request POST "$AGENTAPI_BASE_URL/v1/deployments/$DEPLOYMENT_ID/unpause" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
client.beta.deployments.unpause(deployment.id)
```

TypeScript

````typescript
await client.beta.deployments.unpause(deployment.id);
```csharp
```csharp
await client.Beta.Deployments.Unpause(deployment.ID);
````

Go

```go
if _, err := client.Beta.Deployments.Unpause(ctx, deployment.ID, anthropic.BetaDeploymentUnpauseParams{}); err != nil {
	panic(err)
}
```

Java

```java
client.beta().deployments().unpause(deployment.id());
```

PHP

```php
$client->beta->deployments->unpause($deployment->id);
```

Ruby

```ruby
client.beta.deployments.unpause(deployment.id)
```

归档（Archive）会永久终止计划，归档后的部署无法修改或恢复。

归档后也不能手动运行该部署。部署生命周期操作不会自动归档或删除已经创建的会话；需要停止某次任务或清理产物时，请使用[会话生命周期操作](/products/agentapi/development_guidelines/agentapi-sessions-and-tasks/13598-agentapi-sessions-and-tasks-session-lifecycle)。

cURL

```bash
curl --fail-with-body --silent --show-error --request POST "$AGENTAPI_BASE_URL/v1/deployments/$DEPLOYMENT_ID/archive" \
  --header "x-api-key: $AGENTAPI_API_KEY"
```

Python

```python
client.beta.deployments.archive(deployment.id)
```

TypeScript

````typescript
await client.beta.deployments.archive(deployment.id);
```csharp
```csharp
await client.Beta.Deployments.Archive(deployment.ID);
````

Go

```go
if _, err := client.Beta.Deployments.Archive(ctx, deployment.ID, anthropic.BetaDeploymentArchiveParams{}); err != nil {
	panic(err)
}
```

Java

```java
client.beta().deployments().archive(deployment.id());
```

PHP

```php
$client->beta->deployments->archive($deployment->id);
```

Ruby

```ruby
client.beta.deployments.archive(deployment.id)
```

### 失败行为 [#失败行为]

根据失败发生的阶段，按以下方式排查：

| 观察结果                      | 检查与处理                                                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 部署运行包含 `error`，未返回成功创建的会话 | 查看资源是否可用、是否限流，以及部署的 `paused_reason`。                                                                                                       |
| 部署运行成功，但会话出现错误或等待确认       | 使用 `session_id` 读取事件，处理模型、工具、权限或输入问题。                                                                                                      |
| 有会话，但没有预期文件               | 核对最终回答、输出路径和[会话文件列表](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13602-agentapi-data-and-integrations-files)。 |
| 部署自动暂停                    | 修复 `paused_reason.error.type` 对应的问题，更新模板，手动验证后再恢复。                                                                                         |

会话创建或初始事件提交失败时，查看运行记录的 `error.type` 和 `error.message`。计划是否继续执行取决于部署是否自动暂停；会话已启动后的模型调用错误则通过会话事件排查。

资源失效时，部署按以下规则处理：

| 原因                       | 部署行为                | 运行记录                                      |
| ------------------------ | ------------------- | ----------------------------------------- |
| 智能体被归档                   | 同时自动归档部署            | 不生成                                       |
| 智能体被删除                   | 同时自动归档部署            | 不生成                                       |
| 引用的子智能体被归档               | 下次触发时自动暂停，更新智能体后可恢复 | 记录失败，`error.type: "agent_archived_error"` |
| 其他不可恢复的会话创建错误，如环境或保管库已归档 | 自动暂停，修复后可恢复         | 记录失败                                      |

自动暂停时，`paused_reason.error.type` 与失败运行的 `error.type` 一致。

## 接收部署通知 [#接收部署通知]

在 Portal 的“服务设置 → Webhook”中订阅 `deployment_run.started`、`deployment_run.succeeded` 或 `deployment_run.failed`，接收计划部署运行通知。这些事件仅由计划触发，手动运行不产生 `deployment_run.*` Webhook；部署暂停、恢复和更新可订阅对应的 `deployment.*` 事件。

运行成功表示会话创建和初始化成功，不代表智能体任务完成。收到运行通知后，用 `data.id` 查询运行记录取得 `session_id`，再读取会话事件与产物；也可订阅会话状态通知。接收服务必须处理重复投递和乱序，端点停用期间的事件不会补发，详见 [Webhook 通知](/products/agentapi/development_guidelines/agentapi-data-and-integrations/13605-agentapi-data-and-integrations-webhooks)。


# 创建API Key (/products/aitokenapi/apikey-use-api/0-creat-apikey-api)



最近更新时间: 2026-03-24 17:06:00

您可以在控制台创建API Key，创建时需要设置名称或备注信息，用于您自己记录用途、描述业务场景、或区分企业内部用户。

<br />

# **说明** [#说明]

* 支持您使用中文、大小写英文、数字等设置备注
* 不支持为空
* 支持最多 20 个字符

<br />

# **操作步骤** [#操作步骤]

1. 登录 **AI大模型推理** 控制台进入[API Key](https://portal.qiniu.com/ai-inference/api-key)界面
2. 点击 &#x2A;*【创建 API Key】*&#x2A; 进入 &#x2A;*【API Key】** 创建界面
3. 设置 &#x2A;*【名称或备注信息】*&#x2A; ，单击 &#x2A;*【确定】** 完成API Key创建。
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/0-creat-apikey-api/Fp71H9lZbAscKqJD3fKQULtv2LsS-bf3eadaf525e.webp)


# 启用/禁用/删除API Key (/products/aitokenapi/apikey-use-api/1-enable-disable-delete-apikey-api)



最近更新时间: 2026-05-09 10:41:25

您可以在 &#x2A;*【AI 大模型推理】** 控制台对API Key进行 **启用**、**禁用**、**删除** 等操作

<br />

## **启用API Key** [#启用api-key]

1. 登录 &#x2A;*【AI大模型推理】*&#x2A; 控制台进入 &#x2A;*[API Key](https://portal.qiniu.com/ai-inference/api-key)** 界面
2. 点击 &#x2A;*【启用】** 即可。
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/1-enable-disable-delete-apikey-api/FjE-NgMgJr8-gOujYIsu00RaHfl2-09434f5191f2.webp)

<br />

## **禁用API Key** [#禁用api-key]

1. 登录 &#x2A;*【AI大模型推理】*&#x2A; 控制台进入 &#x2A;*[API Key](https://portal.qiniu.com/ai-inference/api-key)** 界面
2. 点击 &#x2A;*【禁用】** 即可。
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/1-enable-disable-delete-apikey-api/FrK2GqutX-gSrZMgxe_l1F1oOHw9-120b5a359fe2.webp)

<br />

## **删除API Key** [#删除api-key]

1. 登录 &#x2A;*【AI大模型推理】*&#x2A; 控制台进入 &#x2A;*[API Key](https://portal.qiniu.com/ai-inference/api-key)** 界面
2. 点击 &#x2A;*【删除】** 即可。
3. **注意：** 只有禁用状态的API Key才有删除按钮。
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/1-enable-disable-delete-apikey-api/Fv5FsgELEOjJo12U45J-ppBCDyU-04d0448ade0f.webp)


# API Key模型范围配置 (/products/aitokenapi/apikey-use-api/13535-set-api-key-model-scope)



最近更新时间: 2026-07-28 11:55:03

您可以在 &#x2A;*【AI 大模型推理】** 控制台对API Key进行 **模型范围*&#x2A; 限制配置，支持通过 &#x2A;*`分组控制`** 可访问模型。<br />该功能用于限制 API Key 可访问模型，不在模型范围内的模型调用会拒绝请求。

<br />

## **模型范围** [#模型范围]

1. 登录 &#x2A;*【AI大模型推理】*&#x2A; 控制台进入 &#x2A;*[API Key](https://portal.qiniu.com/ai-inference/api-key)** 界面
2. 点击 &#x2A;*【模型范围】** 进入模型范围配置界面
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/13535-set-api-key-model-scope/Fl5a3LK4fcOM-3HdV_TJZDZbZQnn-fb3d4a08d231.webp)
3. 支持通过 &#x2A;*`分组控制`** 可访问模型，您可以根据自身需求 **新建用户分组**，并选择需要访问的模型ID，然后点击 **保存**
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/13535-set-api-key-model-scope/FjdYcoMQ4rEiID8KZiTpAcNnbcep-788258a128a3.webp)
4. 在 api-key 点击开启 **可用模型管理** 按钮，然后在 **分组列表** 中勾选对应所需 **分组*&#x2A;，点击 &#x2A;*【保存】** 即可。
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/13535-set-api-key-model-scope/FpKlnjn8jASZVTsKS0C3Y6TQw6gk-7c970894d77c.webp)

<br />


# API Key配置IP白名单 (/products/aitokenapi/apikey-use-api/13566-api-key-configuration-ip-whitelist)



最近更新时间: 2026-09-02 18:25:13

您可以在 &#x2A;*【AI 大模型推理】** 控制台对API Key进行 **IP白名单配置**，支持设置IP或IP段。<br />&#x2A;*注意：**

1. IP白名单限制暂不适用于 **/v1/messages 接口**。
2. 启用IP白名单限制后，通过七牛内部服务（如在线对话、Agent 等）使用该 API Key 的请求也会受到同样的 IP 限制。

<br />

## **IP白名单配置** [#ip白名单配置]

1. 登录 &#x2A;*【AI大模型推理】*&#x2A; 控制台进入 &#x2A;*[API Key](https://portal.qiniu.com/ai-inference/api-key)** 界面；
2. 点击 &#x2A;*【IP 白名单】** 进入配置界面；
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/13566-api-key-configuration-ip-whitelist/FhtQApQeNlLsd7q6RAABcvyNOntb-052c143d27c9.webp)
3. 再点击 &#x2A;*【自定义分组】*&#x2A;，然后设置：分组名称、IP/CIDR规则等信息，设置完成后，点击 &#x2A;*【保存】** 即可创建成功自定义分组；
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/13566-api-key-configuration-ip-whitelist/FhHFFdDuHfbkdXc8ofWVCcR8h4vY-dbc52908df56.webp)
4. 自定义分组创建成功后，在 &#x2A;*【IP 白名单】** 界面选择需要加白的分组即可
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/13566-api-key-configuration-ip-whitelist/FoYQmrQC5PrZRfUo4UmpV-Uksway-e2f76882f770.webp)

<br />


# API Key限额配置 (/products/aitokenapi/apikey-use-api/2-apikey-use-limit-api)



最近更新时间: 2026-05-09 10:47:41

您可以在 &#x2A;*【AI 大模型推理】** 控制台对API Key进行 **限额配置**，支持日限额、月限额、总限额。<br />该功能用于限制 API Key 最大可消费金额。达到限额后将停止新的请求，但已在处理中的请求会继续完成。因此实际生效额度与配置额度可能存在略微差异。

<br />

## **限额配置** [#限额配置]

1. 登录 &#x2A;*【AI大模型推理】*&#x2A; 控制台进入 &#x2A;*[API Key](https://portal.qiniu.com/ai-inference/api-key)** 界面
2. 点击 &#x2A;*【限额】** 进入限额配置界面
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/2-apikey-use-limit-api/FkmphyPDSllnIGGX5FTvbgNBdFWf-a3a529b58173.webp)
3. 支持 **日限额**、**月限额**、**总限额**，您可以根据自身需求开启所需限额类型，然后设置 **额度** 和 **告警阈值*&#x2A;，点击 &#x2A;*【确定】** ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/2-apikey-use-limit-api/FjSqdSX7oFeBsJIkDiluJLoZkxr1-d812e645bbd5.webp)

<br />

### **说明** [#说明]

1. **日限额：** 设置每日最大消费金额，每日零点自动重置
2. **月限额：** 设置每月最大消费金额，每月 1 号零点自动重置
3. **总限额：** 设置累计最大消费金额，达到后永久停止直到手动调整
4. **若同时开启多项限额：** 其中任一限额达到即会停止服务并发送通知，为不影响正常使用，建议您根据业务波动合理设置。
5. 必须在 &#x2A;*[消息中心](https://portal.qiniu.com/notification/user-setting/basic/finance)** 设置您的通知方式以及接收人，否则我们将无法向您发送告警通知！
   ![image.png](/docs-assets/products/aitokenapi/%282-user-guide%29/apikey-use-api/2-apikey-use-limit-api/Fpjb7ar-QxhZjzLzy8Xcc5v6-jyA-360c10357126.webp)


# 视频生成 (kling系列) (/products/aitokenapi/audio-video-api/0-new-video-generate-kling-api)



最近更新时间: 2026-04-29 16:37:40

七牛云 AI 大模型推理 API 支持可灵（Kling）系列视频生成模型，提供文生视频（Text-to-Video）、图生视频（Image-to-Video）和视频生视频（Video-to-Video）等多种高级功能，兼容 OpenAI Videos API 接口格式，方便您集成到各种业务和应用场景中。

## 可灵模型核心特点 [#可灵模型核心特点]

* **高清分辨率**: 最高支持 **1080P** (1920x1080) 高清视频输出
* **灵活时长**: 支持生成 **5秒** 或 **10秒** 视频
* **多种生成方式**:
  * 文生视频 (Text-to-Video): 根据文本描述生成视频
  * 图生视频 (Image-to-Video): 基于参考图片生成动态视频
  * 视频生视频 (Video-to-Video): 基于参考视频生成新视频
  * 参考首尾帧生视频: 指定首尾关键帧，AI 补充中间过渡
* **无声视频**: 生成的视频默认为无声视频（除非使用视频生视频功能并设置保留原声）

# 接口说明 [#接口说明]

## **Token API 接入点** [#token-api-接入点]

七牛云 AI 大模型推理 API 接入域名：

* **接入点**: `https://api.qnaigc.com/v1`
* 使用前提：[获取 API KEY(API 密钥)](/products/aitokenapi/0-how-to-get-api-key)

## 支持接口列表 [#支持接口列表]

| 接口名         | 说明                                |
| ----------- | --------------------------------- |
| /videos     | 视频创建接口，支持文生视频、图生视频、视频生视频和参考首尾帧生视频 |
| /videos/:id | 查询视频生成状态接口，根据视频任务 ID 查询生成进度和结果    |

## 支持的模型 [#支持的模型]

| 模型 ID            | 模型名称          | 说明                                                                                                         | 状态    |
| ---------------- | ------------- | ---------------------------------------------------------------------------------------------------------- | ----- |
| kling-video-o1   | 可灵 O1         | 可灵最新推出的高性能视频生成模型<br />**特点**: 最新旗舰模型，支持文生视频、图生视频、视频生视频、参考首尾帧生视频全功能<br />**输出**: 支持 std(720P)/pro(1080P) 模式 | ✅ 已上线 |
| kling-v2-1       | 可灵 V2.1       | 可灵 V2.1 视频生成模型<br />**特点**: 支持图生视频及参考首尾帧生成，**不支持文生视频**<br />**输出**: 支持 std(720P)/pro(1080P) 模式             | ✅ 已上线 |
| kling-v2-5-turbo | 可灵 V2.5 Turbo | 可灵 V2.5 Turbo 视频生成模型<br />**特点**: 支持文生视频、图生视频、视频生视频、参考首尾帧生视频全功能<br />**输出**: 支持 std(720P)/pro(1080P) 模式    | ✅ 已上线 |

***

# 请求参数说明 [#请求参数说明]

## 创建视频接口 (POST /videos) [#创建视频接口-post-videos]

**接口说明**: 创建视频生成任务，提交后会返回任务 ID，您需要使用查询接口轮询任务状态并获取生成的视频。

### Header 参数 [#header-参数]

| 参数名           | 类型     | 必填 | 说明                                     |
| ------------- | ------ | -- | -------------------------------------- |
| Authorization | string | 是  | API Key，格式：`Bearer YOUR_QINIU_API_KEY` |
| Content-Type  | string | 是  | 请求内容类型，固定值：`application/json`          |

### Body 参数 (JSON) [#body-参数-json]

| 参数名              | 类型     | 必填 | 默认值       | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | 支持模型                            |
| ---------------- | ------ | -- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
| model            | string | 是  | -         | 视频生成模型名称，例如：`kling-video-o1`<br />**详细说明**：<br />• 指定使用的视频生成模型<br />• 可选值：`kling-video-o1`、`kling-v2-1`、`kling-v2-5-turbo`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | 全部                              |
| prompt           | string | 是  | -         | 视频生成的文本描述提示词，最大 2500 字符<br />**详细说明**：<br />• 字符数限制：不超过 2500 个字符<br />• 建议：提示词越详细、具体，生成的视频质量越好<br />• 建议包含：场景描述、动作、风格、光线、氛围等细节<br />• 示例：`"一只橘色的猫坐在窗台上,温暖的阳光洒在它身上,它慢慢转头看向镜头,电影风格,高清画质"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | 全部                              |
| input\_reference | string | 是  | -         | 参考图像<br />**详细说明**：<br />• **支持传入图片 Base64 编码或图片 URL**（确保可访问）<br />• **Base64 编码格式要求**：<br />  - 若使用 Base64 方式，请确保所有图像数据参数均采用 Base64 编码格式<br />  - 请**不要在 Base64 编码字符串前添加任何前缀**（如 `data:image/png;base64,`）<br />  - 正确格式应该直接是 Base64 编码后的字符串<br />  - ✅ 正确示例：`iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==`<br />  - ❌ 错误示例：`data:image/png;base64,iVBORw0KGgoAAAA...`<br />• **图片格式支持**：`.jpg` / `.jpeg` / `.png`<br />• **图片要求**：<br />  - 文件大小：不能超过 10MB\<br>  - 图片尺寸：宽高不小于 300px\<br>  - 图片宽高比：介于 1:2.5 \~ 2.5:1 之间<br />• 不同模型版本、视频模式支持范围不同，详见[可灵模型能力地图](https://app.klingai.com/cn/dev/document-api/apiReference/model/skillsMap)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | kling-v2-1\<br>kling-v2-5-turbo |
| image\_tail      | string | 否  | -         | 参考图像 - 尾帧控制<br />**详细说明**：<br />• **支持传入图片 Base64 编码或图片 URL**（确保可访问）<br />• **Base64 编码格式要求**：<br />  - 若使用 Base64 方式，请确保所有图像数据参数均采用 Base64 编码格式<br />  - 请**不要在 Base64 编码字符串前添加任何前缀**（如 `data:image/png;base64,`）<br />  - 正确格式应该直接是 Base64 编码后的字符串<br />  - ✅ 正确示例：`iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==`<br />  - ❌ 错误示例：`data:image/png;base64,iVBORw0KGgoAAAA...`<br />• **图片格式支持**：`.jpg` / `.jpeg` / `.png`<br />• **图片要求**：<br />  - 文件大小：不能超过 10MB\<br>  - 图片尺寸：宽高不小于 300px\<br>• **首尾帧控制说明**：<br />  - 当同时配置 `input_reference` 和 `image_tail` 参数时，表示控制首尾帧生视频<br />  - **此时 `mode` 参数仅支持 `pro` 模式**（不支持 `std` 模式）<br />  - 系统将根据首帧和尾帧图片生成连贯过渡的视频<br />• 不同模型版本、视频模式支持范围不同，详见[可灵模型能力地图](https://app.klingai.com/cn/dev/document-api/apiReference/model/skillsMap)                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | kling-v2-1\<br>kling-v2-5-turbo |
| image\_list      | array  | 否  | 空         | 参考图列表<br />**详细说明**：<br />• **功能说明**：<br />  - 包括主体、场景、风格等参考图片<br />  - 也可作为首帧或尾帧生成视频<br />• **首帧/尾帧功能**：<br />  - 通过 `type` 参数来定义图片是否为首尾帧：`first_frame` 为首帧，`end_frame` 为尾帧<br />  - **暂时不支持仅尾帧**，即有尾帧图时必须有首帧图<br />  - 首帧或首尾帧生视频时，不能使用视频编辑功能<br />  - 数组中超过 2 张图片时，不支持设置尾帧<br />• **参数格式**：JSON 数组，每个元素包含 `image_url` 和可选的 `type` 字段<br />• **参数示例**：<br />  - 普通参考图：`"image_list": [{"image": "image_url_or_base64"}]`<br />  - 首尾帧参考：`"image_list": [{"image": "image_url_or_base64", "type": "first_frame"}, {"image": "image_url_or_base64", "type": "end_frame"}]`<br />• **支持传入图片 Base64 编码或图片 URL**（确保可访问）<br />• **Base64 编码格式要求**：<br />  - 若使用 Base64 方式，请确保所有图像数据参数均采用 Base64 编码格式<br />  - 请**不要在 Base64 编码字符串前添加任何前缀**（如 `data:image/png;base64,`）<br />  - 正确格式应该直接是 Base64 编码后的字符串<br />  - ✅ 正确示例：`"image_list": [{"image_url": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="}]`<br />  - ❌ 错误示例：`"image_list": [{"image_url": "data:image/png;base64,iVBORw0KGgoAAAA..."}]`<br />• **图片格式支持**：`.jpg` / `.jpeg` / `.png`<br />• **图片要求**：<br />  - 文件大小：不能超过 10MB\<br>  - 图片尺寸：宽高不小于 300px\<br>  - 图片宽高比：介于 1:2.5 \~ 2.5:1 之间<br />  - `image_url` 参数值不得为空<br />• **数量限制**：<br />  - 有参考视频时：参考图片数量不得超过 4 张<br />  - 无参考视频时：参考图片数量不得超过 7 张 | kling-video-o1                  |
| video\_list      | array  | 否  | -         | 参考视频列表<br />**详细说明**：<br />• 参考视频，通过 URL 方式提供<br />• 参考视频可作为特征参考视频，也可作为待编辑视频（默认为待编辑视频）；可选择性保留视频原声<br />• 通过 `refer_type` 参数区分参考视频类型：<br />  - `feature`：特征参考视频，用于指导视频风格和内容<br />  - `base`：待编辑视频，基于此视频进行编辑和生成<br />• 当参考视频为待编辑视频时，不能定义视频首尾帧<br />• 通过 `keep_original_sound` 参数选择是否保留视频原声：<br />  - `yes`：保留原视频声音<br />  - `no`：不保留原视频声音<br />  - 当前参数对特征参考视频（feature）也生效<br />• **格式要求**：<br />  - 视频格式：仅支持 MP4 和 MOV\<br>  - 视频时长：≥3 秒且 ≤10 秒<br />  - 视频尺寸：宽高均需介于 720px（含）和 2160px（含）之间<br />  - 视频帧率：24fps～60fps，生成视频时会输出为 24fps\<br>  - 视频大小：单个视频不超过 200MB\<br>  - `video_url` 参数值不得为空<br />• **数量限制**：至多仅支持上传 1 段视频<br />• **参数示例**：`"video_list": [{"video_url": "https://example.com/reference-video.mp4", "refer_type": "base", "keep_original_sound": "yes"}]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | kling-video-o1                  |
| seconds          | string | 否  | 5         | 视频时长（秒），可选值：`5`、`10`<br />**详细说明**：<br />• 控制生成视频的时长（单位：秒）<br />• 不同时长会影响生成成本和时间                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | 全部                              |
| size             | string | 否  | 1920x1080 | 视频分辨率，格式：`宽x高`<br />可选值：`1920x1080`、`1080x1920`、`1280x720`、`720x1280`、`1080x1080`、`720x720`<br />**详细说明**：<br />• 该字段仅能控制视频的宽高比例（横屏/竖屏/正方形），视频分辨率品质由 `mode` 字段控制<br />• 作用：主要用于判断横竖屏方向<br />  - 宽 > 高：横屏<br />  - 宽 \< 高：竖屏<br />  - 宽 = 高：正方形                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | 全部                              |
| mode             | string | 否  | std       | 生成视频的模式<br />可选值：`std`、`pro`<br />`std`：标准模式（标准），基础模式，性价比高，输出分辨率为 **720P**<br />`pro`：专家模式（高品质），高表现模式，生成视频质量更佳，输出分辨率为 **1080P**<br />不同品质会影响生成成本和时间                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | 全部                              |

### 响应体说明 [#响应体说明]

创建视频任务成功后，接口会立即返回任务基本信息。接口返回已创建的视频任务基本信息，包含任务 ID、模型、状态等字段。视频尚未生成完成，需要通过查询接口获取最终结果。响应体包含以下字段：

| 字段名         | 类型      | 说明                            |
| ----------- | ------- | ----------------------------- |
| id          | string  | 视频任务唯一 ID，用于后续查询任务状态          |
| object      | string  | 对象类型，固定为 `video`              |
| model       | string  | 使用的模型名称，例如 `kling-video-o1`   |
| mode        | string  | 生成模式，`std`（标准模式）或 `pro`（专家模式） |
| status      | string  | 任务状态，通常为 `queued`（排队中）        |
| created\_at | integer | 创建时间（Unix 时间戳，秒）              |
| updated\_at | integer | 更新时间（Unix 时间戳，秒）              |
| seconds     | string  | 视频时长（秒）                       |
| size        | string  | 请求体中的视频分辨率（宽 x 高）             |

**响应示例：**

```json
{
    "id": "qvideo-user123-1766391125174150336",
    "object": "video",
    "model": "kling-video-o1",
    "mode": "std",
    "status": "queued",
    "created_at": 1766391125,
    "updated_at": 1766391125,
    "seconds": "5",
    "size": "1280x720"
}
```

## 查询视频状态接口 (GET /videos/:id) [#查询视频状态接口-get-videosid]

**接口说明**: 根据视频任务 ID 查询视频生成状态和结果，建议定期轮询直到状态变为 `completed` 或 `failed`。

### Path 参数 [#path-参数]

| 参数名 | 类型     | 必填 | 说明                                                               |
| --- | ------ | -- | ---------------------------------------------------------------- |
| id  | string | 是  | 视频任务 ID，创建视频时返回的 `id` 字段，例如：`qvideo-user123-1766391125174150336` |

### Header 参数 [#header-参数-1]

| 参数名           | 类型     | 必填 | 说明                                     |
| ------------- | ------ | -- | -------------------------------------- |
| Authorization | string | 是  | API Key，格式：`Bearer YOUR_QINIU_API_KEY` |

### 响应体说明 [#响应体说明-1]

根据任务状态不同，返回的字段也有所不同。任务完成后会包含 `task_result` 字段,其中包含生成的视频下载链接。

| 字段名                             | 类型      | 说明                                |
| ------------------------------- | ------- | --------------------------------- |
| id                              | string  | 视频任务唯一 ID                         |
| object                          | string  | 对象类型,固定为 `video`                  |
| model                           | string  | 使用的模型名称                           |
| mode                            | string  | 生成模式,`std` 或 `pro`,仅在成功时返回        |
| status                          | string  | 任务状态,见下方状态说明                      |
| created\_at                     | integer | 创建时间 (Unix 时间戳,秒)                 |
| updated\_at                     | integer | 更新时间 (Unix 时间戳,秒)                 |
| completed\_at                   | integer | 完成时间 (Unix 时间戳,秒),仅在已完成或失败时返回     |
| seconds                         | string  | 视频时长 (秒)                          |
| size                            | string  | 视频分辨率 (宽 x 高)                     |
| task\_result                    | object  | 任务结果,包含生成的视频列表,仅在已完成时返回           |
| task\_result.videos             | array   | 生成的视频列表                           |
| task\_result.videos\[].id       | string  | 视频 ID,全局唯一                        |
| task\_result.videos\[].url      | string  | 视频下载 URL(注意:生成的视频会在 7 天后过期,请及时转存) |
| task\_result.videos\[].duration | string  | 视频时长 (秒)                          |
| error                           | object  | 错误信息,仅在失败时返回                      |
| error.code                      | string  | 错误码                               |
| error.message                   | string  | 错误描述                              |

### 任务状态说明 [#任务状态说明]

| 状态值          | 说明             |
| ------------ | -------------- |
| initializing | 初始化中,任务已创建     |
| queued       | 排队中,等待处理       |
| in\_progress | 处理中,模型正在生成视频   |
| downloading  | 下载中,正在下载结果     |
| uploading    | 上传中,正在上传到七牛云存储 |
| completed    | 已完成,视频生成成功     |
| failed       | 失败,视频生成失败      |
| cancelled    | 已取消,用户主动取消     |

### 响应示例 [#响应示例]

#### 处理中状态 [#处理中状态]

```json
{
  "id": "qvideo-user123-1234567890123456789",
  "object": "video",
  "model": "kling-video-o1",
  "status": "in_progress",
  "created_at": 1234567890,
  "updated_at": 1234567895
}
```

#### 成功完成状态 [#成功完成状态]

```json
{
  "id": "qvideo-user123-1766391125174150336",
  "object": "video",
  "model": "kling-video-o1",
  "mode": "std",
  "status": "completed",
  "created_at": 1766391125,
  "updated_at": 1766391255,
  "completed_at": 1766391255,
  "seconds": "5",
  "size": "1280x720",
  "task_result": {
    "videos": [
      {
        "id": "qvideo-user123-1766391125174150336-1",
        "url": "https://aitoken-video.qnaigc.com/user123/qvideo-user123-1766391125174150336/1.mp4?e=1766996055&token=IDB69r4gicDbMd9Fbmn9w2bWuEENg9i5_yasXqhp:SxmElNSeeug5RahcQ5sSdCTxwPw=",
        "duration": "5"
      }
    ]
  }
}
```

#### 失败状态 [#失败状态]

```json
{
  "id": "qvideo-user123-1234567890123456789",
  "object": "video",
  "model": "kling-video-o1",
  "mode": "std",
  "status": "failed",
  "created_at": 1765776987,
  "updated_at": 1765776990,
  "completed_at": 1765776990,
  "error": {
      "code": "kling_error",
      "message": "Kling API returned error"
  },
  "seconds": "5"
}
```

***

# HTTP 调用示例 [#http-调用示例]

## **基础文生视频 (kling-video-o1)** [#基础文生视频-kling-video-o1]

使用 kling-video-o1 模型生成高分辨率 1080P 视频：

```bash
# 调用 kling-video-o1 文生视频 API
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/videos" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "kling-video-o1",
        "prompt": "一只可爱的橘猫在阳光下奔跑，慢镜头，电影质感",
        "size": "1920x1080",
        "mode": "pro"
    }'
```

**响应示例：**

```json
{
    "id": "qvideo-user123-1764904843275618838",
    "object": "video",
    "model": "kling-video-o1",
    "mode": "pro",
    "status": "queued",
    "created_at": 1764904843,
    "updated_at": 1764904843,
    "seconds": "5",
    "size": "1920x1080"
}
```

<a href="https://aitoken-public.qnaigc.com/example/generate-video/kling-video-o1-text-to-video.mp4" target="_blank">
  点击查看生成的视频
</a>

## **图生视频 (kling-video-o1)** [#图生视频-kling-video-o1]

使用 kling-video-o1 模型基于参考图片生成视频：

```bash
# 基于参考图片生成视频
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 API KEY>"

curl "$OPENAI_BASE_URL/videos" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "kling-video-o1",
        "prompt": "这个人在跑马拉松",
        "image_list": [
            {
                "image": "https://aitoken-public.qnaigc.com/example/generate-video/running-man.jpg"
            }
        ],
        "size": "1920x1080",
        "mode": "pro"
    }'
```

<a href="https://aitoken-public.qnaigc.com/example/generate-video/kling-video-o1-image-to-video.mp4" target="_blank">
  点击查看生成的视频
</a>

## **有参考视频生成视频 (kling-video-o1)** [#有参考视频生成视频-kling-video-o1]

使用 kling-video-o1 模型基于参考视频生成新视频：

```bash
# 基于参考视频生成新视频
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/videos" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "kling-video-o1",
        "prompt": "画面中增加一个小狗",
        "video_list": [
            {
                "video_url": "https://aitoken-public.qnaigc.com/example/generate-video/the-little-dog-is-running-on-the-lawn..mp4",
                "refer_type": "feature",
                "keep_original_sound": "yes"
            }
        ],
        "size": "1920x1080",
        "mode": "pro"
    }'
```

<a href="https://aitoken-public.qnaigc.com/example/generate-video/the-little-dog-is-running-on-the-lawn-result.mp4" target="_blank">
  点击查看生成的视频
</a>

## **多图首尾帧生视频 (kling-video-o1)** [#多图首尾帧生视频-kling-video-o1]

使用 kling-video-o1 模型的 `image_list` 参数，通过指定首帧和尾帧图片生成连贯视频：

```bash
# 基于首尾帧图片生成视频
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/videos" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "kling-video-o1",
        "prompt": "视频连贯在一起",
        "image_list": [
            {
                "image": "https://fastly.picsum.photos/id/173/1280/720.jpg?hmac=xH_ViV5QGlLeWARvoUE2frSLNcUXvAGKHaMs0Hy6c_0",
                "type": "first_frame"
            },
            {
                "image": "https://fastly.picsum.photos/id/999/1280/720.jpg?hmac=YPLs2sdukTxfP4z7CI7wNIWwNXYksSjUi1yENuaT-RI",
                "type": "end_frame"
            }
        ],
        "size": "1920x1080",
        "mode": "pro"
    }'
```

<a href="https://aitoken-public.qnaigc.com/example/generate-video/kling-video-o1-first-end-frame.mp4" target="_blank">
  点击查看生成的视频
</a>

## **图生视频 (kling-v2-1)** [#图生视频-kling-v2-1]

使用 kling-v2-1 模型基于参考图片生成视频：

```bash
# 基于参考图片生成视频
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 API KEY>"

curl "$OPENAI_BASE_URL/videos" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "kling-v2-1",
        "prompt": "人在奔跑",
        "input_reference":"https://aitoken-public.qnaigc.com/example/generate-video/running-man.jpg",
        "size": "1280x720",
        "mode": "pro"
      }'
```

<a href="https://aitoken-public.qnaigc.com/example/generate-video/kling-v2-1-image-to-video.mp4" target="_blank">
  点击查看生成的视频
</a>

## **图生视频 (kling-v2-5-turbo) - 指定尾帧** [#图生视频-kling-v2-5-turbo---指定尾帧]

使用 kling-v2-5-turbo 模型生成视频，并指定尾帧图片：

```bash
# 指定尾帧图生视频
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 API KEY>"

curl "$OPENAI_BASE_URL/videos" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d'{
        "model": "kling-v2-5-turbo",
        "prompt": "人在跑到了天涯海角",
        "input_reference":"https://aitoken-public.qnaigc.com/example/generate-video/running-man.jpg",
        "image_tail":"https://aitoken-public.qnaigc.com/example/generate-video/end-of-the-earth-and-sky.jpg",
        "size": "1280x720",
        "mode": "pro"
    }'
```

<a href="https://aitoken-public.qnaigc.com/example/generate-video/kling-v2-5-turbo-image-to-video.mp4" target="_blank">
  点击查看生成的视频
</a>

## **查询视频生成状态** [#查询视频生成状态]

```bash
# 查询视频任务状态
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"
export VIDEO_ID="qvideo-user123-1234567890123456789"

curl "$OPENAI_BASE_URL/videos/$VIDEO_ID" \
    -H "Authorization: Bearer $OPENAI_API_KEY"
```

**响应示例 (处理中):**

```json
{
  "id": "qvideo-user123-1234567890123456789",
  "object": "video",
  "model": "kling-video-o1",
  "status": "in_progress",
  "created_at": 1234567890,
  "updated_at": 1234567895
}
```

**响应示例 (已完成):**

```json
{
  "id": "qvideo-user123-1234567890123456789",
  "object": "video",
  "model": "kling-video-o1",
  "mode": "std",
  "status": "completed",
  "created_at": 1766391125,
  "updated_at": 1766391255,
  "completed_at": 1766391255,
  "seconds": "5",
  "size": "1280x720",
  "task_result": {
    "videos": [
      {
        "id": "qvideo-user123-1234567890123456789-1",
        "url": "https://aitoken-video.qnaigc.com/root/qvideo-user123-1234567890123456789/1.mp4?e=1766996055&token=IDB69r4gicDbMd9Fbmn9w2bWuEENg9i5_yasXqhp:SxmElNSeeug5RahcQ5sSdCTxwPw=",
        "duration": "5"
      }
    ]
  }
}
```

**响应示例 (错误):**

```json
{
  "id": "qvideo-user123-1234567890123456789",
  "object": "video",
  "model": "kling-video-o1",
  "mode": "std",
  "status": "failed",
  "created_at": 1765776987,
  "updated_at": 1765776990,
  "completed_at": 1765776990,
  "error": {
      "code": "kling_error",
      "message": "Kling API returned error"
  },
  "seconds": "5"
}
```

***

# 常见问题 [#常见问题]

**Q: 如何将生成的视频保存到七牛云对象存储？**

A: 生成的视频已经自动保存在七牛云对象存储 (Kodo) 中，返回的 URL 即为 Kodo 存储地址，但有效期**仅有 7 天**。如需转存到您自己的存储空间，推荐使用七牛对象存储的【[SDK 中心](/sdk-tools/sdk#official-sdk)】进行操作。更多对象存储信息欢迎参考对象存储的【[产品使用文档](/products/kodo/rs/8-upload)】。

**Q: 视频生成需要多长时间？**

A: 视频生成时间取决于视频时长和当前队列情况。通常情况下：

* 5 秒视频：2-5 分钟
* 10 秒视频：5-10 分钟

建议使用轮询方式查询任务状态。

**Q: 生成的视频会保存多久？**

A: 生成的视频**会在 7 天后过期**，建议在视频生成后及时下载或转存到您自己的存储空间。

**Q: 如何提高视频生成质量？**

A:

* **详细的提示词**：描述越详细，生成效果越好
* **包含关键要素**：场景、动作、风格、光线、氛围等
* **使用具体的风格描述**：如"电影风格"、"高清画质"等

**Q: kling 模型的具体能力和参数有什么区别？**

A: 更多详细的模型能力对比和参数说明，可参考 [可灵官方文档](https://app.klingai.com/cn/dev/document-api/apiReference/model/skillsMap)。

# 参考文档 [#参考文档]

* [AI 大模型推理产品介绍](https://www.qiniu.com/ai)
* [AI 大模型推理模型广场](https://www.qiniu.com/ai/models)
* [实时推理请求 API 接入说明](/products/aitokenapi/inference-api/1-real-time-ai-interface-api)
* [文生图 API 接入说明](https://apidocs.qnaigc.com/396977229e0)


# 图片生成 (kling系列) (/products/aitokenapi/image-api/13385-new-image-generate-kling-api)



最近更新时间: 2026-09-17 15:15:44

七牛云 AI 大模型推理 API 支持 Kling 系列模型的图像生成功能，包括文生图（Text-to-Image）和图生图（Image-to-Image），兼容 OpenAI Images API 接口格式，方便您集成到各种业务和应用场景中。

## Kling 模型核心特点 [#kling-模型核心特点]

* **异步接口**: Kling 模型采用异步调用方式，提交任务后返回 task\_id，需要轮询查询任务状态
* **多版本支持**: 支持 v1、v1.5、v2、v2-new、v2.1 等多个版本
* **丰富比例**: 支持多种宽高比例（16:9、9:16、1:1、4:3、3:4 等）
* **高级参考**: 支持多种参考图片类型
  * **角色特征参考**: 保留角色整体特征（服装、姿态、身体特征），适合保持角色形象一致性
  * **人物长相参考**: 重点保留人物面部特征（五官、表情），要求图片仅含1张人脸
  * **主体参考**: 提供主体角色/物体的特征参考，支持2-4张图片综合生成
  * **场景参考**: 保留空间结构、环境氛围、光影关系等场景元素
  * **风格参考**: 提供艺术风格、绘画技法、色调、质感等视觉风格参考
* **URL 返回格式**: 接口返回的图片是 URL 而不是 Base64 编码，有效期为 7 天
* **多种功能**:
  * 文生图 (Text-to-Image): 根据文本描述生成图像
  * 单图生图 (Single Image-to-Image): 基于单张参考图片进行编辑和改造
  * 多图生图 (Multi Image-to-Image): 基于多张参考图片(2-4张)进行综合生成
  * 负向提示词: 支持指定不希望出现的内容
  * 参考强度控制: 支持调节参考图片的影响强度

# 接口说明 [#接口说明]

## **Token API 接入点** [#token-api-接入点]

七牛云 AI 大模型推理 API 接入域名：

* **接入点**: `https://api.qnaigc.com/v1`
* 使用前提：[获取 API KEY(API 密钥)](/products/aitokenapi/0-how-to-get-api-key)

## 支持接口列表 [#支持接口列表]

| 接口名                     | 说明                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| /images/generations     | 文生图/单图生图接口<br />• 文生图：根据文本描述生成图像<br />• 单图生图：基于单张参考图片和文本描述生成新的图像<br />返回格式：task\_id（任务 ID） |
| /images/edits           | 多图生图接口，基于多张参考图片（2-4张）和文本描述生成新的图像<br />返回格式：task\_id（任务 ID）                                 |
| /images/tasks/:task\_id | 查询图像生成任务状态接口，根据任务 ID 查询生成进度和结果                                                             |

## 支持的模型 [#支持的模型]

| 模型 ID        | 模型名称         | 说明                          | 状态    |
| ------------ | ------------ | --------------------------- | ----- |
| kling-v1     | Kling v1     | 文生图 V1.0 模型                 | ✅ 已上线 |
| kling-v1-5   | Kling v1.5   | 文生图 V1.5 模型，支持角色特征参考和人物长相参考 | ✅ 已上线 |
| kling-v2     | Kling v2     | 文生图 V2.0 系列模型，支持图生图功能       | ✅ 已上线 |
| kling-v2-new | Kling v2-new | 文生图 V2.0 系列模型               | ✅ 已上线 |
| kling-v2-1   | Kling v2.1   | 文生图 V2.1 系列模型               | ✅ 已上线 |

***

# 请求参数说明 [#请求参数说明]

## 文生图/单图生图接口 (POST /images/generations) [#文生图单图生图接口-post-imagesgenerations]

**接口说明**: 创建文生图或单图生图任务，提交后会返回任务 ID（task\_id），您需要使用查询接口轮询任务状态并获取生成的图像。

**使用场景**:

* **文生图**：不传 `image` 参数，仅使用 `prompt` 生成图像
* **单图生图**：传入 `image` 参数（单张参考图片），基于该图片和 `prompt` 生成新图像

### Header 参数 [#header-参数]

| 参数名           | 类型     | 必填 | 说明                               |
| ------------- | ------ | -- | -------------------------------- |
| Authorization | string | 是  | API Key，格式：`Bearer YOUR_API_KEY` |
| Content-Type  | string | 是  | 请求内容类型，固定值：`application/json`    |

### Body 参数 (JSON) [#body-参数-json]

| 参数名              | 类型      | 必填 | 默认值  | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------- | ------- | -- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| model            | string  | 是  | -    | 图像生成模型名称<br />**详细说明**：<br />• 可选值：`kling-v1`、`kling-v1-5`、`kling-v2`、`kling-v2-new`、`kling-v2-1`<br />• 不同版本支持的参数和功能可能有所不同                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| prompt           | string  | 是  | -    | 图像生成的文本描述提示词<br />**详细说明**：<br />• 字符数限制：不超过 2500 个字符<br />• 建议：提示词越详细、具体，生成的图像质量越好<br />• 建议包含：风格、光线、构图、色彩等细节<br />• 使用逗号分隔不同的描述要素<br />• 示例：`"一只橘色的猫，坐在窗台上，温暖的阳光，柔和的阴影，专业摄影，高清画质"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| n                | integer | 否  | 1    | 生成图像数量，取值范围：1-10\<br>**详细说明**：<br />• 控制一次请求生成的图像数量<br />• 注意：生成多张图片会消耗更多费用                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| negative\_prompt | string  | 否  | -    | 负向文本提示词<br />**详细说明**：<br />• 用于指定不希望在生成图像中出现的内容<br />• 字符数限制：不超过 2500 个字符<br />• **注意**：图生图场景下（image 字段不为空时）不支持负向提示词                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| image            | string  | 否  | -    | 参考图像（单图生图时使用）<br />**详细说明**：<br />• &#x2A;*支持传入图片 Base64 编码或图片 URL（确保可访问）**<br />• 若使用 Base64 方式，请确保所有图像数据参数均采用 Base64 编码格式<br />• 提交 Base64 编码数据时，**不要**添加任何前缀（如 `data:image/png;base64,`），直接传递 Base64 编码字符串<br />• **正确示例**：`iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==`<br />• **错误示例**：`data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==`<br />• 图片格式支持：.jpg / .jpeg / .png\<br>• 图片文件大小不能超过 10MB\<br>• 图片宽高尺寸不小于 300px\<br>• 图片宽高比要在 1:2.5 \~ 2.5:1 之间<br />• **注意**：进行单图生图时，此参数必填；仅文生图时不传此参数<br />• 对于 `kling-v1-5` 模型，当使用此参数时，`image_reference` 参数也必须同时传入 |
| image\_reference | string  | 否  | -    | 图片参考类型<br />**详细说明**：<br />• 枚举值：`subject`（角色特征参考）、`face`（人物长相参考）<br />• 使用 `face`（人物长相参考）时，上传图片需仅含 1 张人脸<br />• 仅 `kling-v1-5` 支持当前参数<br />• 使用 `kling-v1-5` 且 `image` 参数不为空时，当前参数必填                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| image\_fidelity  | float   | 否  | 0.5  | 生成过程中对用户上传图片的参考强度<br />**详细说明**：<br />• 取值范围：\[0, 1]\<br>• 数值越大，参考强度越大<br />• 控制生成图像与参考图像的相似程度                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| human\_fidelity  | float   | 否  | 0.45 | 面部参考强度，即参考图中人物五官相似度<br />**详细说明**：<br />• 仅 `image_reference` 参数为 `subject` 时生效<br />• 取值范围：\[0, 1]\<br>• 数值越大，参考强度越大                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| aspect\_ratio    | string  | 否  | 16:9 | 生成图片的画面纵横比（宽:高）<br />**详细说明**：<br />• 枚举值：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3`、`21:9`<br />• 控制生成图像的宽高比例                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

### 响应体说明 [#响应体说明]

创建文生图任务成功后，接口会立即返回任务 ID。图像尚未生成完成，需要通过查询接口获取最终结果。响应体包含以下字段：

| 字段名      | 类型     | 说明                     |
| -------- | ------ | ---------------------- |
| task\_id | string | 图像生成任务唯一 ID，用于后续查询任务状态 |

**响应示例：**

```json
{
  "task_id": "chatimage-1762159125266058362-user123"
}
```

## 多图生图接口 (POST /images/edits) [#多图生图接口-post-imagesedits]

**接口说明**: 创建多图生图任务，基于多张参考图像（2-4张）和文本描述生成新的图像。提交后会返回任务 ID（task\_id），您需要使用查询接口轮询任务状态并获取生成的图像。

**使用场景**:

* 基于 2-4 张参考图片进行综合生成
* 支持使用 `subject_image_list`、`scene_image`、`style_image` 等多种参考图片类型

### Header 参数 [#header-参数-1]

| 参数名           | 类型     | 必填 | 说明                               |
| ------------- | ------ | -- | -------------------------------- |
| Authorization | string | 是  | API Key，格式：`Bearer YOUR_API_KEY` |
| Content-Type  | string | 是  | 请求内容类型，固定值：`application/json`    |

### Body 参数 (JSON) [#body-参数-json-1]

| 参数名                  | 类型      | 必填 | 默认值  | 说明                                                                                                                                                                                                                 |
| -------------------- | ------- | -- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| model                | string  | 是  | -    | 图像生成模型名称<br />**详细说明**：<br />• 支持多图生图的模型：`kling-v1`、`kling-v1-5`、`kling-v2`、`kling-v2-new`、`kling-v2-1`                                                                                                            |
| image                | string  | 是  | -    | 输入图像 URL\<br>**详细说明**：<br />• **注意**：多图生图场景下此参数必填，但**可以传空字符串**，实际图像通过 `subject_image_list` 等参数指定<br />• 如果直接提供图像 URL，必须是公开可访问的链接                                                                                   |
| prompt               | string  | 是  | -    | 图像编辑的文本描述提示词<br />**详细说明**：<br />• 清晰描述期望的编辑效果<br />• 包含风格、色彩、构图等具体细节<br />• 字符数限制：不超过 2500 个字符                                                                                                                    |
| n                    | integer | 否  | 1    | 生成图像数量，取值范围：1-10\<br>**详细说明**：<br />• 控制一次请求生成的图像数量<br />• 注意：生成多张图片会消耗更多费用                                                                                                                                        |
| subject\_image\_list | array   | 否  | -    | 多图生图的参考图片列表<br />**详细说明**：<br />• **最多支持 4 张图片，最少支持 2 张图片**<br />• 每个元素包含 `subject_image` 字段（图片 URL）<br />• 图片格式支持：.jpg / .jpeg / .png\<br>• 图片文件大小不能超过 10MB\<br>• 图片宽高尺寸不小于 300px\<br>• 图片宽高比要在 1:2.5 \~ 2.5:1 之间 |
| scene\_image         | string  | 否  | -    | 场景参考图 URL\<br>**详细说明**：<br />• 内容为可公开访问的 URL 链接<br />• 图片格式支持：.jpg / .jpeg / .png\<br>• 图片文件大小不能超过 10MB\<br>• 图片宽高尺寸不小于 300px\<br>• 图片宽高比要在 1:2.5 \~ 2.5:1 之间                                                      |
| style\_image         | string  | 否  | -    | 风格参考图 URL\<br>**详细说明**：<br />• 内容为可公开访问的 URL 链接<br />• 图片格式支持：.jpg / .jpeg / .png\<br>• 图片文件大小不能超过 10MB\<br>• 图片宽高尺寸不小于 300px\<br>• 图片宽高比要在 1:2.5 \~ 2.5:1 之间                                                      |
| aspect\_ratio        | string  | 否  | 16:9 | 生成图片的画面纵横比（宽:高）<br />**详细说明**：<br />• 枚举值：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3`、`21:9`<br />• 控制生成图像的宽高比例                                                                                                    |

### 响应体说明 [#响应体说明-1]

创建图生图任务成功后，接口会立即返回任务 ID。图像尚未生成完成，需要通过查询接口获取最终结果。响应格式与文生图接口相同：

| 字段名      | 类型     | 说明                     |
| -------- | ------ | ---------------------- |
| task\_id | string | 图像生成任务唯一 ID，用于后续查询任务状态 |

**响应示例：**

```json
{
  "task_id": "chatimage-1762159125266058362-user123"
}
```

## 查询任务状态接口 (GET /images/tasks/:task\_id) [#查询任务状态接口-get-imagestaskstask_id]

**接口说明**: 根据任务 ID 查询图像生成状态和结果，建议定期轮询直到状态变为 `succeed` 或 `failed`。

### Path 参数 [#path-参数]

| 参数名      | 类型     | 必填 | 说明                                                                     |
| -------- | ------ | -- | ---------------------------------------------------------------------- |
| task\_id | string | 是  | 图像生成任务 ID，创建任务时返回的 `task_id` 字段，例如：`image-1762159125266058362-user123` |

### Header 参数 [#header-参数-2]

| 参数名           | 类型     | 必填 | 说明                               |
| ------------- | ------ | -- | -------------------------------- |
| Authorization | string | 是  | API Key，格式：`Bearer YOUR_API_KEY` |

### 响应体说明 [#响应体说明-2]

根据任务状态不同，返回的字段也有所不同。任务完成后会包含 `data` 字段，其中包含生成的图像下载链接。

| 字段名             | 类型      | 说明                                          |
| --------------- | ------- | ------------------------------------------- |
| task\_id        | string  | 图像生成任务的唯一标识符                                |
| created         | integer | 任务创建时间（Unix 时间戳，秒）                          |
| status          | string  | 任务的当前状态，见下方状态说明                             |
| status\_message | string  | 描述当前状态的消息                                   |
| data            | array   | 包含生成图像信息的数组，仅在已完成时返回                        |
| data\[].index   | integer | 图像在生成序列中的索引，从 0 开始                          |
| data\[].url     | string  | 访问生成图像文件的可直接访问 URL（注意：生成的图像会在 7 天后过期，请及时转存） |
| quantity        | integer | 此任务中生成的图像数量，同时该数量会用于计费                      |

### 任务状态说明 [#任务状态说明]

| 状态值        | 说明               |
| ---------- | ---------------- |
| submitted  | 任务已接收，等待处理       |
| processing | 任务正在处理中          |
| succeed    | 任务成功完成，图像已生成并可访问 |
| failed     | 任务在处理过程中失败       |

### 响应示例 [#响应示例]

#### 处理中状态 [#处理中状态]

```json
{
  "task_id": "chatimage-1762159125266058362-user123",
  "created": 1761793032,
  "status": "processing",
  "status_message": "处理中"
}
```

#### 成功完成状态 [#成功完成状态]

```json
{
  "task_id": "chatimage-1762159125266058362-user123",
  "created": 1761793032,
  "status": "succeed",
  "status_message": "成功",
  "data": [
    {
      "index": 0,
      "url": "https://aitoken-image.qnaigc.com/user123/image-1761793032508597404-user123/0.png?e=1763089082&token=IDB69r4gicDbMfrecarthgw1btTTWEFNg9i5_yasXqhp:JapC2EihLvSADMficht3pZVn5Xc="
    }
  ],
  "quantity": 1
}
```

#### 失败状态 [#失败状态]

```json
{
  "task_id": "chatimage-1762159125266058362-user123",
  "created": 1761793032,
  "status": "failed",
  "status_message": "失败"
}
```

***

# HTTP 调用示例 [#http-调用示例]

## **基础文生图** [#基础文生图]

使用 Kling 模型生成图像：

```bash
# 调用 Kling 文生图 API
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/images/generations" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "kling-v2",
        "prompt": "一只可爱的橘猫坐在窗台上看着夕阳，照片风格，高清画质",
        "aspect_ratio": "16:9"
    }'
```

**响应：**

```json
{
  "task_id": "chatimage-1762159125266058362-user123"
}
```

## **使用负向提示词** [#使用负向提示词]

使用负向提示词指定不希望出现的内容：

```bash
# 使用负向提示词
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/images/generations" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "kling-v2",
        "prompt": "一个美丽的花园",
        "negative_prompt": "模糊，低质量，变形",
        "aspect_ratio": "1:1"
    }'
```

## **使用参考图片（kling-v1-5）** [#使用参考图片kling-v1-5]

使用 kling-v1-5 模型的角色特征参考功能：

```bash
# 使用角色特征参考
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/images/generations" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "kling-v1-5",
        "prompt": "一个穿着西装的商务人士",
        "image": "https://aitoken-public.qnaigc.com/example/generate-image/smile-woman.png",
        "image_reference": "subject",
        "image_fidelity": 0.7,
        "human_fidelity": 0.6
    }'
```

## **单图生图示例** [#单图生图示例]

使用单张参考图片进行图生图：

```bash
# 使用单张参考图片（单图生图）
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/images/generations" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "kling-v1",
        "image": "https://aitoken-public.qnaigc.com/example/generate-video/running-man.jpg",
        "prompt": "将这张图片转换为水彩画风格",
        "aspect_ratio": "16:9"
    }'
```

## **多图生图示例** [#多图生图示例]

使用多张参考图片（2-4张）进行图生图：

```bash
# 使用多张参考图片（多图生图）
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/images/edits" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "kling-v2",
        "image": "",
        "prompt": "综合两个图像画一个漫画图",
        "subject_image_list": [
          {
              "subject_image": "https://aitoken-public.qnaigc.com/example/generate-image/smile-woman.png"
          },
          {
              "subject_image": "https://aitoken-public.qnaigc.com/example/generate-image/image-to-image-with-mask-1.jpg"
          }
        ],
        "aspect_ratio": "16:9"
    }'
```

## **使用场景和风格参考** [#使用场景和风格参考]

使用场景参考图和风格参考图进行图生图：

```bash
# 使用场景和风格参考
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/images/edits" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "kling-v2",
        "prompt": "一个梦幻般的森林场景",
        "subject_image_list": [
            {
                "subject_image": "https://aitoken-public.qnaigc.com/example/generate-image/smile-woman.png"
            },
            {
                "subject_image": "https://aitoken-public.qnaigc.com/example/generate-image/image-to-image-with-mask-1.jpg"
            }
        ],
        "scene_image": "https://aitoken-public.qnaigc.com/example/generate-image/image-to-image-with-mask-1.jpg",
        "style_image": "https://aitoken-public.qnaigc.com/example/generate-image/smile-woman.png",
        "aspect_ratio": "9:16"
    }'
```

## **查询任务状态** [#查询任务状态]

查询图像生成任务的状态：

```bash
# 查询任务状态
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"
export TASK_ID="chatimage-1762159125266058362-user123"

curl "$OPENAI_BASE_URL/images/tasks/$TASK_ID" \
    -H "Authorization: Bearer $OPENAI_API_KEY"
```

**响应示例（已提交）：**

```json
{
  "task_id": "chatimage-1766654340713562325-user123",
  "created": 1766654340,
  "status": "submitted",
  "status_message": "已提交"
}
```

**响应示例（处理中）：**

```json
{
  "task_id": "chatimage-1762159125266058362-user123",
  "created": 1761793032,
  "status": "processing",
  "status_message": "处理中"
}
```

**响应示例（已完成）：**

```json
{
  "task_id": "chatimage-1762159125266058362-user123",
  "created": 1761793032,
  "status": "succeed",
  "status_message": "成功",
  "data": [
    {
      "index": 0,
      "url": "https://aitoken-image.qnaigc.com/user123/image-1761793032508597404-user123/0.png?e=1763089082&token=IDB69r4gicDbMfrecarthgw1btTTWEFNg9i5_yasXqhp:JapC2EihLvSADMficht3pZVn5Xc="
    }
  ],
  "quantity": 1
}
```

***

# 常见问题 [#常见问题]

**Q: Kling 模型的文生图、单图生图和多图生图有什么区别？**

A:

* **文生图** (`/images/generations`，不传 `image` 参数)：纯粹根据文本描述生成全新的图像
* **单图生图** (`/images/generations`，传入单张 `image` 参数)：基于单张参考图片进行编辑和改造
* **多图生图** (`/images/edits`，传入 2-4 张 `subject_image_list`)：基于多张参考图片进行综合生成，可以保留多个图片的特征并结合

**Q: 为什么 Kling 模型使用异步接口？**

A: Kling 模型的图像生成过程需要较长时间，采用异步方式可以避免长时间等待导致的超时问题。您只需提交任务获得 task\_id，然后定期轮询查询任务状态即可。

**Q: 图像生成需要多长时间？**

A: 图像生成时间取决于模型版本、图像复杂度和当前队列情况。通常情况下：

* 单张图像：1-3 分钟
* 多张图像：2-5 分钟

建议使用轮询方式查询任务状态，轮询间隔建议为 5-10 秒。

**Q: 生成的图像会保存多久？**

A: 生成的图像**会在 7 天后过期**，建议在图像生成后及时下载或转存到您自己的存储空间。

**Q: 如何将生成的图像保存到七牛云对象存储？**

A: 生成的图像已经自动保存在七牛云对象存储 (Kodo) 中，返回的 URL 即为 Kodo 存储地址，但有效期**仅有 7 天**。如需转存到您自己的存储空间，推荐使用七牛对象存储的【[SDK 中心](/sdk-tools/sdk#official-sdk)】进行操作。更多对象存储信息欢迎参考对象存储的【[产品使用文档](/products/kodo/rs/8-upload)】。

**Q: 如何提高图像生成质量？**

A:

* **详细的提示词**：描述越详细，生成效果越好
* **使用负向提示词**：明确指定不希望出现的内容（如"模糊"、"低质量"等）
* **合理设置参考强度**：调整 `image_fidelity` 和 `human_fidelity` 参数
* **包含关键要素**：风格、光线、构图、色彩等

**Q: kling-v1-5 的 image\_reference 参数有什么用？**

A: `image_reference` 参数用于指定参考图片的使用方式：

* **subject**（角色特征参考）：保留参考图中角色的整体特征（服装、姿态等），但可以调整面部相似度
* **face**（人物长相参考）：重点保留参考图中人物的面部特征，要求参考图中只能有 1 张人脸

配合 `image_fidelity` 和 `human_fidelity` 参数可以精确控制参考程度。

**Q: 多图生图支持哪些参考图片类型？**

A: Kling 模型的多图生图功能 (`/images/edits`) 支持以下参考图片类型：

* **subject\_image\_list**：主体参考图片列表（**最少 2 张，最多 4 张**）
* **scene\_image**：场景参考图
* **style\_image**：风格参考图

可以单独使用或组合使用这些参考图片。

**Q: 负向提示词在什么情况下不能使用？**

A: 在图生图场景下（即 `image` 字段不为空时）不支持负向提示词。这是因为图生图已经有了明确的参考，负向提示词可能会产生冲突。

**Q: 任务失败的常见原因？**

A:

* **内容审核未通过**：提示词或参考图片包含违规内容
* **参考图片无法访问**：提供的图片 URL 无法访问或已过期
* **图片格式不符合要求**：图片尺寸、大小或格式不满足要求
* **参数配置错误**：必填参数缺失或参数值超出范围

**Q: 如何优化轮询查询？**

A:

* **轮询间隔**：建议 5-10 秒查询一次，避免过于频繁
* **超时处理**：建议设置超时时间（如 5 分钟），超时后停止轮询
* **状态判断**：只需关注 `succeed` 和 `failed` 两种终态，其他状态继续轮询

# 参考文档 [#参考文档]

* [AI 大模型推理产品介绍](https://www.qiniu.com/ai)
* [AI 大模型推理模型广场](https://www.qiniu.com/ai/models)
* [实时推理请求 API 接入说明](/products/aitokenapi/inference-api/1-real-time-ai-interface-api)
* [Kling 文生图官方文档](https://app.klingai.com/cn/dev/document-api/apiReference/model/imageGeneration)
* [Kling 图生图官方文档](https://app.klingai.com/cn/dev/document-api/apiReference/model/multiImageToImage)


# 聊天补全接口参数说明 (/products/aitokenapi/inference-api/0-chat-completions)



最近更新时间: 2026-09-17 15:11:35

# 聊天补全接口参数说明 [#聊天补全接口参数说明]

## 概述 [#概述]

本文档描述了聊天补全接口的请求参数，该接口用于生成对话模型的响应。支持多种模型配置和生成控制参数。

## 请求参数 [#请求参数]

### 基本信息参数 [#基本信息参数]

| 参数名        | 类型      | 必填 | 默认值     | 说明                                    |
| ---------- | ------- | -- | ------- | ------------------------------------- |
| `model`    | string  | 是  | -       | 指定使用的模型名称。例如："moonshotai/kimi-k2.6" 等 |
| `messages` | array   | 是  | -       | 对话消息数组，包含对话历史记录                       |
| `stream`   | boolean | 否  | `false` | 是否启用流式响应                              |

### 消息格式 [#消息格式]

`messages` 数组中的每个元素应包含：

* `role`: 消息角色，可选值：`"system"`, `"user"`, `"assistant"`, `"tool"`
* `content`: 消息内容，可以是字符串或复杂内容对象
* `name` (可选): 参与者名称
* `tool_calls` (可选): 工具调用信息
* `tool_call_id` (可选): 工具调用ID（仅当role为`"tool"`时）

### 生成控制参数 [#生成控制参数]

| 参数名                  | 类型      | 必填 | 默认值   | 范围/示例        | 说明                            |
| -------------------- | ------- | -- | ----- | ------------ | ----------------------------- |
| `max_tokens`         | integer | 否  | 模型默认值 | ≥1           | 生成的最大令牌数                      |
| `temperature`        | float32 | 否  | 1.0   | \[0.0, 2.0]  | 采样温度。值越高输出越随机，值越低输出越确定        |
| `top_p`              | float32 | 否  | 1.0   | \[0.0, 1.0]  | 核采样参数。仅考虑累计概率达到此值的令牌          |
| `top_k`              | integer | 否  | -     | ≥1           | 仅从概率最高的k个令牌中采样                |
| `presence_penalty`   | float32 | 否  | 0.0   | \[-2.0, 2.0] | 存在惩罚。正值惩罚已出现的令牌，鼓励新内容         |
| `frequency_penalty`  | float32 | 否  | 0.0   | \[-2.0, 2.0] | 频率惩罚。正值惩罚频繁出现的令牌。个别模型不支持或范围不同 |
| `repetition_penalty` | float32 | 否  | 1.0   | \[0.0, 2.0]  | 重复惩罚。>1.0时减少重复内容。个别模型不支持或范围不同 |

### 思维链参数（Anthropic/OpenAI标准） [#思维链参数anthropicopenai标准]

| 参数名                | 类型        | 必填 | 说明                                                                                  |
| ------------------ | --------- | -- | ----------------------------------------------------------------------------------- |
| `thinking`         | ThinkType | 否  | 思维链配置，控制模型的推理过程显示，"thinking": \{"type":"enabled", "budget\_tokens":160}不同kimi版本会有差异 |
| `reasoning_effort` | string    | 否  | 推理强度控制，如："low", "medium", "high"，在大部分模型上，这两个思考参数都可以使用                               |

### 工具调用参数 [#工具调用参数]

| 参数名           | 类型            | 必填 | 说明                                                                                                            |
| ------------- | ------------- | -- | ------------------------------------------------------------------------------------------------------------- |
| `tools`       | FunctionTools | 否  | 可供模型调用的工具定义列表                                                                                                 |
| `tool_choice` | interface\{}  | 否  | 工具调用策略。<br />可选值：<br />- `"none"`: 不调用工具<br />- `"auto"`: 由模型决定<br />- `"required"`: 必须调用工具<br />- 对象: 指定具体工具 |

### 多模态支持 [#多模态支持]

| 参数名               | 类型             | 必填 | 说明                                                      |
| ----------------- | -------------- | -- | ------------------------------------------------------- |
| `image_config`    | ImageConfig    | 否  | 图像输入配置，用于多模态模型处理图像                                      |
| `response_format` | ResponseFormat | 否  | 响应格式控制，如：`{"type": "json_object"}` 或 `{"type": "text"}` |

## 使用示例 [#使用示例]

### 基础对话 [#基础对话]

```json
{
  "model": "moonshotai/kimi-k2.6",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手"},
    {"role": "user", "content": "你好，今天天气怎么样？"}
  ],
  "temperature": 0.7,
  "max_tokens": 500
}
```

### 工具调用 [#工具调用]

```json
{
  "model": "moonshotai/kimi-k2.6",
  "messages": [
    {"role": "user", "content": "查询北京的天气"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}
```

### 流式响应 [#流式响应]

```json
{
  "model": "moonshotai/kimi-k2.6",
  "messages": [
    {"role": "user", "content": "写一首关于春天的诗"}
  ],
  "stream": true,
  "temperature": 0.8
}
```

### 带图像的对话 [#带图像的对话]

```json
{
  "model": "moonshotai/kimi-k2.6",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "描述这张图片"},
        {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
      ]
    }
  ],
  "max_tokens": 300
}
```

## 参数最佳实践 [#参数最佳实践]

1. **温度设置**：
   * 创造性任务：0.7-0.9
   * 事实性回答：0.1-0.3
   * 代码生成：0.1-0.3

2. **惩罚参数**：
   * 减少重复：设置 `repetition_penalty` 为 1.1-1.2
   * 鼓励多样性：设置 `presence_penalty` 为 0.1-0.5

3. **长度控制**：
   * 对话场景：`max_tokens` 设置为 500-1000
   * 摘要场景：根据原文长度适当调整

4. **工具调用**：
   * 明确指定工具功能描述
   * 使用 `tool_choice: "auto"` 让模型自主决定
   * 需要强制工具调用时使用 `tool_choice: "required"`

## 注意事项 [#注意事项]

1. 所有浮点数参数应在指定范围内，超出范围可能导致错误
2. 流式响应时，客户端需要处理分块数据
3. 工具调用需要配合后续的工具响应消息
4. 图像输入需要模型支持多模态能力
5. 不同模型可能对参数有不同支持程度，请参考具体模型文档

## 错误处理 [#错误处理]

常见错误码：

* `400`: 参数验证失败
* `401`: 认证失败
* `429`: 速率限制
* `500`: 服务器内部错误

建议实现重试逻辑和适当的错误处理机制。


# 实时推理请求 API 接入说明🚀 (/products/aitokenapi/inference-api/1-real-time-ai-interface-api)



最近更新时间: 2026-09-17 15:14:34

七牛云AI大模型推理 API 是一个高性能、易集成的Token API (即MaaS服务)，支持50多款主流大模型。兼容`OpenAI API`和`Anthropic API`接口格式，方便您集成到各种业务和应用场景中。

### **Token API 接入点** [#token-api-接入点]

🚀
七牛云AI大模型推理 API 接入域名：

* `https://api.qnaigc.com/v1`
* 使用前提：[获取API KEY（API 密钥）](/products/aitokenapi/0-how-to-get-api-key)

### 支持接口列表 [#支持接口列表]

| 接口名                  | 说明                                                                                                                                            |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| /v1/chat/completions | 对话型推理接口(兼容OpenAI格式)，支持图片文字识别、文件识别<br />图片格式：支持 JPG、JPEG、PNG、BMP、PDF 等常见格式，建议使用 JPG 格式<br />联网搜索：[参考文档](/products/aitokenapi/1-web-search-api) |
| /v1/models           | 列举所有可用模型ID及参数                                                                                                                                 |
| /v1/messages         | 兼容Anthropic API格式                                                                                                                             |

#### **获取可用模型列表** [#获取可用模型列表]

```bash
# 获取所有可用模型
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/models" \
    -H "Authorization: Bearer $OPENAI_API_KEY"
```

或使用 Python：

```python
from openai import OpenAI

client = OpenAI(
    base_url='https://api.qnaigc.com/v1',
    api_key='your qiniu_ai_api_key'
)

# 获取可用模型列表
models = client.models.list()
for model in models.data:
    print(f"模型ID: {model.id}")
```

### **HTTP 调用示例** [#http-调用示例]

使用上一步获取的 七牛云 API KEY 调用 chat 接口，支持的模型列表也可以通过我们的[模型广场](https://www.qiniu.com/ai/models)查看，例如：

```bash
# 调用推理 API
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "messages": [{"role": "user", "content": "夸一夸七牛云 AI 推理服务"}],
        "model": "deepseek-v3",
        "stream": true
    }'
```

***

### Python OpenAI 库调用示例 [#python-openai-库调用示例]

* **流式调用**

```python
from openai import OpenAI

openai_base_url = 'https://api.qnaigc.com/v1'
openai_api_key = 'your qiniu_ai_api_key'

client = OpenAI(
    base_url=openai_base_url,
    api_key=openai_api_key
)

# 发送带有流式输出的请求
content = ""
messages = [
    {"role": "user", "content": "夸一夸七牛云 AI 推理服务"}
]
response = client.chat.completions.create(
    model="deepseek-v3",
    messages=messages,
    stream=True,  # 启用流式输出
    max_tokens=4096
)

# 逐步接收并处理响应
for chunk in response:
    if chunk.choices[0].delta.content:
        content += chunk.choices[0].delta.content

print("第一轮回复:")
print(content)

# Round 2 - 继续对话
messages.append({"role": "assistant", "content": content})
messages.append({'role': 'user', 'content': "继续"})

response = client.chat.completions.create(
    model="deepseek-v3",
    messages=messages,
    stream=True
)

# 重置 content 变量来存储第二轮回复
second_content = ""
for chunk in response:
    if chunk.choices[0].delta.content:
        second_content += chunk.choices[0].delta.content

print("第二轮回复:")
print(second_content)
```

* **非流式调用**

```python
from openai import OpenAI

openai_base_url = 'https://api.qnaigc.com/v1'
openai_api_key = 'your qiniu_ai_api_key'

client = OpenAI(
    base_url=openai_base_url,
    api_key=openai_api_key
)

# 发送非流式输出的请求
messages = [
    {"role": "user", "content": "夸一夸七牛云 AI 推理服务"}
]
response = client.chat.completions.create(
    model="deepseek-v3",
    messages=messages,
    stream=False,
    max_tokens=4096
)
content = response.choices[0].message.content
print("第一轮回复:")
print(content)

# Round 2 - 继续对话
messages.append({"role": "assistant", "content": content})
messages.append({'role': 'user', 'content': "继续"})

response = client.chat.completions.create(
    model="deepseek-v3",
    messages=messages,
    stream=False
)
second_content = response.choices[0].message.content
print("第二轮回复:")
print(second_content)
```

### **图像生成** [#图像生成]

要生成图像，请向 `/v1/chat/completions` 端点发送请求，并将 `modalities` 参数设置为同时包含 `"image"` 和 `"text"`。
示例代码如下：

```python
    import requests
    import json

    url = "https://api.qnaigc.com/v1/chat/completions"
    headers = {
        "Authorization": "Bearer {API_KEY}",
        "Content-Type": "application/json"
    }

    payload = {
        "model": "{{MODEL}}",
        "messages": [
            {
                "role": "user",
                "content": "Create a picture of a nano banana dish in a fancy restaurant with a kimi theme"
            }
        ],
        "modalities": ["image", "text"],
        "image_config": {
            "aspect_ratio": "16:9"
        }
    }

    response = requests.post(url, headers=headers, json=payload)
    result = response.json()

    if result.get("choices"):
        message = result["choices"][0]["message"]
        if message.get("images"):
            for image in message["images"]:
                image_url = image["image_url"]["url"]
                print(f"Generated image: {image_url[:50]}...")
```

* **宽高比**
  通过设置 `image_config.aspect_ratio` 来请求特定的宽高比。支持的宽高比：
  * `1:1` → 1024×1024 (默认)
  * `2:3` → 832×1248
  * `3:2` → 1248×832
  * `3:4` → 864×1184
  * `4:3` → 1184×864
  * `4:5` → 896×1152
  * `5:4` → 1152×896
  * `9:16` → 768×1344
  * `16:9` → 1344×768
  * `21:9` → 1536×672
* **响应格式**
  生成图像时，消息包含一个 `images` 字段，其中包含生成的图像：

```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "I've generated a beautiful sunset image for you.",
        "images": [
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      }
    }
  ]
}
```

* **图像格式**
  * **格式**：图像以 base64 编码的数据 URL 形式返回
  * **类型**：通常是 PNG 格式 (`data:image/png;base64,`)
  * **多张图像**：某些模型可以在单个响应中生成多张图像
  * **尺寸**：图像尺寸因模型能力而异

* **最佳实践**
  * **清晰的提示**：提供详细的描述以获得更好的图像质量
  * **错误处理**：在处理之前检查响应中是否存在 `images` 字段
  * **速率限制**：图像生成可能有与文本生成不同的速率限制
  * **存储**：考虑如何处理和存储 base64 图像数据

### **文件识别推理** [#文件识别推理]

API 已经支持文件内容识别推理，示例代码如下：

```bash
# 调用文件识别 API
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl --location "$OPENAI_BASE_URL/chat/completions" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $OPENAI_API_KEY" \
    --data '{
        "model": "deepseek-v3",
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "pdf",
                        "file_url": {
                            "url": "https://aitoken-public.qnaigc.com/test/transformer.pdf"
                        }
                    },
                    {
                        "type": "text",
                        "text": "总结一下文档内容"
                    }
                ]
            }
        ]
    }'
```

* **参数**：type 为文件格式，url 为文件地址
* **文件格式**：目前仅支持 pdf、docx、xlsx、pptx 类型
* **注意**：文件内容，仍受上下文长度限制(64K tokens)，所以需注意文件内容长度

推荐使用七牛对象存储来存储文件并获取在线访问地址，提供给模型来进行识别和推理。

### **图片文字识别推理** [#图片文字识别推理]

API 已经支持图片文字识别推理，同时接口依然兼容 OpenAI，示例代码如下：

```bash
# 调用图片识别 API
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl "$OPENAI_BASE_URL/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": "请帮我整理图片中的内容并整理一份报告给我"
                    },
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": "https://www.qiniu.com/qiniu_ai_token_snapshot.png"
                        }
                    }
                ]
            }
        ],
        "model": "deepseek-v3"
    }'
```

* **注意**：image\_url 指向的文件大小不能超过 8MB
* **文件格式**：支持 JPG、JPEG、PNG、BMP、PDF 等常见格式，建议使用 JPG 格式

#### **如何通过对象存储获取输入图片地址？** [#如何通过对象存储获取输入图片地址]

推荐使用七牛对象存储来存储文件并获取在线访问地址，提供给模型来进行识别和推理。

可以通过 curl 快速进行上传测试：

```bash
# 上传文件到七牛对象存储
curl "$你的空间区域上传地址" \
    -F "file=@$你的文件路径" \
    -F "token=$你的上传token" \
    -F "key=$你的文件名"
```

或者在代码中使用 Python 来实现：

```python
import requests

# 上传文件到七牛对象存储
def upload_file_to_qiniu(file_path, upload_url, upload_token, file_key):
    """
    上传文件到七牛对象存储

    Args:
        file_path: 本地文件路径
        upload_url: 空间区域上传地址
        upload_token: 上传 token
        file_key: 保存的文件名称

    Returns:
        response: 上传响应结果
    """
    # 使用 with 语句确保文件正确关闭
    with open(file_path, "rb") as file:
        files = {
            "file": file
        }

        # 其他表单字段
        data = {
            "key": file_key,
            "token": upload_token
        }

        # 发送 POST 请求
        response = requests.post(upload_url, files=files, data=data)

    # 输出响应
    print("Status Code:", response.status_code)
    print("Response Body:", response.text)

    return response

# 使用示例
if __name__ == "__main__":
    upload_url = "你的空间区域上传地址"
    file_path = "上传的文件地址"
    upload_token = "你的上传token"
    file_key = "保存的文件名称"

    result = upload_file_to_qiniu(file_path, upload_url, upload_token, file_key)
```

我们还提供了许多语言的上传 SDK，简单易用，欢迎查看我们的【[SDK 中心](/sdk-tools/sdk#official-sdk)】来了解。

更多对象存储信息欢迎参考对象存储的【[产品使用文档](/products/kodo/rs/8-upload)】。

## 参考文档 [#参考文档]

* [AI 大模型推理产品介绍](https://www.qiniu.com/ai)
* [AI 大模型推理模型广场](https://www.qiniu.com/ai/models)


# 批量任务推理 API 接入说明🚆 (/products/aitokenapi/inference-api/2-new-ai-batch-inference-api)



最近更新时间: 2026-03-24 12:33:41

批量推理 API 提供高效异步的批量数据处理能力，支持大规模并行推理任务，适用于离线计算、大数据分析等场景。

## **API 接入点** [#api-接入点]

七牛云推理 API 接入域名：

* `https://api.qnaigc.com/v1`

***

## 创建批量推理任务接口文档 [#创建批量推理任务接口文档]

### 获取接口密钥 [#获取接口密钥]

* [如何获取七牛云 AI API Key](/products/aitokenapi/0-how-to-get-api-key)

### 接口概览 [#接口概览]

创建批量推理任务，支持通过文件 URL 进行批量数据处理。

### 接口详情 [#接口详情]

#### 基本信息 [#基本信息]

🚆

* **接口路径**: `/batchjob/inference`
* **请求方法**: POST
* **认证方式**: Bearer Token

#### 请求头 [#请求头]

```http
Authorization: Bearer <七牛云 AI API Key>
Content-Type: application/json
```

#### 请求参数 [#请求参数]

| 参数名               | 类型     | 必填 | 说明         | 限制                                                       |
| ----------------- | ------ | -- | ---------- | -------------------------------------------------------- |
| name              | string | 是  | 任务名称       | 最大长度100                                                  |
| model             | string | 是  | 使用的模型名称    | 目前支持 `deepseek-v3`、`deepseek-r1`、`deepseek-r1-32b` 这三种模型 |
| description       | string | 否  | 任务描述       | 最大长度255                                                  |
| input\_files\_url | string | 是  | 输入文件的URL地址 | 最大长度1000                                                 |

#### 请求示例 [#请求示例]

```json
{
  "name": "测试批量任务",
  "model": "deepseek-v3",
  "description": "这是一个批量处理测试任务",
  "input_files_url": "https://example.com/input.jsonl"
}
```

#### 响应参数 [#响应参数]

| 参数名 | 类型     | 说明                             |
| --- | ------ | ------------------------------ |
| id  | string | 任务ID，格式：bat-YYYYMMDDHHmmss-xxx |

#### 响应示例 [#响应示例]

```json
{
  "id": "bat-20240315123456-abc123def456"
}
```

#### 错误响应 [#错误响应]

```json
{
  "error": {
    "message": "错误信息描述",
    "type": "错误类型"
  }
}
```

#### 错误类型说明 [#错误类型说明]

| 错误类型                       | 说明       |
| -------------------------- | -------- |
| authentication\_error      | 认证错误     |
| invalid\_request\_error    | 请求参数无效   |
| invalid\_model\_error      | 不支持的模型   |
| file\_processing\_failed   | 文件处理失败   |
| create\_batch\_job\_failed | 创建批量任务失败 |

### 调用示例 [#调用示例]

#### CURL 方式 [#curl-方式]

```bash
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl -X POST "$OPENAI_BASE_URL/batchjob/inference" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "测试批量任务",
    "model": "deepseek-v3",
    "description": "这是一个批量处理测试任务",
    "input_files_url": "https://example.com/input.jsonl"
  }'
```

### 补充说明 [#补充说明]

#### 输入文件要求 [#输入文件要求]

* 文件格式：JSONL（JSON Lines）
* 每行格式：独立的JSON对象
* 访问要求：URL需可公开访问
* 文件大小限制：单个文件大小不超过100MB
* `custom_id` 字段为必填，用于标识每个请求的唯一ID，每行必须包含一个唯一 `custom_id` 值

输入文件实例：

```jsonl
{"custom_id": "your-custom-request-1", "body": {"messages": [{"role": "user", "content": "什么是大语言模型？"}],"max_tokens": 1000,"top_p":1}}
{"custom_id": "your-custom-request-2", "body": {"messages": [{"role": "system", "content": "You are an helpful assistant."},{"role": "user", "content": "大海有多大？"}],"max_tokens": 1000}}
```

#### 注意事项 [#注意事项]

1. 输入文件必须是可公开访问的 URL
2. 文件大小和格式需符合系统要求
3. 模型名称必须是系统支持的型号
4. 任务创建后会自动进入队列等待处理
5. 可以通过任务 ID 查询任务状态和结果

## 列表批量推理任务接口文档 [#列表批量推理任务接口文档]

获取用户创建的批量推理任务列表，支持分页查询。

### 接口详情 [#接口详情-1]

#### 基本信息 [#基本信息-1]

* **接口路径**: `/batchjob/inferences`
* **请求方法**: GET
* **认证方式**: Bearer Token

#### 请求头 [#请求头-1]

```http
Authorization: Bearer <七牛云 AI API Key>
```

#### 请求参数 [#请求参数-1]

| 参数名        | 类型      | 必填 | 说明    | 限制                   |
| ---------- | ------- | -- | ----- | -------------------- |
| page       | integer | 否  | 页码    | 最小值为1，默认为1           |
| page\_size | integer | 否  | 每页记录数 | 最小值为1，最大值为100，默认为100 |

#### 响应参数 [#响应参数-1]

返回批量推理任务列表，每个任务包含以下字段：

| 参数名                | 类型     | 说明                             |
| ------------------ | ------ | ------------------------------ |
| id                 | string | 任务ID，格式：bat-YYYYMMDDHHmmss-xxx |
| name               | string | 任务名称                           |
| model              | string | 使用的模型名称                        |
| description        | string | 任务描述                           |
| input\_files\_url  | string | 输入文件的URL地址                     |
| output\_files\_url | string | 输出文件的URL地址（任务完成后可用），有效期7天      |
| status             | string | 任务状态                           |
| status\_message    | string | 状态描述信息                         |
| created\_at        | string | 创建时间，ISO 8601格式                |
| updated\_at        | string | 更新时间，ISO 8601格式                |

#### 响应示例 [#响应示例-1]

```json
[
  {
    "id": "bat-20240315123456-abc123def456",
    "name": "测试批量任务",
    "model": "deepseek-v3",
    "description": "这是一个批量处理测试任务",
    "input_files_url": "https://example.com/input.jsonl",
    "output_files_url": "https://aitoken.qnaigc.com/xxx/output/bat-20250416171124-a215c5a0dec224757e8d429cd31d2a90.jsonl?e=1745400268&token=xxx",
    "status": "Completed",
    "status_message": "任务已完成",
    "created_at": "2025-04-18T11:37:09+08:00",
    "updated_at": "2025-04-18T11:37:09+08:00"
  },
  {
    "id": "bat-20240316123456-def456ghi789",
    "name": "另一个批量任务",
    "model": "deepseek-r1",
    "description": "这是另一个批量处理任务",
    "input_files_url": "https://example.com/input2.jsonl",
    "output_files_url": "",
    "status": "Running",
    "status_message": "任务正在运行中",
    "created_at": "2025-04-19T11:37:09+08:00",
    "updated_at": "2025-04-19T11:37:09+08:00"
  }
]
```

#### 错误响应 [#错误响应-1]

```json
{
  "error": {
    "message": "错误信息描述",
    "type": "错误类型"
  }
}
```

#### 错误类型说明 [#错误类型说明-1]

| 错误类型                                | 说明         |
| ----------------------------------- | ---------- |
| authentication\_error               | 认证错误       |
| invalid\_request\_error             | 请求参数无效     |
| list\_batch\_inference\_job\_failed | 获取批量任务列表失败 |

### 调用示例 [#调用示例-1]

#### CURL 方式 [#curl-方式-1]

```bash
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl -X GET "$OPENAI_BASE_URL/batchjob/inference?page=1&page_size=10" \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

### 补充说明 [#补充说明-1]

1. 任务状态(status)可能的值包括：
   * Queued: 排队中
   * Running: 运行中
   * Completed: 已完成
   * Failed: 失败
   * Terminating: 正在终止
   * Terminated: 已终止

2. 只有当任务状态为Completed时，output\_files\_url才会有值

3. output\_files\_url 通过七牛对象存储和 CDN 提供对外访问地址，不要外传，有效期7天

\<!-- ================================================ -->

## 查询批量推理任务详情接口文档 [#查询批量推理任务详情接口文档]

### 接口概览 [#接口概览-1]

获取指定批量推理任务的详细信息，包括任务状态、输入输出文件等。

### 接口详情 [#接口详情-2]

#### 基本信息 [#基本信息-2]

* **接口路径**: `/batchjob/inference/{id}`
* **请求方法**: GET
* **认证方式**: Bearer Token

#### 请求头 [#请求头-2]

```http
Authorization: Bearer <七牛云 AI API Key>
```

#### 路径参数 [#路径参数]

| 参数名 | 类型     | 必填 | 说明                               |
| --- | ------ | -- | -------------------------------- |
| id  | string | 是  | 批量任务ID，格式：bat-YYYYMMDDHHmmss-xxx |

#### 响应参数 [#响应参数-2]

| 参数名                | 类型     | 说明                             |
| ------------------ | ------ | ------------------------------ |
| id                 | string | 任务ID，格式：bat-YYYYMMDDHHmmss-xxx |
| name               | string | 任务名称                           |
| model              | string | 使用的模型名称                        |
| description        | string | 任务描述                           |
| input\_files\_url  | string | 输入文件的URL地址                     |
| output\_files\_url | string | 输出文件的URL地址（任务完成后可用），有效期7天      |
| status             | string | 任务状态                           |
| status\_message    | string | 状态描述信息                         |
| created\_at        | string | 任务创建时间                         |
| updated\_at        | string | 任务更新时间                         |

#### 响应示例 [#响应示例-2]

```json
{
  "id": "bat-20240315123456-abc123def456",
  "name": "测试批量任务",
  "model": "deepseek-v3",
  "description": "这是一个批量处理测试任务",
  "input_files_url": "https://example.com/input.jsonl",
  "output_files_url": "https://aitoken.qnaigc.com/xxx/output/bat-20250416171124-a215c5a0dec224757e8d429cd31d2a90.jsonl?e=1745400268&token=xxx",
  "status": "Completed",
  "status_message": "任务已完成",
  "created_at": "2025-04-18T11:37:09+08:00",
  "updated_at": "2025-04-18T11:37:09+08:00"
}
```

#### 错误响应 [#错误响应-2]

```json
{
  "error": {
    "message": "错误信息描述",
    "type": "错误类型"
  }
}
```

#### 错误类型说明 [#错误类型说明-2]

| 错误类型                                | 说明       |
| ----------------------------------- | -------- |
| authentication\_error               | 认证错误     |
| view\_batch\_inference\_job\_failed | 查询批量任务失败 |

### 调用示例 [#调用示例-2]

#### CURL 方式 [#curl-方式-2]

```bash
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl -X GET "$OPENAI_BASE_URL/batchjob/inference/bat-20240315123456-abc123def456" \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

### 任务状态说明 [#任务状态说明]

| 状态值         | 说明         |
| ----------- | ---------- |
| Queued      | 任务已提交，等待处理 |
| Running     | 任务正在运行中    |
| Completed   | 任务已完成      |
| Failed      | 任务执行失败     |
| Terminating | 任务正在终止中    |
| Terminated  | 任务已终止      |

\<!-- ================================================ -->

## 删除批量推理任务接口文档 [#删除批量推理任务接口文档]

### 接口概览 [#接口概览-2]

删除指定的批量推理任务，任务将被标记为已删除并停止处理。

### 接口详情 [#接口详情-3]

#### 基本信息 [#基本信息-3]

* **接口路径**: `/batchjob/inference/{id}`
* **请求方法**: DELETE
* **认证方式**: Bearer Token

#### 请求头 [#请求头-3]

```http
Authorization: Bearer <七牛云 AI API Key>
```

#### 路径参数 [#路径参数-1]

| 参数名 | 类型     | 必填 | 说明                               |
| --- | ------ | -- | -------------------------------- |
| id  | string | 是  | 批量任务ID，格式：bat-YYYYMMDDHHmmss-xxx |

#### 响应参数 [#响应参数-3]

| 参数名     | 类型     | 说明     |
| ------- | ------ | ------ |
| message | string | 操作结果信息 |

#### 响应示例 [#响应示例-3]

```json
{
  "message": "delete_batch_inference_job_success"
}
```

#### 错误响应 [#错误响应-3]

```json
{
  "error": {
    "message": "错误信息描述",
    "type": "错误类型"
  }
}
```

#### 错误类型说明 [#错误类型说明-3]

| 错误类型                                      | 说明       |
| ----------------------------------------- | -------- |
| authentication\_error                     | 认证错误     |
| delete\_batch\_inference\_job\_failed     | 删除批量任务失败 |
| delete\_batch\_inference\_job\_db\_failed | 数据库操作失败  |

### 调用示例 [#调用示例-3]

#### CURL 方式 [#curl-方式-3]

```bash
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl -X DELETE "$OPENAI_BASE_URL/batchjob/inference/bat-20240315123456-abc123def456" \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

### 补充说明 [#补充说明-2]

1. 已删除的任务无法恢复

## 停止批量推理任务接口文档 [#停止批量推理任务接口文档]

### 接口概览 [#接口概览-3]

停止正在运行的批量推理任务。

### 接口详情 [#接口详情-4]

#### 基本信息 [#基本信息-4]

* **接口路径**: `/batchjob/inference/stop/{id}`
* **请求方法**: POST
* **认证方式**: Bearer Token

#### 请求头 [#请求头-4]

```http
Authorization: Bearer <七牛云 AI API Key>
Content-Type: application/json
```

#### 路径参数 [#路径参数-2]

| 参数名 | 类型     | 必填 | 说明                               |
| --- | ------ | -- | -------------------------------- |
| id  | string | 是  | 批量任务ID，格式：bat-YYYYMMDDHHmmss-xxx |

#### 响应 [#响应]

成功停止任务时，返回HTTP状态码204（No Content），无响应体。

#### 错误响应 [#错误响应-4]

```json
{
  "error": {
    "message": "错误信息描述",
    "type": "错误类型"
  }
}
```

#### 错误类型说明 [#错误类型说明-4]

| 错误类型                                    | 说明        |
| --------------------------------------- | --------- |
| authentication\_error                   | 认证错误      |
| stop\_batch\_inference\_job\_failed     | 停止批量任务失败  |
| stop\_batch\_inference\_job\_db\_failed | 更新数据库状态失败 |

### 调用示例 [#调用示例-4]

#### CURL 方式 [#curl-方式-4]

```bash
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl -X POST "$OPENAI_BASE_URL/batchjob/inference/stop/bat-20240315123456-abc123def456" \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

### 补充说明 [#补充说明-3]

#### 任务状态限制 [#任务状态限制]

1. 只有处于运行中（Running）或排队中（Queued）状态的任务可以被停止
2. 已经处于终止中（Terminating）、已终止（Terminated）或失败（Failed）状态的任务无法停止
3. 停止任务后，任务状态将变为已终止（Terminated）
4. 已停止的任务可以通过恢复接口重新启动

## 重启批量推理任务接口文档 [#重启批量推理任务接口文档]

### 接口概览 [#接口概览-4]

重启已停止或失败的批量推理任务，使其恢复执行。

### 接口详情 [#接口详情-5]

#### 基本信息 [#基本信息-5]

* **接口路径**: `/batchjob/inference/resume/{id}`
* **请求方法**: POST
* **认证方式**: Bearer Token

#### 请求头 [#请求头-5]

```http
Authorization: Bearer <七牛云 AI API Key>
Content-Type: application/json
```

#### 路径参数 [#路径参数-3]

| 参数名 | 类型     | 必填 | 说明                               |
| --- | ------ | -- | -------------------------------- |
| id  | string | 是  | 批量任务ID，格式：bat-YYYYMMDDHHmmss-xxx |

#### 响应 [#响应-1]

成功重启任务时，服务器返回 HTTP 204 No Content 状态码，无响应体。

#### 错误响应 [#错误响应-5]

```json
{
  "error": {
    "message": "错误信息描述",
    "type": "错误类型"
  }
}
```

#### 错误类型说明 [#错误类型说明-5]

| 错误类型                                      | 说明       |
| ----------------------------------------- | -------- |
| authentication\_error                     | 认证错误     |
| resume\_batch\_inference\_job\_failed     | 重启批量任务失败 |
| resume\_batch\_inference\_job\_db\_failed | 数据库操作失败  |

### 调用示例 [#调用示例-5]

#### CURL 方式 [#curl-方式-5]

```bash
export OPENAI_BASE_URL="https://api.qnaigc.com/v1"
export OPENAI_API_KEY="<七牛云 AI API KEY>"

curl -X POST "$OPENAI_BASE_URL/batchjob/inference/resume/bat-20240315123456-abc123def456" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"
```

### 补充说明 [#补充说明-4]

#### 使用限制 [#使用限制]

1. 只能重启已停止或失败的任务
2. 正在运行或已完成的任务无法重启
3. 任务重启后会重新进入任务队列等待处理


# 批量创建API Key (/products/aitokenapi/keys-manager-api/0-new-batch-create-keys-api)



最近更新时间: 2026-03-24 15:42:49

**Base URL:** `https://api.qnaigc.com`

## **概述** [#概述]

本接口用于管理员账号批量创建`大模型API Key（密钥）`，适用于需要一次性生成多个访问密钥的场景。接口采用 [管理员AK/SK](https://portal.qiniu.com/developer/user/key) 签名认证机制，请求时需要按照签名规范生成数字签名。

***

## **认证方式** [#认证方式]

使用七牛云账号的 [管理员AK/SK](https://portal.qiniu.com/developer/user/key) 签名认证。
签名实现请参考底部示例：

```
Authorization: Qiniu <AccessKey>:<EncodedSign>
```

***

## **接口详情** [#接口详情]

### **POST** `/v1/apikeys` [#post-v1apikeys]

批量创建 APIKey。

**请求头：**

| 名称              | 类型       | 必填 | 描述                                                                        |
| --------------- | -------- | -- | ------------------------------------------------------------------------- |
| `Authorization` | `string` | 是  | AK/SK 签名，格式为 `Authorization: Qiniu &lt;AccessKey&gt;:&lt;EncodedSign&gt;` |

**请求体示例：**

```json
{
  "count": 2,
  "names": ["测试key1", "测试key2"]
}
```

**参数说明：**

| 字段      | 类型         | 必填 | 说明                                                              |
| ------- | ---------- | -- | --------------------------------------------------------------- |
| `count` | `integer`  | 是  | 需要创建的 APIKey 数量。&#x2A;*注意：** 账户内已有 APIKey 数量加上本次创建数量总和不得超过 100。 |
| `names` | `string[]` | 是  | APIKey 名称列表，长度必须与 `count` 一致。                                   |

***

**响应示例（200 OK）**

```json
{
  "status": true,
  "data": {
    "keys": [
      {
        "key": "sk-xxx",
        "name": "测试key1",
        "createdAt": "2025-11-20T19:56:02+08:00",
        "enabled": true
      },
      {
        "key": "sk-yyy",
        "name": "测试key2",
        "createdAt": "2025-11-20T19:56:02+08:00",
        "enabled": true
      }
    ]
  }
}
```

**响应字段说明：**

| 字段                      | 类型        | 说明                   |
| ----------------------- | --------- | -------------------- |
| `status`                | `boolean` | 请求状态，`true` 表示成功     |
| `data.keys`             | `array`   | 创建的 APIKey 列表        |
| `data.keys[].key`       | `string`  | APIKey 值（以 `sk-` 开头） |
| `data.keys[].name`      | `string`  | APIKey 名称            |
| `data.keys[].createdAt` | `string`  | 创建时间（ISO 8601 格式）    |
| `data.keys[].enabled`   | `boolean` | 是否启用                 |

***

**错误状态码**

| 状态码 | 说明                                |
| --- | --------------------------------- |
| 400 | 请求参数错误（如 `names` 长度与 `count` 不匹配） |
| 401 | 认证失败（签名无效或过期）                     |
| 403 | 权限不足或 APIKey 总数超限                 |
| 500 | 服务器内部错误                           |

***

## **代码示例** [#代码示例]

### **基于 AK/SK 签名创建key** [#基于-aksk-签名创建key]

```bash
curl --location "https://api.qnaigc.com/v1/apikeys" \
  --header "Content-Type: application/json" \
  --header "Authorization: Qiniu <AccessKey>:<EncodedSign>" \
  --data '{
    "count": 2,
    "names": [
        "测试key1",
        "测试key2"
    ]
  }'
```

### **AK/SK 签名实现参考** [#aksk-签名实现参考]

```javascript
const crypto = require('crypto')

/**
 * URL 安全的 Base64 编码
 * @param {Buffer} buffer - 要编码的数据
 * @returns {string} - URL 安全的 Base64 字符串
 */
function urlSafeBase64Encode(buffer) {
  return buffer.toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_');
}

/**
 * 生成待签名的原始字符串
 * @param {Object} options - 请求参数
 * @param {string} options.method - HTTP 方法（大小写敏感）
 * @param {string} options.path - 请求路径
 * @param {string} [options.query] - 查询参数（不包含 ?）
 * @param {string} options.host - 主机名
 * @param {string} [options.contentType] - Content-Type
 * @param {Object} [options.headers] - X-Qiniu-* 开头的自定义头（可选）
 * @param {string} [options.body] - 请求体（可选）
 * @returns {string} - 待签名的字符串
 */
function generateSigningString(options) {
  const { method, path, query, host, contentType, headers, body } = options

  // 1. Method + 空格 + Path
  let signingStr = method.toUpperCase()

  // 2. 添加 Path 和 Query
  signingStr += ' ' + path
  if (query) {
    signingStr += '?' + query
  }

  // 3. 添加 Host
  signingStr += '\nHost: ' + host

  // 4. 添加 Content-Type（如果有）
  if (contentType) {
    signingStr += '\nContent-Type: ' + contentType
  }

  // 5. 添加 X-Qiniu-* 头部（如果有）
  if (headers) {
    // 按 key 的 ASCII 排序
    const sortedKeys = Object.keys(headers).sort()
    sortedKeys.forEach(key => {
      if (key.toLowerCase().startsWith('x-qiniu-')) {
        // 格式化 key：首字母和 - 后的字母大写，其余小写
        const formattedKey = key.split('-')
          .map((part, index) => {
            if (index === 0) {
              return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()
            }
            return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()
          })
          .join('-')
        signingStr += '\n' + formattedKey + ': ' + headers[key]
      }
    })
  }

  // 6. 添加两个连续换行符
  signingStr += '\n\n'

  // 7. 添加 Body（如果有且 Content-Type 不是 application/octet-stream）
  if (body && contentType && contentType !== 'application/octet-stream') {
    signingStr += body
  }

  return signingStr
}


/**
 * 生成七牛云管理凭证（Access Token）
 * @param {string} accessKey - 七牛云 AccessKey
 * @param {string} secretKey - 七牛云 SecretKey
 * @param {Object} requestOptions - 请求参数（同 generateSigningString）
 * @returns {string} - 管理凭证字符串
 */
function generateAccessToken(accessKey, secretKey, requestOptions) {
  // 1. 生成待签名的原始字符串
  const signingStr = generateSigningString(requestOptions);

  // 2. 使用 HMAC-SHA1 计算签名
  const hmac = crypto.createHmac('sha1', secretKey);
  hmac.update(signingStr);
  const sign = hmac.digest();

  // 3. 对签名进行 URL 安全的 Base64 编码
  const encodedSign = urlSafeBase64Encode(sign);

  // 4. 将 AccessKey 和 encodedSign 用冒号连接
  const accessToken = accessKey + ':' + encodedSign;

  return accessToken;
}


// 示例用法：批量创建 APIKey
const accessKey = '你的 AK'
const secretKey = '你的 SK'

// 准备请求体
const requestBody = {
  count: 2,
  names: ['测试key1', '测试key2']
}
const bodyString = JSON.stringify(requestBody)

// 构建签名参数
const requestOptions = {
  method: 'POST',
  path: '/v1/apikeys',
  host: 'api.qnaigc.com',
  contentType: 'application/json',
  body: bodyString
}

// 生成签名
const accessToken = generateAccessToken(accessKey, secretKey, requestOptions)
console.log('生成的 Access Token:', accessToken)

// 实际调用接口
const fetch = require('node-fetch') // 如果使用 Node.js
fetch('https://api.qnaigc.com/v1/apikeys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Qiniu ${accessToken}`
  },
  body: bodyString
})
  .then(res => res.json())
  .then(data => {
    console.log('批量创建成功:', data)
  })
  .catch(err => {
    console.error('请求失败:', err)
  })
```

***

## **注意事项** [#注意事项]

1. 请妥善保管生成的 `sk-xxx` 密钥，避免泄露。
2. 每个账户最多允许创建 100 个 APIKey，创建前请确认总数不超过限制。
3. 签名有效期为 15 分钟，建议在请求前实时生成。
4. 若需创建大量 APIKey，请分批调用本接口。


# API Key限额管理 (/products/aitokenapi/keys-manager-api/1-set-api-key-limit-api)



最近更新时间: 2026-03-24 15:43:48

**Base URL:** `https://api.qnaigc.com`

## **概述** [#概述]

用于**设置**与**查询**指定 APIKey 的金额限额配置（按日 / 按月 / 总限额），当用量达到限额时将触发限额拦截（返回错误）。

## **认证方式** [#认证方式]

本接口仅支持 **AK/SK 签名认证**：使用七牛云标准的 [AK/SK](https://portal.qiniu.com/developer/user/key) 签名认证。

```
Authorization: Qiniu <AccessKey>:<EncodedSign>
```

***

## **设置 API KEY 限额** [#设置-api-key-限额]

### **PUT** `/v1/apikey/quota/:api_key` [#put-v1apikeyquotaapi_key]

**路径参数：**

| 参数        | 类型       | 必填 | 说明       |
| --------- | -------- | -- | -------- |
| `api_key` | `string` | 是  | APIKey 值 |

**请求头：**

| 名称              | 类型       | 必填 | 描述                                                         |
| --------------- | -------- | -- | ---------------------------------------------------------- |
| `Authorization` | `string` | 是  | AK/SK 签名，格式为 `Qiniu &lt;AccessKey&gt;:&lt;EncodedSign&gt;` |
| `Content-Type`  | `string` | 是  | `application/json`                                         |

**请求体：**

```json
{
  "daily_quota": {
    "enabled": false,
    "limit": 0,
    "alert_threshold": 0
  },
  "monthly_quota": {
    "enabled": false,
    "limit": 0,
    "alert_threshold": 0
  },
  "total_quota": {
    "enabled": true,
    "limit": 100,
    "alert_threshold": 80
  }
}
```

**字段说明：**

| 字段                              | 类型        | 必填 | 说明                 |
| ------------------------------- | --------- | -- | ------------------ |
| `daily_quota.enabled`           | `boolean` | 是  | 是否启用日限额            |
| `daily_quota.limit`             | `number`  | 是  | 日限额金额（>= 0）        |
| `daily_quota.alert_threshold`   | `number`  | 是  | 日限额告警阈值百分比（0\~100） |
| `monthly_quota.enabled`         | `boolean` | 是  | 是否启用月限额            |
| `monthly_quota.limit`           | `number`  | 是  | 月限额金额（>= 0）        |
| `monthly_quota.alert_threshold` | `number`  | 是  | 月限额告警阈值百分比（0\~100） |
| `total_quota.enabled`           | `boolean` | 是  | 是否启用总限额（无时间范围）     |
| `total_quota.limit`             | `number`  | 是  | 总限额金额（>= 0）        |
| `total_quota.alert_threshold`   | `number`  | 是  | 总限额告警阈值百分比（0\~100） |

**请求示例：**

```bash
curl --location --request PUT "https://api.qnaigc.com/v1/apikey/quota/sk-xx" \
  --header "Authorization: Qiniu <AccessKey>:<EncodedSign>" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "daily_quota": {"enabled": false, "limit": 0, "alert_threshold": 0},
    "monthly_quota": {"enabled": false, "limit": 0, "alert_threshold": 0},
    "total_quota": {"enabled": true, "limit": 100, "alert_threshold": 80}
  }'
```

**响应示例（200 OK）**

```json
{
  "status": true,
  "data": {
    "daily_quota": {
    "enabled": false,
    "limit": 0,
    "alert_threshold": 0
  },
  "monthly_quota": {
    "enabled": false,
    "limit": 0,
    "alert_threshold": 0
  },
  "total_quota": {
    "enabled": true,
    "limit": 100,
    "alert_threshold": 80
  },
  "created_at": "2006-01-02 15:04:05",
  "updated_at": "2006-01-02 15:04:05"
  }
}
```

***

## **查询指定 API Key 的限额配置** [#查询指定-api-key-的限额配置]

#### **GET** `/v1/apikey/quota/:api_key` [#get-v1apikeyquotaapi_key]

**路径参数：**

| 参数        | 类型       | 必填 | 说明       |
| --------- | -------- | -- | -------- |
| `api_key` | `string` | 是  | APIKey 值 |

**请求头：**

| 名称              | 类型       | 必填 | 描述                                                         |
| --------------- | -------- | -- | ---------------------------------------------------------- |
| `Authorization` | `string` | 是  | AK/SK 签名，格式为 `Qiniu &lt;AccessKey&gt;:&lt;EncodedSign&gt;` |

**请求示例：**

```bash
curl --location "https://api.qnaigc.com/v1/apikey/quota/sk-xx" \
  --header "Authorization: Qiniu <AccessKey>:<EncodedSign>"
```

**响应示例（200 OK）**

```json
{
  "status": true,
  "data": {
    "daily_quota": {
      "enabled": true,
      "limit": 10,
      "alert_threshold": 80
    },
    "monthly_quota": {
      "enabled": true,
      "limit": 200,
      "alert_threshold": 80
    },
    "total_quota": {
      "enabled": false,
      "limit": 0,
      "alert_threshold": 0
    },
    "created_at": "2006-01-02 15:04:05",
    "updated_at": "2006-01-02 15:04:05"
  }
}
```

***

## **错误状态码** [#错误状态码]

| 状态码 | 说明                                              |
| --- | ----------------------------------------------- |
| 400 | 请求参数错误（如 limit \< 0、alert\_threshold 不在 0\~100） |
| 401 | 认证失败（签名无效）                                      |
| 500 | 服务器内部错误                                         |

***

## **注意事项** [#注意事项]

1. `api_key` 支持携带 `Bearer ` 前缀，例如：`Bearer sk-xx`。
2. `alert_threshold` 为百分比值（0\~100），用于告警阈值配置；是否产生告警取决于服务端告警策略。
3. 配额配置写入后可能存在短暂延迟才生效(0\~30s)。

***

## **AK/SK 签名算法** [#aksk-签名算法]

### **概述** [#概述-1]

七牛云 API 使用 HMAC-SHA1 签名算法进行身份验证。签名结果附加在请求头的 `Authorization` 字段中，格式为：

```
Authorization: Qiniu <AccessKey>:<EncodedSign>
```

### **签名生成步骤** [#签名生成步骤]

#### **1. 生成待签名字符串** [#1-生成待签名字符串]

待签名字符串由以下部分组成（每部分用换行符分隔）：

```
<Method> <Path>[?Query]
Host: <Host>
Content-Type: <Content-Type>
[X-Qiniu-<HeaderKey>: <HeaderValue>]
<Body>
```

**注意：**

* `Method` 为 HTTP 方法（如 GET、PUT），大写
* `Path` 为请求路径，不包含域名和查询参数
* `Query` 为查询参数（不包含开头的 `?`），仅在有时才添加
* `Host` 为主机名（如 `api.qnaigc.com`）
* `Content-Type` 为请求内容类型（如 `application/json`）
* `X-Qiniu-*` 为可选的自定义头，按 key 的 ASCII 顺序排列，格式化为 `X-Qiniu-<Key>`（每个单词首字母大写）
* 待签名串中在 headers 部分结束后，会追加两个连续换行符 `\n\n`
* `Body` 为请求体（仅当 Content-Type 不是 `application/octet-stream` 时才添加）

#### **2. 计算 HMAC-SHA1 签名** [#2-计算-hmac-sha1-签名]

使用 `SecretKey` 作为密钥，对待签名字符串进行 HMAC-SHA1 运算：

```javascript
const hmac = crypto.createHmac('sha1', secretKey);
hmac.update(signingStr);
const sign = hmac.digest();
```

#### **3. Base64 编码** [#3-base64-编码]

对签名结果进行 URL 安全的 Base64 编码（`+` 替换为 `-`，`/` 替换为 `_`）：

```javascript
function urlSafeBase64Encode(buffer) {
  return buffer.toString('base64').replace(/\+/g, '-').replace(/\//g, '_');
}
const encodedSign = urlSafeBase64Encode(sign);
```

#### **4. 生成最终凭证** [#4-生成最终凭证]

将 `AccessKey` 和 `encodedSign` 用冒号连接：

```
<AccessKey>:<EncodedSign>
```

### **完整示例代码（Node.js）** [#完整示例代码nodejs]

下面示例演示：

* **GET** `/v1/apikey/quota/sk-xx` 查询限额
* **PUT** `/v1/apikey/quota/sk-xx` 设置限额（包含 JSON Body，因此签名需要包含 `Content-Type` 和 Body）

```javascript
const crypto = require('crypto');

/**
 * URL 安全的 Base64 编码
 */
function urlSafeBase64Encode(buffer) {
  return buffer.toString('base64').replace(/\+/g, '-').replace(/\//g, '_');
}

/**
 * 生成待签名的原始字符串
 */
function generateSigningString(options) {
  const { method, path, query, host, contentType, headers, body } = options;

  let signingStr = method.toUpperCase();
  signingStr += ' ' + path;
  if (query) {
    signingStr += '?' + query;
  }
  signingStr += '\nHost: ' + host;

  if (contentType) {
    signingStr += '\nContent-Type: ' + contentType;
  }

  if (headers) {
    const sortedKeys = Object.keys(headers).sort();
    sortedKeys.forEach((key) => {
      if (key.toLowerCase().startsWith('x-qiniu-')) {
        const formattedKey = key
          .split('-')
          .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
          .join('-');
        signingStr += '\n' + formattedKey + ': ' + headers[key];
      }
    });
  }

  signingStr += '\n\n';

  if (body && contentType && contentType !== 'application/octet-stream') {
    signingStr += body;
  }

  return signingStr;
}

/**
 * 生成七牛云管理凭证（Access Token）
 */
function generateAccessToken(accessKey, secretKey, requestOptions) {
  const signingStr = generateSigningString(requestOptions);
  const hmac = crypto.createHmac('sha1', secretKey);
  hmac.update(signingStr);
  const sign = hmac.digest();
  const encodedSign = urlSafeBase64Encode(sign);
  return accessKey + ':' + encodedSign;
}

async function demo() {
  const accessKey = '你的 AccessKey';
  const secretKey = '你的 SecretKey';
  const host = 'api.qnaigc.com';

  // 1) GET 查询限额
  const getPath = '/v1/apikey/quota/sk-xx';
  const getToken = generateAccessToken(accessKey, secretKey, {
    method: 'GET',
    path: getPath,
    host,
  });

  const getResp = await fetch('https://' + host + getPath, {
    headers: { Authorization: 'Qiniu ' + getToken },
  });
  console.log('GET status:', getResp.status);
  console.log(await getResp.text());

  // 2) PUT 设置限额
  const putPath = '/v1/apikey/quota/sk-xx';
  const putBodyObj = {
    daily_quota: { enabled: true, limit: 10, alert_threshold: 80 },
    monthly_quota: { enabled: true, limit: 200, alert_threshold: 80 },
    total_quota: { enabled: false, limit: 1000, alert_threshold: 80 },
  };
  const putBody = JSON.stringify(putBodyObj);
  const putContentType = 'application/json';
  const putToken = generateAccessToken(accessKey, secretKey, {
    method: 'PUT',
    path: putPath,
    host,
    contentType: putContentType,
    body: putBody,
  });

  const putResp = await fetch('https://' + host + putPath, {
    method: 'PUT',
    headers: {
      Authorization: 'Qiniu ' + putToken,
      'Content-Type': putContentType,
    },
    body: putBody,
  });
  console.log('PUT status:', putResp.status);
  console.log(await putResp.text());
}

demo().catch(console.error);
```


# 大模型Token用量查询 (/products/aitokenapi/usage-billing-api/0-new-usage-api)



最近更新时间: 2026-07-29 17:33:24

* [接口概述](#接口概述)
* [接口信息](#接口信息)
* [请求参数](#请求参数)
* [鉴权方式](#鉴权方式)
* [响应格式](#响应格式)
* [错误码说明](#错误码说明)
* [使用示例](#使用示例)
* [注意事项](#注意事项)
* [AK/SK 签名实现参考](#aksk-签名实现参考)

# 接口概述 [#接口概述]

`/v3/stat/usage` 接口用于查询当前账号的大模型 Token 用量数据，按模型、按计费项返回时间序列用量。

主要能力：

* **多粒度查询**：支持天（`day`）与小时（`hour`）两种时间粒度。
* **时区支持**：通过 `timezone` 参数指定输出时间轴的时区，按所选时区返回每个时间桶。
* **灵活鉴权**：支持 API Key（`sk-` / `tk-`）与 AK/SK 两种鉴权方式。
  * API Key 鉴权：返回当前 Key 的用量。
  * AK/SK 鉴权：返回当前账号下所有 Key 的用量，按 API Key 分组，并返回每个 Key 的名称。
* **日期格式兼容**：AK/SK 鉴权下，时间参数另支持 v2 的 `YYYY-MM-DD` 日期格式（仅 `day` 粒度）。

# 接口信息 [#接口信息]

* **接口路径**: `GET /v3/stat/usage`
* **接口描述**: 查询用户用量数据，支持天粒度和小时粒度查询每一个模型的用量
* **鉴权方式**: 支持用 OAuth2.0 规范的无状态 [API Key](https://portal.qiniu.com/ai-inference/api-key)、或用当前账号的 [AK/SK 签名](https://portal.qiniu.com/developer/user/key) 来鉴权
* **数据返回**:
  * 采用 [**API Key 鉴权**](https://portal.qiniu.com/ai-inference/api-key) 时，返回当前 Key 的 Token 用量。
  * 采用 [**AK/SK 签名**](https://portal.qiniu.com/developer/user/key) 时（即管理员模式），返回当前账号下所有 Key 的用量，并按 API Key 分组（每个分组带 `name`）。
* **请求频率限制**: 同一 IP 每秒可请求 5 次
* **接入端点**: `https://api.qnaigc.com`

# 请求参数 [#请求参数]

## Query 参数 [#query-参数]

| 参数名         | 类型     | 必填 | 描述                                                            | 示例值                       |
| ----------- | ------ | -- | ------------------------------------------------------------- | ------------------------- |
| granularity | string | 是  | 时间粒度，支持 `day`（天）或 `hour`（小时）；兼容别名 `g`                         | day                       |
| start       | string | 是  | 开始时间，RFC3339 格式（AK/SK 鉴权另兼容 `YYYY-MM-DD`）                     | 2024-01-01T00:00:00+08:00 |
| end         | string | 是  | 结束时间，RFC3339 格式（AK/SK 鉴权另兼容 `YYYY-MM-DD`）                     | 2024-01-31T23:59:59+08:00 |
| timezone    | string | 否  | 输出时间轴时区，IANA 时区名称，默认 `Asia/Shanghai`                          | UTC                       |
| api\_key    | string | 否  | API Key。API Key 鉴权按请求头中的 Key 查询；AK/SK 鉴权返回该账号全部 Key，此参数一般无需传入 | sk-xxx                    |

## 时间格式说明 [#时间格式说明]

* **标准格式**: RFC3339 格式，如 `2024-01-01T10:30:00+08:00`
* **v2 兼容格式**: AK/SK 鉴权下，`start` / `end` 也支持 v2 的 `YYYY-MM-DD` 格式（仅 `day` 粒度生效，此时返回 v2 的扁平数组结构，见[响应格式](#aksk-v2-兼容格式yyyy-mm-dd)）

## 时间范围限制 [#时间范围限制]

> 以下限制适用于 RFC3339 格式的查询（v2 的 `YYYY-MM-DD` 格式不受此限制）。

* **天粒度查询**: 时间范围不能超过 1 个月（31 天）
* **小时粒度查询**: 时间范围不能超过 7 天

## timezone 参数说明 [#timezone-参数说明]

* 默认值为 `Asia/Shanghai`。
* 支持任意合法的 IANA 时区名称（如 `UTC`、`America/Los_Angeles`），接口按该时区返回每个时间桶的数值。
* 传入 `Local` 或无法识别的时区名称会返回 400 错误。

# 鉴权方式 [#鉴权方式]

## 1. API Key 鉴权 [#1-api-key-鉴权]

在请求头中添加：

```
Authorization: Bearer sk-xxxxxxxxxxxxxxxxx
```

**说明**:

* Token 须以 `sk-`（正式 Key）或 `tk-`（临时 Key）开头
* 仅返回当前 `API Key` 下的用量信息

## 2. AK/SK 鉴权 [#2-aksk-鉴权]

使用七牛云标准的 AK/SK 鉴权方式，签名实现请参考 [AK/SK 签名实现参考](#aksk-签名实现参考)：

```
Authorization: Qiniu <AccessKey>:<EncodedSign>
```

**说明**:

* 需要按照七牛云鉴权规范构造签名
* 返回该账号下所有 API Key 的用量，按 API Key 分组（每组带 `name`）
* 支持传统的 `YYYY-MM-DD` 日期格式参数（仅 `day` 粒度）

# 响应格式 [#响应格式]

接口统一响应体外壳：

```json
{ "status": true,  "data": ... }      // 成功
{ "status": false, "error": "..." }   // 失败
```

`data` 的具体结构随**鉴权方式**与**时间格式**不同而不同，分为以下三种情况。

## 1. API Key 鉴权（Bearer） [#1-api-key-鉴权bearer]

返回模型用量数组，每个元素为一个模型的用量明细。

```
{
  "status": true,
  "data": [
    {
      "id": "model_name",
      "name": "模型显示名称",
      "items": [
        {
          "name": "输入 Token",
          "unit": "kToken",
          "total": 1000,
          "categories": [
            {
              "name": "输入 Token",
              "values": [
                { "time": "2024-01-01T00:00:00Z", "value": 100 },
                { "time": "2024-01-02T00:00:00Z", "value": 150 }
              ]
            }
          ]
        },
        {
          "name": "输出 Token",
          "unit": "kToken",
          "total": 500,
          "categories": [
            {
              "name": "输出 Token",
              "values": [
                { "time": "2024-01-01T00:00:00Z", "value": 50 },
                { "time": "2024-01-02T00:00:00Z", "value": 75 }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

| 字段                                             | 类型      | 描述               |
| ---------------------------------------------- | ------- | ---------------- |
| status                                         | boolean | 请求状态，`true` 表示成功 |
| data                                           | array   | 用量数据列表           |
| data\[].id                                     | string  | 模型标识符            |
| data\[].name                                   | string  | 模型显示名称           |
| data\[].items                                  | array   | 计费项列表            |
| data\[].items\[].name                          | string  | 计费项名称            |
| data\[].items\[].unit                          | string  | 计费单位             |
| data\[].items\[].total                         | number  | 总量               |
| data\[].items\[].categories                    | array   | 分类数据             |
| data\[].items\[].categories\[].name            | string  | 分类名称             |
| data\[].items\[].categories\[].values          | array   | 时间序列数据           |
| data\[].items\[].categories\[].values\[].time  | string  | 时间点              |
| data\[].items\[].categories\[].values\[].value | number  | 用量值              |

## 2. AK/SK 鉴权（RFC3339 时间） [#2-aksk-鉴权rfc3339-时间]

返回按 API Key 分组的列表，每个元素包含一个 API Key 的用量及其名称。

```
{
  "status": true,
  "data": [
    {
      "api_key": "sk-xx*****xxxxx",
      "name": "我的测试 Key",
      "models": [
        {
          "id": "model_name",
          "name": "模型显示名称",
          "items": [
            {
              "name": "输入 Token",
              "unit": "kToken",
              "total": 1000,
              "categories": [
                {
                  "name": "输入 Token",
                  "values": [
                    { "time": "2024-01-01T00:00:00Z", "value": 100 }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

| 字段                      | 类型      | 描述                                                                 |
| ----------------------- | ------- | ------------------------------------------------------------------ |
| status                  | boolean | 请求状态，`true` 表示成功                                                   |
| data                    | array   | 按 API Key 分组的用量列表                                                  |
| data\[].api\_key        | string  | API Key（脱敏后，格式 `前5位*****后5位`）                                      |
| data\[].name            | string  | 该 API Key 的名称                                                      |
| data\[].models          | array   | 该 API Key 的模型用量列表，结构同 [API Key 鉴权](#1-api-key-鉴权bearer) 的 `data[]` |
| data\[].models\[].id    | string  | 模型标识符                                                              |
| data\[].models\[].name  | string  | 模型显示名称                                                             |
| data\[].models\[].items | array   | 计费项列表（结构同上）                                                        |

## AK/SK v2 兼容格式（YYYY-MM-DD） [#aksk-v2-兼容格式yyyy-mm-dd]

当 AK/SK 鉴权、`granularity=day`、且 `start` / `end` 为 v2 的 `YYYY-MM-DD` 格式时，返回**v2 的扁平数组结构**（无按 API Key 分组、无 `categories` 层）：

```
{
  "status": true,
  "data": [
    {
      "id": "model_name",
      "name": "模型显示名称",
      "items": [
        {
          "name": "输入 Token",
          "values": [
            { "value": 100, "time": "2024-01-01T00:00:00Z" }
          ],
          "unit": "kToken",
          "total": 1000
        }
      ]
    }
  ]
}
```

> 该格式为兼容 v2 而保留，不受时间范围上限与 `timezone` 参数约束，建议新接入方使用 RFC3339 格式。

## 错误响应 [#错误响应]

```
{ "status": false, "error": "错误信息描述" }
```

# 错误码说明 [#错误码说明]

| HTTP 状态码 | 错误类型                  | 描述                             |
| -------- | --------------------- | ------------------------------ |
| 400      | Bad Request           | 请求参数错误（时间格式 / 时间范围 / 时区 / 粒度等） |
| 401      | Unauthorized          | 鉴权失败                           |
| 500      | Internal Server Error | 服务器内部错误                        |

## 常见错误信息 [#常见错误信息]

* `"start parameter parse error, the format should be YYYY-MM-DDTHH:MM:SS±HH:MM(2024-01-01T10:30:00+08:00), but received ..."`: 开始时间格式错误
* `"end parameter parse error, ..."`: 结束时间格式错误
* `"end must be after start"`: 结束时间必须不早于开始时间
* `"当 granularity=day 时，时间范围不能超过 1 个月（31 天）"`: 天粒度查询时间范围超限
* `"当 granularity=hour 时，时间范围不能超过 7 天"`: 小时粒度查询时间范围超限
* `"无效的 timezone，需使用 IANA 时区名称，例如 UTC"`: `timezone` 取值为 `Local` 或无法识别
* `"invalid ak/sk sign"`: AK/SK 签名验证失败
* API Key 无效或格式错误：返回 401

# 使用示例 [#使用示例]

## 示例 1: API Key 查询天粒度数据 [#示例-1-api-key-查询天粒度数据]

```
curl -X GET "https://api.qnaigc.com/v3/stat/usage?granularity=day&start=2024-01-01T00:00:00%2B08:00&end=2024-01-31T23:59:59%2B08:00" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxx"
```

## 示例 2: AK/SK 查询小时粒度数据 [#示例-2-aksk-查询小时粒度数据]

```
curl -X GET "https://api.qnaigc.com/v3/stat/usage?granularity=hour&start=2024-01-01T00:00:00%2B08:00&end=2024-01-07T23:59:59%2B08:00" \
  -H "Authorization: Qiniu <AccessKey>:<EncodedSign>"
```

## 示例 3: 指定 UTC 时区输出 [#示例-3-指定-utc-时区输出]

```
curl -X GET "https://api.qnaigc.com/v3/stat/usage?granularity=day&start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&timezone=UTC" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxx"
```

## 示例 4: AK/SK v2 兼容日期格式（仅 day 粒度） [#示例-4-aksk-v2-兼容日期格式仅-day-粒度]

```
curl -X GET "https://api.qnaigc.com/v3/stat/usage?granularity=day&start=2024-01-01&end=2024-01-31" \
  -H "Authorization: Qiniu <AccessKey>:<EncodedSign>"
```

# 注意事项 [#注意事项]

1. **时区处理**: 建议使用 `+08:00` 时区或显式传入 `timezone=Asia/Shanghai`，避免时区转换问题；需要其他时区时通过 `timezone` 参数指定。
2. **数据时效**: 当天数据可能存在延迟，建议查询昨天及之前的数据。
3. **数据口径**: 返回值为同一模型各来源用量的合并值。
4. **限流保护**: 接口有频率限制（同一 IP 每秒 5 次），请合理控制请求频率。

# AK/SK 签名实现参考 [#aksk-签名实现参考]

```javascript
const crypto = require('crypto')

/**
 * URL 安全的 Base64 编码
 * @param {Buffer} buffer - 要编码的数据
 * @returns {string} - URL 安全的 Base64 字符串
 */
function urlSafeBase64Encode(buffer) {
  return buffer.toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_');
}

/**
 * 生成待签名的原始字符串
 * @param {Object} options - 请求参数
 * @param {string} options.method - HTTP 方法（大小写敏感）
 * @param {string} options.path - 请求路径
 * @param {string} [options.query] - 查询参数（不包含 ?）
 * @param {string} options.host - 主机名
 * @param {string} [options.contentType] - Content-Type
 * @param {Object} [options.headers] - X-Qiniu-* 开头的自定义头（可选）
 * @param {string} [options.body] - 请求体（可选）
 * @returns {string} - 待签名的字符串
 */
function generateSigningString(options) {
  const { method, path, query, host, contentType, headers, body } = options

  // 1. Method + 空格 + Path
  let signingStr = method.toUpperCase()

  // 2. 添加 Path 和 Query
  signingStr += ' ' + path
  if (query) {
    signingStr += '?' + query
  }

  // 3. 添加 Host
  signingStr += '\nHost: ' + host

  // 4. 添加 Content-Type（如果有）
  if (contentType) {
    signingStr += '\nContent-Type: ' + contentType
  }

  // 5. 添加 X-Qiniu-* 头部（如果有）
  if (headers) {
    // 按 key 的 ASCII 排序
    const sortedKeys = Object.keys(headers).sort()
    sortedKeys.forEach(key => {
      if (key.toLowerCase().startsWith('x-qiniu-')) {
        // 格式化 key：首字母和 - 后的字母大写，其余小写
        const formattedKey = key.split('-')
          .map((part, index) => {
            return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()
          })
          .join('-')
        signingStr += '\n' + formattedKey + ': ' + headers[key]
      }
    })
  }

  // 6. 添加两个连续换行符
  signingStr += '\n\n'

  // 7. 添加 Body（如果有且 Content-Type 不是 application/octet-stream）
  if (body && contentType && contentType !== 'application/octet-stream') {
    signingStr += body
  }

  return signingStr
}

/**
 * 生成七牛云管理凭证（Access Token）
 * @param {string} accessKey - 七牛云 AccessKey
 * @param {string} secretKey - 七牛云 SecretKey
 * @param {Object} requestOptions - 请求参数（同 generateSigningString）
 * @returns {string} - 管理凭证字符串
 */
function generateAccessToken(accessKey, secretKey, requestOptions) {
  // 1. 生成待签名的原始字符串
  const signingStr = generateSigningString(requestOptions);

  // 2. 使用 HMAC-SHA1 计算签名
  const hmac = crypto.createHmac('sha1', secretKey);
  hmac.update(signingStr);
  const sign = hmac.digest();

  // 3. 对签名进行 URL 安全的 Base64 编码
  const encodedSign = urlSafeBase64Encode(sign);

  // 4. 将 AccessKey 和 encodedSign 用冒号连接
  const accessToken = accessKey + ':' + encodedSign;

  return accessToken;
}

// 示例用法
const accessKey = '你的 AK'
const secretKey = '你的 SK'
const requestOptions = {
  method: 'GET',
  path: '/v3/stat/usage?granularity=day&start=2025-10-01T00:00:00%2B08:00&end=2025-10-31T23:59:59%2B08:00',
  host: 'api.qnaigc.com',
  contentType: '',
  body: ''
}
const accessToken = generateAccessToken(accessKey, secretKey, requestOptions)
console.log('生成的 Access Token:', accessToken)
```


# 大模型Token预估账单查询 (/products/aitokenapi/usage-billing-api/1-new-billing-api)



最近更新时间: 2026-07-29 17:32:47

* [接口概述](#接口概述)
* [接口信息](#接口信息)
* [认证方式](#认证方式)
* [接口 1：天/周/月消耗汇总](#接口-1天周月消耗汇总)
* [接口 2：消耗明细查询](#接口-2消耗明细查询)
* [响应字段说明](#响应字段说明)
* [错误码说明](#错误码说明)
* [使用示例](#使用示例)
* [注意事项](#注意事项)
* [AK/SK 签名实现参考](#aksk-签名实现参考)

# 接口概述 [#接口概述]

本组接口用于查询 API Key 的大模型消耗费用，包含两个接口：

* **接口 1**：查询 API Key 当天、本周、本月的消耗汇总。
* **接口 2**：查询 API Key 指定时间范围、按天或按月的消耗明细。

主要能力：

* **灵活鉴权**：支持 API Key（`sk-`）与 AK/SK 两种鉴权方式。
  * API Key 鉴权：返回当前 Key 的账单。
  * AK/SK 鉴权：返回当前账号下所有 Key 的账单，按 API Key 分组，并返回每个 Key 的名称。
* **时区支持**：通过 `timezone` 参数指定账单输出时区，按所选时区确定周期起止与明细日期。
* **多粒度明细**：明细查询支持按天（`day`）或按月（`month`）聚合。

# 接口信息 [#接口信息]

* **接入端点**: `https://api.qnaigc.com`
* **说明**: 接口中展示的花费均为原始标准价格，未经资源包等优惠换算
* **费用单位**: 人民币元，保留 2 位小数

# 认证方式 [#认证方式]

支持两种鉴权方式：

1. **AK/SK 签名认证**：使用七牛云标准的 [AK/SK](https://portal.qiniu.com/developer/user/key) 签名认证，返回当前账号下所有 API Key 的账单。
   ```
   Authorization: Qiniu <AccessKey>:<EncodedSign>
   ```
2. **API Key 认证**：使用正式 API Key（`sk-` 开头）认证，返回该 Key 的账单。
   ```
   Authorization: Bearer sk-xxxxxxxxxxxxxxxxx
   ```

> 临时 Key（`tk-` 开头）不允许调用本组接口，会返回 `temporary key is not allowed`（401）。签名实现请参考 [AK/SK 签名实现参考](#aksk-签名实现参考)。

# 接口 1：天/周/月消耗汇总 [#接口-1天周月消耗汇总]

查询 API Key 当天、本周、本月的消耗汇总。

* **接口路径**: `GET /v3/stat/usage/apikey/cost`

## 请求参数 [#请求参数]

| 参数名      | 类型     | 必填 | 描述                                    | 示例值   |
| -------- | ------ | -- | ------------------------------------- | ----- |
| type     | string | 是  | 统计周期：`day`（当天）、`week`（本周）、`month`（本月） | month |
| timezone | string | 否  | 账单输出时区，IANA 时区名称，默认 `Asia/Shanghai`   | UTC   |

周期口径按 `timezone` 计算：

* `day`：当天 0 点至当前时刻
* `week`：本周一 0 点至当前时刻（周一为一周的第一天）
* `month`：本月 1 号 0 点至当前时刻

## 响应示例 [#响应示例]

```
{
  "status": true,
  "data": {
    "timezone": "Asia/Shanghai",
    "api_keys": [
      {
        "api_key": "sk-7c***fbe19",
        "name": "我的测试 Key",
        "models": [
          {
            "model_id": "deepseek-v3",
            "items": [
              {
                "name": "deepseek-v3输入",
                "key": "input",
                "usage": { "count": 100.00, "unit": "k/tokens" },
                "fee": 1.00
              },
              {
                "name": "deepseek-v3输出",
                "key": "output",
                "usage": { "count": 100.00, "unit": "k/tokens" },
                "fee": 1.00
              }
            ],
            "total_fee": 2.00
          }
        ],
        "total_fee": 2.00
      }
    ]
  }
}
```

| 字段                                     | 类型     | 描述                                                |
| -------------------------------------- | ------ | ------------------------------------------------- |
| data.timezone                          | string | 账单输出时区                                            |
| data.api\_keys                         | array  | 按 API Key 分组的账单列表                                 |
| data.api\_keys\[].api\_key             | string | API Key（脱敏，格式 `前缀+前2位+***+后5位`，如 `sk-7c***fbe19`） |
| data.api\_keys\[].name                 | string | 该 API Key 的名称                                     |
| data.api\_keys\[].models               | array  | 按模型分组的账单                                          |
| data.api\_keys\[].models\[].model\_id  | string | 模型 ID                                             |
| data.api\_keys\[].models\[].items      | array  | 计费项列表（结构见 [响应字段说明](#响应字段说明)）                      |
| data.api\_keys\[].models\[].total\_fee | number | 该模型的总费用                                           |
| data.api\_keys\[].total\_fee           | number | 该 API Key 的总费用                                    |

# 接口 2：消耗明细查询 [#接口-2消耗明细查询]

查询 API Key 指定时间范围、按天或按月聚合的消耗明细。

* **接口路径**: `GET /v3/stat/usage/apikey/cost-detail`

## 请求参数 [#请求参数-1]

| 参数名         | 类型     | 必填 | 描述                                  | 示例值        |
| ----------- | ------ | -- | ----------------------------------- | ---------- |
| start\_date | string | 是  | 开始日期，格式 `YYYY-MM-DD`                | 2026-01-01 |
| end\_date   | string | 是  | 结束日期，格式 `YYYY-MM-DD`                | 2026-01-31 |
| grain       | string | 否  | 聚合粒度：`day`（按天，默认）或 `month`（按月）      | day        |
| timezone    | string | 否  | 账单输出时区，IANA 时区名称，默认 `Asia/Shanghai` | UTC        |

## 参数校验 [#参数校验]

* `start_date` / `end_date` 必填，格式须为 `YYYY-MM-DD`
* `start_date` 不能晚于 `end_date`
* 查询范围不能超过 **100 天**
* `grain` 仅支持 `day` 或 `month`

## 响应示例 [#响应示例-1]

响应结构随鉴权方式不同而不同。

### AK/SK 鉴权（返回账号下所有 API Key 的明细） [#aksk-鉴权返回账号下所有-api-key-的明细]

```
{
  "status": true,
  "data": {
    "period": "2025-01-01 ~ 2025-01-31",
    "grain": "day",
    "timezone": "Asia/Shanghai",
    "total_fee": 150.00,
    "api_keys": [
      {
        "api_key": "sk-7c***fbe19",
        "name": "我的测试 Key",
        "total_fee": 100.00,
        "bills": [
          {
            "date": "2025-01-01",
            "total_fee": 50.00,
            "models": [
              {
                "model_id": "deepseek-v3",
                "items": [
                  {
                    "name": "deepseek-v3输入",
                    "key": "input",
                    "usage": { "count": 100.00, "unit": "k/tokens" },
                    "fee": 1.00
                  }
                ],
                "total_fee": 1.00
              }
            ]
          }
        ]
      },
      {
        "api_key": "sk-3a***9b12",
        "name": "生产环境 Key",
        "total_fee": 50.00,
        "bills": [ ... ]
      }
    ]
  }
}
```

### API Key 鉴权（返回单个 API Key 的明细） [#api-key-鉴权返回单个-api-key-的明细]

```
{
  "status": true,
  "data": {
    "api_key": "sk-7c***fbe19",
    "name": "我的测试 Key",
    "period": "2025-01-01 ~ 2025-01-31",
    "grain": "day",
    "timezone": "Asia/Shanghai",
    "total_fee": 100.00,
    "bills": [
      {
        "date": "2025-01-01",
        "total_fee": 50.00,
        "models": [
          {
            "model_id": "deepseek-v3",
            "items": [
              {
                "name": "deepseek-v3输入",
                "key": "input",
                "usage": { "count": 100.00, "unit": "k/tokens" },
                "fee": 1.00
              }
            ],
            "total_fee": 1.00
          }
        ]
      },
      {
        "date": "2025-01-02",
        "total_fee": 50.00,
        "models": [ ... ]
      }
    ]
  }
}
```

# 响应字段说明 [#响应字段说明]

接口 1 与接口 2 共用以下计费项结构。

## 计费项 `items[]` [#计费项-items]

| 字段          | 类型     | 描述                                     |
| ----------- | ------ | -------------------------------------- |
| name        | string | 计费项名称（中文描述）                            |
| key         | string | 计费项标识（如 `input`、`output`）              |
| usage       | object | 用量信息                                   |
| usage.count | number | 用量数值（保留 2 位小数）                         |
| usage.unit  | string | 用量单位（如 `k/tokens`、`百字符`、`分钟`、`tokens`） |
| fee         | number | 该计费项费用（人民币元）                           |

## 明细账单 `bills[]`（接口 2） [#明细账单-bills接口-2]

| 字段         | 类型     | 描述                                                         |
| ---------- | ------ | ---------------------------------------------------------- |
| date       | string | 日期（`grain=day` 时为 `YYYY-MM-DD`；`grain=month` 时为 `YYYY-MM`） |
| total\_fee | number | 该时间点的总费用                                                   |
| models     | array  | 按模型分组的账单（`model_id` / `items` / `total_fee`）               |

## 其他公共字段 [#其他公共字段]

| 字段         | 类型     | 描述                                |
| ---------- | ------ | --------------------------------- |
| api\_key   | string | API Key（脱敏，格式 `前缀+前2位+***+后5位`）   |
| name       | string | 该 API Key 的名称                     |
| period     | string | 时间范围，格式 `YYYY-MM-DD ~ YYYY-MM-DD` |
| grain      | string | 聚合粒度：`day` 或 `month`              |
| timezone   | string | 账单输出时区                            |
| total\_fee | number | 总费用（人民币元）                         |

## 错误响应 [#错误响应]

```
{ "status": false, "error": "错误信息描述" }
```

# 错误码说明 [#错误码说明]

| HTTP 状态码 | 错误类型                  | 描述                                    |
| -------- | --------------------- | ------------------------------------- |
| 400      | Bad Request           | 请求参数错误（type / 日期格式 / 时间范围 / 粒度 / 时区等） |
| 401      | Unauthorized          | 鉴权失败（含临时 Key 被拒绝）                     |
| 500      | Internal Server Error | 服务器内部错误                               |

## 常见错误信息 [#常见错误信息]

**接口 1：**

* `"invalid type, must be day/week/month"`: `type` 取值非法
* `"无效的 timezone，需使用 IANA 时区名称，例如 UTC"`: `timezone` 取值为 `Local` 或无法识别

**接口 2：**

* `"start_date and end_date are required"`: 缺少日期参数
* `"invalid start_date format, expected 2006-01-02"` / `"invalid end_date format, expected 2006-01-02"`: 日期格式错误
* `"start_date cannot be after end_date"`: 开始日期晚于结束日期
* `"date range cannot exceed 100 days"`: 查询范围超过 100 天
* `"invalid grain, must be day or month"`: `grain` 取值非法
* `"无效的 timezone，需使用 IANA 时区名称，例如 UTC"`: `timezone` 取值为 `Local` 或无法识别

**鉴权类（两接口通用）：**

* `"temporary key is not allowed"`: 使用了临时 Key（`tk-`）
* `"invalid api key or aksk"`: API Key 或 AK/SK 无效
* `"missing authorization header"`: 缺少鉴权信息

# 使用示例 [#使用示例]

## 示例 1：查询本月消耗汇总（API Key） [#示例-1查询本月消耗汇总api-key]

```
curl --location "https://api.qnaigc.com/v3/stat/usage/apikey/cost?type=month" \
  --header "Authorization: Bearer sk-xxxxxxxxxxxxxxxxx"
```

## 示例 2：查询本周消耗汇总（AK/SK，指定 UTC 时区） [#示例-2查询本周消耗汇总aksk指定-utc-时区]

```
curl --location "https://api.qnaigc.com/v3/stat/usage/apikey/cost?type=week&timezone=UTC" \
  --header "Authorization: Qiniu <AccessKey>:<EncodedSign>"
```

## 示例 3：按天查询消耗明细（API Key） [#示例-3按天查询消耗明细api-key]

```
curl --location "https://api.qnaigc.com/v3/stat/usage/apikey/cost-detail?start_date=2026-01-01&end_date=2026-01-31&grain=day" \
  --header "Authorization: Bearer sk-xxxxxxxxxxxxxxxxx"
```

## 示例 4：按月查询消耗明细（AK/SK） [#示例-4按月查询消耗明细aksk]

```
curl --location "https://api.qnaigc.com/v3/stat/usage/apikey/cost-detail?start_date=2026-01-01&end_date=2026-03-31&grain=month" \
  --header "Authorization: Qiniu <AccessKey>:<EncodedSign>"
```

# 注意事项 [#注意事项]

1. **价格口径**: 返回费用为原始标准价格，不含资源包等优惠。
2. **时区处理**: 周期起止与明细日期均按 `timezone` 计算，建议按实际业务所在时区传入；不传时默认 `Asia/Shanghai`。
3. **数据时效**: 当天数据可能存在延迟，建议查询昨天及之前的数据。
4. **Key 类型**: 仅正式 Key（`sk-`）可调用，临时 Key（`tk-`）会被拒绝。
5. **范围限制**: 明细查询最大跨度为 100 天。

# AK/SK 签名实现参考 [#aksk-签名实现参考]

```javascript
const crypto = require('crypto')

/**
 * URL 安全的 Base64 编码
 * @param {Buffer} buffer - 要编码的数据
 * @returns {string} - URL 安全的 Base64 字符串
 */
function urlSafeBase64Encode(buffer) {
  return buffer.toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_');
}

/**
 * 生成待签名的原始字符串
 * @param {Object} options - 请求参数
 * @param {string} options.method - HTTP 方法（大小写敏感）
 * @param {string} options.path - 请求路径
 * @param {string} [options.query] - 查询参数（不包含 ?）
 * @param {string} options.host - 主机名
 * @param {string} [options.contentType] - Content-Type
 * @param {Object} [options.headers] - X-Qiniu-* 开头的自定义头（可选）
 * @param {string} [options.body] - 请求体（可选）
 * @returns {string} - 待签名的字符串
 */
function generateSigningString(options) {
  const { method, path, query, host, contentType, headers, body } = options

  // 1. Method + 空格 + Path
  let signingStr = method.toUpperCase()

  // 2. 添加 Path 和 Query
  signingStr += ' ' + path
  if (query) {
    signingStr += '?' + query
  }

  // 3. 添加 Host
  signingStr += '\nHost: ' + host

  // 4. 添加 Content-Type（如果有）
  if (contentType) {
    signingStr += '\nContent-Type: ' + contentType
  }

  // 5. 添加 X-Qiniu-* 头部（如果有）
  if (headers) {
    // 按 key 的 ASCII 排序
    const sortedKeys = Object.keys(headers).sort()
    sortedKeys.forEach(key => {
      if (key.toLowerCase().startsWith('x-qiniu-')) {
        // 格式化 key：每个单词首字母大写，其余小写
        const formattedKey = key.split('-')
          .map((part) => {
            return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()
          })
          .join('-')
        signingStr += '\n' + formattedKey + ': ' + headers[key]
      }
    })
  }

  // 6. 添加两个连续换行符
  signingStr += '\n\n'

  // 7. 添加 Body（如果有且 Content-Type 不是 application/octet-stream）
  if (body && contentType && contentType !== 'application/octet-stream') {
    signingStr += body
  }

  return signingStr
}

/**
 * 生成七牛云管理凭证（Access Token）
 * @param {string} accessKey - 七牛云 AccessKey
 * @param {string} secretKey - 七牛云 SecretKey
 * @param {Object} requestOptions - 请求参数（同 generateSigningString）
 * @returns {string} - 管理凭证字符串
 */
function generateAccessToken(accessKey, secretKey, requestOptions) {
  // 1. 生成待签名的原始字符串
  const signingStr = generateSigningString(requestOptions);

  // 2. 使用 HMAC-SHA1 计算签名
  const hmac = crypto.createHmac('sha1', secretKey);
  hmac.update(signingStr);
  const sign = hmac.digest();

  // 3. 对签名进行 URL 安全的 Base64 编码
  const encodedSign = urlSafeBase64Encode(sign);

  // 4. 将 AccessKey 和 encodedSign 用冒号连接
  return accessKey + ':' + encodedSign;
}

// 示例：调用消耗汇总接口
const accessKey = '你的 AccessKey'
const secretKey = '你的 SecretKey'
const requestOptions = {
  method: 'GET',
  path: '/v3/stat/usage/apikey/cost',
  query: 'type=month',
  // 调用明细接口：
  // path: '/v3/stat/usage/apikey/cost-detail',
  // query: 'start_date=2026-01-01&end_date=2026-01-31&grain=day',
  host: 'api.qnaigc.com'
}
const accessToken = generateAccessToken(accessKey, secretKey, requestOptions)
console.log('Access Token:', accessToken)

// 实际请求
fetch('https://api.qnaigc.com/v3/stat/usage/apikey/cost?type=month', {
  headers: { 'Authorization': 'Qiniu ' + accessToken }
}).then(res => res.json()).then(console.log)
```


# Agentic AI 干货！DeepSeek + OpenAI SDK 构建 Agent 实战 (/products/aitokenapi/agent/1-new-deepseek-with-openai-sdk-build-agent)



最近更新时间: 2026-04-29 17:50:57

![企业微信截图\_5a51b707-77ba-4e6c-8228-8.jpg](/docs-assets/products/aitokenapi/%285-best-practices%29/agent/1-new-deepseek-with-openai-sdk-build-agent/FprbB7n1EDOe2e3EWc8O8dGeWOoP-06cf3f9b0189.webp)

> 在 GTC2025 上英伟达定义了 AI 的四个发展阶段：感知式 AI、生成式 AI、智能体 AI、物理世界 AI。当前正处于二、三阶段。

本文档基于 OpenAI 最新发布的 agents SDK 和 [七牛云 AI 推理 API](/products/aitokenapi/inference-api/1-real-time-ai-interface-api)，详细介绍了由 DeepSeek-R1 推理能力驱动的多智能体系统示例，实现了各个智能体的明确分工协作。

以下展示了基于"规划-执行"模式的多智能体系统实现过程：通过将任务处理流程分解为规划层、执行层，实现了智能体的职责分离，同时充分利用了 DeepSeek-R1 等模型在推理方面的优势，规避了其在函数调用等方面的限制。系统还实现了反思机制，从而提高了系统的可靠性和稳定性。

![编组.png](/docs-assets/products/aitokenapi/%285-best-practices%29/agent/1-new-deepseek-with-openai-sdk-build-agent/FtlkYCQNtgn_nkk32VPAtmfoqUPF-d040d5e565a0.webp)

## 安装指南 [#安装指南]

本教程基于 Python3，请提前安装相关环境。

使用以下命令安装依赖包：

```bash
pip install openai-agents
```

## 基础使用流程 [#基础使用流程]

系统使用包含以下两步：

1. **Agent 定义**
2. **Agent 执行**（输入用户问题）

基础示例代码如下：

```python
from agents import Agent, Runner, set_default_openai_client, set_default_openai_api, set_tracing_disabled
from openai import AsyncOpenAI

# 配置 七牛 API（请替换为实际的 API Key）
custom_client = AsyncOpenAI(base_url="https://api.qnaigc.com/v1", api_key="sk-xxxxx")
set_default_openai_client(custom_client)
# 下面两行很重要，含泪踩过的坑！
set_default_openai_api("chat_completions")
set_tracing_disabled(True)

# Agent 定义示例
libai_agent = Agent(
    name="libai",
    model="deepseek-r1",  # 使用实际部署的模型名称
    instructions="模拟李白风格，根据用户输入创作诗歌。"
)

# 执行 Agent 并传入查询
result = Runner.run_sync(libai_agent, "请创作一首描写科举考生赴京场景的诗。")
print(result.final_output)
```

执行后可能输出如下：

```
《赴京举子》
万里风尘逐帝京，八方士子共云程。
墨香暗度关山月，剑气遥连北斗星。
金殿未登龙虎榜，青衫已染凤凰名。
何须更问功成事，醉卧长安笑公卿。

注：本诗采用李白豪放飘逸的笔法，描绘了举子千里赴京的宏大场景。诗中运用"墨香剑气"暗喻文韬武略，以"龙虎榜"与"凤凰名"展现功名与气节的对比，末联"醉卧长安"体现了对科举制度的超然态度，同时也反映了盛唐气象，延续了李白诗作中特有的浪漫气质与历史纵深感。
```

以上展示了系统的基本工作流程：Agent 定义、执行两个步骤。

***

## 复杂任务 [#复杂任务]

在处理复杂任务时，系统可能面临以下技术挑战：

1. 语言模型能力要求：需要同时具备推理规划和函数调用能力
2. 提示词复杂度：需要同时处理规划制定、函数调用和结果输出
3. 缺乏系统性规划：每次 Function Call 后重新思考，缺乏连贯的执行计划

（**注1：七牛 DeepSeek-V3-Tool 对齐 DeepSeek 官方，支持 Function Call**）

（**注2：官方 DeepSeek-R1 目前尚未支持函数调用功能**）

解决方案：采用多智能体分工协作模式，将单一大型语言模型拆分为多个专门化的智能体。每个智能体负责特定任务，便于系统优化和评估。

我们遵循"智能体职责分离"原则，实现模块化设计，提高系统可维护性和可扩展性。

（由于 DeepSeek V3 官方版 Function Call 功能效果不稳定，会出现循环调用、空回复的情况，且用户问题可能很复杂，因此设计规划智能体和分配智能体两层结构，兼顾 r1 的思考能力和规避 v3 的不稳定。）

下面大致介绍一下工作流程：

系统工作流程示意：

```
用户输入： "please show me the menu"
       │
       ▼
规划智能体【系统管理器】（Deepseek-R1，擅长推理规划）
  分析用户输入并确定调用策略：
  "调用智能体：菜单管理智能体
  用户原始输入：please show me the menu"
       │
       ▼
分配智能体【服务管理器】（Deepseek-V3-Tool，支持 Function Call）
  接收指令并执行：
  -> llm function call：show_order_menu
       │
       ▼
  获取菜单数据：
  -> 执行 show_order_menu 函数
       │
       ▼
语言处理智能体【多语言适配器】（Deepseek-V3-Tool，根据用户语言选择对应处理模块）
  -> 如英文翻译agent：english_translator
       │
       ▼
  返回处理后的菜单数据（包含处理模块标识）
       │
       ▼
  向用户返回处理结果
```

## 进阶实现示例 [#进阶实现示例]

以下代码展示了多智能体协作系统的完整实现流程：

```python
import asyncio
from agents import Agent, Runner, set_default_openai_client, set_default_openai_api, set_tracing_disabled, function_tool
from openai import AsyncOpenAI

custom_client = AsyncOpenAI(base_url="https://api.qnaigc.com/v1", api_key="sk-xxxxx")
set_default_openai_client(custom_client)
set_default_openai_api("chat_completions")
set_tracing_disabled(True)


# 定义英文翻译Agent
english_translator = Agent(
    name="English translator",
    model="deepseek-v3-tool",
    instructions="你处于一个多Agent工作流中，职责是英文翻译，将收到任何文本（包括tool中）返回成英文结果。（请务必遵从以上原则，否则会破坏工作流）最后你要以你的身份来作为结尾告诉我这是来自谁的答复，如This response comes from the English translator.",
)

# 定义中文翻译Agent
chinese_translator = Agent(
    name="Chinese translator",
    model="deepseek-v3-tool",
    instructions="你作为中文翻译，将收到任何文本返回成中文结果。你要以你的身份来作为结尾告诉我来自谁的答复",
)

# 定义菜单展示工具
@function_tool
def show_order_menu():
    menu='''
    1. 美式咖啡 ￥10
    2. 拿铁 ￥15
    3. 卡布奇诺 ￥15
    4. 摩卡 ￥20
    5. 热巧克力 ￥15
    6. 红茶 ￥10
    7. 松饼 ￥10
    8. 蛋糕 ￥15
    '''
    print(menu)
    return "你向顾客展示了"+menu

# 定义执行 Agent
agent_dispatcher = Agent(
    name="dispatcher",
    model="deepseek-v3-tool",
    instructions="你是副总管，请根据用户的问题调用相关工具，拿到相关工具结果后，再根据用户的文本语言选择合适的翻译Agent帮助你回复",
    handoffs=[chinese_translator,english_translator],
    tools=[show_order_menu]
)

# 定义规划 Agent，只负责根据用户问题分配任务，不直接回答问题
agent_planner = Agent(
    name="planner",
    model="deepseek-r1",
    instructions=(
        "你现在处于多智能体协作流程中，身份是 Agent 总管。你的任务是："
        "根据用户的问题分析并决定调用哪种功能，告诉副总管应该调用哪个Agent或tool处理用户的问题，最后加入用户原文"
        "仅输出该指令文本，不包含任何具体答案。示例如：Agent_planner->Agent_dispatcher: @MenuAgent @MenuTool: plz show me the menu"
    ),
)
async def main():
    reply=None
    # 用户提问
    question = "plz show me the menu"

    # 总管处理用户输入，输出分配指令
    orderFromPlanner = await Runner.run(agent_planner, question)
    print("planner输出：", orderFromPlanner.final_output)

    # 副总管根据总管指令调用工具并进行翻译
    result = await Runner.run(agent_dispatcher, input=orderFromPlanner.final_output)
    print("dispatcher输出：", result.final_output)


if __name__ == "__main__":
    asyncio.run(main())
```

## 系统反思机制 [#系统反思机制]

由于大模型有概率产生幻觉，导致工作流出错，因此，这里增加了反思 Agent，以提高工作流稳定性。代码如下：

```python

agent_reflect = Agent(
    name="reflect",
    model="deepseek-r1",
    instructions=(
        "你现在负责整理多智能体的输出，生成最终回复。"
        "输入包含各 Agent 的输出和用户问题。"
        "如果发现流程异常，有两种情况："
        "1. 可通过重新生成问题并执行流程解决，请在开头输出RETRY加重试次数1（若原文中已包含重试次数，则重试次数+1）便于程序做判断，接下来你的输出会作为新的用户输入，请你根据用户问题（保留原文原意原语音）重新生成易于命中的问题。"
        "2. 工作流或重试次数超过3次，请在开头输出ERROR，并在接下来分析原因。"
    ),
)

async def main():
    response = None
    # 用户输入
    query = "plz show me the menu "

    while True:

        # 总管处理用户输入，输出分配指令
        orderFromPlanner = await Runner.run(agent_planner, query)
        print("总管输出：", orderFromPlanner.final_output)

        # 副总管根据总管指令调用工具并进行翻译
        result = await Runner.run(agent_dispatcher, input=orderFromPlanner.final_output)
        print("结果输出：", result.final_output)


        # 响应管理器生成最终输出
        response = await Runner.run(agent_reflect, input="用户输入:" + query + "\n系统指令:" + orderFromPlanner.final_output + "\n执行结果:" + result.final_output)

        if response.final_output.startswith("RETRY"):
            print("重试")
            query = response.final_output
        else:
            print("反思结果：", response.final_output)
            break
```

异常处理示例：

当出现异常如下文，系统将触发反思机制：

```md
总管输出： Agent_planner->Agent_dispatcher: @MenuAgent @MenuTool: plz show me the menu
plz show me the menu

    1. 美式咖啡 ￥10
    2. 拿铁 ￥15
    3. 卡布奇诺 ￥15
    4. 摩卡 ￥20
    5. 热巧克力 ￥15
    6. 红茶 ￥10
    7. 松饼 ￥10
    8. 蛋糕 ￥15

结果输出： {'assistant': '中文翻译'} #这里由于幻觉走到了中文翻译，所以输出的是中文翻译，在反思agent中检测出来并优化重试
总管输出： Agent_planner->Agent_dispatcher: @MenuAgent @MenuTool: plz show me the current menu items and prices in English

    1. 美式咖啡 ￥10
    2. 拿铁 ￥15
    3. 卡布奇诺 ￥15
    4. 摩卡 ￥20
    5. 热巧克力 ￥15
    6. 红茶 ￥10
    7. 松饼 ￥10
    8. 蛋糕 ￥15

结果输出： You have displayed the following items to the customer:
1. Americano - ¥10
2. Latte - ¥15
3. Cappuccino - ¥15
4. Mocha - ¥20
5. Hot Chocolate - ¥15
6. Black Tea - ¥10
7. Muffin - ¥10
8. Cake - ¥15
This response comes from the English translator.
反思结果： The current menu items and prices in English are as follows:
1. Americano - ¥10
2. Latte - ¥15
3. Cappuccino - ¥15
4. Mocha - ¥20
5. Hot Chocolate - ¥15
6. Black Tea - ¥10
7. Muffin - ¥10
8. Cake - ¥15
Let me know if you need further assistance!
```


# 聊天客户端 Cherry Studio 配置说明 (/products/aitokenapi/cherry-studio/0-tools-cherry-studio-configuration-instructions)



最近更新时间: 2026-03-26 11:12:12

Cherry Studio 官方地址：[https://cherry-ai.com/download](https://cherry-ai.com/download)

本教程主要指导大家如何将七牛的推理服务配置到 **Cherry Studio** 客户端中。

Cherry Studio AI 是一款强大的多模型AI 助手，支持iOS、macOS 和Windows 平台。快速切换多个先进的 LLM 模型，提升工作学习效率。

### 前置准备 [#前置准备]

* [如何获取七牛云 Token API 密钥](/products/aitokenapi/0-how-to-get-api-key)

### **配置说明** [#配置说明]

1. 在添加的供应商中选择七牛，填入 API 密钥和服务地址

   1. API 密钥为上方获取到的密钥
   2. API 地址选择：[https://api.qnaigc.com](https://api.qnaigc.com/)

   ![image.png](/docs-assets/products/aitokenapi/%284-tools%29/cherry-studio/0-tools-cherry-studio-configuration-instructions/Fl8teWYPp3n7edc-nhvZFz3NIPfc-ef9683b04e17.webp)

2. 添加模型

   1. 模型 ID 可以填写我们支持的几个模型：
      1. deepseek-r1
      2. deepseek-v3
      3. 更多请参考：[七牛云模型广场](https://portal.qiniu.com/ai-inference/model)
   2. 模型名称根据情况填写
   3. 分组名称根据情况填写

   ![image.png](/docs-assets/products/aitokenapi/%284-tools%29/cherry-studio/0-tools-cherry-studio-configuration-instructions/FreYUxD9QK7SjDnJdmVnl8Hw7t-B-f20b63f31631.webp)

3. 测试配置效果

   1. 点击配置界面的检查按钮，查看配置是否正确

   ![image.png](/docs-assets/products/aitokenapi/%284-tools%29/cherry-studio/0-tools-cherry-studio-configuration-instructions/FvkNYo1TCojtEwWwjcKIrD4lr6Kv-095530f85c4e.webp)

4. 在会话中切换到七牛的模型

   ![image.png](/docs-assets/products/aitokenapi/%284-tools%29/cherry-studio/0-tools-cherry-studio-configuration-instructions/FmlqrN7C8WeZdcqKvMsm_nTkGMNT-b59e1b476243.webp)

5. 在会话中测试效果

   ![image.png](/docs-assets/products/aitokenapi/%284-tools%29/cherry-studio/0-tools-cherry-studio-configuration-instructions/FlznVb1yqsSqWXx35VHv9We__wFD-e38d3d287b8a.webp)

🎉🎉 恭喜你，到这里已经配置成功啦！！


# Hermes Agent配置接入AI (/products/aitokenapi/ai-hermes/13498-Hermes-Agent)



最近更新时间: 2026-08-26 16:08:29

## **1、安装HermesAgent** [#1安装hermesagent]

## **2、成功安装后，输入以下命令开始配置调用七牛模型** [#2成功安装后输入以下命令开始配置调用七牛模型]

hermes model

### **`注意：`** [#注意]

### 1、API base URL填写：`https://api.qnaigc.com/v1` 或 `https://anthropic.qnaigc.com` [#1api-base-url填写httpsapiqnaigccomv1-或-httpsanthropicqnaigccom]

### 2、API key在 [七牛控制台](https://portal.qiniu.com/ai-inference/api-key) 查询获取； [#2api-key在-七牛控制台-查询获取]

### 3、模型ID可以在七牛控制台 [模型广场](https://portal.qiniu.com/ai-inference/model) 查询 [#3模型id可以在七牛控制台-模型广场-查询]

![image.png](/docs-assets/products/aitokenapi/%284-tools%29/ai-hermes/13498-Hermes-Agent/FtPEnjw990nfEHCPrrBzynYzQWx9-f8abdba6ac4f.webp)
![image.png](/docs-assets/products/aitokenapi/%284-tools%29/ai-hermes/13498-Hermes-Agent/Fl6MB5JdzdeoSvbWz6XLB03VE8ej-041499143358.webp)
![image.png](/docs-assets/products/aitokenapi/%284-tools%29/ai-hermes/13498-Hermes-Agent/FlKmLucjn8YlRuuOEhXlE3B6LFCq-f9c9425592d6.webp)

**`说明：Context length配置可以直接回车，使用默认值；配置信息默认保存位置：.hermes/config.yaml`**

## **3、 运行Hermes Agent** [#3-运行hermes-agent]

在终端中输入以下命令，回车即可
hermes
![image.png](/docs-assets/products/aitokenapi/%284-tools%29/ai-hermes/13498-Hermes-Agent/FubcA1A1lg6aNnMZoRScFH5kYzKK-f902c8248b16.webp)


# DeepSeek Harness配置接入AI (/products/aitokenapi/ai-hermes/13550-deepseek-harness-configuration-access-ai)



最近更新时间: 2026-08-26 16:08:23

## **1、安装DeepSeek Harness** [#1安装deepseek-harness]

DeepSeek Harness官方文档：[https://www.deepseek.com/harness/](https://www.deepseek.com/harness/)

```bash
1）、一键使用
npx @deepseek-ai/dsh web

2）、源站安装
git clone https://github.com/deepseek-ai/deepseek-harness
```

## **2、安装完成后，打开工具，在 设置 - 模型 - 自定义设置 中配置七牛AI** [#2安装完成后打开工具在-设置---模型---自定义设置-中配置七牛ai]

![DeepSeek Harness配置.png](/docs-assets/products/aitokenapi/%284-tools%29/ai-hermes/13550-deepseek-harness-configuration-access-ai/Fu1FDQ3Tn6_UBQhJ457EXmKxsUG8-8cd5a9c5af7a.webp)

## **说明**： [#说明]

1、API地址为：`https://api.qnaigc.com/v1`
2、模型目录：设置需要使用的七牛模型ID；模型ID在七牛控制台 [模型广场](https://portal.qiniu.com/ai-inference/model) 查询
3、API-KEY在 [七牛控制台](https://portal.qiniu.com/ai-inference/api-key) 查询获取
4、DeepSeek Harness工具配置调用第三方模型官方说明文档：[配置自定义模型](https://deepseek-harness.github.io/deepseek-harness/guide/providers#%E6%B7%BB%E5%8A%A0%E8%87%AA%E5%AE%9A%E4%B9%89%E6%8F%90%E4%BE%9B%E6%96%B9)


# 基本信息 (/products/cdn/configuration-management-fusion/0-the-basic-information)



最近更新时间: 2026-08-12 17:58:17

您可以登录**七牛管理控制台**选择**CDN控制台**,可以在控制台中查看域名的基本信息，包括加速域名、CNAME、创建时间、修改时间、域名状态、域名类型、协议、使用场景、覆盖信息、IP协议。

<br />

# 操作说明 [#操作说明]

登录**七牛开发者平台**后，进入**CDN控制台**，选择【域名管理】，点击【配置】：

<img src="/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/0-the-basic-information/FhE4z3hd-dB3-8ur3LuIi3hRNK5-de1fd1dd0a3d.webp" width="800" />

<img />

进入域名配置界面，可以查阅包括加速域名、CNAME、创建时间、修改时间、域名状态、域名类型、协议、使用场景、覆盖信息等基本信息。

<img src="/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/0-the-basic-information/Fsd57hAPXTkm5T4359nHbJNC7xuz-03efea4e9e81.webp" width="800" />

<img />


# 回源配置 (/products/cdn/configuration-management-fusion/1-back-to-the-source-configuration)



最近更新时间: 2026-08-31 17:21:55

您可以登录**七牛管理控制台**选择**CDN控制台**,可以在控制台中查看域名的回源配置信息及进行相关配置修改。

<br />

# 操作说明 [#操作说明]

登录**七牛管理控制台**后，进入**CDN控制台**，选择【域名管理】，点击【配置】：

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/1-back-to-the-source-configuration/Fgk_-sqyca-rAzopvUInfzcuPQ42-80fbcd1d2e0d.webp)

进入域名配置界面，点击【修改配置】进行回源配置的修改。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/1-back-to-the-source-configuration/FkaKesh0T7g0kCIZqZcuJzbny26x-b41df750807a.webp)

### 基础配置 [#基础配置]

回源方式支持七牛云存储、源站域名、IP地址、高级设置四种模式。

* 七牛云存储：选定七牛云存储对应的bucket作为CDN回源的源站。
  ![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/1-back-to-the-source-configuration/FrYsZ11KcLJVgCdMCFra7Od2t3BT-9fb39bd48725.webp)

* 源站域名：设置指定域名作为CDN回源的源站，源站的域名需要与加速域名不一致。
  ![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/1-back-to-the-source-configuration/FrJhhsy6xp225TWM-7CqZkybYDUg-b34359baf6fd.webp)

* IP地址：设置IP作为CDN回源的源站，支持配置多个IP；回源采用轮询方式，首次选择配置的第一个IP进行回源，当发现某一源站IP异常时，将跳过此IP并进入惩罚时间，屏蔽5秒。
  ![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/1-back-to-the-source-configuration/FtDohMDiweWLUO9D0N8GiLe8v-uk-1d9fd5c4f9c4.webp)

* 高级配置：支持配置多个回源的主备线路，可以是域名或是IP，并支持权重配置。
  说明：
  （1）权重：请求概率=权重/权重总和，eg：有两个主线路A和B，A权重1 和 B权重3，那么四次请求，1次是A，3次是B。
  （2）回源地址不能与加速域名相同。
  ![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/1-back-to-the-source-configuration/FmNuiai4eDioACErzMHBnPaIEH2a-65e68db7a6ae.webp)

### 回源host [#回源host]

回源host：是指 CDN 节点在回源过程中，在源站访问的站点域名。
源站为七牛云存储，回源HOST无需填写，源站为域名、IP、以及高级回源模式，回源 HOST默认是加速域名，支持自定义配置。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/1-back-to-the-source-configuration/FtK30bCwnduQIYsKGkdilPha54Bn-e101dae59ea5.webp)

### 回源协议 [#回源协议]

回源协议：即请求回源的协议，支持选择HTTP、遵循请求协议、HTTPS三种方式。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/1-back-to-the-source-configuration/FvWb2WMPATbAvLZH4hudvNpewobW-1ce7f3e86e50.webp)

### 去参数回源 [#去参数回源]

去参数回源：请求回源时去除URL「?」后的参数进行回源，支持去除所有参数和去除指定参数两种方式。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/1-back-to-the-source-configuration/FtIGdiBVPa0a1oQFxjrBSTZ_mA-p-f3264a279a9a.webp)

### 回源验证 [#回源验证]

回源验证：保证源站的高可用，只有源站测试通过才能继续创建域名。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/1-back-to-the-source-configuration/Fuh_1MWqGhtZK_kXv-m7KjHAF7ji-5d9550f1011e.webp)

### Range回源 [#range回源]

Range回源：开启此功能，有助于减少大文件分发时回源消耗并缩短响应时间，但是此功能需要源站支持Range请求。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/1-back-to-the-source-configuration/FogCbTCBh1L69gp3sVl01efC-T3T-cc4da1a3097d.webp)

### 回源超时 [#回源超时]

回源超时：开启回源超时配置，可自定义调整 CDN 回源节点到源站的超时时间，TCP 建连超时默认为 5s，可设置时间范围5～30秒；HTTP 读取超时时间默认为 30s，可设置时间范围5～120秒。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/1-back-to-the-source-configuration/FmXYqFrbH0BvRadDj-PmdGMUIAgY-31ae97394b95.webp)


# 缓存配置 (/products/cdn/configuration-management-fusion/2-cache-configuration)



最近更新时间: 2026-08-12 17:58:17

缓存过期配置是指配置 CDN 加速节点在缓存您的业务内容时遵循的一套过期规则，您可以登录**七牛管理控制台**选择**CDN控制台**,可以在控制台中查看域名的缓存配置信息并进行修改。

<br />

# 操作说明 [#操作说明]

登录**七牛管理控制台**后，进入**CDN控制台**，选择【域名管理】，点击【配置】：

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/2-cache-configuration/FjwCPyTKzkCI88de-oBxsT6idkuU-77b524fd0d09.webp)

进入域名配置界面，点击【修改配置】进行缓存配置的修改。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/2-cache-configuration/FqcGYGybigEdCOumDAUP4svp72qt-7a4c3f8dd689.webp)

### 基础配置 [#基础配置]

缓存的基础配置分为自定义、遵循源站两种类型

* 自定义：自定义指定的资源内容的缓存过期规则，默认为全局配置缓存30天，支持按照文件后缀、目录规则进行配置。

（1）后缀：必须以「.」(英文点)开始，多个后缀请用「;」(英文分号)隔开，例如(.png;.jpg;.gif)。

（2）路径：必须以「/」(英文斜杠)开始，多个路径请用「;」(英文分号)隔开，例如: (/a/b/c;/d/e/f;/h/i/j) ，路 径中不能包含「.」，也不能以「/」结尾。

（3）缓存规则最多可配置15条。

（4）1条缓存规则中，最多10个后缀/路径，「;」(英文分号)隔开。

（5）时间单位：分/小时/天，只能输入整数，最大值为 365 天。

（6）0 代表不缓存。

（7）按从上至下顺序，采取优先匹配原则。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/2-cache-configuration/Fp-U5Cm1r_ZHxjEFeUzWpFWTWeat-2b2228aeccbd.webp)

推荐配置：
（1）.jpg;.jpeg;.png;.bmp;.gif;.webp;.ico  图片类型缓存1天。

（2）.js;.css;.txt;.xml;.shtml;.html;.htm;.csv;.bat  文本类型缓存1天。

（3）.m3u8 m3u8类型缓存1小时。

（4).avi;.mkv;.mp4;.mov;.flv;.rm;.rmvb;.swf;.mp3;.wav;.wmv;.rmi;.aac 音视频类型缓存7天。

（5）.exe;.deb;.ipa;.apk;.sis;.psd;.dat 大文件类型缓存7天。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/2-cache-configuration/FloCOsF_kTNVlluzlMNyChgDB9Kp-e5f8f768ee4c.webp)

* 遵循源站：所有全部资源内容的缓存过期时间将与源站同步。
  ![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/2-cache-configuration/FlLWoIGQgXfee-JqlfFFyfbqzISZ-2cbd18ebe990.webp)

### URL参数 [#url参数]

* 保留所有参数：资源缓存时保留 URL「？」后的全部参数进行缓存，请确认请求的 URL 的参数值和文件有关再开启，否则会降低缓存命中率并增加 CDN 回源次数。
  ![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/2-cache-configuration/FuxZ3bjWGwIw7lRgxnNRSYC-H_0-e939efef888f.webp)

* 忽略所有参数：资源缓存时去除 URL「?」后的全部参数进行缓存，忽略全部参数同时会导致图片处理等 FOP 功能失效。
  ![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/2-cache-configuration/FhA-88kWuAzhvaZBvBBouLjgOxuK-1ff87a9c7154.webp)

* 保留指定参数：资源缓存时会仅仅保留您输入的指定参数然后进行缓存。
  ![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/2-cache-configuration/Fi7xQeq7Xxn14sXYxxYmAhFhuT2S-0f0d73eca9f0.webp)

* 忽略指定参数：资源缓存时会去除您输入的指定参数然后进行缓存。
  ![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/2-cache-configuration/FkNm8zrFdQl4eEuCSP5N-_sV-r3r-9855277f965b.webp)


# 配置概览 (/products/cdn/configuration-management-fusion/3-an-overview-of-the-configuration)



最近更新时间: 2026-08-13 14:00:08

**七牛云CDN** 支持多项自定义配置，您可以根据自身业务需要进行设置。

# [回源配置](/products/cdn/configuration-management-fusion/1-back-to-the-source-configuration) [#回源配置]

| 配置项    | 描述                         | 默认值  |
| ------ | -------------------------- | ---- |
| 源站信息   | 资源的回源域名或IP, 推荐使用七牛云存储作为源站  | 用户配置 |
| 回源HOST | 指定请求的服务器的域名，默认为加速域名        | 加速域名 |
| 回源协议   | 请求回源的协议，如需修改回源协议请先开启 HTTPS | HTTP |

<br />

# [缓存配置](/products/cdn/configuration-management-fusion/2-cache-configuration) [#缓存配置]

| 配置项     | 描述                       | 默认值     |
| ------- | ------------------------ | ------- |
| 缓存时间    | 定义指定资源内容的缓存过期时间规则        | 全局缓存1个月 |
| 忽略URL参数 | 资源缓存时去除 URL「?」后的全部参数进行缓存 | 未开启     |

<br />

# 访问控制配置 [#访问控制配置]

| 配置项                                                                                                                          | 描述                                             | 默认值 |
| ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | --- |
| [referer防盗链](/products/cdn/configuration-management-fusion/access-control-configuration/0-domain-name-hotlinking-prevention) | 配置 Request Header 中 referer 黑白名单，从而限制访问来源      | 未开启 |
| [时间防盗链](/products/cdn/configuration-management-fusion/access-control-configuration/1-timestamp-hotlinking-prevention-fusion) | 设置密钥，配合签名过期时间来控制资源内容的访问时限                      | 未开启 |
| [回源鉴权](/products/cdn/configuration-management-fusion/access-control-configuration/2-back-to-the-source-authentication)       | 配置回源验证策略，对 CDN 接收到的访问请求进行鉴权，适用于对防盗链有很高实时性要求的场景 | 未开启 |
| [IP黑白名单](/products/cdn/configuration-management-fusion/access-control-configuration/3-ip-black-and-white-list)               | 允许或者禁止某些 IP 或 IP 段的访问，帮助您解决恶意 IP 盗刷、攻击等问题      | 未开启 |
| [UA黑白名单](/products/cdn/configuration-management-fusion/access-control-configuration/4-ua-black-and-white-list)               | 通过 User-Agent 字段的值来允许或者阻止特定用户访加速域名             | 未开启 |

<br />

# 安全防护 [#安全防护]

| 配置项                                                                                         | 描述                          | 默认值 |
| ------------------------------------------------------------------------------------------- | --------------------------- | --- |
| [用量封顶](/products/cdn/configuration-management-fusion/safety-protection/13546-usage-capping) | 周期性地统计业务流量、带宽或请求数，控制访问域名上限值 | 未开启 |

# [HTTPS配置](/products/cdn/configuration-management-fusion/4-https-configuration) [#https配置]

| 配置项     | 描述                                                    | 默认值 |
| ------- | ----------------------------------------------------- | --- |
| 开启HTTPS | 开启 HTTPS 安全加速，支持 SSL 证书绑定及 HTTPS 状态管理                 | 未开启 |
| 更换证书    | 更换即将过期或泄漏的证书                                          | 无   |
| 强制HTTPS | 开启后 HTTP 请求会强制跳转到 HTTPS 进行访问，关闭时默认兼容用户的 HTTP/HTTPS 请求 | 未开启 |

<br />

# [流量带宽告警](/products/cdn/configuration-management-fusion/3-an-overview-of-the-configuration) [#流量带宽告警]

| 配置项  | 描述                           | 默认值 |
| ---- | ---------------------------- | --- |
| 阈值告警 | 可针对域名流量/带宽设置阈值，接近和触发阈值时会告警通知 | 未开启 |

<br />

# [图片优化](/products/cdn/configuration-management-fusion/5-image-optimization) [#图片优化]

| 配置项    | 描述                               | 默认值 |
| ------ | -------------------------------- | --- |
| 图片自动瘦身 | 无需添加任何参数，自动瘦身；图片体积大幅减少，节省 CDN 流量 | 未开启 |
| 图片处理   | 缩略图，裁剪，选择，格式等多种图片处理，需用户添加参数主动调用  | 未开启 |

<br />

# [HTTP 响应头配置](/products/cdn/configuration-management-fusion/6-the-http-response-header-configuration) [#http-响应头配置]

| 配置项      | 描述                             | 默认值 |
| -------- | ------------------------------ | --- |
| HTTP 响应头 | 支持常见的 HTTP 请求响应头配置，可向客户端提供额外信息 | 未开启 |


# HTTPS配置 (/products/cdn/configuration-management-fusion/4-https-configuration)



最近更新时间: 2026-08-12 17:58:17

HTTPS 是指超文本传输安全协议（Hypertext Transfer Protocol Secure，缩写：HTTPS，常称为HTTP over TLS，HTTP over SSL或HTTP Secure）是一种通过计算机网络进行安全通信的传输协议。HTTPS经由HTTP进行通信，但利用SSL/TLS来加密数据包。HTTPS开发的主要目的，是提供对网站服务器的身份认证，保护交换数据的隐私与完整性。配置 HTTPS 时，需要您提供域名对应的证书，实现全网数据加密传输功能。您可以登录**七牛管理控制台**选择**CDN控制台**，进行HTTPS的配置。

<br />

# 操作说明 [#操作说明]

登录**七牛管理控制台**后，进入**CDN控制台**，选择【域名管理】，点击【配置】：

![域名列表](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/4-https-configuration/Fte7QkOoQPsdm44xqzuRE2bv3bCm-bb99e85c2843.webp)

进入域名配置界面，**HTTPS配置**模块下点击【修改配置】进行配置。

![](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/4-https-configuration/FvoPt1GfRggXFdmGfCoUHWzT65Me-5b6675a59e4d.webp)

### 开启 HTTPS [#开启-https]

如需启用**HTTPS服务**时，选择【HTTPS】即可，开启后需要选择对应的证书。

![](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/4-https-configuration/Ftymvx06MewB4_q99zu7Qm1zSSej-29136f49dfc7.webp)

### 更换证书 [#更换证书]

* 如已经完成了证书的上传，选择对应的证书即可

![](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/4-https-configuration/FmdMOSC0xSB0IJ9b2mEciT2X0W8w-5b28ddfbcb0c.webp)

**注：证书筛选框只显示对应域名可用的所有证书，证书剩余有效期必须大于7天。**

* 如未上传证书或此域名当前无可用证书，点击【七牛云证书服务】进入SSL证书服务控制台进行自有证书上传或购买证书操作。

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/4-https-configuration/Frg3fHxkJaK-udEZ4UB-htRgULQH-31c4ac15d434.webp)

### 强制HTTPS [#强制https]

如果您的加速域名开启了HTTPS配置，您可以设置**强制HTTPS**，开启后即使用户发起 HTTP 请求，也会强制跳转为 HTTPS 请求进行访问。此项默认为关闭状态，此时同时支持HTTP和HTTPS方式的请求。

![](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/4-https-configuration/FigrkqkzoTdfDqXecknDtxsJaTFK-035ddf417caa.webp)

### 开启HTTP/2 [#开启http2]

如果您的加速域名开启了HTTPS配置，您可以设置**开启HTTP/2**，HTTP/2可以兼容HTTP/1.1的访问，优化网络延迟，提升网络速度，优化用户的网络使用体验。目前，Chrome、 Firefox、Safari 等主流浏览器已经支持 HTTP/2协议。
![](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/4-https-configuration/FjUJIn5N1Z3lo8SbGwN6y7oqeEVh-28710252a86f.webp)


# 图片优化 (/products/cdn/configuration-management-fusion/5-image-optimization)



最近更新时间: 2026-08-12 17:58:17

图片优化提供了图片自动瘦身与图片处理，降低CDN分发成本，加快客户端图片的加载速度，提升用户体验。您可以登录**七牛管理控制台**选择**CDN控制台**，进行配置。

<br />

# 操作说明 [#操作说明]

登录**七牛管理控制台**后，进入**CDN控制台**，选择【域名管理】，点击【配置】：
![域名列表](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/5-image-optimization/FjwXISvg44i0yvclTFMm2T485Lqo-a755e6d7f929.webp)

进入域名配置界面，**图片处理** 模块下点击【修改配置】进行配置。

![](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/5-image-optimization/FlAn-jxvOjmCJG79d7VLope8-qxO-7ba94d2a3ae8.webp)

### 图片自动瘦身 [#图片自动瘦身]

图片瘦身服务在尽可能不影响画质的情况下，将JPEG、PNG格式的图片实时压缩，大幅缩小文件体积；降低CDN分发成本，加快客户端图片的加载速度，提升用户体验，默认为关闭状态，如需启用点击开启即可。

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/5-image-optimization/FkomrdzfUS8DlYLgKvahiWR_yoQ-3781fd92ba9f.webp)

### 图片处理 [#图片处理]

图片处理提供了缩略图，裁剪，选择，格式等多种图片处理，功能开启后，还需用户添加参数主动调用。

* [图片基本处理](/products/dora/image-processing-api/4-basic-processing-images-imageview2)：为图片生成各种缩略图。
* [图片高级处理](/products/cdn/configuration-management-fusion/5-image-optimization)：对图片进行缩放、裁剪、旋转等。
* [图片基本信息](/products/dora/image-processing-api/2-pictures-basic-information-imageinfo)：获取图片格式、大小、色彩模型等基本信息。
* [图片EXIF信息](/products/dora/image-processing-api/0-photo-exif-information-exif)：获取图片的 EXIF 格式。
* [图片水印处理](/products/dora/image-processing-api/5-image-watermarking-processing-watermark)：对图片打图片、文字水印。
* [图片主色调](/products/dora/image-processing-api/1-image-average-hue-imageave)：计算图片的平均色调。

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/5-image-optimization/FhnQJdgTw-erZ10bFZ41EJOZBll6-4a325622b440.webp)


# HTTP响应头配置 (/products/cdn/configuration-management-fusion/6-the-http-response-header-configuration)



最近更新时间: 2026-08-12 17:58:17

HTTP 消息头是指，在超文本传输协议（ Hypertext Transfer Protocol，HTTP）的请求和响应消息中，协议头部的组件。在 HTTP 消息头中，按其出现的上下文环境，分为通用头、请求头、响应头等。

其中 HTTP 响应头向客户端提供一些额外信息，比如谁在发送响应、响应者的功能，甚至与响应相关的一些特殊指令。这些头部有助于客户端处理响应，并在将来发起更好的请求。

当您的网站接入 CDN 后，由于客户端和源站会根据 HTTP 响应头的字段信息进行相关的行为处理，所以会有修改 HTTP 响应头的需求。由于 HTTP 响应头配置是针对域名，因此一旦配置生效，对该域名下任意一个资源的响应消息中均会加入所配置头部。配置 HTTP 响应头仅影响客户端（如浏览器）的响应行为，不会影响到 CDN 节点的缓存行为。

# 操作说明 [#操作说明]

您可以登录七牛管理控制台，并进入[**CDN控制台**](https://portal.qiniu.com/cdn/overview)，选择【域名管理】，点击【配置】：
![](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/6-the-http-response-header-configuration/FmYE5CpHTA06KYZV8ZQdqgOgBL7J-b748302e3a77.webp)
进入域名配置界面，点击【添加配置】可添加一条 HTTP 响应头的配置记录。
![](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/6-the-http-response-header-configuration/Fuv2r3Y1YsbfOZAQX9qnwLgMWiIW-324f05529665.webp)

<br />

请根据实际情况选择 HTTP 响应头、响应头操作并配置相应的值。
目前七牛云CDN提供11个 HTTP 响应头参数可供您自定义取值，解释如下表所示。 如果您有其他 HTTP 头设置需求，请 [提交工单](https://support.qiniu.com/tickets/new-for-person/form?category=%E9%85%8D%E7%BD%AE%E9%97%AE%E9%A2%98\&space=CDN) 咨询。

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/6-the-http-response-header-configuration/Fo7EJjR0MXFzCxkDQPuoZ6ehjRMS-bade1b544676.webp)

| HTTP 响应头                         | 描述                               | 示例                                                                                            |
| -------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------- |
| Access-control-allow-origin      | 指定允许的跨域请求的来源。                    | \* （\*表示全部域名；也可填写完整域名，例如 [http://www.qiniu.com](http://www.qiniu.com) 、http\://\*.qiniu.com ) |
| Access-Control-Allow-Headers     | 指定允许的跨域请求的字段。                    | X-Custom-Header                                                                               |
| Access-Control-Allow-Methods     | 指定允许的跨域请求方法。                     | POST,GET,OPTIONS                                                                              |
| Content-Type                     | 指定客户端程序响应对象的内容类型。                | Content-Type                                                                                  |
| Cache-Control                    | 指定客户端程序请求和响应遵循的缓存机制。             | no-cache,no-store                                                                             |
| Content-Disposition              | 指定客户端程序把请求所得的内容存为一个文件时提供的默认的文件名。 | attachment; filename="filename.jpg"                                                           |
| Content-Language                 | 指定客户端程序响应对象的语言。                  | zh-CN,en-US                                                                                   |
| Expires                          | 指定客户端程序响应对象的过期时间。                | Wed, 21 Oct 2015 07:28:00 GMT                                                                 |
| Access-Control-Max-Age           | 指定跨域请求时，对特定资源的预请求返回结果的缓存时间。      | 600（单位为秒，600表示10分钟）                                                                           |
| Access-Control-Expose-Headers    | 指定允许访问的自定义头信息。                   | Content-Length（可以输入多个头部时，需用 “,” 隔开。）                                                          |
| Access-Control-Allow-Credentials | 指定是否允许跨域请求携带验证信息，验证信息可以是cookies。 | true                                                                                          |

```
注：跨域是指某一个域名，如 www.aaa.com 下的某资源，向另一个域名 www.bbb.com 下的某资源发起请求，此时由于资源所属域名不同，即出现 跨域，不同的协议、不同的端口均会造成跨域访问的出现。此时必须在 Response Header 中增加跨域相关配置，才能让前者成功拿到数据。
```

在 HTTP 响应头列表中，您可以单击【修改配置】或【删除】，对当前配置的 HTTP 响应头进行相应操作。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/configuration-management-fusion/6-the-http-response-header-configuration/FjKWSQOOJTAaIx22_pgAWE62gFFt-f00be0a0c97b.webp)


# 用量统计 (/products/cdn/data-statistics-fusion/0-usage-statistics)



最近更新时间: 2026-05-08 15:16:40

用量统计提供了流量、带宽、请求次数的用量情况，您可以登录**七牛管理控制台**，进入 [CDN-统计分析-用量统计](https://portal.qiniu.com/cdn/statistics/usage/flow) 模块进行查询。

# 1. 流量统计 [#1-流量统计]

## 查询条件 [#查询条件]

* 服务类型：服务类型分为CDN、ECDN两种类型，默认为全部。
* 选择域名：可根据标签选择域名。
* 时间范围：默认为最近7天，最大时间范围为3个月。
* 时间粒度：包含5分钟、1小时、1天三种方式，默认为1小时。
* 计费区域：默认为全部地区，支持自定义指定计费区域查询。

## 查询结果 [#查询结果]

* 访问总流量：时间范围内的总流量。
* 日均流量：：时间范围内的日平均流量，不满一天按一天计算。
* 可分别查看ECDN和静态加速的流量明细。

![wecom-temp-158274-b252c0b00fe8ee6625df2327f2b608d9.jpg](/docs-assets/products/cdn/%284-development-guidelines%29/data-statistics-fusion/0-usage-statistics/FjngIny8w5uKNcQwjw12UDBR4MW0-12c371aec2a9.webp)

##

按域名堆叠
图表支持按域名（不能超过10个）堆叠展示；支持数据导出功能。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/data-statistics-fusion/0-usage-statistics/FgGBLQZiU4g4eByPAmUMhT3v-oe5-00b7957fc8d2.webp)

# 2. 带宽统计 [#2-带宽统计]

## 查询条件 [#查询条件-1]

* 服务类型：服务类型分为CDN、ECDN两种类型，默认为全部。
* 选择域名：可根据标签选择域名。
* 时间范围：默认为最近7天，最大时间范围为3个月。
* 时间粒度：包含5分钟、1小时、1天三种方式，默认为1小时。
* 计费区域：默认为全部地区，支持自定义指定计费区域查询。

## 查询结果 [#查询结果-1]

* 带宽峰值：选择时间区域内的最大带宽值。
* 95峰值带宽：在一个自然月内，账户下分别取各使用节点内的5分钟有效带宽值，并把同一时间点各节点的5分钟有效带宽值求和。 将得到的带宽值求和结果进行降序排列，将带宽数值最高的5%的点去掉，剩余最高带宽即为整体的95月峰值带宽。
* 平均峰值带宽：每天带宽峰值相加/总天数。
* 平均95峰值带宽：每天95带宽峰值相加/总天数。
* 可分别查看ECDN加速和静态加速的带宽统计明细。
  ![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/data-statistics-fusion/0-usage-statistics/Fs26xMK41llBXrMDA_pUH7vKZ9xI-33bafe58e11a.webp)

## 按域名堆叠 [#按域名堆叠]

图表支持按域名（不能超过10个）堆叠展示；支持数据导出功能。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/data-statistics-fusion/0-usage-statistics/Fq372Q4dV4_IMlwnHY8PJmCkF7AR-173f02f0a67d.webp)

# 3. 常见问题 [#3-常见问题]

<span id="all-selected">
  **在域名筛选的条件中，域名“全选”和“全部域名”的差异是什么**

  ？
</span>

域名“全选”和点击“全部域名”按钮在绝大多数场景完全的数据统计结果完全一致，但在以下场景下会产生计量结果差异:
（1）对于域名数量超过 1000 个的场景，“全选”域名的统计结果仅为当前选中的 1000 个域名，“全部域名”的统计结果则为当前账号下的所有域名产生的用量。
（2）若客户将域名配置为“普通域名”并产生流量，之后后删除该域名，又将同一个域名配置为一个“泛子域名”，则在“全选”域名的统计结果不包含该域名作为普通域名时产生的流量，点击“全部域名”的统计结果为当前账号下的所有域名产生的用量结果。

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/data-statistics-fusion/0-usage-statistics/FgYyTxqe6B1-dyrsumkZ2yN-Yd-Z-3a5c4008c603.webp)

七牛账单上的计量数据以点击“全部域名”的结果为准，即账户下产生的所有使用量。


# 统计分析 (/products/cdn/data-statistics-fusion)



最近更新时间: 2026-08-12 17:56:52

CDN 统计分析模块提供[用量统计](https://portal.qiniu.com/cdn/statistics/usage/flow)和[日志分析](https://portal.qiniu.com/cdn/statistics/log/access)两大分析模块。

# 用量统计 [#用量统计]

用量统计基于服务端访问数据统计，提供流量、带宽、请求次数等产品用量相关的统计数据。

| 模块                                                                        | 说明                                    |
| ------------------------------------------------------------------------- | ------------------------------------- |
| [流量统计](/products/cdn/data-statistics-fusion/0-usage-statistics#traffic)   | 提供全量、日间、闲时的流量统计，主要给流量计费型（默认）客户提供用量参考。 |
| [带宽统计 ](/products/cdn/data-statistics-fusion/0-usage-statistics#width)    | 提供峰值带宽、95峰值带宽统计，主要给带宽计费型客户提供用量参考。     |
| [请求次数统计 ](/products/cdn/data-statistics-fusion/0-usage-statistics#querry) | 提供静态、动态请求次数统计，其中仅动态请求次数收费。            |

# 日志分析 [#日志分析]

日志分析功能基于用户访问数据统计，提供以下用户访问的统计分析数据，便于您进行业务洞察分析：

| 模块                                                                                                 | 说明                               |
| -------------------------------------------------------------------------------------------------- | -------------------------------- |
| [地区运营商分布 ](/products/cdn/data-statistics-fusion/log-analysis/3-distribution-of-regional-operators) | 提供终端用户的地区分布和运营商分布的数据统计。          |
| [ 状态码](/products/cdn/data-statistics-fusion/log-analysis/0-status-code)                            | 提供用户访问的状态码的数据统计。                 |
| [命中率](/products/cdn/data-statistics-fusion/log-analysis/1-shooting)                                | 命中率提供了域名的请求与流量两个维度的域名访问命中情况数据统计。 |
| [TOP URL/IP ](/products/cdn/data-statistics-fusion/log-analysis/4-top-url-ip)                      | 提供热点资源 URL 和用户 IP 的相关数据统计。       |
| [独立 IP ](/products/cdn/data-statistics-fusion/log-analysis/2-independent-ip)                       | 独立IP提供了域名的UV的统计数据分析。             |

由于日志分析数据采用客户端 ip 统计，相关数据仅用于业务分析，具体账单相关计量数据参考[用量统计](https://portal.qiniu.com/cdn/statistics/usage/flow)模块。


# 域名接入 (/products/cdn/the-domain-name-management/0-the-domain-name-to-access)



最近更新时间: 2026-05-08 14:38:34

享受七牛云CDN为您提供的加速服务时，需要先进行域名接入。

# 添加域名 [#添加域名]

1. 登陆[七牛开发者平台](https://portal.qiniu.com/signin)。

2. **方式1**:

   选择 **控制台** ,然后选择 **添加加速域名** 。

   <img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/0-the-domain-name-to-access/Fg6noo41nRrOns7B4CffwjACfNo5-f424419b999d.webp" width="800" />

   <img />

   **方式2**:

   点击 **产品与方案** ,然后选择 **CDN** 。

   <img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/0-the-domain-name-to-access/FjUB6Q8vI5gWV7cQFxMAm9kHxEdi-2650dd379f07.webp" width="800" />

   <img />

   操作完 方式1 或者 方式2 之后，会出现 **创建域名** 界面。

   <img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/0-the-domain-name-to-access/FvRMYLVNm18UcgIKdhBNBMgj5JVl-d26206ce56b0.webp" width="800" />

   <img />

   **注意**：

   如果您界面上方显示的是 **未完成实名认证** ，如下图所示：

   <img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/0-the-domain-name-to-access/FrfZDZ9oXaa307z0KUXoakdri7Ks-0b314a2c576b.webp" width="800" />

   <img />

   此时您需要在 **个人中心** 进行实名认证

   <img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/0-the-domain-name-to-access/FviwriqdPIcPL0RuRTewn5EG8U7x-66948064de9f.webp" width="800" />

   <img />

   此外，请您确认您的绑定域名是否是已备案的状态，您可以在[域名信息备案系统](http://beian.miit.gov.cn/publish/query/indexFirst.action)查询。

3. **创建加速域名** 界面，在 **域名类型** 栏选择域名类型。域名类型包含：普通域名，泛域名，泛子域名。

* 普通域名，是指您的主域名下的子域名。例如主域名qiniu.com，developer.qiniu.com是其二级域名，a.developer.qiniu.com是其三级域名,.....,这些都属于普通域名。
* 泛域名，是指域名\*.主域名，配置成功后可任意指定前缀进行访问；可基于该泛域名创建多个泛子域名来指定不同源站，例如泛域名 \*.qiniu.com。
* 泛子域名，基于泛域名创建的子域名；可独立指定源站，其它配置继承泛域名。

4. **创建加速域名** 界面，在 **加速域名** 栏填写域名。建议对加速域名进行 ICP 备案，若域名未进行备案，加速区域只能选择不含中国大陆的纯海外加速区域。

5. **创建加速域名** 界面，在 **通信协议** 栏选择所需的通信协议。您可以选择 https 通信协议或者 http 通信协议。如果您选择 https协议，您还需上传有效期大于半年的 HTTPS 证书。（注：为了不影响正常使用，证书到期后请及时续期）

6. **创建加速域名** 界面，在 **使用场景** 栏选择所在的使用场景。使用场景分为图片小文件，下载分发和点播平台。

* 图片小文件，适用于网页、图片、小文件。
* 下载分发，适用于文件下载，例如安装包，压缩包等二进制大文件。
* 点播平台，适用于需要MP4/FLV等文件按照时间点进行播放。
* 动态加速，适用于电商、社交、社区论坛、金融支付和游戏娱乐等方面。

7. **创建加速域名** 界面，在 **IP协议** 栏选择所需CDN支持的IP协议。

* IPv4，仅支持通过IPv4协议访问CDN节点，回源仍是IPv4协议。
* IPv4/IPv6，支持IPv4或IPv6协议访问CDN节点，回源仍是IPv4协议。IPv6协议仅支持中国大陆，非中国大陆地区暂不支持IPv6配置。

8. **创建加速域名** 界面，在 **源站配置** 栏选择源站。可以选择七牛云存储，源站域名，IP地址，高级设置。

* 七牛云存储，选择您的七牛云空间，您将需要加速的资源上传到空间 或者 您可以设置**空间镜像**，这样您的资源会更快的迁移到七牛云空间（如何设置空间[镜像存储](/products/kodo/kodo-console-guide/bucket-management/space-settings/8-set-up-the-mirror-back-to-the-source)）。注意，若您的域名未进行 ICP 备案，则源站存储只能选择七牛海外存储。
* 源站域名，填写您的源站域名，不能与**加速域名**相同。**源站测试**中需要您填写您需要加速的资源名，通过源站测试，表明源站配置正确。
* IP地址，填写您源站的IP地址，**源站测试**中需要您填写您需要加速的资源名，通过源站测试，表明源站配置正确。
* 高级配置，设置多个主线路或者备线路，访问请求根据权重分配。

9. **创建加速域名** 界面，选择 **创建** ，此时创建成功。

<br />

# 配置CNAME [#配置cname]

创建加速域名成功后，七牛云会提供cname地址，需要在域名服务提供商处将加速域名指向分配的CNAME地址，配置生效后，即可享受CDN加速服务。
选择 **CDN** ，在 **域名管理** 界面选择创建好的 **域名** ，点击 **配置** ，提供的cname在红框中标注。您可以参考链接 [CNAME配置](/products/cdn/the-domain-name-management/2-cname-configuration) 配置cname值。

<img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/0-the-domain-name-to-access/Fl-6-lbBOcENyyo-7EXzfpeFWFG4-2e276692955d.webp" width="800" />

<img />


# 域名操作 (/products/cdn/the-domain-name-management/1-domain-name-operation)



最近更新时间: 2026-05-08 14:40:35

您可以登录[七牛管理控制台](https://portal.qiniu.com/) 在 [CDN域名管理](https://portal.qiniu.com/cdn/domain) 界面，对接入**CDN**的加速域名进行启用域名、停用域名、删除域名、配置域名、查询统计分析等操作。

# 启用域名 [#启用域名]

域名状态为**已停用**时，可以点击**启用**，重新启用域名的CDN加速服务。

<img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/1-domain-name-operation/FtmbTOqQ8rqZuUeeRmaKatd1xuI8-f71c81f7bb81.webp" width="800" />

<img />

<br />

# 停用域名 [#停用域名]

如需暂时停用某个域名的CDN加速服务时，可以点击**停用**，暂停该域名的服务。
该状态会将解析解析指向一个不可用的地址，若部分DNS缓存未过期而请求到节点上的服务依旧可以正常访问。

<img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/1-domain-name-operation/Fu7ZXuVg26HC9ifSI7AMZVYyQVRY-20eac03c3877.webp" width="800" />

<img />

<br />

# 删除域名 [#删除域名]

域名状态为**已停用**时，可以对该域名执行删除操作，删除后其配置将不会保留。

<img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/1-domain-name-operation/Fk1rlG7jN3AvgI7epY3LOCXUUoB-60a6f5afd6fa.webp" width="800" />

<img />

<br />

# 配置域名 [#配置域名]

域名状态为成功时，可以修改其配置。

<br />

# 统计分析 [#统计分析]

可以直接点击**统计**查询域名的统计分析数据。

<br />

# 操作状态说明 [#操作状态说明]

| 域名操作 | 说明                                                                                                                                                      |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 停用域名 | 1.根据需求用户在CDN控制台上可以将域名停用。<br />2.过去90天，没有流量且没有任何操作的域名会被停用，停用前3天会发送通知告知用户。<br />3.域名停用后如3天内没有启用，将删除域名配置。                                                  |
| 启用域名 | 1.根据需求用户在CDN控制台上可以启用出已停用状态的域名。<br />2.域名启用后将重新恢复域名解析，并将配置下发至CDN节点。                                                                                      |
| 删除域名 | 1.根据需求用户在CDN控制台上可以删除出已停用状态的域名。<br />2.冻结后90天，没有解冻且没有任何操作的域名会被删除，删除前3天会发送通知告知用户。<br />3.停用后90天，没有启用且没有任何操作的域名会被删除，删除前3天会发送通知告知用户。<br />4.域名删除后将会删除其所有配置。 |


# CNAME配置 (/products/cdn/the-domain-name-management/2-cname-configuration)



最近更新时间: 2026-05-08 14:42:47

您的域名接入 CDN 后，系统会为您自动分配一个 CNAME 域名，要启用CDN加速服务，需要在域名服务提供商处将加速域名指向分配的CNAME地址，配置生效后，即可享受CDN加速服务。

# 获取加速域名的CNAME [#获取加速域名的cname]

* 在 **七牛管理控制台** 页面选择 [**CDN**](https://portal.qiniu.com/cdn/overview) ，选择 [**域名管理**](https://portal.qiniu.com/cdn/domain) ，将鼠标悬停在对应的 **cname** 后，会出现蓝色字样 **复制** ，如下图所示，点击即可复制CNAME值。

<img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/2-cname-configuration/Fr77uBzUgpIULfWXHpyxqsPSg51F-494a1aaf29b7.webp" width="800" />

<img />

* 或者您也可以通过在 [**七牛管理控制台**](https://portal.qiniu.com/create) 页面选择 [**CDN**](https://portal.qiniu.com/cdn/overview) ，选择 [**域名管理**](https://portal.qiniu.com/cdn/domain) ，点击您需要配置的 **域名** 后的 **配置** 字样，进入 **配置** 界面，在基本信息中查看CNAME值 ，如下图所示。

<img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/2-cname-configuration/FgDKRt13POsf0Lon-fthGyG3FfWm-4f721c043aff.webp" width="800" />

<img />

<img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/2-cname-configuration/FiOwoXWs0jz-3Im0rvGJirs4nvI6-f8b52363a244.webp" width="800" />

<img />

***

# 添加CNAME记录 [#添加cname记录]

* 添加CNAME记录需要在您的 &#x2A;*`域名厂商`*&#x2A; 处配置，比如您在阿里云/腾讯云/新网等处购买的域名，您需要前往 &#x2A;*`购买域名的厂商`*&#x2A; 的相应控制台配置做域名解析。
  1.在域名列表中找到您加速域名对应的 &#x2A;*`主域名`**，进入解析设置页。
  2.依次填写主机记录，记录类型以及记录值，其他可设为默认值。

  <img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/2-cname-configuration/00157dfa3bb59f2916e851536da6890-1c970351ac13.webp" width="800" />

| 记号 | 说明                                                              |
| -- | --------------------------------------------------------------- |
| A  | 记录类型为CNAME                                                      |
| B  | 主机记录处填子域名                                                       |
| C  | 线路类型（默认为必填项，否则会导致部分用户无法解析；在上图中，默认的作用为：除了联通用户之外的所有用户，都会指向 1.com） |
| D  | 记录值填写七牛提供的cname值，记录生成后会自动在域名后面补一个 “.”，这是正常现象                    |
| E  | MX优先级不需要填写                                                      |
| F  | TTL 不需要填写，添加时系统会自动生成，默认为 600 秒（TTL 为缓存时间，数值越小，修改记录各地生效时间越快）     |

例如，记录类型请选择为CNAME，主机记录为主域名的前缀，假设购买的域名为‘qiniu.com’，这是一个一级域名：

* 您创建的加速`普通域名`为 qiniu.com ，主机值为@
* 您创建的加速`普通域名`为 cdn.qiniu.com ，主机值为 cdn
* 您创建的加速`普通域名`为 img.cdn.qiniu.com ，主机值为 img.cdn
* 您创建的加速`泛域名` .qiniu.com ，主机值为\*
* 您创建的加速`泛域名` .img.qiniu.com ，主机值为\*.img

记录值填写在七牛控制台`复制的CNAME值`，解析线路和TTL保持默认值即可。

* CNAME配置生效时间：新增CNAME记录会实时生效，而修改CNAME记录需要等待生效时间。

# 验证CNAME是否配置正确 [#验证cname是否配置正确]

* 在空间内查看 CDN 加速域名 的状态，如果是成功，即解析成功，如果是等待CNAME，则未正确解析。
  <img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/2-cname-configuration/FiawiJa717zwG2-mawXz194jFbkr-dd200c7ad18e.webp" width="800" />
* 如果您在域名厂商处已经正确配置CNAME解析后，但还是“等待CNAME”状态。
  linux/mac系统您可以通过dig命令查看，第一条是否解析到您配置的CNAME值，如果已经解析成功，则可以忽略不计。
  <img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/2-cname-configuration/FpqjWyiiCInCQp7ZS2HpIW_jcTnT-34dd834c5eb2.webp" width="600" />

windows系统可以通过Win+R 或 点击左下角的“开始”按钮打开“开始”菜单，从中打开“运行”，输入cmd回车，在命令行模式下输入`nslookup 您的加速域名`
示例如图，如果图中可以看到您复制的cname值即可。

<img src="/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/2-cname-configuration/FgeCvjPMtpw4csmNtK3cSvuS-Pzr-aa9c574264af.webp" width="400" />

***

如果您同时需要对源站进行[镜像存储](/faq/kodo/image-storage-common-problems/1376-seven-cattle-image-storage-instruction-manuals)，您还需要进行如下操作：

1. 如原指向资源的域名是 pic.abc.com ，要把该域名 CNAME 到 portal平台“成功”状态的新域名。
2. 重新配置一个二级域名（比如叫：image.abc.com ）指向资源存放目录
3. 设置镜像为 `http://image.abc.com`
   以上三步完成后，不需要更改代码及数据库，即可用 `http://pic.abc.com/path/10.jpg`


# 域名找回 (/products/cdn/the-domain-name-management/3-the-domain-name-back)



最近更新时间: 2026-08-27 16:17:13

# 一、填写域名并点击找回 [#一填写域名并点击找回]

由于域名在其他账号下创建，域名归属权不在当前账号，需要进行验证操作才可以获得该域名
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/3-the-domain-name-back/Fqs2JKnpN3JzmrK065ZDOzENYf9m-195763983d38.webp)

<br />

# 二、选择验证方式 [#二选择验证方式]

验证方式分为两种，文件验证和TXT记录验证。
1.文件验证
域名如果解析到之前的存储空间，下载该文件并上传到之前账号的存储空间
域名如果解析到自己的服务器，下载该文件并上上传到自己的服务器网站根目录
**注意**：需要保持 `http://<您要找回的域名>/verifyingfile.html` 这个链接可以正常访问达到如下效果即可
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/3-the-domain-name-back/FjUSRdMHYH6w7emlwn8aaoj4kq2q-c96213507997.webp)
2.TXT记录验证
TXT记录验证
需要到域名当前DNS服务商处给域名添加 TXT 记录值
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/3-the-domain-name-back/FtxNVZe8s1alskZXcI3wVsHmFexu-e0b2f3cff748.webp)

# 三、提交验证 [#三提交验证]

点击验证之后，显示弹窗说明，则验证通过，然后等待 6 - 8 小时系统自动过户即可

![企业微信截图\_12bb9f10-34f2-4ddf-b6c8-10faa431ed66.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/3-the-domain-name-back/FtB9ZhGyja1EyyUYJmSvDqiMstAy-4df35f565ba3.webp)

> **如果长时间验证不通过，建议拨打 400-101-8589 转 2 号线，联系技术支持处理。**


# 标签管理 (/products/cdn/the-domain-name-management/4-label-management)



最近更新时间: 2026-05-08 14:34:10

考虑客户业务场景复杂，域名数量较多难以管理，七牛云引入标签的概念，支持对域名进行分类管理。七牛云不对CDN标签进行任何定义，仅严格按字符串对标签和域名进行匹配。标签管理支持绑定标签、解绑标签、使用标签管理域名等功能。

# 限制条件 [#限制条件]

* CDN标签为单值标签；
* 每个域名绑定的标签名称不可重复；
* 每个域名最多绑定 10个标签；
* 区分大小写。

# 相关功能 [#相关功能]

## 绑定标签 [#绑定标签]

1、登录控制台。
2、域名管理页面，选择您需要设置标签的域名，将光标移动到对应标签上并点击“编辑”。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/4-label-management/Fkl6BxEqArAry6XTekQAa41cfUIC-357d781cac0d.webp)
3、在编辑标签对话框，您可以选择已有标签或新建标签进行绑定。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/4-label-management/FraMrMjWd7Udr6XqDpoYtjKMO2OF-32febf0334ff.webp)
4、点击确认。

<br />

## 解绑标签 [#解绑标签]

1、登录控制台。
2、域名管理页面，选择您需要解绑标签的域名，将光标移动到对应标签上并点击“编辑”。
3、在编辑标签对话框，选择您需要解绑的标签并点击“X”号进行解绑；当某标签不在有域名绑定时，自动从列表中删除。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/4-label-management/FpIVtyGJIiIykBgW4gY1bfn-USu-82914acc95f8.webp)
4、点击确定；当某标签不在有域名绑定时，自动从列表中删除。

<br />

## 筛选域名管理 [#筛选域名管理]

1、登录控制台。
2、域名管理页面，右上角“请选择标签”处选择对应标签，支持多选，且多选时支持“或”和“且”关系选择。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/4-label-management/FpRJHSF25NWXB484Vow7wH4rmxa9-0a7ff476a88e.webp)
3、点击任意空白处，根据标签筛选出相关域名。
![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/4-label-management/FruOrJNM5HTQL7KJ7thSLGtp8mAE-27920c657595.webp)


# 批量复制 (/products/cdn/the-domain-name-management/5-cdn-domain-bulk-copy)



最近更新时间: 2026-09-07 14:14:08

批量复制可以实现复制已有域名的配置完成批量添加域名，支持调整基础配置批量复制，也支持自定义勾选Referer 防盗链、IP 黑白名单、时间戳防盗链、图片自动瘦身、图片处理、HTTP 响应头等配置项批量复制。

<br />

# 操作说明 [#操作说明]

### 1.进入CDN控制台 [#1进入cdn控制台]

登录**七牛开发者平台**后，进入**CDN控制台**，选择【域名管理】，点击目标域名**操作**项下的**复制**进入配置界面。

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/5-cdn-domain-bulk-copy/FhtgM35PVSocCsCcFIai5cDUaLeW-eb7df62c5296.webp)
注意：只有**成功**状态的域名支持批量复制

### 2.添加域名&确认配置 [#2添加域名确认配置]

在**加速域名**输入框中输入需要批量添加的域名，并确认**基本信息、源站配置和缓存配置**，若非预期配置可以修改。

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/5-cdn-domain-bulk-copy/Fh1DFvBXo7OCaIdOOh_WaL4-4QPN-8c9522d2525e.webp)

注意：
a. 添加域名中存在未备案域名，加速范围只能选择海外；
b. 完整域名和泛域名需要分开添加，不能混在一起批量复制；
c. **源站测试**需要点击并显示测试通过后，才可以点击**下一步**，否则会报错提示“源站待测试”。

### 3.选择复制配置 [#3选择复制配置]

**配置项**：支持自定义勾选的批量复制配置项，包含Referer 防盗链、IP 黑白名单、时间戳防盗链、图片自动瘦身、图片处理、HTTP 响应头等配置批。
**配置状态**：配置项的配置状态，包含开启和关闭两种。
**操作**：点击**详情**可以查看配置项的配置详情。

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/5-cdn-domain-bulk-copy/FiDAKfmGK0Zmx4BKUYr_ol5CTVML-3ac50d0ac001.webp)

注意：
a. 若被复制域名存在后端特殊配置（非控制台配置），该特殊配置无法复制，若需要请联系客服补充配置。
b. 因 HTTPS 证书配置需要重新绑定当前域名，不支持复制此配置，若需要请自助补充配置。
c. 配置状态为关闭的配置项勾选和不勾选，实际配置效果均为关闭。

### 4.确认提交 [#4确认提交]

确认无误，点击**确认**即可，否则点击**取消**返回上一步。

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/5-cdn-domain-bulk-copy/Fr_i8KQKNjodhmkuVgiFIHO3Wqft-c61e526d92be.webp)

### 5.创建完成 [#5创建完成]

![image.png](/docs-assets/products/cdn/%284-development-guidelines%29/the-domain-name-management/5-cdn-domain-bulk-copy/Fr7Uw9f-_IUkg__tXosM5p5c5yMG-402de42177d7.webp)
注意：
a. 域名的状态若为“创建完成”，仅表示创建域名的任务提交成功，不表示域名配置下发完成；
b. 域名的状态若为“域名所有权待验证”，需要点击**操作**项下的**所有权验证**逐个域名进行所有权验证，否则无法成功添加域名。


# 机器智能审核阶梯计费方式 (/products/censor/pricing/0-censor-price)



最近更新时间: 2026-05-08 10:27:14

# 计费说明 [#计费说明]

* 按照各资源类型各场景独立计量计费。
* 默认采用按量付费模式，每月提供账单，按当月的使用量进行阶梯收费。
* 图片审核、视频审核对应场景合并总数，统一结算。

## 计费项目 [#计费项目]

| 类型   | 计费项      | 说明                                   |
| ---- | -------- | ------------------------------------ |
| 图片审核 | 图片鉴黄     | 按图片张数计量<br />各项独立计费                  |
| 图片审核 | 图片鉴暴恐    | 按图片张数计量<br />各项独立计费                  |
| 图片审核 | 图片敏感人物识别 | 按图片张数计量<br />各项独立计费                  |
| 图片审核 | 图片广告识别   | 按图片张数计量<br />各项独立计费                  |
| 图片审核 | 图片不良场景识别 | 按图片张数计量<br />各项独立计费                  |
| 图片审核 | 图片异常检测   | 按图片张数计量<br />各项独立计费                  |
| 视频审核 | 视频鉴黄     | 按截帧张数计量<br />各项独立计费<br />与图片审核对应项目合并 |
| 视频审核 | 视频鉴暴恐    | 按截帧张数计量<br />各项独立计费<br />与图片审核对应项目合并 |
| 视频审核 | 视频敏感人物识别 | 按截帧张数计量<br />各项独立计费<br />与图片审核对应项目合并 |
| 视频审核 | 视频广告识别   | 按截帧张数计量<br />各项独立计费<br />与图片审核对应项目合并 |
| 直播审核 | 直播鉴黄     | 按截帧张数计量<br />各项独立计费                  |
| 直播审核 | 直播鉴暴恐    | 按截帧张数计量<br />各项独立计费                  |
| 直播审核 | 直播敏感人物识别 | 按截帧张数计量<br />各项独立计费                  |
| 直播审核 | 直播图文违规识别 | 按截帧张数计量<br />各项独立计费                  |
| 直播审核 | 直播音频反垃圾  | 按直播时长计量                              |
| 音频审核 | 音频反垃圾    | 按音频时长计量                              |
| 文本审核 | 文本反垃圾    | 按调用次数计量                              |

# 图片鉴黄 [#图片鉴黄]

| 总调用量                | 机器智能审核价格（单位：元／百张） |
| :------------------ | :---------------- |
| 第 0 张 至 300 万张      | 0.085             |
| 第 300 万张 至 1500 万张  | 0.075             |
| 第 1500 万张 至 3000 万张 | 0.065             |
| 3000 万至1亿张          | 0.055             |
| 1 亿张以上              | 0.05              |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-pulp-usageCnt">500</span>

  万次，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-pulp-expr" />
  </code>
</p>

# 图片鉴暴恐 [#图片鉴暴恐]

| 总调用量                | 机器智能审核价格（单位：元／百张） |
| :------------------ | :---------------- |
| 第 0 张 至 300 万张      | 0.085             |
| 第 300 万张 至 1500 万张  | 0.075             |
| 第 1500 万张 至 3000 万张 | 0.065             |
| 3000 万至1亿张          | 0.055             |
| 1 亿张以上              | 0.05              |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-terror-usageCnt">500</span>

  万次，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-terror-expr" />
  </code>
</p>

# 图片敏感人物识别 [#图片敏感人物识别]

| 总调用量                | 机器智能审核价格（单位：元／百张） |
| :------------------ | :---------------- |
| 第 0 张 至 300 万张      | 0.085             |
| 第 300 万张 至 1500 万张  | 0.075             |
| 第 1500 万张 至 3000 万张 | 0.065             |
| 3000 万至1亿张          | 0.055             |
| 1 亿张以上              | 0.05              |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-politician-usageCnt">500</span>

  万次，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-politician-expr" />
  </code>
</p>

# 图片广告识别 [#图片广告识别]

| 总调用量                | 机器智能审核价格（单位：元／百张） |
| :------------------ | :---------------- |
| 第 0 张 至 300 万张      | 0.085             |
| 第 300 万张 至 1500 万张  | 0.075             |
| 第 1500 万张 至 3000 万张 | 0.065             |
| 3000 万至1亿张          | 0.055             |
| 1 亿张以上              | 0.05              |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-ads-usageCnt">500</span>

  万次，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-ads-expr" />
  </code>
</p>

# 图片不良场景识别 [#图片不良场景识别]

| 总调用量                | 机器智能审核价格（单位：元／百张） |
| :------------------ | :---------------- |
| 第 0 张 至 300 万张      | 0.085             |
| 第 300 万张 至 1500 万张  | 0.075             |
| 第 1500 万张 至 3000 万张 | 0.065             |
| 3000 万至1亿张          | 0.055             |
| 1 亿张以上              | 0.05              |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-behavior-usageCnt">500</span>

  万次，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-behavior-expr" />
  </code>
</p>

# 图片异常检测 [#图片异常检测]

| 总调用量 | 机器智能审核价格（单位：元／千次） |
| :--- | :---------------- |
| 无阶梯  | 0.1               |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-inspect-usageCnt">500</span>

  万次，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-inspect-expr" />
  </code>
</p>

# 图片审核（图片多鉴合一） [#图片审核图片多鉴合一]

图片审核接口根据实际调用的服务单独收费，例如，调用图片审核接口时，同时做了图片鉴黄、鉴暴恐、敏感人物识别和图片广告识别，那么最终的价格是按照单个服务的价格总和。

例：
用户一个月调用图片审核，同时使用了图片鉴黄、图片鉴暴恐、图片敏感人物识别和图片广告识别，其调用量为500万次，账单金额为:
图片鉴黄：

```text
3000000*0.085/100+2000000*0.075/100＝2550+1500=4050元
```

图片鉴暴恐：

```text
3000000*0.085/100+2000000*0.075/100＝2550+1500=4050元
```

图片敏感人物识别：

```text
3000000*0.085/100+2000000*0.075/100＝2550+1500=4050元
```

图片广告识别：

```text
3000000*0.085/100+2000000*0.075/100＝2550+1500=4050元
```

总价为：

```text
4050+4050+4050+4050=16200元
```

# 视频鉴黄 [#视频鉴黄]

视频鉴黄是对视频截帧后，对截帧进行图片鉴黄，所以视频鉴黄价格实际使用的是截帧图片鉴黄的价格，与图片鉴黄共用范围。

例：
某月视频文件使用视频鉴黄服务，视频截帧的数量为400万，即视频鉴黄产生的图片鉴黄量为400万；当月图片文件使用鉴黄服务，其调用量为100万。则这个月总的图片鉴黄调用量为500万，账单金额则为:
图片鉴黄：

```text
3000000*0.085/100+2000000*0.075/100＝2550+1500=4050元
```

# 视频鉴暴恐 [#视频鉴暴恐]

视频鉴暴恐是对视频截帧后，对截帧进行图片鉴暴恐，所以视频鉴暴恐价格实际使用的是截帧图片鉴暴恐的价格，与图片鉴暴恐共用范围。

例：
某月视频文件使用视频鉴暴恐服务，视频截帧的数量为400万，即视频鉴暴恐产生的图片鉴暴恐量为400万；当月图片文件使用鉴暴恐服务，其调用量为100万。则这个月总的图片鉴暴恐调用量为500万，账单金额则为:
图片鉴暴恐：

```text
3000000*0.085/100+2000000*0.075/100＝2550+1500=4050元
```

# 视频敏感人物识别 [#视频敏感人物识别]

视频敏感人物识别是对视频截帧后，对截帧进行图片敏感人物识别，所以视频敏感人物识别价格实际使用的是截帧图片敏感人物识别的价格，与图片敏感人物识别共用范围。

例：
某月视频文件使用视频敏感人物识别服务，视频截帧的数量为400万，即视频敏感人物识别产生的图片敏感人物识别量为400万；当月图片文件使用敏感人物识别服务，其调用量为100万。则这个月总的图片敏感人物识别调用量为500万，账单金额则为:
图片敏感人物识别：

```text
3000000*0.085/100+2000000*0.075/100＝2550+1500=4050元
```

# 视频广告识别 [#视频广告识别]

视频广告识别是对视频截帧后，对截帧进行图片广告识别，所以视频广告识别价格实际使用的是截帧图片广告识别的价格，与图片广告识别共用范围。

例：
某月视频文件使用视频广告识别服务，视频截帧的数量为400万，即视频广告识别产生的图片广告识别量为400万；当月图片文件使用广告识别服务，其调用量为100万。则这个月总的图片广告识别调用量为500万，账单金额则为:
图片广告识别：

```text
3000000*0.085/100+2000000*0.075/100＝2550+1500=4050元
```

# 直播鉴黄 [#直播鉴黄]

| 总调用量                | 机器智能审核价格（单位：元／百张） |
| :------------------ | :---------------- |
| 第 0 张 至 300 万张      | 0.18              |
| 第 300 万张 至 1500 万张  | 0.16              |
| 第 1500 万张 至 3000 万张 | 0.15              |
| 3000 万张以上           | 0.13              |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-lpulp-usageCnt">500</span>

  万次，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-lpulp-expr" />
  </code>
</p>

# 直播鉴暴恐 [#直播鉴暴恐]

| 总调用量                | 机器智能审核价格（单位：元／百张） |
| :------------------ | :---------------- |
| 第 0 张 至 300 万张      | 0.18              |
| 第 300 万张 至 1500 万张  | 0.16              |
| 第 1500 万张 至 3000 万张 | 0.15              |
| 3000 万张以上           | 0.13              |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-lterror-usageCnt">500</span>

  万次，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-lterror-expr" />
  </code>
</p>

# 直播敏感人物识别 [#直播敏感人物识别]

| 总调用量                | 机器智能审核价格（单位：元／百张） |
| :------------------ | :---------------- |
| 第 0 张 至 300 万张      | 0.18              |
| 第 300 万张 至 1500 万张  | 0.16              |
| 第 1500 万张 至 3000 万张 | 0.15              |
| 3000 万张以上           | 0.13              |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-lpolitician-usageCnt">500</span>

  万次，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-lpolitician-expr" />
  </code>
</p>

# 直播广告识别 [#直播广告识别]

| 总调用量                | 机器智能审核价格（单位：元／百张） |
| :------------------ | :---------------- |
| 第 0 张 至 300 万张      | 0.18              |
| 第 300 万张 至 1500 万张  | 0.16              |
| 第 1500 万张 至 3000 万张 | 0.15              |
| 3000 万张以上           | 0.13              |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-lads-usageCnt">500</span>

  万次，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-lads-expr" />
  </code>
</p>

# 直播音频反垃圾 [#直播音频反垃圾]

| 总调用量 | 机器智能审核价格（单位：元／分钟） |
| :--- | :---------------- |
| 无阶梯  | 0.02              |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-laantispam-usageCnt">500</span>

  分钟，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-laantispam-expr" />
  </code>
</p>

# 音频反垃圾 [#音频反垃圾]

| 总调用量 | 机器智能审核价格（单位：元／分钟） |
| :--- | :---------------- |
| 无阶梯  | 0.02              |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-aantispam-usageCnt">500</span>

  分钟，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-aantispam-expr" />
  </code>
</p>

# 文本反垃圾 [#文本反垃圾]

| 总调用量 | 机器智能审核价格（单位：元／千次） |
| :--- | :---------------- |
| 无阶梯  | 1.0               |

<p>
  例：

  <br />

  用户一个月的调用量为

  <span class="censor-border-bottom" data-calc-id="censor-price-tantispam-usageCnt">500</span>

  万次，账单金额约为:
</p>

<p>
  <code>
    <span data-calc-id="censor-price-tantispam-expr" />
  </code>
</p>


# 机器智能审核资源包 (/products/censor/pricing/1-censor-plus-manual)



最近更新时间: 2026-05-08 10:27:14

如果您有大量内容需要审核，或每月计划审核量相对固定，建议您购买资源包，资源包享有更多优惠折扣。可以从[云商城](https://qmall.qiniu.com/template/NTg?ref=category\&spec_combo=MjIzOQ)自助下单。

# **1.审核通用资源包** [#1审核通用资源包]

通用资源包支持抵扣图片鉴黄、鉴暴恐、政治人物识别、图片广告识别、直播视频鉴黄、鉴暴恐、政治人物识别、图文违规识别，抵扣系数为1:1:1:1:2:2:2:2。
例如，当您购买了规格为1000万的包，当实际使用图片鉴黄100张时，可用资源包抵扣100张，当实际使用直播视频鉴黄一百张，相当于抵扣本资源包两百张。

| 总调用量P  | 价格        |
| :----- | :-------- |
| 10 万   | 60 元      |
| 100 万  | 550 元     |
| 1000 万 | 5,100 元   |
| 3000 万 | 14,580 元  |
| 5000 万 | 23,580 元  |
| 1 亿    | 45,480 元  |
| 2 亿    | 83,280 元  |
| 5 亿    | 182,280 元 |
| 10 亿   | 335,280 元 |

# **2.单鉴服务包** [#2单鉴服务包]

单鉴服务包是指单个鉴黄包、单个鉴暴恐包、单个敏感人物识别包。
例如，总调用量5000万的包，指用户在半年内可以调用图片鉴黄5000万，或图片鉴暴恐5000万，或图片敏感人物识别5000万。

| 总调用量P  | 价格        |
| :----- | :-------- |
| 10 万   | 60 元      |
| 100 万  | 550 元     |
| 1000 万 | 5,100 元   |
| 3000 万 | 14,580 元  |
| 5000 万 | 23,580 元  |
| 1 亿    | 45,480 元  |
| 2 亿    | 83,280 元  |
| 5 亿    | 182,280 元 |
| 10 亿   | 335,280 元 |


# 审核结果复核 (/products/censor/scenarios/0-result-self-check)



最近更新时间: 2026-05-08 11:17:44

查看最新文档：[结果复核](/products/censor/6-censor-portal-review)


# 增量审核回调 (/products/censor/scenarios/1-incremental-audit-callback)



最近更新时间: 2026-05-08 11:17:44

本文介绍触发并完成了七牛增量审核后，回调地址可收到的回调信息，增量审核回调的使用须知等，帮助您正确地处理回调信息。

# 使用限制须知 [#使用限制须知]

* 支持不设置增量审核回调
* 增量审核回调与自动封禁，至少需要开启一种
* 若设置了回调，进行了一次增量审核，则触发一次回调
* 若回调失败（回调地址响应5XX状态码），则会进行一定次数重试
* 增量审核支持回调，存量审核不支持回调
* 关于开启/修改增量审核回调，请参考：[开通增量审核](/products/censor/scenarios/1-incremental-audit-callback#3)、[查看修改配置](/products/censor/scenarios/1-incremental-audit-callback#4)

# 新图片审核回调格式 [#新图片审核回调格式]

\| 参数 | 类型 | 说明 |
\| :--- | :--- : | :--- |
\| `id` | string | 处理任务的persistentID，请参考：[persistent ID 的常见问题](/faq/dora/other-dora/3643-how-to-acquire-persistent-id)。 |
\| `pipeline` | string | 处理队列名，请参考：[关于七牛的流媒体队列](/faq/dora/av-processing/2500-streaming-media-queue-about-seven-cows)。 |
\| `code` | string | 状态码`0`成功，`1`等待处理，`2`正在处理，`3`处理失败，`4`通知提交失败。 |
\| `desc` | string | 与状态码相对应的详细描述。 |
\| `reqid` | string | 云处理请求的请求id，主要用于七牛技术人员的问题排查。 |
\| `inputBucket` | string | 处理源文件所在的空间名。 |
\| `inputKey` | string | 处理源文件的文件名。 |
\| `result.disable` | bool | 文件是否被禁用的标识，`true`表示文件已被禁用，`false`表示文件没有被禁用。如果用户在增量设置中开启了“自动禁用违规文件”，那么增量违规文件就会被自动禁用，此时该字段就显示为`true`。 |
\| `result.result.suggestion` | string | `suggestion`是针对文件级别的管控建议，取值包括：\[“block”,”review”,”pass”]，请参考本文档后面的审核结果管控建议说明部分，查看管控建议详细说明。这个值主要取决于单个审核类型的管控建议值`result.result.scenes.op.suggestion`，如果单个审核类型中存在 `block`的值，那么文件级别的管控建议值一定是`block`；如果单个审核类型中不存在 `block`的值，但是存在`review`的值，那么文件级别的管控建议值一定是`review`；如果单个审核类型中都是 `normal`的值，那么文件级别的管控建议值一定是`normal`。|
\| `result.result.scenes.op.result` | json | `op`显示审核设置中勾选的审核类型，`pulp`是涉黄识别的检测结果、`terror`是暴恐识别的检测结果、`politician`是敏感人物识别的检测结果。|
\| `result.result.scenes.op.suggestion` | string | `suggestion`是各种审核类型的对应的管控建议，取值包括：\[“block”,”review”,”pass”]，请参考本文档后面的审核结果管控建议说明部分，查看管控建议详细说明。 |
\| `op.result.label` | string | 图片所属的标签，一张图片只会有一个标签。 |
\| `op.result.score` | float | 图片所属标签的置信度。 |
\| `op.suggestion` | string | 图片的管控建议值，取值包括：\[“block”,”review”,”pass”]。 |
\| `op.result.faces` | interface | `op`为`politician` 且 `op.result.label`非`normal` 时，显示详细检测人脸结果。其中`boundingBox`表示人脸矩形框信息，类型为map。`boundingBox.pst`表示人脸矩形框在图片中的位置坐标\[左上，右上，右下，左下]，类型为list\[4]。`boundingBox.score`表示人脸位置检测置信度，类型为float。 |

```
{
    "id": "z0.5b8911ea38b9f324a5734c32",
    "pipeline": "0.default",
    "code": 0,
    "desc": "The fop was completed successfully",
    "reqid": "mH0AAOWK5yLQ708V",
    "inputBucket": "netback",
    "inputKey": "Image-2016-09-08-00-50-1632.jpg",
    "items": [
        {
            "cmd": "image-censor/v2/pulp/terror/politician|bucket-inspect/v2/true|notify-filter/true/http%3A%2F%2Fargus-ccp.xs.cg.dora-internal.qiniu.io%3A5001%2Fv1%2Fmsg%2Fpfop%2F1380827137%2Fe7db1a97-8cf8-4bb7-8664-7d5d8fb7bd53%2Fimage",
            "code": 0,
            "desc": "The fop was completed successfully",
            "result": {
                "disable": true,
                "result": {
                    "code": 200,
                    "message": "OK",
                    "scenes": {
                        "politician": {
                            "result": {
                                "faces": [
                                    {
                                        "bounding_box": {
                                            "pts": [
                                                [
                                                    277,
                                                    37
                                                ],
                                                [
                                                    340,
                                                    37
                                                ],
                                                [
                                                    340,
                                                    124
                                                ],
                                                [
                                                    277,
                                                    124
                                                ]
                                            ],
                                            "score": 0.99987173
                                        }
                                    }
                                ],
                                "label": "face"
                            },
                            "suggestion": "pass"
                        },
                        "pulp": {
                            "result": {
                                "label": "pulp",
                                "score": 0.98557895
                            },
                            "suggestion": "block"
                        },
                        "terror": {
                            "result": {
                                "label": "normal",
                                "score": 0.96237665
                            },
                            "suggestion": "pass"
                        }
                    },
                    "suggestion": "block"
                }
            },
            "returnOld": 0
        }
    ]
}
```

# 旧图片审核回调格式 [#旧图片审核回调格式]

为了兼容老用户的使用，我们保留了旧的图片审核回调格式。

```
{
    "id": "z0.5b6bb27938b9f324a587e7c8",
    "pipeline": "0.default",
    "code": 0,
    "desc": "The fop was completed successfully",
    "reqid": "InkAAF_K_UoOGUkV",
    "inputBucket": "netback",
    "inputKey": "pulp-2018-04-04T04-09-27-XZ498IU50WTbUB_u91bHyw==.jpg",
    "items": [
        {
            "cmd": "image-censor/pulp|bucket-inspect/v1/tpulp/0.6|notify-filter/true/http%3A%2F%2Fargus-ccp.xs.cg.dora-internal.qiniu.io%3A5001%2Fv1%2Fmsg%2Fpfop%2F1380827137%2F23c26dae-6856-4ca7-85bd-33a6fc22a5a8%2Fimage",
            "code": 0,
            "desc": "The fop was completed successfully",
            "result": {
                "disable": false,
                "result": {
                    "code": 0,
                    "message": "",
                    "result": {
                        "details": [
                            {
                                "label": 2,
                                "review": false,
                                "score": 0.94214475,
                                "type": "pulp"
                            }
                        ],
                        "label": 0,
                        "review": false,
                        "score": 0.94214475
                    }
                }
            },
            "returnOld": 0
        }
    ]
}
```

# 视频审核回调格式 [#视频审核回调格式]

\| 参数 | 类型 | 说明 |
\| :--- | :--- : | :--- |
\| `id` | string | 处理任务的persistentID，请参考：[persistent ID 的常见问题](/faq/dora/other-dora/3643-how-to-acquire-persistent-id)。 |
\| `pipeline` | string | 处理队列名，请参考：[关于七牛的流媒体队列](/faq/dora/av-processing/2500-streaming-media-queue-about-seven-cows)。 |
\| `code` | string | 状态码`0`成功，`1`等待处理，`2`正在处理，`3`处理失败，`4`通知提交失败。 |
\| `desc` | string | 与状态码相对应的详细描述。 |
\| `reqid` | string | 云处理请求的请求id，主要用于七牛技术人员的问题排查。 |
\| `inputBucket` | string | 处理源文件所在的空间名。 |
\| `inputKey` | string | 处理源文件的文件名。 |
\| `result.disable` | bool | 文件是否被禁用的标识，`true`表示文件已被禁用，`false`表示文件没有被禁用。如果用户在增量设置中开启了“自动禁用违规文件”，那么增量违规文件就会被自动禁用，此时该字段就显示为`true`。 |
\| `result.result.suggestion` | string | `suggestion`是针对文件级别的管控建议，取值包括：\[“block”,”review”,”pass”]，请参考本文档后面的审核结果管控建议说明部分，查看管控建议详细说明。这个值主要取决于单个审核类型的管控建议值`result.result.scenes.op.suggestion`，如果单个审核类型中存在 `block`的值，那么文件级别的管控建议值一定是`block`；如果单个审核类型中不存在 `block`的值，但是存在`review`的值，那么文件级别的管控建议值一定是`review`；如果单个审核类型中都是 `normal`的值，那么文件级别的管控建议值一定是`normal`。|
\| `result.result.scenes.op.segments` | interface | `op`显示审核设置中勾选的审核类型，`pulp`是涉黄识别的检测结果、`terror`是暴恐识别的检测结果、`politician`是敏感人物识别的检测结果。|
\| `result.result.scenes.op.suggestion` | string | `suggestion`是各种审核类型的对应的管控建议，取值包括：\[“block”,”review”,”pass”]，请参考本文档后面的审核结果管控建议说明部分，查看管控建议详细说明。|
\| `op.segments.cuts` | interface | 每种审核类型下的视频片段结果。例如`pulp.segments.cuts`表示`pulp`是涉黄识别的一个视频片段的审核结果。 |
\| `op.segments.offset_begin` | int | 视频片段起始的时间位置，单位为毫秒。 |
\| `op.segments.offset_end` | int | 视频片段结束的时间位置，单位为毫秒。 |
\| `op.segments.cuts.offset` | int | 视频片段中，视频截帧的时间位置，单位为毫秒。|
\| `op.segments.cuts.result` | interface  | 视频截帧得到的图片的检测标签，结果与具体的命令有关，里面包含`op.segments.cuts.result.label`和`op.segments.cuts.result.score`。例如，视频鉴黄的命令`pulp`的label有`normal`正常, `terror`。 |
\| `op.segments.cuts.result.label` | string  | 视频截帧所属的标签，一个视频截帧只会有一个标签。|
\| `op.segments.cuts.result.score` | float  | 视频截帧所属标签的置信度。 |
\| `op.segments.cuts.suggestion` | string  | 视频截帧的管控建议值，取值包括：\[“block”,”review”,”pass”]。 |
\| `op.segments.cuts.uri` | string | 视频截帧的保存路径，增量的保存路径是用户在审核设置中填入的视频截帧地址。 |
\| `op.segments.cuts.result.faces` | interface | `op`为`politician` 且 `op.segments.cuts.result.label`非`normal` 时，显示详细检测人脸结果。其中`boundingBox`表示人脸矩形框信息，类型为map。`boundingBox.pst`表示人脸矩形框在图片中的位置坐标\[左上，右上，右下，左下]，类型为list\[4]。`boundingBox.score`表示人脸位置检测置信度，类型为float。 |

```
{
    "id":"z0.5ba33a7838b9f349c890494e",
    "pipeline":"1380432151.aaaaa",
    "code":0,
    "desc":"The fop was completed successfully",
    "reqid":"mHIAADaYZi76BlYV",
    "inputBucket":"netback",
    "inputKey":"alicia_love_summer-2018-06-11-4.mp4",
    "items":[
        {
            "cmd":"video-censor/v1/pulp/terror/politician/save/eyJidWNrZXQiOiJndW9qdW4iLCJwcmVmaXgiOiJyZXN1bHQwMiJ9/vframe/eyJtb2RlIjowLCJpbnRlcnZhbCI6MX0=|bucket-inspect/v2/true|notify-filter/true/http%3A%2F%2Fargus-ccp.xs.cg.dora-internal.qiniu.io%3A5001%2Fv1%2Fmsg%2Fpfop%2F1380827137%2F6b21bf0d-487f-4482-ac84-0eacaa84fdd1%2Fvideo",
            "code":0,
            "desc":"The fop was completed successfully",
            "result":{
                "disable":true,
                "result":{
                    "scenes":{
                        "politician":{
                            "segments":[
                                {
                                    "cuts":[
                                        {
                                            "offset":0,
                                            "result":{
                                                "faces":[
                                                    {
                                                        "bounding_box":{
                                                            "pts":[
                                                                [
                                                                    373,
                                                                    0
                                                                ],
                                                                [
                                                                    621,
                                                                    0
                                                                ],
                                                                [
                                                                    621,
                                                                    201
                                                                ],
                                                                [
                                                                    373,
                                                                    201
                                                                ]
                                                            ],
                                                            "score":0.999931
                                                        }
                                                    }
                                                ],
                                                "label":"face"
                                            },
                                            "suggestion":"pass",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/0"
                                        }
                                    ],
                                    "offset_begin":0,
                                    "offset_end":0,
                                    "suggestion":"pass"
                                }
                            ],
                            "suggestion":"pass"
                        },
                        "pulp":{
                            "segments":[
                                {
                                    "cuts":[
                                        {
                                            "offset":0,
                                            "result":{
                                                "label":"pulp",
                                                "score":0.99717283
                                            },
                                            "suggestion":"block",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/0"
                                        },
                                        {
                                            "offset":1000,
                                            "result":{
                                                "label":"pulp",
                                                "score":0.9972186
                                            },
                                            "suggestion":"block",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/1000"
                                        },
                                        {
                                            "offset":2000,
                                            "result":{
                                                "label":"pulp",
                                                "score":0.9977402
                                            },
                                            "suggestion":"block",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/2000"
                                        },
                                        {
                                            "offset":3000,
                                            "result":{
                                                "label":"pulp",
                                                "score":0.99914116
                                            },
                                            "suggestion":"block",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/3000"
                                        },
                                        {
                                            "offset":4000,
                                            "result":{
                                                "label":"pulp",
                                                "score":0.9995518
                                            },
                                            "suggestion":"block",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/4000"
                                        },
                                        {
                                            "offset":5000,
                                            "result":{
                                                "label":"pulp",
                                                "score":0.99918985
                                            },
                                            "suggestion":"block",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/5000"
                                        },
                                        {
                                            "offset":6000,
                                            "result":{
                                                "label":"pulp",
                                                "score":0.9961891
                                            },
                                            "suggestion":"block",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/6000"
                                        },
                                        {
                                            "offset":7000,
                                            "result":{
                                                "label":"pulp",
                                                "score":0.9980135
                                            },
                                            "suggestion":"block",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/7000"
                                        },
                                        {
                                            "offset":8000,
                                            "result":{
                                                "label":"pulp",
                                                "score":0.9989619
                                            },
                                            "suggestion":"block",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/8000"
                                        },
                                        {
                                            "offset":9000,
                                            "result":{
                                                "label":"pulp",
                                                "score":0.99891454
                                            },
                                            "suggestion":"block",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/9000"
                                        }
                                    ],
                                    "offset_begin":0,
                                    "offset_end":9000,
                                    "suggestion":"block"
                                }
                            ],
                            "suggestion":"block"
                        },
                        "terror":{
                            "segments":[
                                {
                                    "cuts":[
                                        {
                                            "offset":0,
                                            "result":{
                                                "label":"normal",
                                                "score":0.99140936
                                            },
                                            "suggestion":"pass",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/0"
                                        },
                                        {
                                            "offset":1000,
                                            "result":{
                                                "label":"normal",
                                                "score":0.9995901
                                            },
                                            "suggestion":"pass",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/1000"
                                        },
                                        {
                                            "offset":2000,
                                            "result":{
                                                "label":"normal",
                                                "score":0.9995938
                                            },
                                            "suggestion":"pass",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/2000"
                                        },
                                        {
                                            "offset":3000,
                                            "result":{
                                                "label":"normal",
                                                "score":0.9969735
                                            },
                                            "suggestion":"pass",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/3000"
                                        },
                                        {
                                            "offset":4000,
                                            "result":{
                                                "label":"normal",
                                                "score":0.99999845
                                            },
                                            "suggestion":"pass",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/4000"
                                        },
                                        {
                                            "offset":5000,
                                            "result":{
                                                "label":"normal",
                                                "score":1
                                            },
                                            "suggestion":"pass",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/5000"
                                        },
                                        {
                                            "offset":6000,
                                            "result":{
                                                "label":"normal",
                                                "score":0.99997556
                                            },
                                            "suggestion":"pass",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/6000"
                                        },
                                        {
                                            "offset":7000,
                                            "result":{
                                                "label":"normal",
                                                "score":0.9999733
                                            },
                                            "suggestion":"pass",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/7000"
                                        },
                                        {
                                            "offset":8000,
                                            "result":{
                                                "label":"normal",
                                                "score":0.9999771
                                            },
                                            "suggestion":"pass",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/8000"
                                        },
                                        {
                                            "offset":9000,
                                            "result":{
                                                "label":"normal",
                                                "score":0.9999926
                                            },
                                            "suggestion":"pass",
                                            "uri":"qiniu://1380827137@/guojun/result02/qiniu_censor_tmp/CAAAAAatfi36BlYV/9000"
                                        }
                                    ],
                                    "offset_begin":0,
                                    "offset_end":9000,
                                    "suggestion":"pass"
                                }
                            ],
                            "suggestion":"pass"
                        }
                    },
                    "suggestion":"block"
                }
            },
            "returnOld":0
        }
    ]
}
```


# API调用图片审核 历史文档 (/products/censor/image-censor/0-image-content-audit-to-historical-documents)



最近更新时间: 2019-07-11 17:54:54

目前七牛API调用审核接口有两个版本：v1版本、v3版本
我们推荐您使用v3版本，如果您目前在使用v1版本，建议您更换至v3版本

v1与v3版本区别

* v3版本是线上环境最新版本，v1是旧版本，不提供维护。内容审核存量/增量审核，目前都是用的v3版本
* v3与v1接口参数有所差异，比如 图片审核参数中审核类型，v3是params.scenes，v1是params.type
* v3版本审核结果准确度更高

以下是v1版本的历史文档，若需要可以参考：

* [API调用图片审核 V1](/products/censor/image-censor/0-image-content-audit-to-historical-documents)
* [API调用图片鉴黄V1](/products/censor/image-censor/0-image-content-audit-to-historical-documents)
* [API调用图片鉴暴恐V1](/products/censor/image-censor/0-image-content-audit-to-historical-documents)
* [API调用图片敏感人物识别V1](/products/censor/image-censor/0-image-content-audit-to-historical-documents)


# API调用图片审核 (/products/censor/image-censor)



最近更新时间: 2026-04-21 11:43:40

本文介绍了同步调用图片内容审核`/v3/image/censor`的接口，帮助您正确使用此API进行图片内容审核。图片内容审核API支持基于API URL发起HTTP/HTTPS POST请求。

# 使用限制 [#使用限制]

* 图片大小不超过10M
* 图片尺寸大于32x32，小于5000x5000
* RGB通道数为3和3以内的图片，不能包含 alpha 通道
* 图片格式支持 png、jpg、jpeg、bmp、webp、tif 和 gif
* 接口响应时间依赖图片的下载时间。请保证被审核图片所在的存储服务稳定可靠，建议您使用七牛云存储或者CDN缓存等。

# 功能描述 [#功能描述]

图片内容审核 API 主要用于检测或识别图片中的不良信息，并给出审核结果管控建议。支持的审核类型包括：图片鉴黄、图片鉴暴恐、图片敏感人物识别、图片广告识别。
**审核类型scenes与相应的label/group**
在提交内容审核任务时，您需要指定审核类型**scenes**；而在返回结果中，则包含了您指定的类型对应的label结果分类参数。

| 审核类型     | 说明             | scenes     | label/group                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :------- | :------------- | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 图片鉴黄     | 识别图片中的色情、性感内容。 | pulp       | normal：正常图片，无色情内容<br />sexy：性感图片<br />pulp：色情图片                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 图片鉴暴恐    | 识别图片中的暴恐内容。    | terror     | bloodiness：血腥<br />self\_burning：自焚<br />beheaded：斩首类<br />march\_crowed：人群聚集类<br />fight\_police：警民冲突<br />fight\_person：民众肢体接触<br />illegal\_flag：违规旗帜类<br />guns：枪<br />knives：刀<br />special\_characters: 特殊字符文字<br />special\_clothing: 特殊着装<br />anime\_bloodiness：动漫血腥类<br />anime\_knives：二次元刀<br />anime\_guns：二次元枪<br />bloodiness\_animal: 动物血腥<br />fire\_weapon: 武器火光<br />army: 军队<br />bomb: 爆炸<br />national\_logo: 国家标志<br />military\_uniform: 军警制服<br />politics：涉政<br />violence：暴恐<br />normal：正常<br /> |
| 图片敏感人物识别 | 识别图片中的敏感人物人脸。  | politician | 图片敏感人物识别的label返回的是敏感人物的姓名；<br />group返回的是该敏感人物所属的分组，目前支持的分组有：<br />domestic\_statesman：国内政要<br />foreign\_statesman：国外政要<br />chinese\_martyr：革命英烈<br />affairs\_official\_gov：落马官员（政府）<br />affairs\_official\_ent：落马官员（企事业）<br />terrorist：恐怖分子<br />affairs\_celebrity：劣迹艺人<br />politics：涉政人物<br />anti\_china\_people: 反华分子<br />famous\_people: 知名人物<br />pub\_opinion\_people: 舆论人物<br />porn\_celebrity: 色情人物<br />normal: 正常<br />                                                                                  |
| 图片广告识别   | 识别图片中的广告内容。    | ads        | 图片广告识别的label有：<br />summary\_ads：文字广告<br /> qr\_code：二维码<br />bar\_code：一维码<br />ad: 其它广告<br />normal: 正常                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 图片不良场景识别 | 识别图片中的不良场景内容。  | behavior   | 图片不良场景识别的label有：<br />behavior：不良场景<br /> normal: 正常                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

# 请求参数 [#请求参数]

对公网可访问的图片，通过图片URL发起POST请求的方式，进行高性能的图片鉴黄、图片鉴暴恐、图片敏感人物识别和图片广告识别。目前，支持提交单张图片进行同步审核。此方法同时支持对七牛云bucket中的单张图片进行同步审核。

**请求方式** POST

**请求接口** [http://ai.qiniuapi.com/v3/image/censor](http://ai.qiniuapi.com/v3/image/censor)

**请求Header**

| 字段            | 取值                                                                                                                                                                            |
| :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | application/json                                                                                                                                                              |
| Authorization | Qiniu \<AccessKey>:\<Sign> <br />注意: 用户请根据AccessKey和SecretKey后生成鉴权，以便进行身份验证。`Sign`的取值以及`Authorization`签名方法请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken) |

**请求参数**

| 字段            | 类型           | 是否必选 | 说明                                                                                                                                                                                                                          |
| :------------ | :----------- | :--- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data.uri      | string       | Y    | 图片资源。支持两种资源表达方式：<br />1. 网络图片URL地址，支持http、https和[qiniu协议](/products/censor/3-censor-params#2)的资源；<br />2. 图片 base64 编码字符串，需在编码字符串前加上前缀 `data:application/octet-stream;base64`, 例：`data:application/octet-stream;base64,xxx` |
| params.scenes | string array | Y    | 审核类型，必填字段，没有默认值，可选项：pulp/terror/politician/ads                                                                                                                                                                              |

# 返回参数 [#返回参数]

**返回参数**

| 字段                                                  | 取值           | 说明                                                                                                                                                                                                                                     |
| :-------------------------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code                                                | int          | 处理状态：200 调用成功                                                                                                                                                                                                                          |
| message                                             | string       | 与code对应的状态描述信息                                                                                                                                                                                                                         |
| result.suggestion                                   | string       | 图片的审核结果管控建议说明<br /> 根据内容审核中各种审核类型的返回结果，系统会将审核结果转换成对应的管控建议，取值包括：block/review/pass。<br />  suggestion=block：表示系统确认审核内容违规，建议您将其删除。<br /> suggestion=review：表示系统无法确认审核内容是否违规，建议您进行人工复核。<br /> suggestion=pass：表示系统确认审核内容正常，建议您忽略该文件。<br /> |
| result.scenes.`&lt;scene&gt;`                       | json 结构体     | 审核类型，目前支持：pulp/terror/politician/ads/behavior                                                                                                                                                                                          |
| result.scenes.`&lt;scene&gt;`.suggestion            | string       | 该审核类型的结果管控建议，参见result.suggestion                                                                                                                                                                                                       |
| result.scenes.`&lt;scene&gt;`.details\[]            | object array | 该审核类型的详细信息数组                                                                                                                                                                                                                           |
| result.scenes.`&lt;scene&gt;`.details\[].suggestion | string       | 详细的结果管控建议，参见result.suggestion                                                                                                                                                                                                          |
| result.scenes.`&lt;scene&gt;`.details\[].label      | string       | 该审核类型返回的标签，具体请参见上文中**审核类型scenes与相应的label/group**                                                                                                                                                                                       |
| result.scenes.`&lt;scene&gt;`.details\[].score      | float        | 该审核类型结果置信度                                                                                                                                                                                                                             |

## 敏感人物识别返回参数 [#敏感人物识别返回参数]

| 字段                                                      | 取值     | 说明                                                    |
| :------------------------------------------------------ | :----- | :---------------------------------------------------- |
| result.scenes.politician.details\[].group               | string | 敏感人物的分组，具体请参见上文中**审核类型scenes与相应的label/group**         |
| result.scenes.politician.details\[].detections\[].pts   | array  | 图片中检测到的敏感人物人方框坐标，形式为\[4]\[2]int，分别表示方框的\[左上，右上，右下，左下] |
| result.scenes.politician.details\[].detections\[].score | float  | 图片中检测到的人脸匹配为敏感人物的置信度                                  |
| result.scenes.politician.details\[].sample.uri          | string | 该敏感人物的参考图链接                                           |
| result.scenes.politician.details\[].sample.pts          | array  | 参考图中敏感人物的人脸方框坐标                                       |

## 鉴暴恐返回参数 [#鉴暴恐返回参数]

| 字段                                                  | 取值    | 说明                                                                                                                                                                                          |
| :-------------------------------------------------- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| result.scenes.terror.details\[].detections\[].pts   | array | 形式为\[4]\[2]int，分别表示方框的\[左上，右上，右下，左下]。图片鉴暴恐审核，当审核结果label为以下五种时，该字段用于返回检测到的物体方框坐标：<br />“illegal\_flag：违规旗帜类”<br />”guns：枪”<br />”knives：刀”<br />”anime\_knives：二次元刀”<br />“anime\_guns：二次元枪” |
| result.scenes.terror.details\[].detections\[].score | float | 图片中检测到的物体置信度                                                                                                                                                                                |

## 广告识别返回参数 [#广告识别返回参数]

| 字段                                                  | 取值    | 说明                                                                 |
| :-------------------------------------------------- | :---- | :----------------------------------------------------------------- |
| result.scenes.ads.details\[].detections\[].pts      | array | 形式为\[4]\[2]int，分别表示方框的\[左上，右上，右下，左下]。图片广告审核，该字段用于返回检测到的物体或敏感词的方框坐标 |
| result.scenes.ads.details\[].detections\[].score    | float | 图片中检测到的物体置信度                                                       |
| result.scenes.ads.details\[].detections\[].comments | array | 图片广告审核，当审核结果label为"summary\_ads”(文字广告)，该字段用于返回识别到的敏感词              |

# 示例 [#示例]

## 请求示例 [#请求示例]

```
POST /v3/image/censor HTTP/1.1
Host: ai.qiniuapi.com
Content-Type: application/json
Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=
{
    "data": {
        "uri": "https://mars-assets.qnssl.com/resource/gogopher.jpg"
    },
    "params": {
        "scenes": [
            "pulp",
            "terror",
            "politician"
        ]
    }
}
```

注意： 请把 Authorization 换成您的账号七牛鉴权 QiniuToken

## 返回示例 [#返回示例]

```
{
    "message": "OK",
    "code": 200,
    "result": {
        "scenes": {
            "terror": {
                "details": [
                    {
                        "score": 0.99985,
                        "suggestion": "pass",
                        "label": "normal"
                    }
                ],
                "suggestion": "pass"
            },
            "politician": {
                "suggestion": "pass"
            },
            "pulp": {
                "details": [
                    {
                        "score": 0.65191,
                        "suggestion": "pass",
                        "label": "normal"
                    }
                ],
                "suggestion": "pass"
            }
        },
        "suggestion": "pass"
    }
}
```

# 代码示例 [#代码示例]

**注意**

* 运行方法：`python ImageReview.py &lt;censor \| pulp \| terror \| politician \| ads&gt; &lt;uri&gt;`
* 代码中需填入账号的 `ak`、`sk`

图片内容审核（ImageReview\.py）

```
# -*- coding: utf-8 -*-
from qiniu import Auth, QiniuMacAuth, http
import requests, json, sys

url = 'http://ai.qiniuapi.com/v3/image/censor'

access_key = '<ak>'
secret_key = '<sk>'

auth = QiniuMacAuth(access_key, secret_key)

body = {
    "data": {
        "uri": "<uri>"
    },
    "params": {
        "scenes": []
    }
}

scenes = {
    'censor': ['pulp', 'terror', 'politician', 'ads'],
    'pulp': ['pulp'],
    'terror': ['terror'],
    'politician': ['politician'],
		'ads': ['ads']
}

body["params"]["scenes"] = scenes[sys.argv[1]]
body["data"]["uri"] = sys.argv[2]

header = {"Content-Type": "application/json"}
ret, res = http._post_with_qiniu_mac_and_headers(url,json.dumps(body), auth,header)

headers = {"code": res.status_code, "reqid": res.req_id, "xlog": res.x_log}

print(json.dumps(headers, indent=4, ensure_ascii=False))
print(json.dumps(ret, indent=4, ensure_ascii=False))
```

**注意**

* 调用命令：`python ImageReview.py censor https://mars-assets.qnssl.com/resource/gogopher.jpg`
* 第一段是响应头headers，请在反馈问题时提供`reqid`字段
* 第二段是响应body，即审核结果，字段解释参考返回报文

```
{
    "reqid": "IisAABW7lT5croUV, IisAABW7lT5croUV",
    "code": 200,
    "xlog": "COMMON-GATE:255;AI:256"
}
{
    "message": "OK",
    "code": 200,
    "result": {
        "scenes": {
            "terror": {
                "details": [
                    {
                        "score": 0.99985,
                        "suggestion": "pass",
                        "label": "normal"
                    }
                ],
                "suggestion": "pass"
            },
            "politician": {
                "suggestion": "pass"
            },
            "pulp": {
                "details": [
                    {
                        "score": 0.65191,
                        "suggestion": "pass",
                        "label": "normal"
                    }
                ],
                "suggestion": "pass"
            }
        },
        "suggestion": "pass"
    }
}
```

# 服务价格 [#服务价格]

内容审核 API 仅支持机器智能审核，服务价格请参考[机器智能审核阶梯计费方式](/products/censor/pricing/0-censor-price)。


# API调用视频审核 历史文档 (/products/censor/video-censor/0-video-content-audit-to-historical-documents)



最近更新时间: 2020-09-09 14:50:18

目前七牛API调用审核接口有两个版本：v1版本、v3版本
我们推荐您使用v3版本，如果您目前在使用v1版本，建议您更换至v3版本

v1与v3版本区别

* v3版本是线上环境最新版本，v1是旧版本，不提供维护。内容审核存量/增量审核，目前都是用的v3版本
* v3与v1接口参数有所差异，比如 图片审核参数中审核类型，v3是params.scenes，v1是params.type
* v3版本审核结果准确度更高

以下是v1版本的历史文档，若需要可以参考：

* [API调用视频鉴黄V1](/products/censor/video-censor/0-video-content-audit-to-historical-documents)
* [API调用视频鉴暴恐V1](/products/censor/video-censor/0-video-content-audit-to-historical-documents)
* API调用视频敏感人物识别V1


# API调用视频审核回调 (/products/censor/video-censor/1-video-review-callback)



最近更新时间: 2023-06-19 14:01:19

本文介绍发送并完成了API调用视频审核后，回调地址可收到的回调信息，视频审核回调的使用须知等，帮助您正确地处理回调信息。

# 使用限制须知 [#使用限制须知]

* API调用视频审核支持不设置回调
* 若设置了回调，进行了一次API调用视频审核，则触发一次回调
* 若回调失败（回调地址响应5XX状态码），目前不会进行重试
* API调用视频审核支持回调，API调用图片审核不支持回调
* API调用视频审核回调 与 增量审核回调 属于两种回调，需求场景、调用方法、返回内容格式均不同
* 关于API调用视频审核接口，请参考：[API调用视频审核](/products/censor/video-censor)

# API调用视频审核回调格式 [#api调用视频审核回调格式]

| 字段                                                              | 取值      | 说明                                                                                                                                                                                                                                   |
| :-------------------------------------------------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                                                              | string  | 服务器返回的，唯一标识该视频任务的ID。                                                                                                                                                                                                                 |
| request                                                         | json结构体 | 视频审核请求中的body。                                                                                                                                                                                                                        |
| status                                                          | string  | 任务状态，`WAITING/DOING/RESCHEDULED/FAILED/FINISHED`,`RESCHEDULED`是指等待重试中。                                                                                                                                                               |
| result                                                          | json结构体 | 视频内容审核的返回结果，详情请查看`*表.视频内容审核的返回结果*`。                                                                                                                                                                                                  |
| created\_at                                                     | string  | 任务创建时间，如：2019-01-02T15:03:04。                                                                                                                                                                                                        |
| updated\_at                                                     | string  | 任务更新时间，如：2019-01-02T15:03:04。                                                                                                                                                                                                        |
| rescheduled\_at                                                 | string  | 任务重试时间，如：2019-01-02T16:03:04。                                                                                                                                                                                                        |
| result.code                                                     | int     | 处理状态：200 调用成功                                                                                                                                                                                                                        |
| result.message                                                  | string  | 与code对应的状态描述信息                                                                                                                                                                                                                       |
| result.suggestion                                               | string  | 视频的审核结果管控建议说明<br />根据内容审核中各种审核类型的返回结果，系统会将审核结果转换成对应的管控建议，取值包括：\[“block”,”review”,”pass”]。<br />suggestion=block：表示系统确认审核内容违规，建议您将其删除。<br />suggestion=review：表示系统无法确认审核内容是否违规，建议您进行人工复核。<br />suggestion=pass：表示系统确认审核内容正常，建议您忽略该文件。 |
| result.scenes.`&lt;type&gt;`                                    | json结构体 | 审核类型,目前支持"pulp", "terror", "politician"                                                                                                                                                                                              |
| result.scenes.`&lt;type&gt;`.suggestion                         | string  | 该审核类型的结果管控建议，参见result.suggestion                                                                                                                                                                                                     |
| result.scenes.`&lt;type&gt;`.cuts\[]                            | array   | 该审核类型的截帧审核结果数组                                                                                                                                                                                                                       |
| result.scenes.`&lt;type&gt;`.cuts\[].suggestion                 | string  | 该审核类型的截帧审核结果管控建议，参见result.suggestion                                                                                                                                                                                                 |
| result.scenes.`&lt;type&gt;`.cuts\[].offset                     | int     | 该审核类型的截帧的时间位置                                                                                                                                                                                                                        |
| result.scenes.`&lt;type&gt;`.cuts\[].uri                        | string  | 该审核类型的截帧uri                                                                                                                                                                                                                          |
| result.scenes.`&lt;type&gt;`.cuts\[].details\[]                 | array   | 该审核类型的截帧审核详细信息数组                                                                                                                                                                                                                     |
| result.scenes.`&lt;type&gt;`.cuts\[].details\[].suggestion      | string  | 该审核类型的截帧审核结果详细的结果管控建议，参见result.suggestion                                                                                                                                                                                            |
| result.scenes.`&lt;type&gt;`.cuts\[].details\[].label           | string  | 该审核类型的截帧审核结果标签，具体请参见[图片内容审核](/products/censor/image-censor)的label/group                                                                                                                                                              |
| result.scenes.`&lt;type&gt;`.cuts\[].details\[].score           | string  | 该审核类型的截帧审核结果置信度                                                                                                                                                                                                                      |
| result.scenes.politician.cuts\[].details\[].group               | string  | 该审核类型的截帧审核结果分组，具体请参见[图片内容审核](/products/censor/image-censor)的label/group                                                                                                                                                              |
| result.scenes.politician.cuts\[].details\[].sample.uri          | string  | 该敏感人物的参考图链接                                                                                                                                                                                                                          |
| result.scenes.politician.cuts\[].details\[].sample.pts          | array   | 参考图中敏感人物的人脸方框坐标                                                                                                                                                                                                                      |
| result.scenes.politician.cuts\[].details\[].detections\[].pts   | array   | 截帧中检测到的敏感人物人方框坐标                                                                                                                                                                                                                     |
| result.scenes.politician.cuts\[].details\[].detections\[].score | string  | 截帧中检测到的人脸匹配为敏感人物的置信度                                                                                                                                                                                                                 |
| result.scenes.terror.cuts\[].details\[].detections\[].pts       | array   | 当截帧审核结果label为以下五种时，该字段用于返回检测到的物体方框坐标：<br />“illegal\_flag：违规旗帜类”<br />”guns：枪”<br />”knives：刀”<br />”anime\_knives：二次元刀”<br />“anime\_guns：二次元枪”                                                                                     |
| result.scenes.terror.cuts\[].details\[].detections\[].score     | string  | 截帧中检测到的物体置信度                                                                                                                                                                                                                         |

```
{
  "id": "5d271f33e74cf10008cb8ae3",
  "vid": "",
  "request": {
    "data": {
      "uri": "http://video.a.com/xxx/0.ts"
    },
    "params": {
      "sync": false,
      "scenes": [
        "pulp",
        "terror",
        "politician"
      ],
      "cut_param": {
        "interval_msecs": 5000
      },
      "hook_url": "http://requestbin.fullcontact.com/1mhqoh41"
    }
  },
  "status": "FINISHED",
  "result": {
    "code": 200,
    "message": "OK",
    "result": {
      "suggestion": "pass",
      "scenes": {
        "politician": {
          "cuts": [
            {
              "offset": 520,
              "suggestion": "pass"
            },
            {
              "offset": 5520,
              "suggestion": "pass"
            }
          ],
          "suggestion": "pass"
        },
        "pulp": {
          "cuts": [
            {
              "details": [
                {
                  "label": "normal",
                  "score": 0.97960997,
                  "suggestion": "pass"
                }
              ],
              "offset": 520,
              "suggestion": "pass"
            },
            {
              "details": [
                {
                  "label": "normal",
                  "score": 0.95487005,
                  "suggestion": "pass"
                }
              ],
              "offset": 5520,
              "suggestion": "pass"
            }
          ],
          "suggestion": "pass"
        },
        "terror": {
          "cuts": [
            {
              "details": [
                {
                  "label": "normal",
                  "score": 0.9920667,
                  "suggestion": "pass"
                }
              ],
              "offset": 520,
              "suggestion": "pass"
            },
            {
              "details": [
                {
                  "label": "normal",
                  "score": 0.84314996,
                  "suggestion": "pass"
                }
              ],
              "offset": 5520,
              "suggestion": "pass"
            }
          ],
          "suggestion": "pass"
        }
      }
    }
  },
  "created_at": "2019-07-11T19:36:19.982+08:00",
  "updated_at": "2019-07-11T19:36:24.349+08:00",
  "rescheduled_at": "2019-07-11T19:36:19.982+08:00"
}
```


# API调用视频审核 (/products/censor/video-censor)



最近更新时间: 2022-09-23 15:35:28

本文介绍了异步调用视频内容审核`/v3/video/censor`的接口，帮助您正确使用此 API 进行视频内容审核，支持基于API URL发起HTTP/HTTPS POST请求的方式调用。

# 使用限制 [#使用限制]

* 视频大小不超过1G。
* 视频格式支持 mp4、flv、mov、avi、wmv、ts和mpg。
* 支持用户设定截帧频率，但单个视频最大截帧数为3000帧。如根据截帧频率计算出来的截帧数大于3000帧，则会按最大3000帧对整个视频进行均匀截帧。
* 接口响应时间依赖视频的下载时间。请保证被审核视频所在的存储服务稳定可靠，建议您使用七牛云存储或者CDN缓存等。

# 功能描述 [#功能描述]

视频内容审核 API 主要用于检测或识别视频中的不良信息，并给出审核结果管控建议。支持的审核类型包括：视频鉴黄、视频鉴暴恐、视频敏感人物识别。

**审核类型scenes与相应的label/group**
在提交内容审核任务时，您需要指定审核类型**scenes**；而在返回结果中，则包含了您指定的类型对应的label结果分类参数，具体label/group请参见[图片内容审核](/products/censor/image-censor)。

# 请求说明 [#请求说明]

请求方式： POST

请求url： [http://ai.qiniuapi.com/v3/video/censor](http://ai.qiniuapi.com/v3/video/censor)

**请求Header**

| 字段            | 取值                                                                                                                                                                                 |
| :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | application/json                                                                                                                                                                   |
| Authorization | Qiniu \<AccessKey>:\<Sign> <br />注意: 用户请根据 AccessKey 和 SecretKey 后生成鉴权，以便进行身份验证，`Sign`的取值以及`Authorization`签名方法请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken)。 |

**请求参数**

| 字段                                | 类型      | 是否必选 | 说明                                                                                                    |
| :-------------------------------- | :------ | :--- | :---------------------------------------------------------------------------------------------------- |
| data.uri                          | string  | Y    | 视频URL地址，目前支持http、https和[qiniu协议](/products/censor/3-censor-params#2)的资源。                              |
| data.id                           | string  | N    | 调用者设置的视频唯一标识，异步处理的返回结果中会带上该信息。                                                                        |
| params.scenes                     | array   | Y    | 审核类型，必填字段，没有默认值，可选项：pulp/terror/politician/ads/behavior。                                              |
| params.cut\_param.interval\_msecs | int     | N    | 截帧频率，单位：毫秒，默认为5000（5s)，取值范围为1000～60000（即1s\~60s）。                                                     |
| params.saver.bucket               | string  | N    | 视频截帧文件存入的bucket，目前只支持存入七牛云华东的bucket。如何创建七牛云bucket，请参见[文档](/products/kodo/0-console-quickstart#step1)。 |
| params.saver.prefix               | string  | N    | 保存的截帧文件的前缀。                                                                                           |
| params.hook\_url                  | string  | N    | 视频检测结束后的回调地址。关于API调用视频审核回调文档，请参见[文档](/products/censor/video-censor/1-video-review-callback)           |
| params.hook\_auth                 | Boolean | N    | true/false，默认为false，设置回调请求中加入请求头authorization，用于回调服务器鉴权                                               |

**请求示例**

```
POST /v3/video/censor HTTP/1.1
Host: ai.qiniuapi.com
Content-Type: application/json
Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=

{
    "data": {
        "uri": "https://mars-assets.qnssl.com/scene.mp4",
        "id": "video_censor_test"
    },
    "params": {
        "scenes": [
            "pulp",
            "terror",
            "politician"
        ],
        "cut_param": {
            "interval_msecs": 5000
        }
    }
}
```

注意： 请把 Authorization 换成您的账号七牛鉴权 QiniuToken

## 系统接受到请求后，会立即返回job\_id，视频审核结果通过job\_id获得。 [#系统接受到请求后会立即返回job_id视频审核结果通过job_id获得]

```
HTTP/1.1 200 OK
Content-Type: application/json

{
	"job": <job_id>
}
```

| 参数       | 类型     |  必选 | 说明                   |
| :------- | :----- | :-: | :------------------- |
| `job_id` | string |  是  | 服务器返回的，唯一标识该视频任务的ID。 |

# 通过job\_id获取视频审核结果 [#通过job_id获取视频审核结果]

**请求语法**

```
GET /v3/jobs/video/<job-id> HTTP/1.1
Host: ai.qiniuapi.com
Authorization: Qiniu <AccessKey>:<Sign>
```

**注意：** 需要在请求的 head 部分添加[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken)，以进行用户身份验证。

| 参数       | 类型     |  必选 | 说明                   |
| :------- | :----- | :-: | :------------------- |
| `job_id` | string |  是  | 服务器返回的，唯一标识该视频任务的ID。 |

**返回参数说明**

| 字段              | 取值      | 说明                                                                     |
| :-------------- | :------ | :--------------------------------------------------------------------- |
| id              | string  | 服务器返回的，唯一标识该视频任务的ID。                                                   |
| vid             | string  | 视频唯一标识，申请任务时传入的data.id。                                                |
| request         | json结构体 | 视频审核请求中的body。                                                          |
| status          | string  | 任务状态，`WAITING/DOING/RESCHEDULED/FAILED/FINISHED`,`RESCHEDULED`是指等待重试中。 |
| result          | json结构体 | 视频内容审核的返回结果，详情请查看`*表.视频内容审核的返回结果*`。                                    |
| created\_at     | string  | 任务创建时间，如：2019-01-02T15:03:04。                                          |
| updated\_at     | string  | 任务更新时间，如：2019-01-02T15:03:04。                                          |
| rescheduled\_at | string  | 任务重试时间，如：2019-01-02T16:03:04。                                          |

*表.视频内容审核的返回结果*

| 字段                                                              | 取值      | 说明                                                                                                                                                                                                                                   |
| :-------------------------------------------------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code                                                            | int     | 处理状态：200 调用成功                                                                                                                                                                                                                        |
| message                                                         | string  | 与code对应的状态描述信息                                                                                                                                                                                                                       |
| result.suggestion                                               | string  | 视频的审核结果管控建议说明<br />根据内容审核中各种审核类型的返回结果，系统会将审核结果转换成对应的管控建议，取值包括：\[“block”,”review”,”pass”]。<br />suggestion=block：表示系统确认审核内容违规，建议您将其删除。<br />suggestion=review：表示系统无法确认审核内容是否违规，建议您进行人工复核。<br />suggestion=pass：表示系统确认审核内容正常，建议您忽略该文件。 |
| result.scenes.`&lt;type&gt;`                                    | json结构体 | 审核类型,目前支持"pulp", "terror", "politician"                                                                                                                                                                                              |
| result.scenes.`&lt;type&gt;`.suggestion                         | string  | 该审核类型的结果管控建议，参见result.suggestion                                                                                                                                                                                                     |
| result.scenes.`&lt;type&gt;`.cuts\[]                            | array   | 该审核类型的截帧审核结果数组                                                                                                                                                                                                                       |
| result.scenes.`&lt;type&gt;`.cuts\[].suggestion                 | string  | 该审核类型的截帧审核结果管控建议，参见result.suggestion                                                                                                                                                                                                 |
| result.scenes.`&lt;type&gt;`.cuts\[].offset                     | int     | 该审核类型的截帧的时间位置                                                                                                                                                                                                                        |
| result.scenes.`&lt;type&gt;`.cuts\[].uri                        | string  | 该审核类型的截帧uri                                                                                                                                                                                                                          |
| result.scenes.`&lt;type&gt;`.cuts\[].details\[]                 | array   | 该审核类型的截帧审核详细信息数组                                                                                                                                                                                                                     |
| result.scenes.`&lt;type&gt;`.cuts\[].details\[].suggestion      | string  | 该审核类型的截帧审核结果详细的结果管控建议，参见result.suggestion                                                                                                                                                                                            |
| result.scenes.`&lt;type&gt;`.cuts\[].details\[].label           | string  | 该审核类型的截帧审核结果标签，具体请参见[图片内容审核](/products/censor/image-censor)的label/group                                                                                                                                                              |
| result.scenes.`&lt;type&gt;`.cuts\[].details\[].score           | string  | 该审核类型的截帧审核结果置信度                                                                                                                                                                                                                      |
| result.scenes.politician.cuts\[].details\[].group               | string  | 该审核类型的截帧审核结果分组，具体请参见[图片内容审核](/products/censor/image-censor)的label/group                                                                                                                                                              |
| result.scenes.politician.cuts\[].details\[].sample.uri          | string  | 该敏感人物的参考图链接                                                                                                                                                                                                                          |
| result.scenes.politician.cuts\[].details\[].sample.pts          | array   | 参考图中敏感人物的人脸方框坐标                                                                                                                                                                                                                      |
| result.scenes.politician.cuts\[].details\[].detections\[].pts   | array   | 截帧中检测到的敏感人物人方框坐标                                                                                                                                                                                                                     |
| result.scenes.politician.cuts\[].details\[].detections\[].score | string  | 截帧中检测到的人脸匹配为敏感人物的置信度                                                                                                                                                                                                                 |
| result.scenes.terror.cuts\[].details\[].detections\[].pts       | array   | 当截帧审核结果label为以下五种时，该字段用于返回检测到的物体方框坐标：<br />“illegal\_flag：违规旗帜类”<br />”guns：枪”<br />”knives：刀”<br />”anime\_knives：二次元刀”<br />“anime\_guns：二次元枪”                                                                                     |
| result.scenes.terror.cuts\[].details\[].detections\[].score     | string  | 截帧中检测到的物体置信度                                                                                                                                                                                                                         |

**返回示例**

```
{
    "id":"5c416b7afb09fe00089e37be",
	"vid":"video_censor_test",
    "request":{
        ...
    },
    "status":"FINISHED",
    "result":{
        "code":200,
        "message":"OK",
        "result":{
            "suggestion":"pass",
            "scenes":{
                "politician":{
                    "cuts":[
                        {
                            "offset":0,
                            "suggestion":"pass"
                        },
                        {
                            "offset":657,
                            "suggestion":"pass"
                        }
                    ],
                    "suggestion":"pass"
                },
                "pulp":{
                    "cuts":[
                        {
                            "details":[
                                {
                                    "label":"normal",
                                    "score":0.99976,
                                    "suggestion":"pass"
                                }
                            ],
                            "offset":0,
                            "suggestion":"pass"
                        },
                        {
                            "details":[
                                {
                                    "label":"normal",
                                    "score":0.99998,
                                    "suggestion":"pass"
                                }
                            ],
                            "offset":657,
                            "suggestion":"pass"
                        }
                    ],
                    "suggestion":"pass"
                },
                "terror":{
                    "cuts":[
                        {
                            "details":[
                                {
                                    "label":"normal",
                                    "score":0.76111,
                                    "suggestion":"pass"
                                }
                            ],
                            "offset":0,
                            "suggestion":"pass"
                        },
                        {
                            "details":[
                                {
                                    "label":"normal",
                                    "score":0.52299,
                                    "suggestion":"pass"
                                }
                            ],
                            "offset":657,
                            "suggestion":"pass"
                        }
                    ],
                    "suggestion":"pass"
                }
            }
        }
    },
    "created_at":"2019-01-18T14:00:26.865+08:00",
    "updated_at":"2019-01-18T14:01:01.148+08:00",
    "rescheduled_at":"2019-01-18T14:00:26.865+08:00"
}
```

# 代码示例 [#代码示例]

**注意**

* 运行方法：`python VideoReview.py &lt;censor \| pulp \| terror \| politician&gt; &lt;uri&gt;`，得到job\_id
* 代码中需填入账号的 `ak`、`sk`

视频内容审核（VideoReview\.py）

```
# -*- coding: utf-8 -*-
from qiniu import Auth, QiniuMacAuth, http
import requests, json, sys

access_key = '<ak>'
secret_key = '<sk>'

auth = QiniuMacAuth(access_key, secret_key)

url = 'http://ai.qiniuapi.com/v3/video/censor'

body = {
	"data": {
		"uri": "<uri>"
	},
	"params": {
        "scenes":[],
        "cut_param": {
            "interval_msecs": 5000
        }
    }
}

ops = {
	"censor": ["pulp","terror","politician"],
	"pulp": ["pulp"],
	"terror": ["terror"],
	"politician": ["politician"],
}

body["params"]["scenes"] = ops[sys.argv[1]]
body["data"]["uri"] = sys.argv[2]

ret, res = http._post_with_qiniu_mac(url, body, auth)

headers = {"code": res.status_code, "reqid": res.req_id, "xlog": res.x_log}

print(json.dumps(headers, indent=4, ensure_ascii=False))
print(json.dumps(ret, indent=4, ensure_ascii=False))
```

**注意**

* 调用命令：`python VideoReview.py.py censor https://mars-assets.qnssl.com/scene.mp4`

```
{
    "reqid": "lSQAAPpUdoS3roUV, lSQAAPpUdoS3roUV",
    "code": 200,
    "xlog": "COMMON-GATE:2;AI:2"
}
{
    "job": "5c6fe7f59a0b0500082b774f"
}
```

**注意**

* 运行方法：`python AsyncResult.py <job_id>`，得到视频审核结果
* 代码中需填入账号的 `ak`、`sk`

通过job\_id获取视频审核结果（AsyncResult.py）

```
# -*- coding: utf-8 -*-
from qiniu import Auth, QiniuMacAuth
import requests, json, sys

access_key = '<ak>'
secret_key = '<sk>'

auth = QiniuMacAuth(access_key, secret_key)

url = 'http://ai.qiniuapi.com/v3/jobs/video/' + sys.argv[1]

token = "Qiniu " + auth.token_of_request("GET", "ai.qiniuapi.com", url, "")

r = requests.get(url, headers={'Authorization': token})
print json.dumps(json.loads(r.text), indent=4, ensure_ascii=False)
```

**注意**

* 调用命令：`python AsyncResult.py 5c6fe7f59a0b0500082b774f`

```
{
    "status": "FINISHED",
    "rescheduled_at": "2019-02-22T20:15:49.931+08:00",
    "created_at": "2019-02-22T20:15:49.931+08:00",
    "request": {
        "params": {
            "cut_param": {
                "interval_msecs": 5000
            },
            "sync": false,
            "scenes": [
                "pulp",
                "terror",
                "politician"
            ]
        },
        "data": {
            "uri": "https://mars-assets.qnssl.com/scene.mp4"
        }
    },
    "updated_at": "2019-02-22T20:15:52.426+08:00",
    "result": {
        "message": "OK",
        "code": 200,
        "result": {
            "scenes": {
                "terror": {
                    "suggestion": "pass",
                    "cuts": [
                        {
                            "details": [
                                {
                                    "score": 0.8864266,
                                    "suggestion": "pass",
                                    "label": "normal"
                                }
                            ],
                            "suggestion": "pass",
                            "offset": 520
                        },
                        {
                            "details": [
                                {
                                    "score": 0.99499327,
                                    "suggestion": "pass",
                                    "label": "normal"
                                }
                            ],
                            "suggestion": "pass",
                            "offset": 5520
                        }
                    ]
                },
                "politician": {
                    "suggestion": "pass",
                    "cuts": [
                        {
                            "suggestion": "pass",
                            "offset": 520
                        },
                        {
                            "suggestion": "pass",
                            "offset": 5520
                        }
                    ]
                },
                "pulp": {
                    "suggestion": "pass",
                    "cuts": [
                        {
                            "details": [
                                {
                                    "score": 0.6159534,
                                    "suggestion": "pass",
                                    "label": "normal"
                                }
                            ],
                            "suggestion": "pass",
                            "offset": 520
                        },
                        {
                            "details": [
                                {
                                    "score": 0.65406007,
                                    "suggestion": "pass",
                                    "label": "normal"
                                }
                            ],
                            "suggestion": "pass",
                            "offset": 5520
                        }
                    ]
                }
            },
            "suggestion": "pass"
        }
    },
    "id": "5c6fe7f59a0b0500082b774f"
}
```

# 服务价格 [#服务价格]

视频内容审核是对视频截帧后，进行截帧图片内容审核，所以视频内容审核的价格实际使用的是截帧图片审核的价格，与图片内容审核共用范围。

1）按照设置的截帧频率对视频进行截帧，不额外收费
2）对截帧进行图片内容审核
图片内容审核价格请[参考](https://www.qiniu.com/prices?source=dora)。

**示例：**

某月客户视频文件使用视频鉴黄服务，视频截帧的数量为400万，即视频鉴黄产生的图片鉴黄量为400万；当月图片文件使用鉴黄服务，其调用量为106万。则这个月总的图片鉴黄调用量为506万，账单金额则为:
图片鉴黄：

```text
3000000*0.155/100+2000000*0.145/100=4650+2900＝7550元
```


# 配置概览 (/products/dcdn/configuration/0-dcdn-an-overview-of-the-configuration)



最近更新时间: 2023-08-11 15:21:59

**七牛云 DCDN** 支持多项自定义配置，您可以根据自身业务需要进行设置。

# [基础信息](http://) [#基础信息]

| 配置项  | 描述            | 默认值       |
| ---- | ------------- | --------- |
| 覆盖   | 切换加速区域，变更加速区域 | 中国大陆      |
| IP协议 | CDN支持的IP协议    | IPv4/IPv6 |

# [回源配置](/products/cdn/configuration-management-fusion/1-back-to-the-source-configuration) [#回源配置]

| 配置项    | 描述                         | 默认值  |
| ------ | -------------------------- | ---- |
| 源站信息   | 资源的回源域名或IP                 | 用户配置 |
| 回源HOST | 指定请求的服务器的域名，默认为加速域名        | 加速域名 |
| 回源协议   | 请求回源的协议，如需修改回源协议请先开启 HTTPS | HTTP |

# [缓存配置](/products/cdn/configuration-management-fusion/2-cache-configuration) [#缓存配置]

| 配置项     | 描述                          | 默认值 |
| ------- | --------------------------- | --- |
| 静态缓存规则  | 定义指定资源内容的缓存行为及缓存时间规则        | 未开启 |
| 忽略URL参数 | 资源缓存时去除 URL「?」后的全部或指定参数进行缓存 | 未开启 |

# [访问控制配置](http://) [#访问控制配置]

| 配置项                                                                                                               | 描述                                        | 默认值 |
| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | --- |
| [referer防盗链](/products/dcdn/configuration/dcdn-access-control-configuration/0-dcdn-referer-hotlinking-prevention) | 配置 Request Header 中 referer 黑白名单，从而限制访问来源 | 未开启 |
| [IP黑白名单](/products/dcdn/configuration/dcdn-access-control-configuration/1-dcdn-ip-black-and-white-list)           | 允许或者禁止某些 IP 或 IP 段的访问，帮助您解决恶意 IP 盗刷、攻击等问题 | 未开启 |

# [HTTPS配置](/products/cdn/configuration-management-fusion/4-https-configuration) [#https配置]

| 配置项       | 描述                                                      | 默认值 |
| --------- | ------------------------------------------------------- | --- |
| 开启HTTPS   | 开启 HTTPS 安全加速，支持 SSL 证书绑定及 HTTPS 状态管理                   | 未开启 |
| 更换证书      | 更换即将过期或泄漏的证书                                            | 无   |
| 强制HTTPS   | 开启后 HTTP 请求会强制跳转到 HTTPS 进行访问，关闭时默认兼容用户的 HTTP/HTTPS 请求   | 未开启 |
| HTTP/2 访问 | HTTP/2 是最新的 HTTP 协议，用以最小化网络延迟，提升网络速度，如需使用请您先配置 HTTPS 证书 | 未开启 |

# [HTTP 响应头配置](/products/dcdn/configuration/0-dcdn-an-overview-of-the-configuration) [#http-响应头配置]

| 配置项                                                                                    | 描述                                   | 默认值 |
| -------------------------------------------------------------------------------------- | ------------------------------------ | --- |
| [HTTP 响应头](/products/dcdn/configuration/4-dcdn-the-http-response-header-configuration) | 支持设置或删除常见的 HTTP 请求响应头配置，用以向客户端提供额外信息 | 未开启 |


# 回源配置 (/products/dcdn/configuration/1-dcdn-back-to-the-source-configuration)



最近更新时间: 2026-08-31 17:22:08

您可以登录**七牛管理控制台**选择**DCDN控制台**,可以在控制台中查看域名的回源配置信息及进行相关配置修改。

<br />

# 操作说明 [#操作说明]

登录**七牛管理控制台**后，进入**DCDN控制台**，选择【域名管理】，点击【配置】：

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/1-dcdn-back-to-the-source-configuration/FqXSrwGOCH1gnV5yp6gwVM8XzMkL-2b6ce3773312.webp" width="600" />

<img />

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/1-dcdn-back-to-the-source-configuration/Fs7TdH1N-jqezX6cjWAqY1PORfHF-64feb858234d.webp" width="600" />

<img />

进入域名配置界面，点击【修改配置】进行回源配置的修改。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/1-dcdn-back-to-the-source-configuration/FjiEPRn1s6qkyykth4lAsTLeI1Gq-14c8f2f9170f.webp" width="600" />

<img />

### 1. 基础配置 [#1-基础配置]

回源方式支持源站域名、IP地址两种模式：

* 源站域名：设置指定域名作为DCDN回源的源站，源站的域名需要与加速域名不一致。
* IP地址：设置IP作为CDN回源的源站，支持配置多个IP；回源采用轮询方式，首次选择配置的第一个IP进行回源，当发现某一源站IP异常时，将跳过此IP并进入惩罚时间，屏蔽5秒。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/1-dcdn-back-to-the-source-configuration/FtDiy25uA3GBX1rsd9QPyBP4v3G0-3655509ecfc5.webp" width="600" />

<img />

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/1-dcdn-back-to-the-source-configuration/Fs0PBCIaJiKwPj1Bc1_WUvrJtKJb-accde4d783fb.webp" width="600" />

<img />

### 2. 回源 HOST [#2-回源-host]

回源 HOST：是指 CDN 节点在回源过程中，在源站访问的站点域名，默认是加速域名。「源站域名」模式下，回源 HOST 支持指定加速域名、源站域名、自定义配置，「IP地址」模式下，回源HOST 支持指定加速域名、自定义配置。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/1-dcdn-back-to-the-source-configuration/FkfXLvU4ebnAkK1QkYqso4KtTtHb-1666ec4ae991.webp" width="600" />

<img />

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/1-dcdn-back-to-the-source-configuration/Fr48pu2qDCvPOx38uabHHli9QA35-0cfa752e545a.webp" width="600" />

<img />

### 3. 回源协议 [#3-回源协议]

回源协议：即请求回源的协议，支持选择回源协议HTTP、遵循请求协议、HTTPS三种模式。

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/1-dcdn-back-to-the-source-configuration/FtdraeK0IzzTPiGXAK9j222Hbtqf-8d619ac2e34f.webp)

### 4. 回源验证 [#4-回源验证]

回源验证：保证源站的高可用，只有源站测试通过才能继续创建域名。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/1-dcdn-back-to-the-source-configuration/FpSr11R4ozCVG0VJutGhCJOQoXiy-325f74111da6.webp" width="600" />

<img />

### 5. Range回源 [#5-range回源]

Range回源：开启此功能，有助于减少大文件分发时回源消耗并缩短响应时间，但是此功能需要源站支持Range请求。
![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/1-dcdn-back-to-the-source-configuration/FiraqI7Pq20WdHR3qeXp8teZALiC-59903e191663.webp)

### 6. 回源超时 [#6-回源超时]

回源超时：开启回源超时配置，可自定义调整 DCDN 回源节点到源站的超时时间，HTTP 读取超时时间默认为 30s，可设置时间范围5～120秒。
![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/1-dcdn-back-to-the-source-configuration/Fr6HemczsC3F-upPlq8yhekHk3VK-40b725b0dc40.webp)


# 缓存配置 (/products/dcdn/configuration/2-dcdn-cache-configuration)



最近更新时间: 2026-04-30 16:38:28

缓存配置是指动静态混合资源中，静态资源在 DCDN 加速节点上遵循的一套缓存过期规则。全站加速默认全局动态回源不缓存，结合缓存规则可以实现动静态混合加速的效果。您可以登录**七牛管理控制台**选择**DCDN控制台**，在控制台中查看域名的缓存配置信息并进行修改。

<br />

# 操作说明 [#操作说明]

登录**七牛管理控制台**后，进入**DCDN控制台**，选择【域名管理】，点击【配置】

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/2-dcdn-cache-configuration/FkdTjx7pi_FF1o3LWN514Vkf6sfs-82be6ee0270b.webp" width="600" />

<img />

进入域名配置界面，点击【修改配置】进行缓存配置的修改。
![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/2-dcdn-cache-configuration/FgF2poxFCVyzL8cZzkro9MS3oL4f-db2d131342e1.webp)

### 1、静态缓存规则 [#1静态缓存规则]

静态缓存规则默认关闭，即没有任何缓存行为。开启后，可配置静态缓存规则针对部分资源进行缓存。

（1）推荐配置：

* .jpg;.jpeg;.png;.bmp;.gif;.webp;.ico  图片类型缓存1天。
* .js;.css;.txt;.xml;.shtml;.html;.htm;.csv;.bat  文本类型缓存1天。
* .m3u8 m3u8类型缓存1小时。
* .avi;.mkv;.mp4;.mov;.flv;.rm;.rmvb;.swf;.mp3;.wav;.wmv;.rmi;.aac 音视频类型缓存7天。
* .exe;.deb;.ipa;.apk;.sis;.psd;.dat 大文件类型缓存7天。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/2-dcdn-cache-configuration/FkK9p4rQT1ipIBHLRPBm4OvTaVHP-10f765db6b4f.webp" width="600" />

<img />

（2）添加后缀

* 后缀：必须以「.」(英文点)开始，多个后缀请用「;」(英文分号)隔开，例如(.png;.jpg;.gif)。
* 缓存规则最多可配置15条。
* 1条缓存规则中，最多10个后缀，「;」(英文分号)隔开。
* 时间单位：分/小时/天，只能输入整数，最大值为 365 天。
* 按从上至下顺序，采取优先匹配原则。

（3）添加目录

* 路径：必须以「/」(英文斜杠)开始，多个路径请用「;」(英文分号)隔开，例如: (/a/b/c;/d/e/f;/h/i/j) ，路 径中不能包含「.」，也不能以「/」结尾。
* 缓存规则最多可配置15条。
* 1条缓存规则中，最多10个路径，「;」(英文分号)隔开。
* 时间单位：分/小时/天，只能输入整数，最大值为 365 天。
* 按从上至下顺序，采取优先匹配原则。

### 2. 忽略URL参数 [#2-忽略url参数]

（1）保留所有参数：资源缓存时保留 URL「？」后的全部参数进行缓存，请确认请求的 URL 的参数值和文件有关再开启，否则会降低缓存命中率并增加 CDN 回源次数。
![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/2-dcdn-cache-configuration/Fk4NTCYP5xlvJU0YF-TFiISHJGjL-7711f4e3e87a.webp)

（2）忽略所有参数：资源缓存时去除 URL「?」后的全部参数进行缓存，忽略全部参数同时会导致图片处理等 FOP 功能失效。
![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/2-dcdn-cache-configuration/FopRORQtUP623qkRKB4kY6rSpxFp-7304eec48fb3.webp)

（3）保留指定参数：资源缓存时会仅仅保留您输入的指定参数然后进行缓存。
![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/2-dcdn-cache-configuration/FsMwWAXrjlIdTNxPSk-cRneB7Rj7-74fe61a34a78.webp)

（4）忽略指定参数：资源缓存时会去除您输入的指定参数然后进行缓存。
![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/2-dcdn-cache-configuration/FhXemBB8Zx8U6a0HaCmTje_0L10z-cf9eb0adbc46.webp)


# HTTPS配置 (/products/dcdn/configuration/3-dcdn-https-configuration)



最近更新时间: 2026-04-30 16:45:33

HTTPS 是指超文本传输安全协议（Hypertext Transfer Protocol Secure，缩写：HTTPS，常称为HTTP over TLS，HTTP over SSL或HTTP Secure）是一种通过计算机网络进行安全通信的传输协议。HTTPS经由HTTP进行通信，但利用SSL/TLS来加密数据包。HTTPS开发的主要目的，是提供对网站服务器的身份认证，保护交换数据的隐私与完整性。配置 HTTPS 时，需要您提供域名对应的证书，实现全网数据加密传输功能。您可以登录**七牛过滤控制台**选择**DCDN控制台**，进行HTTPS的配置。

<br />

# 操作说明 [#操作说明]

登录**七牛管理控制台**后，进入**DCDN控制台**，选择【域名管理】，点击【配置】。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/3-dcdn-https-configuration/Fl2jqVkwicwuVk55e8sKGNOXK9vU-b160f2bb30bd.webp" width="600" />

<img />

进入域名配置界面，**HTTPS配置**模块下点击【修改配置】。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/3-dcdn-https-configuration/FobdThhjRYJaztKe0cxRHxqOR9iE-ec1d10677689.webp" width="600" />

<img />

### 1. 开启 HTTPS [#1-开启-https]

如需启用**HTTPS服务**时，选择【HTTPS】即可，开启后需要选择对应的证书。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/3-dcdn-https-configuration/FtkGv9etD1UoLPRKLmzBkfoF_E93-6ad9d89de83e.webp" width="600" />

<img />

### 2. 更换证书 [#2-更换证书]

如已经完成了证书的上传，选择对应的证书即可

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/3-dcdn-https-configuration/Fi0DOyOW9_S_BpbtM-bw3FTT2PWs-605366eaad27.webp" width="600" />

<img />

注意：

* 证书筛选框只显示对应域名可用的所有证书，证书剩余有效期必须大于7天。
* 如未上传证书或此域名当前无可用证书，点击**七牛云证书服务**进入SSL证书服务控制台进行自有证书上传或购买证书操作。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/3-dcdn-https-configuration/FiOHSVgtfd9vo0z1X0z8K6LN_lqS-8cfedd7b2f82.webp" width="600" />

<img />

### 3. 强制HTTPS [#3-强制https]

如果您的加速域名开启了HTTPS配置，您可以设置【强制HTTPS】，开启后即使用户发起 HTTP 请求，也会强制跳转为 HTTPS 请求进行访问。此项默认为关闭状态，此时同时支持HTTP和HTTPS方式的请求。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/3-dcdn-https-configuration/FmvlUt7NHN76RqBIsqFH_Tr4nJ7X-b6294b0830c6.webp" width="600" />

<img />

### 4. 开启HTTP/2 [#4-开启http2]

如果您的加速域名开启了HTTPS配置，您可以设置【开启HTTP/2】，HTTP/2可以兼容HTTP/1.1的访问，优化网络延迟，提升网络速度，优化用户的网络使用体验。目前，Chrome、 Firefox、Safari 等主流浏览器已经支持 HTTP/2协议。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/3-dcdn-https-configuration/FrQ3PYJ6c9ET3q_fZ-SdMz3s5Umh-a17b7e92bb16.webp" width="600" />

<img />


# HTTP响应头配置 (/products/dcdn/configuration/4-dcdn-the-http-response-header-configuration)



最近更新时间: 2026-04-30 16:47:25

HTTP 消息头是指，在超文本传输协议（ Hypertext Transfer Protocol，HTTP）的请求和响应消息中，协议头部的组件。在 HTTP 消息头中，按其出现的上下文环境，分为通用头、请求头、响应头等。

其中 HTTP 响应头向客户端提供一些额外信息，比如谁在发送响应、响应者的功能，甚至与响应相关的一些特殊指令。这些头部有助于客户端处理响应，并在将来发起更好的请求。

当您的网站接入 DCDN 后，由于客户端和源站会根据 HTTP 响应头的字段信息进行相关的行为处理，所以会有修改 HTTP 响应头的需求。由于 HTTP 响应头配置是针对域名，因此一旦配置生效，对该域名下任意一个资源的响应消息中均会加入所配置头部。配置 HTTP 响应头仅影响客户端（如浏览器）的响应行为，不会影响到节点的缓存行为。

# 操作说明 [#操作说明]

您可以登录七牛管理控制台，并进入[**DCDN控制台**](https://portal.qiniu.com/dcdn/overview)，选择【域名管理】，点击【配置】。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/4-dcdn-the-http-response-header-configuration/Fp7dYxPFGHhhrOrdYPhtM_VV8CMO-3306a5023ce4.webp" width="600" />

<img />

进入域名配置界面，点击【修改配置】对 HTTP 响应头进行配置。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/4-dcdn-the-http-response-header-configuration/Fujb044OoVjGyl1tNF5QPXHbowyf-459463be98d2.webp" width="600" />

<img />

响应头支持【删除】【设置】操作。

<img src="/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/4-dcdn-the-http-response-header-configuration/Fk09AArR-I4WkKaR-sqD2dRZLbaM-73aa1ccb543c.webp" width="600" />

<img />

<br />

请根据实际情况选择 HTTP 响应头、响应头操作并配置相应的值。
目前七牛云CDN提供11个 HTTP 响应头参数可供您自定义取值，解释如下表所示。 如果您有其他 HTTP 头设置需求，请[提交工单](https://support.qiniu.com/tickets/new/form?category=%E9%85%8D%E7%BD%AE%E9%97%AE%E9%A2%98\&space=CDN)处理。

| HTTP 响应头                         | 描述                               | 示例                                                                                            |
| -------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------- |
| Access-control-allow-origin      | 指定允许的跨域请求的来源。                    | \* （\*表示全部域名；也可填写完整域名，例如 [http://www.qiniu.com](http://www.qiniu.com) 、http\://\*.qiniu.com ) |
| Access-Control-Allow-Headers     | 指定允许的跨域请求的字段。                    | X-Custom-Header                                                                               |
| Access-Control-Allow-Methods     | 指定允许的跨域请求方法。                     | POST,GET,OPTIONS                                                                              |
| Content-Type                     | 指定客户端程序响应对象的内容类型。                | Content-Type                                                                                  |
| Cache-Control                    | 指定客户端程序请求和响应遵循的缓存机制。             | no-cache,no-store                                                                             |
| Content-Disposition              | 指定客户端程序把请求所得的内容存为一个文件时提供的默认的文件名。 | attachment; filename="filename.jpg"                                                           |
| Content-Language                 | 指定客户端程序响应对象的语言。                  | zh-CN,en-US                                                                                   |
| Expires                          | 指定客户端程序响应对象的过期时间。                | Wed, 21 Oct 2015 07:28:00 GMT                                                                 |
| Access-Control-Max-Age           | 指定跨域请求时，对特定资源的预请求返回结果的缓存时间。      | 600（单位为秒，600表示10分钟）                                                                           |
| Access-Control-Expose-Headers    | 指定允许访问的自定义头信息。                   | Content-Length（可以输入多个头部时，需用 “,” 隔开。）                                                          |
| Access-Control-Allow-Credentials | 指定是否允许跨域请求携带验证信息，验证信息可以是cookies。 | true                                                                                          |

```
注：跨域是指某一个域名，如 www.aaa.com 下的某资源，向另一个域名 www.bbb.com 下的某资源发起请求，此时由于资源所属域名不同，即出现 跨域，不同的协议、不同的端口均会造成跨域访问的出现。此时必须在 Response Header 中增加跨域相关配置，才能让前者成功拿到数据。
```


# 批量复制 (/products/dcdn/configuration/5-dcdn-domain-bulk-copy)



最近更新时间: 2026-09-07 14:13:25

批量复制可以实现复制已有域名的配置完成批量添加域名，支持调整基础配置批量复制，也支持自定义勾选Referer 防盗链、IP 黑白名单、HTTP 响应头等配置项批量复制。

<br />

# 操作说明 [#操作说明]

### 1.进入CDN控制台 [#1进入cdn控制台]

登录**七牛管理控制台**后，进入**CDN控制台**，选择【域名管理】，点击目标域名**操作**项下的**复制**进入配置界面。

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/5-dcdn-domain-bulk-copy/FjvkgxHBhXE9etS7puf3_jFeuMy6-5c30852c09b8.webp)
注意：只有**成功**状态的域名支持批量复制

### 2.添加域名&确认配置 [#2添加域名确认配置]

在**加速域名**输入框中输入需要批量添加的域名，并确认**基本信息、源站配置和缓存配置**，若非预期配置可以修改。

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/5-dcdn-domain-bulk-copy/FtTif9_CtKrvpc7QLzHrC4Kocecd-309ced076595.webp)

注意：
a. 添加域名中存在未备案域名，加速范围只能选择海外；
b. 完整域名和泛域名需要分开添加，不能混在一起批量复制；
c. **源站测试**需要点击并显示测试通过后，才可以点击**下一步**，否则会报错提示“源站待测试”。

### 3.选择复制配置 [#3选择复制配置]

**配置项**：支持自定义勾选的批量复制配置项，包含Referer 防盗链、IP 黑白名单、HTTP 响应头等配置批。
**配置状态**：配置项的配置状态，包含开启和关闭两种。
**操作**：点击**详情**可以查看配置项的配置详情。

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/5-dcdn-domain-bulk-copy/FvQ-Hec22-NAOq45LxklUGf-DnSM-76607b98480d.webp)

注意：
a. 若被复制域名存在后端特殊配置（非控制台配置），该特殊配置无法复制，若需要请联系客服补充配置。
b. 因 HTTPS 证书配置需要重新绑定当前域名，不支持复制此配置，若需要请自助补充配置。
c. 配置状态为关闭的配置项勾选和不勾选，实际配置效果均为关闭。

### 4.确认提交 [#4确认提交]

确认无误，点击**确认**即可，否则点击**取消**返回上一步。

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/5-dcdn-domain-bulk-copy/FkZUbP_Gs4-NuSQxL_1tAjrb3BcB-cd0ee027092d.webp)

### 5.创建完成 [#5创建完成]

![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/configuration/5-dcdn-domain-bulk-copy/FmK3IxVdgBr8DMK_yBC9j3SNfZ5G-c71a54b8f034.webp)
注意：
a. 域名的状态若为“创建完成”，仅表示创建域名的任务提交成功，不表示域名配置下发完成；
b. 域名的状态若为“域名所有权待验证”，需要点击**操作**项下的**所有权验证**逐个域名进行所有权验证，否则无法成功添加域名。


# 用量统计 (/products/dcdn/dcdn-statistical-analysis/0-dcdn-usage-statistics)



最近更新时间: 2026-04-30 15:50:07

用量统计提供了流量、带宽、请求次数的用量情况，您可以登录**七牛开发者平台**，进入[DCDN-统计分析-用量统计](https://portal.qiniu.com/dcdn/statistics/usage/flow "DCDN-统计分析-用量统计")模块进行查询。

# 1. 流量统计 [#1-流量统计]

## 查询条件 [#查询条件]

* 域名：默认为域名全选状态，支持自定义指定域名查询，当域名超过1000时可选择“全部域名”。
* 时间粒度：包含5分钟、1小时、1天三种方式，默认为1小时。
* 时间范围：默认为最近7天，最大时间范围为3个月。
* 计费区域：默认为全部地区，支持自定义指定计费区域查询。

## 查询结果 [#查询结果]

* 访问总流量：时间范围内的总流量。
* 日均流量：：时间范围内的日平均流量，不满一天按一天计算。
* 闲时总流量：每日 0:00 - 9:00 时段的总流量。
* 日间总流量：每日 9:00 - 18:00 时段的总流量。
* 可分别查看静态加速和动态加速的流量明细。
  ![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/dcdn-statistical-analysis/0-dcdn-usage-statistics/Ft8IJ9tPd0wvLFvZ1sI-mduPwkb9-025d44fa0664.webp)

## 按域名或地区堆叠 [#按域名或地区堆叠]

图表支持按域名（不能超过15个）、计量区域堆叠展示；支持数据导出功能。
![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/dcdn-statistical-analysis/0-dcdn-usage-statistics/FnIENMPlgDc_Y7-fvlRotGigcGWm-caae6f0f0f63.webp)

# 2. 带宽统计 [#2-带宽统计]

## 查询条件 [#查询条件-1]

* 域名：默认为域名全选状态，支持自定义指定域名查询，当域名超过1000时可选择“全部域名”。
* 时间粒度：包含5分钟、1小时、1天三种方式，默认为1小时。
* 时间范围：默认为最近7天，最大时间范围为3个月。
* 计费区域：默认为全部地区，支持自定义指定计费区域查询。

## 查询结果 [#查询结果-1]

* 带宽峰值：选择时间区域内的最大带宽值。
* 可分别查看静态加速和动态加速的带宽统计明细。
  ![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/dcdn-statistical-analysis/0-dcdn-usage-statistics/FlSvSCBPl9vqhTRYF_uM4oYs1miL-786c73df3ffb.webp)

## 按域名或地区堆叠 [#按域名或地区堆叠-1]

图表支持按域名（不能超过15个）、计量区域堆叠展示；支持数据导出功能。

# 3. 请求次数统计 [#3-请求次数统计]

## 查询条件 [#查询条件-2]

* 域名：默认为域名全选状态，支持自定义指定域名查询。
* 时间粒度：包含5分钟、1小时、1天三种方式，默认为1小时。
* 时间范围：默认为最近7天，最大时间范围为3个月。

由于静态请求次数不收费、动态请求次数全球价格相同，所以请求次数的计量统计暂不提供分区域统计，若需参考用户请求次数的地区分布，可至[日志分析-地区运营商分布](https://portal.qiniu.com/dcdn/statistics/log/access)模块查询日志分析结果。

## 查询结果 [#查询结果-2]

* 动态访问次数：时间范围内动态请求的总次数。
* 访问总次数：时间范围内的总次数。
* 日均访问次数：：时间范围内的日平均次数，不满一天按一天计算。
* 闲时访问总次数：每日 0:00 - 9:00 时段的访问次数。
* 日间访问总次数：每日 9:00 - 18:00 时段的访问次数。
* 可分别查看静态加速和动态加速的访问次数明细。

![](/docs-assets/products/dcdn/%284-development-guidelines%29/dcdn-statistical-analysis/0-dcdn-usage-statistics/FtLuxicFli8aZPd1ixdISKtacPE1-cbbe66f7ff69.webp)

## 按域名堆叠 [#按域名堆叠]

图表支持按域名（不能超过15个）展示；支持数据导出功能。

# 4. 常见问题 [#4-常见问题]

<span id="all-selected">
  **在域名筛选的条件中，域名“全选”和“全部域名”的差异是什么**

  ？
</span>

域名“全选”和点击“全部域名”按钮在绝大多数场景完全的数据统计结果完全一致，但在以下场景下会产生计量结果差异:
（1）对于域名数量超过 1000 个的场景，“全选”域名的统计结果仅为当前选中的 1000 个域名，“全部域名”的统计结果则为当前账号下的所有域名产生的用量。
（2）点击“全量域名”的统计结果为当前账号下的所有DCDN域名产生的用量结果。
![image.png](/docs-assets/products/dcdn/%284-development-guidelines%29/dcdn-statistical-analysis/0-dcdn-usage-statistics/FkSozmnK1y3A6IL2ggZjt2yMhBbL-2e80d09d92b7.webp)

七牛账单上的计量数据以点击“全部域名”的结果为准，即账户下产生的所有使用量。
由于“请求次数”下的静态请求次数不收费，所以“请求次数”下目前暂无“全部域名”选项，若域名超过 1000 可以联系七牛技术售后拉取全部域名的动态请求次数的统计明细。


# 统计分析 (/products/dcdn/dcdn-statistical-analysis)



最近更新时间: 2026-08-28 16:39:26

CDN 统计分析模块提供[用量统计](https://portal.qiniu.com/cdn/statistics-v2/usage/flow)和[日志分析](https://portal.qiniu.com/cdn/statistics-v2/log/access)两大分析模块。

# 用量统计 [#用量统计]

用量统计基于服务端访问数据统计，提供流量、带宽、请求次数等产品用量相关的统计数据。

| 模块                                                                        | 说明                                    |
| ------------------------------------------------------------------------- | ------------------------------------- |
| [流量统计](/products/cdn/data-statistics-fusion/0-usage-statistics#traffic)   | 提供全量、日间、闲时的流量统计，主要给流量计费型（默认）客户提供用量参考。 |
| [带宽统计 ](/products/cdn/data-statistics-fusion/0-usage-statistics#width)    | 提供峰值带宽、95峰值带宽统计，主要给带宽计费型客户提供用量参考。     |
| [请求次数统计 ](/products/cdn/data-statistics-fusion/0-usage-statistics#querry) | 提供静态、动态请求次数统计，其中仅动态请求次数收费。            |

# 日志分析 [#日志分析]

日志分析功能基于用户访问数据统计，提供以下用户访问的统计分析数据，便于您进行业务洞察分析：

| 模块                                                                                                 | 说明                         |
| -------------------------------------------------------------------------------------------------- | -------------------------- |
| [地区运营商分布 ](/products/cdn/data-statistics-fusion/log-analysis/3-distribution-of-regional-operators) | 提供终端用户的地区分布和运营商分布的数据统计。    |
| [ 状态码](/products/cdn/data-statistics-fusion/log-analysis/0-status-code)                            | 提供用户访问的状态码的数据统计。           |
| [TOP URL/IP ](/products/cdn/data-statistics-fusion/log-analysis/4-top-url-ip)                      | 提供热点资源 URL 和用户 IP 的相关数据统计。 |
| [独立 IP ](/products/cdn/data-statistics-fusion/log-analysis/2-independent-ip)                       | 独立IP提供了域名的UV的统计数据分析。       |

由于日志分析数据采用客户端 ip 统计，相关数据仅用于业务分析，具体账单相关计量数据参考[用量统计](https://portal.qiniu.com/dcdn/statistics-v2/usage/traffic)模块。


# 按量计费 (/products/dora/billing-way1/0-volumetric-billing)



最近更新时间: 2024-08-28 14:25:31

智能多媒体服务是一款后付费产品，每月 3 ～ 5 日生成上个月的账单并进行结算。 音视频转码按分钟收费。部分图片处理按图片原文件的大小计算数据的处理量进行计量，按量付费，每月提供一定量免费处理量。 部分数据处理按调用次数收费。

关于价格详情，请参考[智能多媒体服务定价](https://www.qiniu.com/prices?source=dora)。

# **音视频处理** [#音视频处理]

**计费说明**：

* 部分服务按照不同帧率进行收费，普帧：\<= 30 帧/秒；高帧：30 帧/秒 \< r \<= 60 帧/秒

### **中国大陆用户** [#中国大陆用户]

| 类型                         | 输出规格                                 | 普通任务单价      | 闲时任务单价            | 单位   |
| -------------------------- | ------------------------------------ | ----------- | ----------------- | ---- |
| **音视频元信息**                 |                                      | 0.1         |                   | 元/千次 |
| **音频转码**                   |                                      | 0.0048      | 0.0014            | 元/分钟 |
| **音视频转封装**                 |                                      | 0.003       | 0.0009            | 元/分钟 |
| **视频加密**                   | 当VideoCodec和 AudioCodec 的值同时指定为copy  | 0.018       | 0.0054            | 元/分钟 |
|                            | 当VideoCodec和 AudioCodec 的值，都不为 copy时 | 0.018 +转码费用 | 0.0054 +转码费用\*0.3 | 元/分钟 |
| **视频截图**                   | 其中雪碧图以截取小图和拼接大图的总张数计量                | 0.1         | 0.03              | 元/千次 |
| **音视频拼接**                  | 使用 avconcat/1，按照转封装收费                | 0.003       | 0.0009            | 元/分钟 |
|                            | 使用 avconcat/2，按照普通转码收费               | 参考普通转码收费说明  | 参考普通转码收费说明        | 元/分钟 |
| **普通转码普帧（H.264）**          | 普通转码 SD240（ 320x240）                 | 0.0057      | 0.0017            | 元/分钟 |
|                            | 普通转码 SD480（640x480）                  | 0.0072      | 0.0022            | 元/分钟 |
|                            | 普通转码 SD（1080x720）                    | 0.0189      | 0.0057            | 元/分钟 |
|                            | 普通转码 HD（1920x1080）                   | 0.0324      | 0.0098            | 元/分钟 |
|                            | 普通转码 2K（2560x1440）                   | 0.06        | 0.018             | 元/分钟 |
|                            | 普通转码 4K（4096x2160）                   | 0.12        | 0.036             | 元/分钟 |
|                            | 普通转码 8K（8192x4320）                   | 0.58        | 0.174             | 元/分钟 |
| **普通转码高帧（H.264）**          | 普通转码 SD240（ 320x240）                 | 0.0114      | 0.0034            | 元/分钟 |
|                            | 普通转码 SD480（640x480）                  | 0.0144      | 0.0043            | 元/分钟 |
|                            | 普通转码 SD（1080x720）                    | 0.0378      | 0.0113            | 元/分钟 |
|                            | 普通转码 HD（1920x1080）                   | 0.0648      | 0.0194            | 元/分钟 |
|                            | 普通转码 2K（2560x1440）                   | 0.12        | 0.036             | 元/分钟 |
|                            | 普通转码 4K（4096x2160）                   | 0.24        | 0.072             | 元/分钟 |
|                            | 普通转码 8K（8192x4320）                   | 1.16        | 0.348             | 元/分钟 |
| **普通转码普帧（H.265）**          | 普通转码 SD240（ 320x240）                 | 0.0285      | 0.0085            | 元/分钟 |
|                            | 普通转码 SD480（640x480）                  | 0.036       | 0.0108            | 元/分钟 |
|                            | 普通转码 SD（1080x720）                    | 0.0945      | 0.0284            | 元/分钟 |
|                            | 普通转码 HD（1920x1080）                   | 0.162       | 0.0486            | 元/分钟 |
|                            | 普通转码 2K（2560x1440）                   | 0.3         | 0.09              | 元/分钟 |
|                            | 普通转码 4K（4096x2160）                   | 0.6         | 0.18              | 元/分钟 |
|                            | 普通转码 8K（8192x4320）                   | 2.4         | 0.72              | 元/分钟 |
| **普通转码高帧（H.265）**          | 普通转码 SD240（ 320x240）                 | 0.057       | 0.0171            | 元/分钟 |
|                            | 普通转码 SD480（640x480）                  | 0.072       | 0.0216            | 元/分钟 |
|                            | 普通转码 SD（1080x720）                    | 0.189       | 0.0567            | 元/分钟 |
|                            | 普通转码 HD（1920x1080）                   | 0.324       | 0.0972            | 元/分钟 |
|                            | 普通转码 2K（2560x1440）                   | 0.6         | 0.18              | 元/分钟 |
|                            | 普通转码 4K（4096x2160）                   | 1.2         | 0.36              | 元/分钟 |
|                            | 普通转码 8K（8192x4320）                   | 4.8         | 1.44              | 元/分钟 |
| **普通转码普帧（AV1）**            | 普通转码 SD240（ 320x240）                 | 0.057       | 0.0171            | 元/分钟 |
|                            | 普通转码 SD480（640x480）                  | 0.072       | 0.0216            | 元/分钟 |
|                            | 普通转码 SD（1280x720）                    | 0.189       | 0.0567            | 元/分钟 |
|                            | 普通转码 HD（1920x1080）                   | 0.324       | 0.0972            | 元/分钟 |
|                            | 普通转码 2K（2560x1440）                   | 0.6         | 0.18              | 元/分钟 |
|                            | 普通转码 4K（4096x2160）                   | 1.2         | 0.36              | 元/分钟 |
|                            | 普通转码 8K（8192x4320）                   | 4.8         | 1.44              | 元/分钟 |
| **普通转码高帧（AV1）**            | 普通转码 SD240（ 320x240）                 | 0.114       | 0.0342            | 元/分钟 |
|                            | 普通转码 SD480（640x480）                  | 0.144       | 0.0432            | 元/分钟 |
|                            | 普通转码 SD（1280x720）                    | 0.378       | 0.1134            | 元/分钟 |
|                            | 普通转码 HD（1920x1080）                   | 0.648       | 0.1944            | 元/分钟 |
|                            | 普通转码 2K（2560x1440）                   | 1.2         | 0.36              | 元/分钟 |
|                            | 普通转码 4K（4096x2160）                   | 2.4         | 0.72              | 元/分钟 |
|                            | 普通转码 8K（8192x4320）                   | 9.6         | 2.88              | 元/分钟 |
| **锐智转码（H.264）**            | 锐智转码 SD（1280x720）及以下                 | 0.08        | 0.024             | 元/分钟 |
|                            | 锐智转码 HD（1920x1080）                   | 0.16        | 0.048             | 元/分钟 |
|                            | 锐智转码 2K（2560x1440）                   | 0.32        | 0.096             | 元/分钟 |
|                            | 锐智转码 4K（4096x2160）                   | 0.64        | 0.192             | 元/分钟 |
|                            | 锐智转码 8K（8192x4320）                   | 3.24        | 0.972             | 元/分钟 |
| **锐智转码（H.265）**            | 锐智转码 SD（1280x720）及以下                 | 0.4         | 0.12              | 元/分钟 |
|                            | 锐智转码 HD（1920x1080）                   | 0.8         | 0.24              | 元/分钟 |
|                            | 锐智转码 2K（2560x1440）                   | 1.6         | 0.48              | 元/分钟 |
|                            | 锐智转码 4K（4096x2160）                   | 3.2         | 0.96              | 元/分钟 |
|                            | 锐智转码 8K（8192x4320）                   | 5.6         | 1.68              | 元/分钟 |
| **倍速转码普帧（H.264）**          | 倍速转码 SD240（320x240）                  | 0.0086      |                   | 元/分钟 |
|                            | 倍速转码 SD480（640x480）                  | 0.0108      |                   | 元/分钟 |
|                            | 倍速转码 SD（1080x720）                    | 0.0284      |                   | 元/分钟 |
|                            | 倍速转码 HD（1920x1080）                   | 0.0486      |                   | 元/分钟 |
|                            | 倍速转码 2K（2560x1440）                   | 0.09        |                   | 元/分钟 |
|                            | 倍速转码 4K（4096x2160）                   | 0.18        |                   | 元/分钟 |
|                            | 倍速转码 8K（8192x4320）                   | 0.87        |                   | 元/分钟 |
| **倍速转码高帧（H.264）**          | 倍速转码 SD240（320x240）                  | 0.0172      |                   | 元/分钟 |
|                            | 倍速转码 SD480（640x480）                  | 0.0216      |                   | 元/分钟 |
|                            | 倍速转码 SD（1080x720）                    | 0.057       |                   | 元/分钟 |
|                            | 倍速转码 HD（1920x1080）                   | 0.0972      |                   | 元/分钟 |
|                            | 倍速转码 2K（2560x1440）                   | 0.18        |                   | 元/分钟 |
|                            | 倍速转码 4K（4096x2160）                   | 0.36        |                   | 元/分钟 |
|                            | 倍速转码 8K（8192x4320）                   | 1.74        |                   | 元/分钟 |
| **倍速转码普帧（H.265）**          | 倍速转码 SD240（320x240）                  | 0.0428      |                   | 元/分钟 |
|                            | 倍速转码 SD480（640x480）                  | 0.054       |                   | 元/分钟 |
|                            | 倍速转码 SD（1080x720）                    | 0.1418      |                   | 元/分钟 |
|                            | 倍速转码 HD（1920x1080）                   | 0.243       |                   | 元/分钟 |
|                            | 倍速转码 2K（2560x1440）                   | 0.45        |                   | 元/分钟 |
|                            | 倍速转码 4K（4096x2160）                   | 0.9         |                   | 元/分钟 |
|                            | 倍速转码 8K（8192x4320）                   | 3.6         |                   | 元/分钟 |
| **倍速转码高帧（H.265）**          | 倍速转码 SD240（320x240）                  | 0.0856      |                   | 元/分钟 |
|                            | 倍速转码 SD480（640x480）                  | 0.108       |                   | 元/分钟 |
|                            | 倍速转码 SD（1080x720）                    | 0.2836      |                   | 元/分钟 |
|                            | 倍速转码 HD（1920x1080）                   | 0.486       |                   | 元/分钟 |
|                            | 倍速转码 2K（2560x1440）                   | 0.9         |                   | 元/分钟 |
|                            | 倍速转码 4K（4096x2160）                   | 1.8         |                   | 元/分钟 |
|                            | 倍速转码 8K（8192x4320）                   | 7.2         |                   | 元/分钟 |
| **倍速转码（H.264）/启用 avsmart** | 倍速转码 SD（1080x720）及以下                 | 0.12        |                   | 元/分钟 |
|                            | 倍速转码 HD（1920x1080）                   | 0.24        |                   | 元/分钟 |
|                            | 倍速转码 2K（2560x1440）                   | 0.48        |                   | 元/分钟 |
|                            | 倍速转码 4K（4096x2160）                   | 0.96        |                   | 元/分钟 |
|                            | 倍速转码 8K（8192x4320）                   | 4.86        |                   | 元/分钟 |
| **倍速转码（H.265）/启用avsmart**  | 倍速转码 SD（1080x720）及以下                 | 0.6         |                   | 元/分钟 |
|                            | 倍速转码 HD（1920x1080）                   | 1.2         |                   | 元/分钟 |
|                            | 倍速转码 2K（2560x1440）                   | 2.4         |                   | 元/分钟 |
|                            | 倍速转码 4K（4096x2160）                   | 4.8         |                   | 元/分钟 |
|                            | 倍速转码 8K（8192x4320）                   | 8.4         |                   | 元/分钟 |

### **海外用户** [#海外用户]

| 类型                         | 输出规格                                 | 普通任务单价      | 闲时任务单价           | 单位     |
| -------------------------- | ------------------------------------ | ----------- | ---------------- | ------ |
| **音视频元信息**                 |                                      | 0.0154      |                  | USD/千次 |
| **音频转码**                   |                                      | 0.0007      | 0.00021          | USD/分钟 |
| **音视频转封装**                 |                                      | 0.0005      | 0.00015          | USD/分钟 |
| **视频加密**                   | 当VideoCodec和 AudioCodec 的值同时指定为copy  | 0.0028      | 0.00084          | USD/分钟 |
|                            | 当VideoCodec和 AudioCodec 的值，都不为 copy时 | 0.0028+转码费用 | 0.0008+转码费用\*0.3 | USD/分钟 |
| **视频截图**                   | 其中雪碧图以截取小图和拼接大图的总张数计量                | 0.0154      | 0.00462          | USD/千次 |
| **音视频拼接**                  | 使用 avconcat/1，按照转封装收费                | 0.0005      | 0.00015          | USD/分钟 |
|                            | 使用 avconcat/2，按照普通转码收费               | 参考普通转码收费说明  | 参考普通转码收费说明       |        |
| **普通转码普帧（H.264）**          | 普通转码 SD240（ 320x240）                 | 0.0009      | 0.00027          | USD/分钟 |
|                            | 普通转码 SD480（640x480）                  | 0.0011      | 0.00033          | USD/分钟 |
|                            | 普通转码 SD（1080x720）                    | 0.0029      | 0.00087          | USD/分钟 |
|                            | 普通转码 HD（1920x1080）                   | 0.005       | 0.0015           | USD/分钟 |
|                            | 普通转码 2K（2560x1440）                   | 0.0092      | 0.00276          | USD/分钟 |
|                            | 普通转码 4K（4096x2160）                   | 0.0185      | 0.00555          | USD/分钟 |
|                            | 普通转码 8K（8192x4320）                   | 0.0916      | 0.02748          | USD/分钟 |
| **普通转码高帧（H.264）**          | 普通转码 SD240（ 320x240）                 | 0.0018      | 0.00054          | USD/分钟 |
|                            | 普通转码 SD480（640x480）                  | 0.0022      | 0.00066          | USD/分钟 |
|                            | 普通转码 SD（1080x720）                    | 0.0058      | 0.00174          | USD/分钟 |
|                            | 普通转码 HD（1920x1080）                   | 0.01        | 0.003            | USD/分钟 |
|                            | 普通转码 2K（2560x1440）                   | 0.0185      | 0.00555          | USD/分钟 |
|                            | 普通转码 4K（4096x2160）                   | 0.0369      | 0.01107          | USD/分钟 |
|                            | 普通转码 8K（8192x4320）                   | 0.1832      | 0.05496          | USD/分钟 |
| **普通转码普帧（H.265）**          | 普通转码 SD240（ 320x240）                 | 0.0044      | 0.00132          | USD/分钟 |
|                            | 普通转码 SD480（640x480）                  | 0.0055      | 0.00165          | USD/分钟 |
|                            | 普通转码 SD（1080x720）                    | 0.0145      | 0.00435          | USD/分钟 |
|                            | 普通转码 HD（1920x1080）                   | 0.0249      | 0.00747          | USD/分钟 |
|                            | 普通转码 2K（2560x1440）                   | 0.0462      | 0.01386          | USD/分钟 |
|                            | 普通转码 4K（4096x2160）                   | 0.0923      | 0.02769          | USD/分钟 |
|                            | 普通转码 8K（8192x4320）                   | 0.3789      | 0.11367          | USD/分钟 |
| **普通转码高帧（H.265）**          | 普通转码 SD240（ 320x240）                 | 0.0088      | 0.00264          | USD/分钟 |
|                            | 普通转码 SD480（640x480）                  | 0.0111      | 0.00333          | USD/分钟 |
|                            | 普通转码 SD（1080x720）                    | 0.0291      | 0.00873          | USD/分钟 |
|                            | 普通转码 HD（1920x1080）                   | 0.0498      | 0.01494          | USD/分钟 |
|                            | 普通转码 2K（2560x1440）                   | 0.0923      | 0.02769          | USD/分钟 |
|                            | 普通转码 4K（4096x2160）                   | 0.1846      | 0.05538          | USD/分钟 |
|                            | 普通转码 8K（8192x4320）                   | 0.7579      | 0.22737          | USD/分钟 |
| **普通转码普帧（AV1）**            | 普通转码 SD240（ 320x240）                 | 0.0088      | 0.00264          | USD/分钟 |
|                            | 普通转码 SD480（640x480）                  | 0.0111      | 0.00333          | USD/分钟 |
|                            | 普通转码 SD（1280x720）                    | 0.0291      | 0.00873          | USD/分钟 |
|                            | 普通转码 HD（1920x1080）                   | 0.0499      | 0.01497          | USD/分钟 |
|                            | 普通转码 2K（2560x1440）                   | 0.0924      | 0.02772          | USD/分钟 |
|                            | 普通转码 4K（4096x2160）                   | 0.1848      | 0.05544          | USD/分钟 |
|                            | 普通转码 8K（8192x4320）                   | 0.7392      | 0.22176          | USD/分钟 |
| **普通转码高帧（AV1）**            | 普通转码 SD240（ 320x240）                 | 0.0176      | 0.00528          | USD/分钟 |
|                            | 普通转码 SD480（640x480）                  | 0.0222      | 0.00666          | USD/分钟 |
|                            | 普通转码 SD（1280x720）                    | 0.0582      | 0.01746          | USD/分钟 |
|                            | 普通转码 HD（1920x1080）                   | 0.0998      | 0.02994          | USD/分钟 |
|                            | 普通转码 2K（2560x1440）                   | 0.1848      | 0.05544          | USD/分钟 |
|                            | 普通转码 4K（4096x2160）                   | 0.3696      | 0.11088          | USD/分钟 |
|                            | 普通转码 8K（8192x4320）                   | 1.4784      | 0.44352          | USD/分钟 |
| **锐智转码（H.264）**            | 锐智转码 SD（1280x720）及以下                 | 0.0123      | 0.00369          | USD/分钟 |
|                            | 锐智转码 HD（1920x1080）                   | 0.0246      | 0.00738          | USD/分钟 |
|                            | 锐智转码 2K（2560x1440）                   | 0.0492      | 0.01476          | USD/分钟 |
|                            | 锐智转码 4K（4096x2160）                   | 0.0985      | 0.02955          | USD/分钟 |
|                            | 锐智转码 8K（8192x4320）                   | 0.5116      | 0.15348          | USD/分钟 |
| **锐智转码（H.265）**            | 锐智转码 SD（1280x720）及以下                 | 0.0615      | 0.01845          | USD/分钟 |
|                            | 锐智转码 HD（1920x1080）                   | 0.1231      | 0.03693          | USD/分钟 |
|                            | 锐智转码 2K（2560x1440）                   | 0.2462      | 0.07386          | USD/分钟 |
|                            | 锐智转码 4K（4096x2160）                   | 0.4923      | 0.14769          | USD/分钟 |
|                            | 锐智转码 8K（8192x4320）                   | 0.8842      | 0.26526          | USD/分钟 |
| **倍速转码普帧（H.264）**          | 倍速转码 SD240（320x240）                  | 0.0013      |                  | USD/分钟 |
|                            | 倍速转码 SD480（640x480）                  | 0.0017      |                  | USD/分钟 |
|                            | 倍速转码 SD（1080x720）                    | 0.0044      |                  | USD/分钟 |
|                            | 倍速转码 HD（1920x1080）                   | 0.0075      |                  | USD/分钟 |
|                            | 倍速转码 2K（2560x1440）                   | 0.0138      |                  | USD/分钟 |
|                            | 倍速转码 4K（4096x2160）                   | 0.0277      |                  | USD/分钟 |
|                            | 倍速转码 8K（8192x4320）                   | 0.1314      |                  | USD/分钟 |
| **倍速转码高帧（H.264）**          | 倍速转码 SD240（320x240）                  | 0.0026      |                  | USD/分钟 |
|                            | 倍速转码 SD480（640x480）                  | 0.0033      |                  | USD/分钟 |
|                            | 倍速转码 SD（1080x720）                    | 0.0088      |                  | USD/分钟 |
|                            | 倍速转码 HD（1920x1080）                   | 0.015       |                  | USD/分钟 |
|                            | 倍速转码 2K（2560x1440）                   | 0.0277      |                  | USD/分钟 |
|                            | 倍速转码 4K（4096x2160）                   | 0.0554      |                  | USD/分钟 |
|                            | 倍速转码 8K（8192x4320）                   | 0.2683      |                  | USD/分钟 |
| **倍速转码普帧（H.265）**          | 倍速转码 SD240（320x240）                  | 0.0066      |                  | USD/分钟 |
|                            | 倍速转码 SD480（640x480）                  | 0.0083      |                  | USD/分钟 |
|                            | 倍速转码 SD（1080x720）                    | 0.0218      |                  | USD/分钟 |
|                            | 倍速转码 HD（1920x1080）                   | 0.0374      |                  | USD/分钟 |
|                            | 倍速转码 2K（2560x1440）                   | 0.0693      |                  | USD/分钟 |
|                            | 倍速转码 4K（4096x2160）                   | 0.1386      |                  | USD/分钟 |
|                            | 倍速转码 8K（8192x4320）                   | 0.5544      |                  | USD/分钟 |
| **倍速转码高帧（H.265）**          | 倍速转码 SD240（320x240）                  | 0.0132      |                  | USD/分钟 |
|                            | 倍速转码 SD480（640x480）                  | 0.0166      |                  | USD/分钟 |
|                            | 倍速转码 SD（1080x720）                    | 0.0436      |                  | USD/分钟 |
|                            | 倍速转码 HD（1920x1080）                   | 0.0748      |                  | USD/分钟 |
|                            | 倍速转码 2K（2560x1440）                   | 0.1385      |                  | USD/分钟 |
|                            | 倍速转码 4K（4096x2160）                   | 0.2769      |                  | USD/分钟 |
|                            | 倍速转码 8K（8192x4320）                   | 1.1368      |                  | USD/分钟 |
| **倍速转码（H.264）/启用 avsmart** | 倍速转码 SD（1080x720）及以下                 | 0.0189      |                  | USD/分钟 |
|                            | 倍速转码 HD（1920x1080）                   | 0.0379      |                  | USD/分钟 |
|                            | 倍速转码 2K（2560x1440）                   | 0.07579     |                  | USD/分钟 |
|                            | 倍速转码 4K（4096x2160）                   | 0.1516      |                  | USD/分钟 |
|                            | 倍速转码 8K（8192x4320）                   | 0.7367      |                  | USD/分钟 |
| **倍速转码（H.265）/启用avsmart**  | 倍速转码 SD（1080x720）及以下                 | 0.0909      |                  | USD/分钟 |
|                            | 倍速转码 HD（1920x1080）                   | 0.1819      |                  | USD/分钟 |
|                            | 倍速转码 2K（2560x1440）                   | 0.3638      |                  | USD/分钟 |
|                            | 倍速转码 4K（4096x2160）                   | 0.7276      |                  | USD/分钟 |
|                            | 倍速转码 8K（8192x4320）                   | 1.2733      |                  | USD/分钟 |

# **画质增强** [#画质增强]

**计费说明**：

* 部分服务按照不同帧率进行收费，普帧：\<= 30 帧/秒；高帧：30 帧/秒 \< r \<= 60 帧/秒

### **中国大陆用户** [#中国大陆用户-1]

**表1. 音视频画质增强**

| 类型                 | 输出规格          | 普通任务单价    | 闲时任务单价     |
| ------------------ | ------------- | --------- | ---------- |
| **SDR to HDR（普帧）** | 1080p 及以下     | 0.4 元/分钟  | 0.12 元/分钟  |
|                    | 2K（2560x1440） | 0.75 元/分钟 | 0.225 元/分钟 |
|                    | 4K（4096x2160） | 1.5元/分钟   | 0.45元/分钟   |
|                    | 8K（8192x4320） | 1.8元/分钟   | 0.54元/分钟   |
| **SDR to HDR（高帧）** | 1080p 及以下     | 0.8 元/分钟  | 0.24 元/分钟  |
|                    | 2K（2560x1440） | 1.5 元/分钟  | 0.45 元/分钟  |
|                    | 4K（4096x2160） | 3元/分钟     | 0.9元/分钟    |
|                    | 8K（8192x4320） | 3.6元/分钟   | 1.08元/分钟   |
| **视频超分-普通版（普帧）**   | 1080p 及以下     | 0.8 元/分钟  |            |
|                    | 2K（2560x1440） | 1.6 元/分钟  |            |
|                    | 4K（4096x2160） | 3.2元/分钟   |            |
|                    | 8K（8192x4320） | 4.8元/分钟   |            |
| **视频超分-普通版（高帧）**   | 1080p 及以下     | 1.6 元/分钟  |            |
|                    | 2K（2560x1440） | 3.2 元/分钟  |            |
|                    | 4K（4096x2160） | 6.4元/分钟   |            |
|                    | 8K（8192x4320） | 9.6元/分钟   |            |
| **视频超分-人脸增强版（普帧）** | 1080p 及以下     | 1.6 元/分钟  |            |
|                    | 2K（2560x1440） | 3.2 元/分钟  |            |
|                    | 4K（4096x2160） | 6.4元/分钟   |            |
|                    | 8K（8192x4320） | 9.6元/分钟   |            |
| **视频超分-人脸增强版（高帧）** | 1080p 及以下     | 3.2 元/分钟  |            |
|                    | 2K（2560x1440） | 6.4元/分钟   |            |
|                    | 4K（4096x2160） | 12.8元/分钟  |            |
|                    | 8K（8192x4320） | 19.2元/分钟  |            |
| **音频降噪**           |               | 0.1元/分钟   |            |

**表2. 图像画质增强**

\| 类型
\| 普通任务单价
|
\| --- | --- |
\| 图像超分（增强版） | 0.1 元/次 |
\| 图像超分（普通版） | 0.04 元/次 |

### **海外用户** [#海外用户-1]

**表1. 音视频画质增强**

| 类型                 | 输出规格          | 普通任务单价        | 闲时任务单价        |
| ------------------ | ------------- | ------------- | ------------- |
| **SDR to HDR（普帧）** | 1080p 及以下     | 0.0616 USD/分钟 | 0.0185 USD/分钟 |
|                    | 2K（2560x1440） | 0.1155 USD/分钟 | 0.0347 USD/分钟 |
|                    | 4K（4096x2160） | 0.231 USD/分钟  | 0.0693 USD/分钟 |
|                    | 8K（4096x2160） | 0.2772 USD/分钟 | 0.0832 USD/分钟 |
| **SDR to HDR（高帧）** | 1080p 及以下     | 0.1232 USD/分钟 | 0.037 USD/分钟  |
|                    | 2K（2560x1440） | 0.231 USD/分钟  | 0.0693 USD/分钟 |
|                    | 4K（4096x2160） | 0.462 USD/分钟  | 0.1386 USD/分钟 |
|                    | 8K（4096x2160） | 0.5544 USD/分钟 | 0.1663 USD/分钟 |
| **视频超分-普通版（普帧）**   | 1080p 及以下     | 0.1232 USD/分钟 |               |
|                    | 2K（2560x1440） | 0.2464 USD/分钟 |               |
|                    | 4K（4096x2160） | 0.4928 USD/分钟 |               |
|                    | 8K（8192x4320） | 0.7392 USD/分钟 |               |
| **视频超分-普通版（高帧）**   | 1080p 及以下     | 0.2464 USD/分钟 |               |
|                    | 2K（2560x1440） | 0.4928 USD/分钟 |               |
|                    | 4K（4096x2160） | 0.9856 USD/分钟 |               |
|                    | 8K（8192x4320） | 1.4784 USD/分钟 |               |
| **视频超分-人脸增强版（普帧）** | 1080p 及以下     | 0.2464 USD/分钟 |               |
|                    | 2K（2560x1440） | 0.4928 USD/分钟 |               |
|                    | 4K（4096x2160） | 0.9856 USD/分钟 |               |
|                    | 8K（8192x4320） | 1.4784 USD/分钟 |               |
| **视频超分-人脸增强版（高帧）** | 1080p 及以下     | 0.4928 USD/分钟 |               |
|                    | 2K（2560x1440） | 0.9856 USD/分钟 |               |
|                    | 4K（4096x2160） | 1.9712 USD/分钟 |               |
|                    | 8K（8192x4320） | 2.9568 USD/分钟 |               |
| **音频降噪**           |               | 0.0154 USD/分钟 |               |

**表2. 图像画质增强**

\| 类型
\| 普通任务单价
|
\| --- | --- |
\| 图像超分（增强版） | 0.0154 USD/次 |
\| 图像超分（普通版） | 0.0062 USD/次 |

# **图片处理** [#图片处理]

### **中国大陆用户** [#中国大陆用户-2]

| 类型                 | 单价                                       |
| ------------------ | ---------------------------------------- |
| imageslim（图片瘦身）    | 0.1 元/千次                                 |
| animate（动图合成）      | 0.2 元/千次                                 |
| imageAve（图片主色调）    | 0.1 元/千次                                 |
| 图片盲水印处理            | 添加：1 元/千次                                |
| 图片盲水印处理            | 提取：1 元/千次                                |
| imageView2（图片基本处理） | 每月 0 - 10 TB：免费<br />10 TB 以上：0.025 元/GB |
| imageMogr2（图片高级处理） | 每月 0 - 10 TB：免费<br />10 TB 以上：0.025 元/GB |
| imageInfo（图片基本信息）  | 每月 0 - 10 TB：免费<br />10 TB 以上：0.025 元/GB |
| exif（图片 EXIF 信息）   | 每月 0 - 10 TB：免费<br />10 TB 以上：0.025 元/GB |
| watermark（图片水印处理）  | 每月 0 - 10 TB：免费<br />10 TB 以上：0.025 元/GB |
| roundPic（图片圆角）     | 每月 0 - 10 TB：免费<br />10 TB 以上：0.025 元/GB |
| 图片高级压缩-HEIC        | 800 x 600 及以下：0.025 元/千次                 |
| 图片高级压缩-HEIC        | 1600 x 1200及以下：0.1 元/千次                  |
| 图片高级压缩-HEIC        | 3200 x 2400 以下：0.4 元/千次                  |
| 图片高级压缩-HEIC        | 6400 x 4800 以下：1.6 元/千次                  |
| 图片高级压缩-AVIF        | 800 x 600 及以下：0.075 元/千次                 |
| 图片高级压缩-AVIF        | 1600 x 1200及以下：0.3 元/千次                  |
| 图片高级压缩-AVIF        | 3200 x 2400 以下：1.6 元/千次                  |
| 图片高级压缩-AVIF        | 6400 x 4800 以下：5.4 元/千次                  |
| 全景拼接               | 800 x 600 及以下：0.28 元/百张                  |
| 全景拼接               | 1600 x 1200：0.46 元/百张                    |
| 全景拼接               | 3200 x 2400：1.48 元/百张                    |
| 异常图片检测             | 0.1 元/千次                                 |

### **海外用户** [#海外用户-2]

| 类型                 | 单价                                          |
| ------------------ | ------------------------------------------- |
| imageslim（图片瘦身）    | 0.0154 USD/千次                               |
| animate（动图合成）      | 0.0308 USD/千次                               |
| imageAve（图片主色调）    | 0.0154 USD/千次                               |
| 图片盲水印处理            | 添加：0.1538 USD/千次                            |
| 图片盲水印处理            | 提取：0.1538 USD/千次                            |
| imageView2（图片基本处理） | 每月 0 - 20 TB：免费<br />20 TB 以上：0.0038 USD/GB |
| imageMogr2（图片高级处理） | 每月 0 - 20 TB：免费<br />20 TB 以上：0.0038 USD/GB |
| imageInfo（图片基本信息）  | 每月 0 - 20 TB：免费<br />20 TB 以上：0.0038 USD/GB |
| exif（图片 EXIF 信息）   | 每月 0 - 20 TB：免费<br />20 TB 以上：0.0038 USD/GB |
| watermark（图片水印处理）  | 每月 0 - 20 TB：免费<br />20 TB 以上：0.0038 USD/GB |
| roundPic（图片圆角）     | 每月 0 - 20 TB：免费<br />20 TB 以上：0.0038 USD/GB |
|                    |                                             |
| 图片高级压缩-HEIC        | 800 x 600 及以下：0.0039 USD/千次                 |
| 图片高级压缩-HEIC        | 1600 x 1200及以下：0.0154 USD/千次                |
| 图片高级压缩-HEIC        | 3200 x 2400 以下：0.0619 USD/千次                |
| 图片高级压缩-HEIC        | 6400 x 4800 以下：0.2475 USD/千次                |
| 图片高级压缩-AVIF        | 800 x 600 及以下：0.0116 USD/千次                 |
| 图片高级压缩-AVIF        | 1600 x 1200及以下：0.0462 USD/千次                |
| 图片高级压缩-AVIF        | 3200 x 2400 以下：0.2475 USD/千次                |
| 图片高级压缩-AVIF        | 6400 x 4800 以下：0.8352 USD/千次                |
| 全景拼接               | 800 x 600 及以下：0.0431 USD/百张                 |
| 全景拼接               | 1600 x 1200：0.0708 USD/百张                   |
| 全景拼接               | 3200 x 2400：0.2277 USD/百张                   |
| 异常图片检测             | 0.0154 USD/千次                               |

# **文件处理** [#文件处理]

**计费说明**：

* 计费项：qhash、concat、mkzip 服务是按照输入源文件大小进行计费。

### **中国大陆用户** [#中国大陆用户-3]

\| 类型
\| 单价
|
\| --- | --- |
\| qhash（文件 HASH 值） | 0.05 元/GB |
\| concat（文本文件合并） | 0.05 元/GB |
\| mkzip（多文件压缩） | 0.05 元/GB |
\| md2html（MD 转 HTML） | 0.1 元/千次 |
\| qrcode（资源下载二维码） | 0.1 元/千次 |

### **海外用户** [#海外用户-3]

\| 类型
\| 单价
|
\| --- | --- |
\| qhash（文件 HASH 值） | 0.0077 USD/GB |
\| concat（文本文件合并） | 0.0077 USD/GB |
\| mkzip（多文件压缩） | 0.0077 USD/GB |
\| md2html（MD 转 HTML） | 0.0154 USD/千次 |
\| qrcode（资源下载二维码） | 0.0154 USD/千次 |


# 资源包 (/products/dora/billing-way1/1-resource-pack)



最近更新时间: 2024-06-28 17:45:40

智能媒体处理服务提供了丰富的资源包，本章节为您介绍资源包的定价和使用说明。

**注意事项**：

* 已购买但从未使用且包未过期的情况下可以工单联系进行退款，其他情况不能退款；

* 支持购买多个流量包叠加使用，时长不叠加，优先抵扣先过期的流量包；

* 按月结流量计费的抵扣，抵扣完毕后，超出部分按流量（公开价）后计费；

# **普通转码资源包** [#普通转码资源包]

<a href="https://qmall.qiniu.com/template/NjQ?ref=category&spec_combo=MjQwNw">
  视频转码和锐智转码包特惠选购 >>
</a>

| 类型          | 产品种类                 | 规格（分钟） | 预付费价格  | 单价（元/分钟） |
| ----------- | -------------------- | ------ | ------ | -------- |
| 视频转码（H.264） | H264视频转码<br />通用     | 5000   | 32.4   | 0.006    |
| 视频转码（H.264） | H264视频转码<br />通用     | 20000  | 115.2  | 0.006    |
| 视频转码（H.264） | H264视频转码<br />通用     | 100000 | 504    | 0.005    |
| 视频转码（H.264） | H264视频转码<br />通用     | 300000 | 1296   | 0.004    |
| 视频转码（H.264） | H264视频转码<br />SD480  | 5000   | 32.4   | 0.006    |
| 视频转码（H.264） | H264视频转码<br />SD480  | 20000  | 115.2  | 0.006    |
| 视频转码（H.264） | H264视频转码<br />SD480  | 100000 | 504    | 0.005    |
| 视频转码（H.264） | H264视频转码<br />SD480  | 300000 | 1296   | 0.004    |
| 视频转码（H.264） | H264视频转码<br />SD720  | 5000   | 85.08  | 0.017    |
| 视频转码（H.264） | H264视频转码<br />SD720  | 20000  | 302.4  | 0.015    |
| 视频转码（H.264） | H264视频转码<br />SD720  | 100000 | 1323   | 0.013    |
| 视频转码（H.264） | H264视频转码<br />SD720  | 300000 | 3402   | 0.011    |
| 视频转码（H.264） | H264视频转码<br />HD1080 | 5000   | 145.8  | 0.029    |
| 视频转码（H.264） | H264视频转码<br />HD1080 | 20000  | 518.4  | 0.026    |
| 视频转码（H.264） | H264视频转码<br />HD1080 | 100000 | 2268   | 0.023    |
| 视频转码（H.264） | H264视频转码<br />HD1080 | 300000 | 5832   | 0.019    |
| 视频转码（H.265） | H265视频转码<br />通用包    | 5000   | 162    | 0.032    |
| 视频转码（H.265） | H265视频转码<br />通用包    | 20000  | 576    | 0.029    |
| 视频转码（H.265） | H265视频转码<br />通用包    | 100000 | 2520   | 0.025    |
| 视频转码（H.265） | H265视频转码<br />通用包    | 300000 | 6480   | 0.022    |
| 视频转码（H.265） | H265视频转码<br />SD480  | 5000   | 162    | 0.032    |
| 视频转码（H.265） | H265视频转码<br />SD480  | 20000  | 576    | 0.029    |
| 视频转码（H.265） | H265视频转码<br />SD480  | 100000 | 2520   | 0.025    |
| 视频转码（H.265） | H265视频转码<br />SD480  | 300000 | 6480   | 0.022    |
| 视频转码（H.265） | H265视频转码<br />SD720  | 5000   | 425.28 | 0.085    |
| 视频转码（H.265） | H265视频转码<br />SD720  | 20000  | 1512   | 0.076    |
| 视频转码（H.265） | H265视频转码<br />SD720  | 100000 | 6615   | 0.066    |
| 视频转码（H.265） | H265视频转码<br />SD720  | 300000 | 17010  | 0.057    |
| 视频转码（H.265） | H265视频转码<br />HD1080 | 5000   | 729    | 0.146    |
| 视频转码（H.265） | H265视频转码<br />HD1080 | 20000  | 2592   | 0.130    |
| 视频转码（H.265） | H265视频转码<br />HD1080 | 100000 | 11340  | 0.113    |
| 视频转码（H.265） | H265视频转码<br />HD1080 | 300000 | 29160  | 0.097    |

# **锐智转码资源包** [#锐智转码资源包]

<a href="https://qmall.qiniu.com/template/NjQ?ref=category&spec_combo=MjQwNw">
  视频转码和锐智转码包特惠选购 >>
</a>

| 类型                | 产品种类       | 规格（分钟） | 预付费价格 | 单价（元/分钟） |
| ----------------- | ---------- | ------ | ----- | -------- |
| 锐智转码<br />(H.264) | 锐智转码H264通用 | 5000   | 360   | 0.072    |
| 锐智转码<br />(H.264) | 锐智转码H264通用 | 20000  | 1280  | 0.064    |
| 锐智转码<br />(H.264) | 锐智转码H264通用 | 100000 | 5600  | 0.056    |
| 锐智转码<br />(H.264) | 锐智转码H264通用 | 300000 | 14400 | 0.048    |
| 锐智转码<br />(H.265) | 锐智转码H265通用 | 5000   | 1800  | 0.360    |
| 锐智转码<br />(H.265) | 锐智转码H265通用 | 20000  | 6400  | 0.320    |
| 锐智转码<br />(H.265) | 锐智转码H265通用 | 100000 | 28000 | 0.280    |
| 锐智转码<br />(H.265) | 锐智转码H265通用 | 300000 | 72000 | 0.240    |


# 计费方式 (/products/dora/billing-way1)



最近更新时间: 2026-04-30 18:11:00

# 计费组成 [#计费组成]

智能多媒体服务费用的各项组成，包括：

1. 通过 **调用多媒体 api 接口**，产生的费用。

2. 在对象存储控制台，通过 **工作流** 发起的任务处理，产生的费用。

* 工作流可以编排多任务处理流程，会对处理成功的节点进行收费，对处理失败的节点不会进行收费。

* 由系统故障导致任务处理失败，都不进行收费。

  > 例如：一个任务有几个处理节点，其中2个节点处理成功，其他节点是系统故障导致的处理失败，则所有节点都不会进行收费。

# 计费模式 [#计费模式]

1. **按量付费**

   [按量计费](https://www.qiniu.com/prices/dora)，将按照各计费项的实际用量结算费用，属于先使用，后付费的结算方式。您可以通过  [财务中心](https://portal.qiniu.com/financial/estimated-consume) 查看实时消费明细。

2. **资源包计费**

   即预先购买指定资源包，之后使用资源时扣除相应的额度。目前提供转码时长包，详情请参见 [购买视频转码时长包。](https://qmall.qiniu.com/template/NjQ?spec_combo=MjQwNw)

# 免费额度 [#免费额度]

开通七牛云智能多媒体服务的标准用户，每月可享受一定量的免费额度。每月计费时，会先抵扣免费额度，超出部分按价格详情付费结算。

| 类别                | 额度    |
| ----------------- | ----- |
| 每月多媒体处理服务         | 20元   |
| 每月部分图片处理服务        | 10TB  |
| 每月 C1M1 自定义数据处理服务 | 750小时 |

# 定价详情 [#定价详情]

| 类别      | 价格说明                                                                       |
| ------- | -------------------------------------------------------------------------- |
| 智能多媒体服务 | 关于价格详情，请参考[智能多媒体服务定价](https://www.qiniu.com/prices?source=dora)。           |
| 资源包定价   | 关于价格详情，请参考[转码包定价](https://qmall.qiniu.com/template/NjQ?spec_combo=MjQwNw)。 |
| 第三方服务   | 关于价格详情，请参考 Open API 文档。                                                    |

# 计费示例 [#计费示例]

**示例1**

某公司2019年1月使用七牛转码服务，采用H.264编码方式，普通转码转出1080 x 720 分辨率视频时长100分钟。使用转封装1000分钟，则产生的费用如下：

```
转码费用=100（分钟）* 0.0189（元/分钟）=1.89（元）
装封装费用=1000（分钟）* 0.003（元/分钟）=3（元）
```

**示例2**

某公司2018年5月使用七牛图普图片鉴黄服务，共发起500万次鉴黄请求，其中结果确定的次数为480万次，结果不确定的次数为20万次，则当月使七牛鉴黄服务产生的费用为：

```
确定的结果费用：0.25(元/百次) * 300(万次) + 0.23(元/百次) * (480万次 - 300万次) = 11640(元)
不确定的结果费用：0.0625(元/百次) * 20(万次) = 125(元)
```


# 工作流使用 (/products/dora/section-cc46gx/0-tasks-and-workflows)



最近更新时间: 2026-08-18 12:00:15

本文将为您介绍 **V2/V3版本工作流** 的使用场景、设计、示例、使用方式。

> **V1版本工作流** 的使用，详情参见对象存储kodo推出的 [数据工作流](/products/kodo/development-guidelines/dev-the-data-processing/5-workflowtask)。

# **简介** [#简介]

工作流旨在将大部分多媒体处理功能流程化、实例化，用户可提前编排任务处理流程，对多媒体文件按照特定工作流进行处理，避免用户重复、繁琐的调用接口，提供一站式的多媒体处理服务。同时，工作流提供了条件判断机制，可自定义下一节点处理的触发条件，便于灵活组建场景化处理流程。

## 适用哪些场景？ [#适用哪些场景]

如果您有以下多媒体处理需求时，或者您期望实现一个 **弹性、易用、低成本、灵活支持处理逻辑** 的多媒体处理系统，那么工作流则是您期待的最佳解决方案。

* 您有大量并发处理需求，需要同时对一批多媒体文件做多种处理。
  > * 比如转码成不同规格的视频，适配不同终端设备播放。

* 提供丰富的计算处理原子服务，如转码、拼接、截图、水印，后期将接入内容审核、智能标签等AI能力。

* 支持串行化处理，上一步的输出作为下一步的输入，通过多个步骤的计算处理，从而将源文件转化成符合业务需求的输出。

  > * 比如先锐智转码、加水印，再对转码后的文件添加固定的片头/片尾。

* 您有更高级的自定义处理需求，条件判断机制的引入，可自定义下一节点处理的触发条件。

  > * 比如仅对>=1080p的视频做转码，需要通过执行条件来判断对哪些视频做处理，从而减少不必要的处理。
  > * 比如先对原视频进行内容审核，对审核结果正常的视频进行转码，对违规视频进行封禁，来规避风险和减少不必要的处理开销。

* 对上传到 kodo 空间的文件，自动触发工作流，发起任务处理请求。

* 工作流模板可固化工作流，减少重复工作，统一业务处理流程标准。

# **工作流示例** [#工作流示例]

**1. 创建多个并发处理的工作流**

![img](/docs-assets/products/dora/%283-development-guidelines%29/section-cc46gx/0-tasks-and-workflows/WX20201208-145138-d4a6b6a598a1.webp)

> * 示例：**普通转码 + 锐智转码 + 视频拼接 + 截图处理**
>   * 此流程表示：同时对源文件进行普通转码、锐智转码、视频拼接、截图处理。
> * 输入源说明：
>   * 所有节点的输入源： **源文件**

**2. 创建多个原子服务串联处理的工作流**

![img](/docs-assets/products/dora/%283-development-guidelines%29/section-cc46gx/0-tasks-and-workflows/WX20201222-102840-9bd91660eb4f.webp)

> * 示例：**锐智转码 -> 视频拼接 -> 输出**
>   * 此流程表示：先对源文件进行锐智转码处理，然后对锐智转码后的结果进行视频拼接处理。
> * 输入源说明：
>   * 锐智转码节点的输入源：源文件
>   * 视频拼接节点的输入源：锐智转码后的处理结果

**3. 创建有条件判断的工作流**

1）示例：**视频审核 -> 执行条件（结果违规） -> 封禁 、视频审核 -> 执行条件（结果正常）-> 普通转码 -> 输出**

![img](/docs-assets/products/dora/%283-development-guidelines%29/section-cc46gx/0-tasks-and-workflows/WX20210223-114858-2x-1d7338e97ffd.webp)

> * 此流程表示：先对源文件进行内容审核，根据执行条件对【违规视频】进行封禁，对【正常视频】进行普通转码处理。
> * 输入源说明：
>   * 视频审核节点的输入源是： 源文件
>   * 执行条件节点的输入源是 ： 视频审核后的处理结果
>   * 普通转码节点的输入源是 ：源文件

2）示例：**音视频元信息 -> 执行条件 -> 普通转码 -> 输出**

![img](/docs-assets/products/dora/%283-development-guidelines%29/section-cc46gx/0-tasks-and-workflows/WX20201222-100236-2717d041fb6a.webp)

> * 此流程表示：先对源文件获取音视频元信息，判断原视频分辨率范围，在范围内的视频，进行普通转码处理；不在范围内的视频，不再流转到下一步处理。
> * 输入源说明：
>   * 音视频元信息节点的输入源： 源文件
>   * 执行条件节点的输入源 ： 音视频元信息处理后的处理结果
>   * 普通转码节点的输入源 ：源文件

**4.串行工作流子节点输入源说明**

| 父节点类型 | 输入源                                                    | 下一节点可选处理类型                                                     |
| ----- | ------------------------------------------------------ | -------------------------------------------------------------- |
| 普通转码  | 默认处理结果，作为下一节点输入源<br />**注意**:当转码格式为 m3u8 时，不支持继续添加处理节点 | - 普通转码<br />- 锐智转码<br />- 截图<br />- 视频拼接<br />                 |
| 锐智转码  | 默认处理结果，作为下一节点输入源<br />**注意**:当转码格式为 m3u8 时，不支持继续添加处理节点 | - 普通转码<br />- 锐智转码<br />- 截图视频<br />- 视频拼接<br />- 截图           |
| 视频拼接  | 默认处理结果，作为下一节点输入源                                       | - 普通转码<br />- 锐智转码<br />- 截图视频<br />- 视频拼接<br />- 截图           |
| 音视频信息 | 默认处理结果，作为下一节点输入源                                       | - 条件判断<br />- 输出                                               |
| 视频审核  | 默认处理结果，作为下一节点输入源                                       | - 条件判断<br />- 输出<br />- 封禁                                     |
| 执行条件  | 作为下一节点处理的前置判断条件，当前支持的有：<br />1、音视频元信息<br />2、视频审核      | - 普通转码<br />- 锐智转码<br />- 截图视频<br />- 视频拼接<br />- 截图<br />- 输出 |
| 截图    | 当前版本，处理结果不支持作为下一节点的输入源                                 | - 输出                                                           |
| 封禁    |                                                        | 当前只适用于视频审核场景，为结束节点                                             |
| 输出    |                                                        | 为结束节点                                                          |

父节点为【音视频元信息】，执行条件介绍如下：

| 条件  | 条件描述                     |
| --- | ------------------------ |
| 分辨率 | 判断视频分辨率范围，对范围内的视频做下一步处理。 |

父节点为【视频审核】，执行条件介绍如下：

| 执行条件         | 条件描述                       |
| ------------ | -------------------------- |
| 视频审核结果为【正常】  | 父节点审核结果为正常时，执行下一节点处理       |
| 视频审核结果为【违规】  | 父节点审核结果为违规时，执行下一节点处理       |
| 视频审核结果为【疑似】  | 父节点审核结果为疑似时，执行下一节点处理       |
| 视频审核结果不是【正常】 | 父节点审核结果为【违规】或【疑似】，执行下一节点处理 |
| 视频审核结果不是【违规】 | 父节点审核结果为【正常】或【疑似】，执行下一节点处理 |

# **任务创建** [#任务创建]

您可以通过以下几种方式来创建任务：

### **方式一：登录 [智能多媒体服务控制台](https://portal.qiniu.com/dora/media-gate/overview)，使用任务触发器** [#方式一登录-智能多媒体服务控制台使用任务触发器]

* `对符合规则策略的上传文件自动触发`：从导航栏进入**任务触发器**页面，点击新建 任务触发器；创建完成后，需要将状态设置为**已启用**，然后通过对象存储kodo控制台或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

  ![img](/docs-assets/products/dora/%283-development-guidelines%29/section-cc46gx/0-tasks-and-workflows/20241212-140902-4fd4d87d269c.webp)

### **方式二：登录 [智能多媒体服务控制台](https://portal.qiniu.com/kodo/bucket)**，指定文件手动触发 [#方式二登录-智能多媒体服务控制台指定文件手动触发]

* `指定文件手动触发`：指定单个文件创建任务，从导航栏进入**任务**页面，点击【新建任务】。

  ![img](/docs-assets/products/dora/%283-development-guidelines%29/section-cc46gx/0-tasks-and-workflows/20241212-140932-95b782b11bb9.webp)

# **任务查询** [#任务查询]

使用【智能多媒体服务控制台->工作流模板】创建的任务，您可以使用以下2种方式进行查询：

1、通过 **状态查询接口** 发起查询请求，目前仅支持查询10天内创建的任务记录。

* 任务版本为 `V1/V2`，请参考 [状态查询API](/products/dora/processing-mechanism/persist/1-persistent-processing-status-query-prefop)，发起查询请求
* 任务版本为 `V3`，请使用 V3状态查询API，发起查询请求

2、登录 [智能多媒体控制台](https://portal.qiniu.com/dora/media-gate/overview) ，进入【导航栏->任务】页面，在任务列表中进行查询。

![img](/docs-assets/products/dora/%283-development-guidelines%29/section-cc46gx/0-tasks-and-workflows/20241212-115144-d57faeedbc60.webp)

# **任务通知** [#任务通知]

在创建工作流模板时，支持设置回调地址URL，支持对任务处理后的结果，及时进行消息通知。任务通知是异步进行的，不影响正常的操作。

下面介绍的是使用 `工作流模板（V3版本） ` 产生任务的回调内容，包括字段名称、类型、描述。

> **注意**：使用V2和V3工作流模板创建的任务，任务内容是不同的，如何升级回调版本，详情查看 [回调升级](/products/dora/section-cc46gx/1-the-callback-to-upgrade) 。

* **基本属性**

  是一个JSON对象。定义：\{`当前任务的基本属性`}，字段如下。

  | 字段名称        | 说明                          |
  | ----------- | --------------------------- |
  | version     | 版本号，新版本统一都为“v3”             |
  | id          | 任务ID                        |
  | reqid       | 云处理请求的请求id，主要用于七牛技术人员的问题排查。 |
  | pipeline    | 默认使用队列为：default.sys         |
  | created\_at | 任务创建的时间戳，单位为毫秒              |

* **任务处理对象**

  是一个JSON对象。定义：\{`input`}，字段如下。

  | 字段名称   | 说明                           |
  | ------ | ---------------------------- |
  | bucket | 输入文件，当前仅支持kodo文件，待处理文件所在存储空间 |
  | key    | 待处理文件名                       |
  | hash   | 云处理结果保存在服务端的唯一`hash`标识       |

* **任务结果**

  是一个JSON对象。定义：\{`任务处理结果`}，字段如下。

  | 字段名称 | 说明                                                   |
  | ---- | ---------------------------------------------------- |
  | code | 返回码， 0成功、1等待处理、2处理中、3失败、5已取消(删除pipeline时，并且有任务还在等待中) |
  | desc | 返回信息描述，例如： success                                   |

* **工作流节点处理详情**。

  是一个JSON对象组，所有工作流节点处理的详情。定义：\{`ops`}，字段如下。

```
  "ops": [
        {
            "id": "<opid>", // 具体执行的操作，fop与cond只会有一个非空，fop为计算节点、cond为条件判断节点
            "fop": {                    // 表示具体的音视频计算节点信息
                "cmd": "xxx",           // 计算的命令
                "input_from": "<opid>", // 计算的输入文件，"__origin__"表示来源于触发的主输入文件，其它表示来源于某个节点的处理结果
                "result": {             // 处理结果
                    "code": 0,          // 0成功、3处理失败、6跳过、7无效
                    "desc": "...",      // 处理结果描述
                    "has_output": true, // 表示是否存在输出文件，如果是中间临时节点为false
                    "kodo_file": {      // 具体输出文件信息
                        "bucket": "aaa",
                        "key": "abc.mp4",
                        "hash": "..."
                    }
                }
            },
            "depends": ["<opid>",...] // 依赖的前置处理节点
        },
        {
            "id": "<opid>",
            "cond": {                              // 条件节点信息
                "expression": "xxx",               // 条件表达式，当前为“go template expression”
                "result": {                        // 条件表达式的执行结果
                    "code": 0,                     // 0成功、1等待处理、2处理中、3处理失败、5任务被取消、6跳过、7无效
                    "desc": "...",                 // 处理结果描述
                    "output": "<opid>,<opid>,..."  // 输出信息，为允许执行的后置节点名称列表
                }
            },
            "depends": ["<opid>",...] // 依赖的前置处理节点
        },
        ...
    ],
}
```

### **示例** [#示例]

如果请求成功，返回包含如下内容的JSON字符串（已格式化，便于阅读）：

```
{
    "version": "v3",
    "id": "z0.01z001c7n9d3q0nylt000001jm0001d4",
    "reqid": "zVcAAFE4Z742sE4W",
    "pipeline": "2002.default.sys",
    "input": {
        "kodo_file": {
            "bucket": "dora-async-test",
            "key": "upload.mp4"
        }
    },
    "code": 0,
    "desc": "successfully completed",
    "ops": [
        {
            "id": "A",
            "fop": {
                "cmd": "avinfo",
                "input_from": "__origin__",
                "result": {
                    "code": 0,
                    "desc": "successfully completed",
                    "has_output": false
                }
            }
        },
        {
            "id": "B",
            "cond": {
                "expression": "C",
                "result": {
                    "code": 0,
                    "desc": "successfully completed",
                    "output": "C"
                }
            },
            "depends": [
                "A"
            ]
        },
        {
            "id": "C",
            "fop": {
                "cmd": "avthumb/mp4",
                "input_from": "__origin__",
                "result": {
                    "code": 3,
                    "desc": "failed to parse result",
                    "has_output": false
                }
            },
            "depends": [
                "B"
            ]
        },
        {
            "id": "D",
            "fop": {
                "cmd": "saveas/ZG9yYS1hc3luYy10ZXN0OnVwbG9hZF9vdXRwdXQubXA0/jsonQuery/eyJidWNrZXQiOiJ7ey5idWNrZXR9fSIsImtleV90ZW1wbGF0ZSI6Int7LmZuYW1lfX1fb3V0cHV0e3suZXh0fX0ifQ==",
                "input_from": "C",
                "result": {
                    "code": 0,
                    "desc": "successfully completed",
                    "has_output": true,
                    "kodo_file": {
                        "bucket": "dora-async-test",
                        "key": "upload_output.mp4",
                        "hash": "FuBWVXNCdqNQxgrtSkERZqLDz5Yp"
                    }
                }
            },
            "depends": [
                "C"
            ]
        },
        {
            "id": "E",
            "fop": {
                "cmd": "avthumb/mp4",
                "input_from": "__origin__",
                "result": {
                    "code": 6,
                    "desc": "skipped",
                    "has_output": false
                }
            },
            "depends": [
                "B"
            ]
        },
        {
            "id": "F",
            "fop": {
                "cmd": "saveas/YWJjZDp1cGxvYWRfb3V0XzIubXA0/jsonQuery/eyJidWNrZXQiOiJhYmNkIiwia2V5X3RlbXBsYXRlIjoie3suZm5hbWV9fV9vdXRfMnt7LmV4dH19In0=",
                "input_from": "E",
                "result": {
                    "code": 6,
                    "desc": "skipped",
                    "has_output": false
                }
            },
            "depends": [
                "E"
            ]
        }
    ],
    "created_at": 1607415851017
}
```

### **常见问题** [#常见问题]

**Q1：回调超时，重试几次？重试间隔多久？**

A：重试次数：13；重试间隔依次为：1s 2s 4s 8s 16s 32s …. 最大不超过3600s；重试条件： 回调超时或者客户回调服务器返回 5xx。

**Q2：没有收到回调该如何排查？**

A：首先需要在 【控制台 -> 工作流】，进入工作流详情页面，查看是否填写了回调地址。

如果填写了回调地址，还是没有收到回调，则排查回调地址接收服务是否有问题。或者 [提交工单](https://support.qiniu.com/tickets/category) 给我们。

# **计费说明** [#计费说明]

多媒体处理能力由智能多媒体服务进行计费，费用详情请参见 [计费项](https://www.qiniu.com/prices/dora)。


# 回调升级 (/products/dora/section-cc46gx/1-the-callback-to-upgrade)



最近更新时间: 2024-12-12 14:51:56

V3版本的工作流模板健壮了任务处理的计算编排能力，回调同样做了升级，您的业务系统可能需要适配最新的回调格式。

* 查看新版V3回调内容
* 查看老版V2回调内容

本文会告知如何升级回调，以及V2和V3工作流模板的差异。阅读本文前，请登录 &#x2A;*[智能多媒体服务控制台](https://portal.qiniu.com/dora/media-gate/overview)**，切换到**工作流** 页面，在该页面进行确认：
![img](/docs-assets/products/dora/%283-development-guidelines%29/section-cc46gx/1-the-callback-to-upgrade/20241212-141739-9023984d5605.webp)

* 如果仅可见工作流版本为`V3`，说明您的回调默认已是V3回调，无需阅读本文。
* 如果同时可见`V2`和`V3 ` 工作流版本，说明您正在使用V2回调，**请继续阅读下面的内容**。

> **注意：**
>
> * 如果您仍在使用V2版本的回调，建议您将使用的回调逐步迁移到V3，以便您可以使用升级后的工作流去创建任务处理流程。
> * 因为 V2 版本的回调格式受限于既有的数据格式，表达能力及扩展性，无法表达**升级后的工作流**产生的任务结果。

升级回调后，您的[工作流](/products/dora/section-cc46gx/0-tasks-and-workflows)可以满足：

> * 支持更多处理的计算能力；
> * 支持串联/并行的组合方式；
> * 支持部分节点的条件处理逻辑，可自定义下一节点处理的触发条件，举例：avinfo, 对>=720p的视频文件做某种处理；
> * 不仅可以针对原片进行处理，还可对中间处理结果进行处理。

# **如何升级回调** [#如何升级回调]

如果您的工作流不是最新的回调版本，可通过以下2种方式去升级。

1. **直接点击回调升级**

* 登录 &#x2A;*[智能多媒体服务控制台](https://portal.qiniu.com/dora/media-gate/overview)**，点击左侧【导航栏->工作流】，进入工作流列表页，选择需要升级的V2版本工作流，点击 **编辑** ，进入工作流编辑页面。

* 开启 【回调升级】开关键，会提示您升级回调，点击 **确认** 按钮，即可升级成功，升级后不能恢复。

  ![img](/docs-assets/products/dora/%283-development-guidelines%29/section-cc46gx/1-the-callback-to-upgrade/20241212-141232-9e6bdab4a795.webp)

2. **编辑工作流节点**

* 当您需要对【工作流->增加处理节点】时，会提示您升级回调，点击 **确认** 按钮，即可升级成功，升级后不能恢复。如果不升级将无法增加处理节点。

  ![img](/docs-assets/products/dora/%283-development-guidelines%29/section-cc46gx/1-the-callback-to-upgrade/WX20201210-112551-f2b98dfbd9c3.webp)


# 资源用量 (/products/dora/console-guide/0-resource-usage)



最近更新时间: 2024-04-29 10:48:57

为了您能够更好更透明地了解自己的业务使用情况，支持查看基础音视频处理、基础图片处理、画质增强等统计数据，通常用于核对计量计费信息。

# **查询条件** [#查询条件]

支持切换不同的任务类型：普通任务、闲时任务。当前只有部分多媒体处理支持闲时任务的使用量查询：

![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/0-resource-usage/%E9%97%B2%E6%97%B6%E7%94%A8%E9%87%8F%E7%BB%9F%E8%AE%A1-a84dda5329ed.webp)

# **操作步骤** [#操作步骤]

1. 您可以登录 &#x2A;*[智能多媒体服务 -> 概览](https://portal.qiniu.com/dora/media-gate/overview?activeTab=%E5%9F%BA%E7%A1%80%E9%9F%B3%E8%A7%86%E9%A2%91%E5%A4%84%E7%90%86\&subActiveTab=0\&thirdActiveTab=0)**。

   ![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/0-resource-usage/%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A120240424-104253-ad8464ce4e22.webp)

2. 选择不同服务类型标签，查看对应的统计数据，如下所示：

   * **基础音视频处理**

     | 服务项     | 说明                       |
     | ------- | ------------------------ |
     | 普通音视频转码 | 查看不同转码格式、视频帧率下，不同分辨率的使用量 |
     | 音频转码    | 查看使用量                    |
     | 音视频装封装  | 查看使用量                    |
     | 视频截图    | 查看使用量                    |
     | 音视频元信息  | 查看使用量                    |
     | 锐智视频转码  | 查看不同分辨率的使用量              |

   * **基础图片处理**

     | 服务项      | 说明                     |
     | -------- | ---------------------- |
     | 图片瘦身     | 查看图片瘦身主动调用、CDN自动调用的使用量 |
     | 图片平均色调   | 查看使用量                  |
     | 图片基本处理   | 查看处理文件大小               |
     | 图片高级处理   | 查看处理文件大小               |
     | 图片基本信息   | 查看处理文件大小               |
     | 图片EXIF信息 | 查看处理文件大小               |
     | 图片水印处理   | 查看处理文件大小               |
     | 图片圆角     | 查看处理文件大小               |
     | 盲水印处理    | 查看盲水印解码、编码的使用量         |
     | 异常图片检测   | 查看使用量                  |

   * **画质增强**

     | 服务项        | 说明                  |
     | ---------- | ------------------- |
     | SDR to HDR | 查看不同视频帧率下、不同分辨率的使用量 |
     | 视频超分       | 查看不同视频帧率下、不同分辨率的使用量 |
     | 图像超分       | 查看不同模型下的使用量         |

   * **智能内容审核**

   * **人脸识别**

   * **OCR身份证识别**

   * **文件处理**

   * **摄像头AI算法**


# 任务管理 (/products/dora/console-guide/1-task-01)



最近更新时间: 2026-04-30 18:35:29

在任务列表中，可以查看任务的处理结果及进度。

登录 &#x2A;*[对象存储](https://portal.qiniu.com/kodo/bucket)**，点击左侧【导航栏->任务管理】，进入任务列表页。

# 添加任务 [#添加任务]

1. 登录【对象存储控制台空间管理】，在左侧菜单栏点击 **任务管理** ，进入任务列表页。

![image.png](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/1-task-01/FsL2pFU2KasEOlW0CxhKvp-Q7cNN-1d82bd17966a.webp)

2. 点击左上角 **添加任务** 按钮，进入添加任务页面，您需要选择指定对象（对象文件）、配置工作流模版，来发起指定文件的任务处理请求。

![image.png](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/1-task-01/Foq0nd8-VKxILNnca6bqaNUK5U1q-bab2ff11f275.webp)

**1. 选择输入文件**，必填项，可以通过下拉选择待处理文件，或者前缀匹配查找待处理文件。
**2. 闲时任务*&#x2A;：可勾选闲时任务，详情参考：&#x2A;*[闲时任务](/products/dora/processing-mechanism/persist/2-idle-time-task-strategy)**
**3. 强制执行数据策略**：默认关闭，服务端会检查结果文件是否存在，如果已经存在会认为已经处理成功，不再执行数据处理；开启后，服务端不会检查，会强制执行数据处理，如果存在同名文件会覆盖
**4.队列**：默认为default.sys默认队列，如需使用私有队列可在[队列](https://portal.qiniu.com/dora/media-gate/pipeline)进行创建

**5.工作流模版** 选择 **工作流模板**：
选择工作流，下拉选择预先创建好的工作流模板。可以帮助您快速发起任务处理请求，减少重复工作，统一业务处理流程标准。或点击 创建工作流模版 ，可以自定义编排一个完整的处理流程。具体的操作步骤和说明，可参考 [工作流操作指南](/products/dora/console-guide/the-workflow-template) 。
![image.png](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/1-task-01/FnTEcnQoMpyG7-a8t1rNbOXy4aL-1d89968ce056.webp)
**6. 确认**：点击【确认】，任务创建成功后会自动返回到任务列表页，可在查看任务处理结果、进度、详情。

# 查看任务详情 [#查看任务详情]

1. 登录【对象存储】，进入【空间管理->任务管理】页面，点击【任务ID】。

2. 查看 **通过 protal 创建** 的任务详情，如下所示。

![image.png](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/1-task-01/Fp9xqGweHgBEMQmRyxasKk-RMqbd-bfa7503e5b3a.webp)

**i. 查看子节点详情**

* 点击【子节点】，可查看子节点详情。内容和示例如下。

  > 1、【子任务ID】：每个子节点会有单独任务id
  >
  > 2、【执行状态】：
  >
  > * **已提交**：提交到队列中，还未处理的任务
  >
  > * **处理中**：正在处理
  >
  > * **成功**：子节点任务处理成功
  >
  > * **失败**：子节点任务处理失败
  >
  > * **跳过**：执行条件处理后，不在条件范围里的，就会跳过不处理子节点
  >
  > * **无效**：父节点处理失败，不会流转处理下一节点，此时子节点无效
  >
  > 3、【配置详情】：每个子节点的参数详情，格式为 json
  >
  > 4、【特殊字段说明】：
  >
  > * 是否执行下一步：表示父节点处理结果满足了执行条件，可以处理下一节点（执行条件节点特有字段）
  > * 错误信息：当子节点处理失败，会返回报错内容

* 示例：执行条件

  ![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/1-task-01/WX20201208-171253-4c3053cd1e95.webp)

* 示例：普通转码

  ![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/1-task-01/WX20201209-093825-d8ccfa9347dc.webp)

* 示例：输出

  ![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/1-task-01/WX20201209-095926-39eb44beaea3.webp)

1. 查看 **通过 API 创建** 的任务详情，如下所示。

   ![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/1-task-01/WX20201208-160631-ad0ebaaf6617.webp)

**注意：**

> 新老版本的任务详情展示会有差异，之前版本的任务详情无法完全兼容最新的展示格式。

# **任务查询** [#任务查询]

登录【智能多媒体控制台】，进入【导航栏->任务】页面，进入任务列表页面。查询条件说明：

1. **切换区域**

   * 任务资源可切换的区域有：**华东-浙江、华东-浙江2、华北-河北、华南-广东、亚太-新加坡、北美-洛杉矶**

2. **按任务类型查询**

   * 默认全部任务类型

     > ![image.png](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/1-task-01/FiWbN_eCGWC4HPOP1JgPbq66eNn8-61c36044d6ce.webp)
     >
     > **查询条件说明：**
     >
     > * 按时间查询：当前支持查询 **近7天** 的任务

   * 切换到普通任务

     > ![image.png](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/1-task-01/FmBJxySnxATa4CuIFmh58Ap_BpSz-5b6d0492ff92.webp)
     >
     > **查询条件说明：**
     >
     > * 按时间查询：当前支持查询 **近7天** 的任务
     >
     > * 按队列查询：默认全部队列，可选择其他队列

   * 切换到闲时任务

     > ![image.png](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/1-task-01/FgU7Bl0D2m4oLfESexIb6UnrjXpe-a0992b3f4fb2.webp)
     >
     > **查询条件说明：**
     >
     > * 按时间查询：当前支持查询 **近7天** 的任务

3. **按任务ID查询**

   * 输入任务ID，进行精确匹配查询
   * 其他查询条件均置灰

![image.png](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/1-task-01/FjQjX4z4mOs4-kJqFxxZi8O6Ldwc-62e2c4d11394.webp)

4. **搜索结果展示**

对应查询条件以任务列表形式展示信息。

| 任务列表 | 说明                |
| ---- | ----------------- |
| 任务ID |                   |
| 资源名称 |                   |
| 任务类型 | 普通任务、闲时任务         |
| 状态   | 成功、失败、处理中、已提交、已取消 |
| 队列   |                   |


# 任务触发器 (/products/dora/console-guide/2-task-workflow)



最近更新时间: 2026-04-30 18:40:01

**任务触发器**，与输入 Bucket 路径绑定，当符合某种资源规则策略时（比如：前缀匹配空间下的资源），会被自动触发执行任务处理操作，并将处理结果上传至指定的 Bucket 。

# 新建任务触发器 [#新建任务触发器]

1. 登录 [对象存储控制台](https://portal.qiniu.com/kodo/bucket)，选择具体空间，左侧导航栏点击【任务与工作流 -> 任务触发器】，进入【任务触发器】页面。

   ![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/2-task-workflow/20241107-151152-96e0b5a999cc.webp)

2. 点击右上角的 **新建任务触发器** 按钮，进入新建任务触发器页面。

3. 详细的参数说明如下表所示。

   | 参数       | 说明                                                                                                                                             |
   | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
   | 名称       | 必填项，长度不能超过32个字符。                                                                                                                               |
   | 规则策略     | 必填项，可选择项：  <br />1. 默认，对整个Bucket生效：空间内所有资源 <br />2. 对前缀生效：前缀匹配空间下的资源 <br />3. 对后缀生效：后缀匹配空间下的资源                                                 |
   | 输入源过滤    | 选填项，默认关闭，启用后，会按照指定输入源类型进行任务处理；不启用，不会过滤输入源类型，可能会造成不必要的资源浪费。<br />可选择项：<br />1. 视频    2. 音频    3. 音/视频  4. 音/视频/动图（仅限gif和webp动图）  5. 图片          |
   | 工作流模板    | 必填项，选择工作流模板。如果没有工作流模板，需创建[工作流模板](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template)。 |
   | 闲时任务     | 选填项，默认关闭，开启后，利用非峰值时间段的机器资源来处理，不保证任务的实时性。                                                                                                       |
   | 强制执行数据处理 | 选填项，默认关闭，开启后，服务端不会检查，会强制执行数据处理，如果存在同名文件会覆盖。                                                                                                    |
   | 回调设置     | 默认使用工作流模板中的回调设置。<br />如果工作流模板设置了回调地址，创建任务触发器时，允许改写。                                                                                            |

# **查看任务** [#查看任务]

触发器产生的任务，可以在 **任务管理** 中查看，任务来源为【触发器创建】。

![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/2-task-workflow/20241107-151016-caabd6b50712.webp)

# **开启/关闭任务触发器** [#开启关闭任务触发器]

1. 选择左侧导航栏**任务触发器**，进入列表页面。
2. 将**上传触发开关** 按钮，从 **开启** 切换成**关闭**，关闭后的任务触发器，将不会对符合规则策略的上传文件进行自动触发处理。
3. 将**上传触发开关** 按钮，从 **关闭** 切换成**开启**，开启后的任务触发器，立即生效，将会对符合规则策略的上传文件，根据触发器的配置，自动触发多媒体任务处理。

![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/2-task-workflow/20240924-144942-f3c816d058f0.webp)

# **删除任务触发器** [#删除任务触发器]

1. 选择左侧导航栏**任务触发器**，进入列表页面。
2. **关闭**状态的任务触发器，才允许删除，开启状态的任务触发器不允许删除；
3. 单击**删除**按钮，弹窗提醒是否删除，单击**确定删除**按钮，删除成功。

![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/2-task-workflow/20240924-145036-f19c5680de90.webp)


# 队列 (/products/dora/console-guide/3-the-queue)



最近更新时间: 2026-04-30 19:05:20

您可以在管理队列列表和新建队列。

登录  **智能多媒体**，点击左侧【导航栏 -> 队列】，进入队列列表页面。

# **队列列表** [#队列列表]

![image.png](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/3-the-queue/FqcKN0cJjql1tpO9t-Yheo-sw6xH-94b0a50c1363.webp)

> **1、字段说明**
>
> * 队列名称
> * 等待处理任务数
> * 正在处理任务数
>
> **2、操作说明：**
>
> * 删除
>   * default.sys 为默认队列，默认队列不能删除
>   * 其他队列点击【删除】，若存在等待处理任务，删除后，会清空等待处理任务；若存在正在处理任务，删除后，会继续完成任务处理。

# **新建队列** [#新建队列]

1.登录【智能多媒体控制台】，进入【导航栏->队列】页面。

2.点击右上角的 **新建队列** 按钮，弹出创建队列弹窗，如下：

* **队列名称**：必填项，只能由 0-9、A-Z、a-z、-、\_ 组成，长度为5-20个字符以内，名称不可重复。输入队列名称，点击【保存】即可。

![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/3-the-queue/pipeline-02-75c21cd6f71a.webp)

* 每个账户下的队列最多可新建4个。


# 使用限制 (/products/dora/console-guide/4-use-the-information)



最近更新时间: 2021-07-22 16:49:02

### 任务触发器 [#任务触发器]

每个用户最多可创建50个任务触发器

### 工作流 [#工作流]

每个用户最多可创建50个工作流模板
每个工作流最多可添加50个处理节点

### 自定义预设 [#自定义预设]

每个用户最多可创建150个预设

### 队列 [#队列]

每个用户最多可创建4个队列

### 区域 [#区域]

页面标题栏提供区域进行切换，默认为华东。所有任务、任务触发器、工作流和自定义预设只能选择该区域内的空间和文件，并且在被创建后也属于该区域，只有选择相应区域才会被展示和获取。
![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/4-use-the-information/region-1-e65510479dbf.webp)


# 控制台介绍 (/products/dora/console-guide/5-an-overview-of-the)



最近更新时间: 2021-07-23 18:07:29

智能多媒体平台，是为了给您提供更好的多媒体处理服务体验，通过控制台几个简单步骤，将计算原子和逻辑条件进行灵活配置，精准打造云上自动生产线，有效提升视频处理效率。

开发指南为您介绍功能、使用说明等，以便您更好地理解和使用。

​

# 整体流程 [#整体流程]

使用智能多媒体服务的整体流程如下：![img](/docs-assets/products/dora/%283-development-guidelines%29/console-guide/5-an-overview-of-the/image01-af31699c37ce.webp)

1. **任务处理对象**

   > * 即 input，bucket + key ，有2种方式：
   > * 指定文件：选择文件，发起任务处理请求。
   > * 自动触发：创建任务触发器（如上传到指定Bucket 的文件） ，会自动触发工作流，并发起任务处理请求。

2. **配置工作流**

   > * 定义处理一个对象文件的所有计算能力（包含转码、视频拼接、条件判断、截图、内容审核等），支持串行、并行操作，用户可根据实际需求，来编排任务处理流程。
   >
   > * 不仅可以针对原片进行处理，还可对中间处理结果进行处理。
   >
   > * 工作流的配置操作，请参考 [工作流](/products/dora/console-guide/the-workflow-template)。

3. **任务结果**

   > * 即 output，处理成功，会将处理结果文件上传到您指定的 Bucket。
   > * 可登录控制台->任务，在任务列表中查询其进度和结果，[查看任务列表](https://portal.qiniu.com/dora/media-gate/task)。

4. **消息通知**

   > * 通过配置回调 url ，就能及时获得任务处理结果（成功或失败）。

​

# 功能使用 [#功能使用]

| 分类      | 描述                                                        | 参考文档                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 工作流原理   | 介绍工作流的核心能力                                                | [工作流原理](/products/dora/section-cc46gx/0-tasks-and-workflows)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 多媒体处理能力 | 提供音视频转码、视频截图、视频拼接、视频水印等基础多媒体处理能力，未来会继续提供内容审核、视频内容识别等强大功能。 | [普通转码](/products/dora/section-cc46gx/1-ordinary-transcoding01)<br />[锐智转码](/products/dora/section-cc46gx/2-perceptive-transcoding01)<br />[视频截图](/products/dora/section-cc46gx/3-video-capture01)<br />[视频拼接](/products/dora/section-cc46gx/4-video-stitching01)<br />[视频水印](/products/dora/section-cc46gx/5-video-watermarking01)<br />[音视频元信息](/products/dora/section-cc46gx/6-audio-and-video-metadata-information)<br />[视频审核](/products/dora/introduction-to-the-third-party-data-processing/1-the-video-review)<br />[系统预设配置](/products/dora/section-cc46gx/7513-the-default-configuration-system)<br /> |
| 任务通知    | 支持通过消息回调的方式获取任务结果通知。                                      | 任务通知                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 回调升级    | 关于回调版本和如何升级回调的说明                                          | [回调升级](/products/dora/section-cc46gx/1-the-callback-to-upgrade)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |


# 多码率自适应转码（adapt） (/products/dora/audio-and-video-processing-api/0-multiple-rate-adaptive-transcoding-adapt)



最近更新时间: 2026-06-10 15:21:22

# **简介** [#简介]

多码率自适应转码(adapt)用于对已经上传到七牛云的视频转码成包含多种码率的HLS视频流。以便能随着终端网络带宽的变化动态选择适应的码率播放。

<a id="adapt-specification" />

# **参数说明** [#参数说明]

```
adapt/<Format>
    /envBandWidth/<EnvBandWidth>
    /multiAb/<MultiAb>
    /multiVb/<MultiVb>
    /multiResolution/<MultiResolution>
    /multiPrefix/<MultiPrefix>
    /vb/<VideoBitrate>
    /ab/<AudioBitrate>
    /resolution/<Resolution>
    /multiPrefix/<MultiPrefix>
    /hlstime/<HlsTime>
    /wmImage/<Encodedkodocheme>
    /wmText/<EncodedText>
    /wmFont/<Font>
    /wmFontSize<FontSize>
    /wmFontColor/<FontColor>
    /wmBorderWidth/<BorderWidth>
    /wmBorderColor/<BorderColor>
    /wmGravity/<Gravity>
    /wmGravityText/<GravityText>
    /wmOffsetX/<offsetX>
    /wmOffsetY/<offsetY>
```

| 参数名称                                       | 类别 | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| :----------------------------------------- | :- | :- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `&lt;Format&gt;`                           | V  | 是  | 目前只支持 `m3u8`格式                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `/envBandWidth/&lt;EnvBandWidth&gt;`       | V  | 是  | 不同码流切换的带宽标准，采用符号`,`分隔多个网络带宽，个数范围\[2,5]，取值范围\[50000,30000000]，单位是b/s。注：个数与存在的multi参数值个数需要保持一致，建议与设置的码率值接近，带宽值采用升序方式。                                                                                                                                                                                                                                                                                                                      |
| `/multiAb/&lt;MultiAb&gt;`                 | V  | 否  | 与ab参数不共存，单位：比特每秒（bit/s），采用符号`,`分隔多个音频码率，个数范围\[2,5]，例如64k,128k,256k。注：码率个数与其他存在的multi参数值个数需要保持一致，魔法变量$(origin)表示原音频码率。                                                                                                                                                                                                                                                                                                                    |
| `/multiVb/&lt;MultiVb&gt;`                 | V  | 否  | 与vb参数不共存，单位：比特每秒（bit/s），采用符号`,`分隔多个视频码率，个数范围\[2,5]，例如128k,600k,1.25m。注：码率个数与其他存在的multi参数值个数需要保持一致，魔法变量$(origin)表示原视频码率。                                                                                                                                                                                                                                                                                                                  |
| `/multiResolution/&lt;MultiResolution&gt;` | V  | 否  | 与resolution参数不共存，分辨率格式为`w:h` ，vcodec 为libx265/libx264时，`w` 取值范围\[20,8192]，`h` 取值范围\[20,4320]。vcodec 取其他值时 `w` 取值范围\[20,3840]，`h `取值范围\[20,2160]，采用符号,分隔多个视频分辨率，个数范围\[2,5]，例如 320:240,640:480,1080:720。注：会改变DAR，分辨率个数与其他存在的 multi 参数值个数需要保持一致，魔法变量$(origin)表示原视频分辨率。                                                                                                                                                                      |
| `/vb/&lt;VideoBitRate&gt;`                 | V  | 否  | 视频码率，单位：比特每秒（bit/s），常用视频比特率：128k, 1.25m, 5m 等。<br />若未指定码率，转码结果的码率会小于等于原音视频码率，若指定码率大于原音视频码率，转码操作会使用原视频码率进行转码。                                                                                                                                                                                                                                                                                                                            |
| `/ab/&lt;AudioBitRate&gt;`                 | V  | 否  | 音频码率，单位：比特每秒（bit/s），常用码率：320k, 256k, 192k, 128k, 64k 等。                                                                                                                                                                                                                                                                                                                                                                                  |
| `/resolution/&lt;Resolution&gt;`           | V  | 否  | 指定视频分辨率，格式为 w:h 或者预定义值，w取值范围\[20,3840]，h取值范围\[20,2160]。                                                                                                                                                                                                                                                                                                                                                                                  |
| `/multiPrefix/&lt;MultiPrefix&gt; `        | V  | 否  | 设置文件内的m3u8名称，同时该名称作为子m3u8的所有ts文件名的前缀。如果输出多个m3u8文件，则采用字符 `,` 来分隔。<br />**示例**：`/multiPrefix/cWluaXUtYQ==,cWluaXUtYg==，其中cWluaXUtYQ==`是定义的第一个m3u8文件的前缀，是qiniu-a的URL安全的Base64编码，cWluaXUtYg==是定义的第二个m3u8文件的前缀，是qiniu-b的URL安全的Base64编码，每个子m3u8文件中的ts名称为`前缀名称-$(count).ts`，其中$(count)是六位占位符数字串，最后得到的结果中会有两个子m3u8，名称为qiniu-a.m3u8 (内部ts为qiniu-a\_000000.ts,qiniu-a\_000001.ts...)和 qiniu-b.m3u8(内部ts为qiniu-b\_000000.ts,qiniu-b\_000001.ts...)。 |
| `/hlstime/&lt;HlsTime&gt;`                 | V  | 否  | 用于 HLS 自定义每一小段音/视频流的播放时间长度，取值范围为: 2 - 60 （秒），默认值为 10（单位:秒）。                                                                                                                                                                                                                                                                                                                                                                              |

## **视频水印参数** [#视频水印参数]

| 分类       | 参数名称                                 | 类别 | 必填 | 说明                                                                                                                                                                       |
| :------- | :----------------------------------- | :- | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **图片水印** | `/wmImage/&lt;Encodedkodocheme&gt;`  | V  | N  | 1、图片水印的源路径，目前支持 kodo 资源。kodo 资源可由 `kodo://&lt;bucketname&gt;/&lt;key&gt;` 表示（此时 bucketname 需要与输入源在同一区域），均需要经过 `urlsafe_base64_encode`。<br /> 2、支持的格式有：图片、部分动图（GIF、APNG）。 |
| **文字水印** | `/wmText/&lt;EncodedText&gt;`        | V  | N  | 水印文本内容,需要经过`urlsafe_base64_encode`。                                                                                                                                      |
|          | `/wmFont/&lt;Font&gt;`               | V  | N  | 文本字体（详见支持[字体列表](/faq/dora/other-dora/1379-image-and-video-text-watermarking-support-font-list) ），需要经过`urlsafe_base64_encode`。存在`/wmText/`时生效。 注意：默认为方正黑体。                |
|          | `/wmFontSize&lt;FontSize&gt;`        | V  | N  | 水印文字大小，单位: px。存在`/wmText/`时生效，默认值为16px。                                                                                                                                  |
|          | `/wmFontColor/&lt;FontColor&gt;`     | V  | N  | 水印文字颜色，需要经过`urlsafe_base64_encode`，RGB格式，可以是颜色名称（例如red）或十六进制（例如#FF0000），参考[RGB颜色编码表](https://www.rapidtables.com/web/color/RGB_Color.html)。存在`/wmText/`时生效，默认为黑色。        |
|          | `/wmBorderWidth/&lt;BorderWidth&gt;` | V  | N  | 水印文字描边宽度，单位：像素，取值范围\[0,4096]。                                                                                                                                            |
|          | `/wmBorderColor/&lt;BorderColor&gt;` | V  | N  | 水印文字描边颜色，需要经过`urlsafe_base64_encode`，RGB格式，可以是颜色名称（例如red）或十六进制（例如 #FF0000），参考[RGB颜色编码表](https://www.rapidtables.com/web/color/RGB_Color.html)。存在`/wmText/`时生效，默认为黑色      |
| **水印位置** | `/wmGravity/&lt;Gravity&gt;`         | V  | N  | 视频或者图片水印位置。存在``/wmImage/` or `/wmVideo/``时生效。                                                                                                                            |
|          | `/wmGravityText/&lt;GravityText&gt;` | V  | N  | 文本位置，存在`/wmText/`时生效，默认 NorthEast。                                                                                                                                       |
|          | `/wmOffsetX/&lt;offsetX&gt;`         | V  | N  | 设置图片、文字、视频水印位置的相对横向偏移量，当值为正数时则向右偏移，反之向左。位置里包含West时，默认有+10的固定偏移，位置里包含East时，默认有-10的固定偏移，中间位置则固定偏移为0。                                                                       |
|          | `/wmOffsetY/&lt;offsetY&gt;`         | V  | N  | 设置图片、文字、视频水印位置的相对纵向偏移量，当值为正数时则向下偏移，反之向上。位置里包含North时，默认有+10的固定偏移，位置里包含South时，默认有-10的固定偏移，中间位置则固定偏移为0。                                                                     |

# **操作方式** [#操作方式]

您可以通过以下几种方式来创建任务：

### **方式一：使用任务触发器** [#方式一使用任务触发器]

* `对符合规则策略的上传文件自动触发`：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 [任务触发器](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/1-tigger)；创建完成后，需要开启 **上传触发开关**，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/0-multiple-rate-adaptive-transcoding-adapt/20240924-104416-84b0fd76e29a.webp)

### **方式二：使用[对象存储控制台](https://portal.qiniu.com/kodo/bucket)** [#方式二使用对象存储控制台]

* `上传文件手动触发`：在具体空间下， [上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file) 时，指定工作流模板 。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/0-multiple-rate-adaptive-transcoding-adapt/20240924-104626-b4de95907ff6.webp)

* `指定文件手动触发`：有两种指定单个文件创建任务的入口

  * 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

    ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/0-multiple-rate-adaptive-transcoding-adapt/20240924-104912-8de5e60349e1.webp)

    ```
    注意：仅对音视频/gif动图/webp动图文件提供该操作。
    ```

  * 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

    ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/0-multiple-rate-adaptive-transcoding-adapt/20240924-104746-36342fe1033e.webp)

### **方式三：使用API** [#方式三使用api]

* `资源上传时手动触发`：可以在构造[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)时在[上传策略](/products/kodo/development-guidelines/security/1-put-policy)中，设置相关字段，在资源文件上传时触发处理。
* `对已有资源手动触发`：可以在调用 [持久化数据处理(pfop)](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 时，设置相关字段，对已存在空间中的资源文件发起处理。

### **方式四：使用SDK** [#方式四使用sdk]

* 查看各语言 SDK 使用指南中 `持久化数据处理`  章节，可在[七牛官方SDK](/sdk-tools/sdk) 进行下载。

# **操作示例** [#操作示例]

`对已有资源手动触发`的形式，使用 adapt 命令把源mp4视频转成包含如下四路HLS码流（分辨率：320\*240 码率：200KB；分辨率：640\*480 码率：1200KB；分辨率：1280\*720 码率：6500KB；分辨率：1920\*1080 码率：8500KB；）的自适应HLS码流：

```
POST /pfop/ HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization:  Qiniu <AccessToken>
  bucket=publicbucket_z0&key=4k.mp4&fops=adapt/m3u8/multiResolution/320:240,640:480,1280:720,1920:1080/envBandWidth/200000,800000,1700000,2400000/multiVb/200k,1200k,6500k,8500k/hlstime/10/multiPrefix/cWluaXUtMjQw,cWluaXUtNDgw,cWluaXUtNzIw,cWluaXUtMTA4MA==
```

**注意**：要在Authorization头部的\<AccessToken>前添加 **Qiniu** 和半角空格。

# **计费说明** [#计费说明]

多码率自适应转码(adapt），服务价格=普通转码价格，定价参考 [智能多媒体服务定价](https://www.qiniu.com/prices/dora) 。


# 音视频拼接（avconcat） (/products/dora/audio-and-video-processing-api/1-audio-and-video-stitching-avconcat)



最近更新时间: 2026-08-18 12:01:08

# **简介** [#简介]

音视频拼接接口(avconcat)，用于将指定的数个音频片段拼接成一段音频，或者将数个视频片段拼接成一段视频。

### 使用限制 [#使用限制]

1. 不支持m3u8文件的拼接。如果要拼接m3u8文件，建议先音视频转码再调用该接口拼接。
2. 除去作为数据处理对象的源文件以外，还可以指定最多20个源文件（即总计21个片段）

<a id="avconcat-specification" />

# **参数说明** [#参数说明]

**注意**：接口规格不含任何空格与换行符，下列内容经过格式化以便阅读。

```
avconcat/<Mode>
        /format/<Format>
        /s/<Resolution>
        /index/<Index>
        /addAudio/<AddAudio>
        /<encodedkodocheme0>
        /<encodedkodocheme1>
        /<encodedkodocheme2>
        /<encodedkodochemeN>
```

| 参数名称                         | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| :--------------------------- | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `&lt;Mode&gt;`               | 是  | 1. 值为 `1 `时，可改变待拼接视频的封装格式，不进行编解码，不支持设置 `s `与`addAudio` 参数。<br />2. 值为 `2 `时，可改变待拼接视频的封装格式、分辨率等。<br />**注意**： 两个模式的计费有区别，[价格参考](https://www.qiniu.com/prices/dora?source=dora)。                                                                                                                                                                                                                                                                                                                               |
| `&lt;Format&gt;`             | 是  | 目标视频的格式，例如 flv、mp4 等。<br />请参考[支持转换的视频格式](https://support.qiniu.com/hc/kb/article/182125/)。                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `/index/&lt;Index&gt;`       | 否  | 用于设置源文件在拼接时的位置（表示位于第几个视频），默认值为1，表示源文件在拼接时作为第一个视频，最大值为拼接视频的文件数，如果设置的值超过最大值，则会报错。                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `/s/&lt;Resolution&gt;`      | 否  | 指定视频的目标分辨率，格式为宽 x 高 ，长边取值范围\[20,3840]的整数，短边取值范围\[20,2160]的整数。                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `/maxrate/&lt;Maxrate&gt;`   | 否  | 限制输出视频流的峰值码率，单位：比特每秒（bit/s）。<br />当 `&lt;Mode&gt;` 值为 `2` 时，且输出格式为 mp4、mov、mkv 时设置才有效。                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `/addAudio/&lt;AddAudio&gt;` | 否  | 当待拼接视频文件中，部分有音频流部分没有音频流时，是否给没有音频流的视频文件填充空的音频流。默认值为 1，表示填充；值为 0，则表示不填充。<br />**注意**：转场不支持填充音频，设置了转场动画的情况下本参数会无效。                                                                                                                                                                                                                                                                                                                                                                                              |
| `/&lt;encodedUrlN&gt;`       | 是  | 待拼接的文件，目前支持两种类型： kodo 资源、转场动画。<br />1、kodo 资源可由 `kodo://&lt;bucketname&gt;/&lt;key&gt;` 表示（此时 bucketname 需要与输入源在同一区域），需要经过`urlsafe_base64_encode`。<br />2、转场过渡动画可以看作一个视频，但是不占用拼接视频的数量名额，添加转场动画的方式也用 url 表示，具体格式为 `video://transition/&lt;transitionType&gt;/&lt;transitionTime&gt;` 表示，转场只支持 `&lt;Mode&gt;` 为 2 时使用，待拼接序列（含输入源文件）中不能连续两个转场， `transitionType`即转场支持的类型如下表，`transitionTime` 支持小数，向下取整取两位小数，不能超过两端任何一个视频的时长。支持首尾设置转场，此时的转场时间为 `&lt;transitionTime&gt;` 的一半。上述 url 均需要经过 `urlsafe_base64_encode`。 |

## **转场类型** [#转场类型]

视频拼接时，在两个视频片段之间添加转场动画，可以让视频拼接过渡更自然或者实现一些特殊视觉效果，达到吸引观众的效果。下表是转场类型的效果演示。

| 转场名  | transitionType 取值 |
| ---- | ----------------- |
| 闪白转场 | flashwhite        |
| 闪黑转场 | flashblack        |

敬请期待其他转场效果，如有需求可[提交工单](https://support.qiniu.com/tickets/new/?ref=developer.qiniu.com)。

## **转场使用示例** [#转场使用示例]

设置源文件拼接位置，index=3

* 示例1：片头+转场特效+源文件

```
avconcat/2/format/mp4/index/3/base64待拼接片头视频url/base64转场url
```

* 示例2：片头+转场特效+源文件+转场特效+片尾

```
avconcat/2/format/mp4/index/3/base64待拼接片头视频url/base64转场url/base64转场url/base64待拼接片尾视频url
```

# **操作方式** [#操作方式]

您可以通过以下几种方式来创建任务：

### **方式一：使用任务触发器** [#方式一使用任务触发器]

* `对符合规则策略的上传文件自动触发`：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 [任务触发器](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/1-tigger)；创建完成后，需要开启 **上传触发开关**，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/1-audio-and-video-stitching-avconcat/20240924-104416-84b0fd76e29a.webp)

### **方式二：使用[对象存储控制台](https://portal.qiniu.com/kodo/bucket)** [#方式二使用对象存储控制台]

* `上传文件手动触发`：在具体空间下， [上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file) 时，指定工作流模板 。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/1-audio-and-video-stitching-avconcat/20240924-104626-b4de95907ff6.webp)

* `指定文件手动触发`：有两种指定单个文件创建任务的入口

  * 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

    ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/1-audio-and-video-stitching-avconcat/20240924-104912-8de5e60349e1.webp)

```
注意：仅对音视频/gif动图/webp动图文件提供该操作。
```

* 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/1-audio-and-video-stitching-avconcat/20240924-104746-36342fe1033e.webp)

### **方式三：使用API** [#方式三使用api]

* `资源上传时手动触发`：可以在构造[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)时在[上传策略](/products/kodo/development-guidelines/security/1-put-policy)中，设置相关字段，在资源文件上传时触发处理。
* `对已有资源手动触发`：可以在调用 [持久化数据处理(pfop)](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 时，设置相关字段，对已存在空间中的资源文件发起处理。

### **方式四：使用SDK** [#方式四使用sdk]

* 查看各语言 SDK 使用指南中 `持久化数据处理`  章节，可在[七牛官方SDK](/sdk-tools/sdk) 进行下载。

# **操作示例** [#操作示例]

`对已有资源手动触发`  的形式，将多段mp4视频拼接成一段（分别是`thinking-in-go.1.mp4`、`thinking-in-go.2.mp4`、`thinking-in-go.3.mp4`。 假设这几个视频放在一个绑定了域名`test.clouddn.com`的空间中）：

```
POST /pfop/ HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>

bucket=qiniu-ts-demo&key=thinking-in-go.1.mp4&fops=avconcat/2/format/mp4/a29kbzovL3Fpbml1LXRzLWRlbW8vdGhpbmtpbmctaW4tZ28uMi5tcDQ=/a29kbzovL3Fpbml1LXRzLWRlbW8vdGhpbmtpbmctaW4tZ28uMy5tcDQ=&notifyURL=http://fake.com/qiniu/notify
```

**注意**：要在`Authorization`头部的`<AccessToken>`前添加`Qiniu`和半角空格。访问权限，见[管理凭证](/products/kodo/development-guidelines/security/access-token)方式。

# **计费说明** [#计费说明]

音视频拼接服务，不同mode有不同的收费，定价参考 [智能多媒体服务定价](https://www.qiniu.com/prices/dora) 。

* 使用 `avconcat/1`，服务价格=音视频转封装价格。
* 使用 `avconcat/2`，服务价格=普通转码价格。


# 锐智转码（avsmart） (/products/dora/audio-and-video-processing-api/10-perceptive-transcoding-avsmart-1)



最近更新时间: 2026-08-18 12:01:30

# **简介** [#简介]

* 锐智转码接口可根据视频场景内容自适应进行转码，在不损失画质的情况下（肉眼无感知）以总体更低的码率进行转码，实现`视频转码的质量更高`和`输出视频体积更小`的兼得。对于简单场景的视频，锐智转码可以调整编码组合使得码率更低一些，用户就能够在相同码率下观看更高分辨率的视频，在`带宽节省`的同时`观看体验更佳`。对于复杂场景的视频，锐智转码在编码过程中可以更加高效地分配比特，在保持总体码率不变情况下改善编码视频的视觉质量。通过加入这种场景内容自适应技术，原有的分辨率和码率组合会更加精简，从而有效降低内容提供商的存储和分发开销。
* 不同于基础音视频转码（avthumb），锐智转码无需用户指定输出视频的码率帧率等，而是由锐智转码依据源视频场景内容智能匹配最佳转码参数组合。

# **参数说明** [#参数说明]

锐智转码功能已经和 [普通音视频转码](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 功能合并，可以转码的同时支持锐智转码（即视频瘦身）。

```
avthumb/<format>
       /...
       /avsmart/<0|1>
       /smtMaxvbr/<maxvbr>
       /smtQuality/<quality>

```

| 参数名称                          | 类别 | 必填 | 说明                                                                                                                                                                                                                                                                                       |
| :---------------------------- | -- | :- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `...`                         |    |    | 其他参数使用,请参考 [avthumb](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb)                                                                                                                                                                                |
| `/avsmart/&lt;avsmart&gt;`    | V  | N  | 0、是否启用锐智转码，设置为 1 时开启。<br /> 1、支持使用H.264和H.265编码，默认使用H.264。<br /> 2、`使用 avsmart 的计费和 avthumb 有区别`，[价格参考](https://www.qiniu.com/prices/dora?source=dora)。<br />3、默认使用锐智转码2.0，[锐智转码2.0](https://www.qiniu.com/products/avsmart) 是基于 锐智转码1.0 的升级版本，1.0和2.0 支持的参数范围详情，建议使用锐智转码1.0的客户咨询客服进行升级。 |
| `/smtMaxvbr/&lt;maxvbr&gt;`   | V  | N  | 开启 `avsmart`时生效。最大平均码率, 单位：比特每秒（bit/s），常用视频比特率：128k 1.25m 5m 等。小于 1k 会默认使用 1k。暂时对 H.265 无效。                                                                                                                                                                                              |
| `/smtQuality/&lt;quality&gt;` | V  | N  | 开启`avsmart`时生效。瘦身时的转码质量等级，值越大，画质越好。整数，取值范围\[-7,9]。                                                                                                                                                                                                                                       |

# **操作方式** [#操作方式]

您可以通过以下几种方式来创建任务：

### **方式一：使用任务触发器** [#方式一使用任务触发器]

* `对符合规则策略的上传文件自动触发`：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 [任务触发器](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/1-tigger)；创建完成后，需要开启 **上传触发开关**，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/10-perceptive-transcoding-avsmart-1/20240924-104416-84b0fd76e29a.webp)

### **方式二：使用[对象存储控制台](https://portal.qiniu.com/kodo/bucket)** [#方式二使用对象存储控制台]

* `上传文件手动触发`：在具体空间下， [上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file) 时，指定工作流模板 。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/10-perceptive-transcoding-avsmart-1/20240924-104626-b4de95907ff6.webp)

* `指定文件手动触发`：有两种指定单个文件创建任务的入口

  * 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

    ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/10-perceptive-transcoding-avsmart-1/20240924-104912-8de5e60349e1.webp)

```
注意：仅对音视频/gif动图/webp动图文件提供该操作。
```

* 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/10-perceptive-transcoding-avsmart-1/20240924-104746-36342fe1033e.webp)

### **方式三：使用API** [#方式三使用api]

* `资源上传时手动触发`：可以在构造[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)时在[上传策略](/products/kodo/development-guidelines/security/1-put-policy)中，设置相关字段，在资源文件上传时触发处理。
* `对已有资源手动触发`：可以在调用 [持久化数据处理(pfop)](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 时，设置相关字段，对已存在空间中的资源文件发起处理。

### **方式四：使用SDK** [#方式四使用sdk]

* 查看各语言 SDK 使用指南中 `持久化数据处理`  章节，可在[七牛官方SDK](/sdk-tools/sdk) 进行下载。

# **操作示例** [#操作示例]

* 以 `资源上传时手动触发` 形式，将mp4视频进行锐智转码（即视频瘦身），设置视频编码格式为x264，分辨率为480x260，并关闭视频增强：

  ```
    {
        "scope":                "qiniu-ts-demo:thinking-in-go.mp4",
        "deadline":             1390528576,
        "persistentOps":        "avthumb/mp4/vcodec/libx264/s/480x360/avsmart/1",
        "persistentNotifyUrl":  "http://fake.com/qiniu/notify"
    }
  ```

* 以 `对已有资源手动触发` 形式，将mp4视频进行锐智转码（即视频瘦身），设置视频编码格式为x264，分辨率为480x260，并开启视频增强：

  ```
   POST /pfop/ HTTP/1.1
    Host: api.qiniu.com
    Content-Type: application/x-www-form-urlencoded
    Authorization: QBox <AccessToken>

    bucket=qiniu-ts-demo
    &key=thinking-in-go.mp4
    &fops=avthumb%2Fmp4%2Fvcodec%2Flibx264%2Fs%2F480x360%2Favsmart%2F1
    &notifyURL=http%3A%2F%2Ffake.com%2Fqiniu%2Fnotify
  ```

**注意**：

* 要在`Authorization`头部的`<AccessToken>`前添加`QBox`和半角空格。
* 转码的结果会保存在原文件的空间中，但是文件名按照默认规则生成，为了方便获取转码后资源链接，建议自定义结果文件的名称，请参考 [处理结果另存 (saveas)](/products/dora/processing-mechanism/0-processing-results-save-saveas)。

# **计费说明** [#计费说明]

锐智转码与普通音视频转码计费有区别，服务价格= 锐智转码价格，定价参考 [智能多媒体服务定价](https://www.qiniu.com/prices/dora) 。

**转码费用计算公式**

* 转码费用 = 输出文件时长 x 转码单价，价格单位： 元／分钟。

* 输出规格按输出视频分辨率的长边和短边属于输出规格划定的范围进行判定，以锐智转码输出HD (1920 x 1080) 规格为例：
  * 输出视频的分辨率长边不大于1920且短边不大于1080，则属于HD输出规格。
  * 输出视频的长边大于1920或输出视频的短边大于1080，该属于更高输出规格。

**注意**

七牛云的数据处理API均支持[管道](/products/dora/processing-mechanism/3-the-pipe)，通过管道操作符 `\|` 实现串行处理，即将一个资源经由多个 `&lt;fop&gt;` 串行处理。

处理规格如下：

```
<fop1>|<fop2>|<fop3>|<fopN>
```

* `<fop>` (File Operation的缩写)，表示数据处理指令及其所需要的参数。
* 整个串行处理中，只要有处理成功的 `fop`，就会有相应的计量计费。


# 视频雪碧截图 (/products/dora/audio-and-video-processing-api/11-video-sprite-screenshots)



最近更新时间: 2026-08-18 15:26:24

# **简介** [#简介]

雪碧图功能作为vsample功能的扩展， 所谓 **雪碧图** 是指先用 **vsample** 接口截取一系列图片，并按照一定的排列规则拼成一张大图，而这张大图即为雪碧图。生成雪碧图的同时可以选择保存多张单帧截图。

截取雪碧图的优势在于可降低图片的请求数量，从而可以通过请求雪碧图一次获取多张截图的信息，加强了客户端的性能。

<a id="video-sample-specification" />

# **参数说明** [#参数说明]

```
vsample/<Format>
       /spriteFormat/<SpriteFormat>
       /ss/<StartTime>
       /t/<Duration>
       /rotate/<Degree>
       /interval/<Interval>
       /frames/<Frames>
       /cellSize/<CellSize>
       /padding/<Padding>
       /margin/<Margin>
       /color/<Color>
       /lines/<Lines>
       /columns/<Columns>
       /savePattern/<savePattern>
       /saveSpritePattern/<saveSpritePattern>
```

| 参数名称                                           | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                             |
| :--------------------------------------------- | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `&lt;Format&gt;`                               | 是  | 指定单帧截图的图片格式，支持jpg、png等。                                                                                                                                                                                                                                                                                                                                                                                                        |
| `/spriteFormat/&lt;SpriteFormat&gt;`           |    | 指定雪碧图的图片格式，支持jpg、png等。<br />不设置则和`Format`一致。                                                                                                                                                                                                                                                                                                                                                                                   |
| `/ss/&lt;StartTime&gt;`                        |    | 指定截取视频的开始时刻，单位：秒,精度为 100ms，例如 `/ss/1.1`；<br />默认从片头开始。                                                                                                                                                                                                                                                                                                                                                                         |
| `/t/&lt;Duration&gt;`                          |    | 采样总时长，单位：秒,精度为 100ms，例如 `t/1.1`；<br />默认表示到片尾结束。                                                                                                                                                                                                                                                                                                                                                                               |
| `/rotate/&lt;Degree&gt;`                       |    | 指定顺时针旋转的度数，可取值为`90`、`180`、`270`、`auto`。<br />默认为不旋转。                                                                                                                                                                                                                                                                                                                                                                           |
| `/interval/&lt;Interval&gt;`                   |    | 指定截帧间隔时间，单元：秒。<br />默认为5秒,精度为 100ms，例如`/interval/0.1`指定平均截帧，截取的图片数量。 例如`/frames/1`。 <br />&#x2A;*注意：**<br />1. 和 `frames` 参数不能同时设置。<br />2. `frames`  和 `interval` 都不指定的情况，默认使用 `interval`。                                                                                                                                                                                                                                    |
| `/frames/&lt;Frames&gt;`                       |    | 指定平均截帧，截取的图片数量。 例如`/frames/10`，截取10张图片。 <br />&#x2A;*注意：**<br />1. 和 `interval` 参数不能同时设置。<br />2. `frames`  和 `interval` 都不指定的情况，默认使用 `interval`。<br />3. 当设置`frames` 值大于源视频帧数时，会按照源视频最大帧数来输出。<br />4. 建议截帧频率是视频帧率的整数倍。                                                                                                                                                                                                        |
| `/cellSize/&lt;CellSize&gt;`                   |    | 雪碧图中小图的分辨率，格式：WidthxHeight；长边取值范围  \[20,3840]，短边取值范围 \[20,2160]。<br />1、Widthx，指定宽，高随宽等比缩放；<br />2、xHeight，指定高，宽随高等比缩放。<br />3、宽高为空时，则和源视频保持一致。<br />4、宽高都不为空时，按指定宽高强制缩放。<br />**注意**：不能超出源分辨率，超出会处理失败。                                                                                                                                                                                                                        |
| `/padding/&lt;Padding&gt;	`                    |    | 雪碧图中小图内边距大小，取值范围\[0,100]，单位：px；<br />默认值为0。                                                                                                                                                                                                                                                                                                                                                                                    |
| `/margin/&lt;Margin&gt;`                       |    | 雪碧图中小图外边距大小，取值范围\[0,100]，单位：px；<br />默认值为0。                                                                                                                                                                                                                                                                                                                                                                                    |
| `/color/&lt;Color&gt;`                         |    | 雪碧图背景颜色，需要经过urlsafe\_base64\_encode。RGB格式，可以是颜色名称（例如红色）或十六进制（例如#FF0000），参考RGB颜色编码表；<br />默认为黑色。                                                                                                                                                                                                                                                                                                                                |
| `/lines/&lt;Lines&gt;`                         |    | 雪碧图大图中小图行数，取值范围\[1,100]；<br />默认值为10。                                                                                                                                                                                                                                                                                                                                                                                          |
| `/columns/&lt;Columns&gt;	`                    |    | 雪碧图大图中小图列数，取值范围\[1,100]；<br />默认值为10。<br />**注意**：输出单张雪碧图大小不能超过 2147483647字节。                                                                                                                                                                                                                                                                                                                                                  |
| `/savePattern/&lt;savePattern&gt;`             |    | 指定 **单帧截图** 的资源名格式，需要对设定值做[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。<br />**命名支持使用变量**：<br />1. 可以使用 `$(变量名)`或`${变量名}` 形式求值，魔法变量使用说明，参考 文件名变量 。<br />2. 注意：`$(count)`为必填项，必须存在的六位占位符数字串。<br /><br />**注意**：<br /> 1. 需要对设定值做 [URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。<br /> 2. 如果不指定该参数，则不保存雪碧图小图。<br /> 3. 不能和 `saveSpritePattern` 资源名格式相同。 |
| `/saveSpritePattern/&lt;saveSpritePattern&gt;` | 是  | 指定 **雪碧图** 的资源名格式，需要对设定值做[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。<br />**命名支持使用变量**：<br />1. 可以使用 `$(变量名)`或`${变量名}` 形式求值，魔法变量使用说明，参考 文件名变量 。<br />2. 注意：`$(count)`为必填项，必须存在的六位占位符数字串。<br /><br />&#x2A;*注意：**<br /> 1. 需要对设定值做 [URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。<br /> 2. 如果不指定该参数，则关闭雪碧图模式。<br /> 3. 不能和 `savePattern` 资源名格式相同。    |

# **操作方式** [#操作方式]

您可以通过以下几种方式来创建任务：

### **方式一：使用任务触发器** [#方式一使用任务触发器]

* `对符合规则策略的上传文件自动触发`：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 [任务触发器](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/1-tigger)；创建完成后，需要开启 **上传触发开关**，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/11-video-sprite-screenshots/20240924-104416-84b0fd76e29a.webp)

### **方式二：使用[对象存储控制台](https://portal.qiniu.com/kodo/bucket)** [#方式二使用对象存储控制台]

* `上传文件手动触发`：在具体空间下， [上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file) 时，指定工作流模板 。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/11-video-sprite-screenshots/20240924-104626-b4de95907ff6.webp)

* `指定文件手动触发`：有两种指定单个文件创建任务的入口

  * 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

    ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/11-video-sprite-screenshots/20240924-104912-8de5e60349e1.webp)

```
注意：仅对音视频/gif动图/webp动图文件提供该操作。
```

* 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/11-video-sprite-screenshots/20240924-104746-36342fe1033e.webp)

### **方式三：使用API** [#方式三使用api]

* `资源上传时手动触发`：可以在构造[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)时在[上传策略](/products/kodo/development-guidelines/security/1-put-policy)中，设置相关字段，在资源文件上传时触发处理。
* `对已有资源手动触发`：可以在调用 [持久化数据处理(pfop)](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 时，设置相关字段，对已存在空间中的资源文件发起处理。

### **方式四：使用SDK** [#方式四使用sdk]

* 查看各语言 SDK 使用指南中 `持久化数据处理`  章节，可在[七牛官方SDK](/sdk-tools/sdk) 进行下载。

# **操作示例** [#操作示例]

**示例1，参数如下：**

| 雪碧图输出格式(spriteFormat) | 平均截帧图片数(frames) | 小图大小(cellSize) | 雪碧图背景色(color) | 小图行数(lines) | 小图列数(columns) | 雪碧图大图命名(saveSpritePattern) |
| --------------------- | --------------- | -------------- | ------------- | ----------- | ------------- | -------------------------- |
| jpg                   | 10              | 960x540        | I0ZGRkZGRg==  | 15          | 6             | dmZyYW1lLSQoY291bnQp       |

[资源上传时自动触发]()：上传的`token`中指定`persistentOps`

```
{
"scope":                "qiniu-ts-demo:thinking-in-go.mp4",
"deadline":             1390528576,
"persistentOps":          "vsample/png/spriteFormat/jpg/frames/10/s/960x540/color/I0ZGRkZGRg==/lines/15/columns/6/saveSpritePattern/dmZyYW1lLSQoY291bnQp",
"persistentNotifyUrl":  "http://fake.com/qiniu/notify"
}
```

**示例2，参数如下：**

| 雪碧图输出格式(spriteFormat) | 截取开始时间(ss) | 截取结束时间(t) | 小图大小(cellSize) | 雪碧图背景色(color) | 小图行数(lines) | 小图列数(columns) | 雪碧图大图命名(saveSpritePattern) |
| --------------------- | ---------- | --------- | -------------- | ------------- | ----------- | ------------- | -------------------------- |
| jpg                   | 0          | 240       | 960x540        | I0ZGRkZGRg==  | 15          | 6             | dmZyYW1lLSQoY291bnQp       |

[资源上传时自动触发]()：上传的`token`中指定`persistentOps`

```
{
"scope":                "qiniu-ts-demo:thinking-in-go.mp4",
"deadline":             1390528576,
"persistentOps":          "vsample/png/spriteFormat/jpg/ss/0/t/240/s/960x540/color/I0ZGRkZGRg==/lines/15/columns/6/saveSpritePattern/dmZyYW1lLSQoY291bnQp",
"persistentNotifyUrl":  "http://fake.com/qiniu/notify"
}
```

[对已有资源手动触发]()：

```
POST /pfop/ HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>

bucket=qiniu-ts-demo&key=thinking-in-go.mp4&fops=vsample/png/spriteFormat/jpg/ss/0/t/240/s/960x540/color/I0ZGRkZGRg==/lines/15/columns/6/saveSpritePattern/dmZyYW1lLSQoY291bnQp
```

以 Python Sdk 为例，具体可以看下[音视频转码的示例](/products/dora/1-features_introduction)。需要在音视频转码的示例的基础修改数据处理命令 `fops` ，将其修改为：

```
fops = vsample/png/spriteFormat/jpg/ss/0/t/240/s/960x540/color/I0ZGRkZGRg==/lines/15/columns/6/saveSpritePattern/dmZyYW1lLSQoY291bnQp
```

**示例2，结果**

![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/11-video-sprite-screenshots/xuebitu-eac345c201a8.webp)

# **计费说明** [#计费说明]

视频雪碧截图，以 截取小图和拼接大图的总张数 来计量计费。比如视频截取了100张小图，最终生成的雪碧图是5张，则最终计量是105次。服务价格=视频截图价格，定价参考[智能多媒体服务定价](https://www.qiniu.com/prices/dora) 。


# 实时转码（avcvt） (/products/dora/audio-and-video-processing-api/12-real-time-transcode)



最近更新时间: 2025-06-06 11:06:10

本文主要介绍实时转码（边转边播）功能。

<a id="realTimeTranscoding" />

# **简介** [#简介]

传统离线转码需要对整个视频进行解码和编码后才能访问处理后的视频，这是一种异步处理模式，需要用户的等待时间较长。然而，实时转码技术可以即播即转、秒级开播，为用户提供全新的转码体验。

<img src="/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/12-real-time-transcode/0730%E9%85%8D%E5%9B%BE-16ab4e7296ee.webp" width="512" />

## **功能优势** [#功能优势]

* 耗时极短：无需等待异步转码完成，即播即转、可以在极短时间内播放实时转码后的视频
* 使用/对接简单：无需接收离线转码任务完成回调、开发复杂业务逻辑，接入简单
* 节约转码成本：只在视频访问时才触发转码处理、非必要不转码，减少转码量

## **使用限制** [#使用限制]

* 不支持av1编码格式的视频输入
* 不支持H.265  HDR 编码的视频输入
* 输入封装格式支持 3gp、mp4（含m4a)、mov，输出封装格式暂时仅支持 m3u8
* 输出分辨率不超过2K（2560×1440）
* 不支持[管道](/products/dora/processing-mechanism/3-the-pipe)命令
* 目前仅限国内华东-浙江、华南-广东、华北-河北区域使用

# **参数说明** [#参数说明]

注意：接口规格不含任何空格与换行符，下列内容经过格式化以便阅读。

```
avcvt/3
     /format/<Format>
     /segtime/<SegSeconds>
     /t/<Duration>
     /vcodec/<VideoCodec>
     /vb/<VideoBitRate>
     /r/<FrameRate>
     /s/<Resolution>
     /acodec/<AudioCodec>
     /ab/<AudioBitRate>
     /ar/<SamlingRate>
     /output/<Output>
```

| 分类       | 参数名                             | 类别  | 必填 | 说明                                                                                                                                                                                          |
| -------- | ------------------------------- | --- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 封装格式     | `/format/&lt;Format&gt;`        | A/V | Y  | 封装格式，只支持输出 m3u8 流（HLS协议）                                                                                                                                                                    |
| 切片时长     | `/segtime/&lt;SegSeconds&gt;`   | A/V | N  | 音视频切片时长，单位为秒（s），精确到毫秒（ms），取值范围为 2-10 秒，默认为10秒。                                                                                                                                              |
| 截取长度     | `/t/&lt;Duration&gt;`           | A/V | N  | 指定音视频截取的长度，单位：秒，支持精确到毫秒，例如1.500s。用于截取（0,Duration] 的音视频流进行切片。                                                                                                                                |
| 视频编码格式   | `/vcodec/&lt;VideoCodec&gt;`    | V   | N  | 视频编码格式，值范围：`libx264`、`libx265`、`copy`，默认值为 `libx264`                                                                                                                                        |
| 视频码率     | `/vb/&lt;VideoBitRate&gt;`      | V   | N  | 1、视频码率，单位：比特每秒（bit/s），常用视频码率：128k，1.25m，5m等。<br />2、默认等于源视频码率，在不改变视频编码格式时，若指定码率大于原视频码率，则使用原视频码率进行转码。<br />3、参数末尾使用 ! ，如 128k!，可以强制使用指定码率转码, 使平均码率不高于指定值，会牺牲一些视频播放质量；不使用!强制，会在码率与视频质量之间自动平衡。 |
| 视频帧率     | `/r/&lt;FrameRate&gt;`          | V   | N  | 1、视频帧率，每秒显示的帧数，单位：赫兹（Hz），常用帧率：24，25，30 等。<br />2、默认等于源视频帧率，取值范围为：\[1,60]。<br />3、帧范围不同收费有区别，\[1,30]  按普帧收费，(30,60] 按高帧收费，[价格参考](https://www.qiniu.com/prices/dora)。                         |
| 分辨率      | `/s/&lt;Resolution&gt;`         | V   | N  | 1、指定目标视频分辨率，格式为宽 x 高，长边范围\[20,2560]，短边取值范围\[20,1440]。<br />2、w、h 都为空时，则和原视频保持一致。<br />3、w为空，h不为空，则按h的值对原视频等比例缩放。<br />4、w不为空，h为空时，则按w的值对原视频等比例缩放。<br />5、w、h都不为空时，则根据w、h来缩放。                |
| 音频编码格式   | `/acodec/&lt;AudioCodec&gt;`    | A   | N  | 音频编码格式，值范围：`libmp3lame`，`libfdk_aac`、`copy`，默认值 为`libfdk_aac`。                                                                                                                              |
| 音频码率     | `/ab/&lt;AudioBitRate&gt;`      | A   | N  | 1、音频码率，单位：比特每秒（bit/s），常用码率：64k，128k，192k，256k，320k等。<br />2、默认等于源音频码率，在不改变音频编码格式时，若指定码率大于原音频码率，则使用原音频码率进行转码。<br />3、参数末尾使用 !, 可以以强制使用指定码率转码, 如 64k!                                         |
| 音频采样频率   | `/ar/&lt;AudioSamplingRate&gt;` | V   | N  | 音频采样频率，单位：赫兹（Hz），常用音频采样频率有 8000, 11025、12000、16000、22050、24000、32000、44056、44100、47250、48000、50000、64000、88200、96000 等。默认等于源音频采样频率。                                                         |
| m3u8 文件名 | `/output/&lt;Output&gt;`        | A/V | N  | 指定 m3u8 文件存储时的文件名（url 安全的 base64 编码）。ts 文件名为 \<m3u8\_name>~~/$(count).ts，其中 $(count) 是六位的占位符数字串。比如 m3u8 是 aaa.m3u8，则 ts 文件名为 aaa.m3u8~~/000000.ts、aaa.m3u8\~/000001.ts 。                    |

# **实时音视频转封装** [#实时音视频转封装]

* 当 `<VideoCodec> ` 和 `<AudioCodec>`  值同时为 `copy`  时，不进行音视频编解码操作，即音视频转封装。以实时音视频装封装计费。

# **操作方式** [#操作方式]

您可以通过以下两种方式对视频文件进行实时转码处理：

### **方式一：视频访问链接?参数** [#方式一视频访问链接参数]

**使用示例**

1. 原始视频链接 `http://aaa.com/sample.mp4`，转码为标清 720P 的 m3u8 文件
2. 将原始视频链接使用 `?` 拼接实时转码参数，即`http://aaa.com/sample.mp4?avcvt/3/format/m3u8` 便可直接获取 720P 的 m3u8 视频文件。

### **方式二：Kodo 支持通过控制台设置视频样式** [#方式二kodo-支持通过控制台设置视频样式]

| 支持的操作方式 | 参考文档                                                                                                                 |
| ------- | -------------------------------------------------------------------------------------------------------------------- |
| 控制台     | [设置视频样式](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/media-styles/2-set-the-video-style) |

**视频样式**

实时转码的使用方式和图片处理类似。您可以将视频实时转码的参数保存成视频样式，作为视频文件访问时触发实时处理的模板。

视频样式访问链接格式：`视频访问链接 + 分隔符 + 样式名称`

* 视频样式，是视频实时处理参数组合的模板。
* 样式分隔符，是用于连接资源链接和视频样式的特殊符号。
* 服务处理访问请求时，会优先定位到链接中的分隔符、并尝试以分隔符之后的内容去匹配视频样式、触发视频处理。

**使用示例**

1. 原始视频链接 `http://aaa.com/sample.mp4`，转码为标清 720P 的 m3u8 文件
2. 视频样式命名为 `sd.m3u8`，并指定样式分隔符为 `-`。
3. 将原始视频链接使用样式分隔符 `-` 拼接视频样式名 `sd.m3u8`，即访问 `http://aaa.com/sample.mp4-sd.m3u8` 便可直接获得 720P 的 m3u8 视频文件。

# **计费说明** [#计费说明]

按输出时长计量计费，服务定价=实时转码价格，定价参考 [智能多媒体服务定价](https://www.qiniu.com/prices/dora)。


# 音视频元信息（avinfo） (/products/dora/audio-and-video-processing-api/2-audio-and-video-metadata-information-avinfo)



最近更新时间: 2026-08-18 15:26:05

# **简介** [#简介]

音视频元信息接口(avinfo)用于获取指定音频、视频资源的元信息。

<a id="avinfo-request-syntax" />

# **参数说明** [#参数说明]

```
avinfo
```

# **操作方式** [#操作方式]

您可以通过以下几种方式来创建任务：

### **方式一：视频访问链接?参数** [#方式一视频访问链接参数]

* 即通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing) 的方式，即在访问文件URL时，添加数据处理指令，以直接获取处理后的结果。

### **方式二：使用任务触发器** [#方式二使用任务触发器]

* `对符合规则策略的上传文件自动触发`：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 [任务触发器](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/1-tigger)；创建完成后，需要开启 **上传触发开关**，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/2-audio-and-video-metadata-information-avinfo/20240924-104416-84b0fd76e29a.webp)

### **方式三：使用[对象存储控制台](https://portal.qiniu.com/kodo/bucket)** [#方式三使用对象存储控制台]

* `上传文件手动触发`：在具体空间下， [上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file) 时，指定工作流模板 。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/2-audio-and-video-metadata-information-avinfo/20240924-104626-b4de95907ff6.webp)

* `指定文件手动触发`：有两种指定单个文件创建任务的入口

  * 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

    ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/2-audio-and-video-metadata-information-avinfo/20240924-104912-8de5e60349e1.webp)

```
注意：仅对音视频/gif动图/webp动图文件提供该操作。
```

* 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/2-audio-and-video-metadata-information-avinfo/20240924-104746-36342fe1033e.webp)

### **方式四：使用API** [#方式四使用api]

* `资源上传时手动触发`：可以在构造[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)时在[上传策略](/products/kodo/development-guidelines/security/1-put-policy)中，设置相关字段，在资源文件上传时触发处理。
* `对已有资源手动触发`：可以在调用 [持久化数据处理(pfop)](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 时，设置相关字段，对已存在空间中的资源文件发起处理。

### **方式五：使用SDK** [#方式五使用sdk]

* 查看各语言 SDK 使用指南中 `持久化数据处理`  章节，可在[七牛官方SDK](/sdk-tools/sdk) 进行下载。

<a id="avinfo-samples" />

# **操作示例** [#操作示例]

```
http://78re52.com1.z0.glb.clouddn.com/resource%2Fthinking-in-go.mp4?avinfo
```

将返回如下元信息（已经经过格式化，以便阅读）：

```
{
    "streams": [
        {
            "index": 0,    流索引号
            "codec_name": "h264",   编码器名
            "codec_long_name": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",    编码器名全称
            "codec_type": "video",    编码器类型
            "codec_time_base": "1/30",    编码器每帧时长
            "codec_tag_string": "avc1",    编码器标签名
            "codec_tag": "0x31637661",    编码器标签
            "width": 1152,   宽度
            "height": 864,   高度
            "has_b_frames": 0,   记录帧缓存大小
            "sample_aspect_ratio": "1:1",   采样率
            "display_aspect_ratio": "4:3",
            "pix_fmt": "yuv420p",   像素格式
            "level": 40,   级别
            "is_avc": "1",
            "nal_length_size": "4",
            "r_frame_rate": "15/1",   真实基础帧率
            "avg_frame_rate": "15/1",   平均帧率
            "time_base": "1/15000",   每帧时长
            "start_time": "0.000000",   首帧时间
            "duration": "6413.333333",   文件总时间
            "nb_frames": "96200",   帧数
            "tags": {    标签
                "creation_time": "2013-01-07 12:58:08",     创建时间
                "language": "eng",   语言
                "handler_name": "Video Media Handler"    处理器名字
            }
        },
        {
            "index": 1,   流索引号
            "codec_name": "aac",   编码器名
            "codec_long_name": "Advanced Audio 编码器全名Coding",   编码器名全称
            "codec_type": "audio",   编码器类型
            "codec_time_base": "1/44100",   编码器每帧时长
            "codec_tag_string": "mp4a",   编码器标签名
            "codec_tag": "0x6134706d",   编码器标签
            "sample_fmt": "s16",   采样格式
            "sample_rate": "44100",   采样率
            "channels": 2,   音频数
            "bits_per_sample": 0,   采样码率
            "r_frame_rate": "0/0",   真实基础帧率
            "avg_frame_rate": "0/0",   平均帧率
            "time_base": "1/44100",   每帧时长
            "start_time": "0.000000",   首帧时间
            "duration": "6413.374694",   文件总时间
            "nb_frames": "276201",   帧数
            "tags": {   标签信息
                "creation_time": "2013-01-07 12:58:08",   创建时间
                "language": "eng",   语言
                "handler_name": "Sound Media Handler"   处理器名字
            }
        }
    ],
    "format": {
        "nb_streams": 2,   流的数目
        "format_name": "mov,mp4,m4a,3gp,3g2,mj2",   格式名
        "format_long_name": "QuickTime/MPEG-4/Motion JPEG 2000 format",   格式名全称
        "start_time": "0.000000",   首帧时间
        "duration": "6413.359589",   时长
        "size": "101416337",   文件大小
        "bit_rate": "126506",   码率
        "tags": {   标签信息
            "major_brand": "mp42",   主品牌
            "minor_version": "1",   次要版本
            "compatible_brands": "M4V mp42isom",   兼容性品牌
            "creation_time": "2013-01-07 12:58:08"   创建时间
        }
    }
}
```

* [点击查看示例结果](http://78re52.com1.z0.glb.clouddn.com/resource%2Fthinking-in-go.mp4?avinfo)

* [视频元信息响应内容的属性及说明](/faq/dora/av-processing/1678-video-meta-information-response-content-properties-and-instructions)

# **计费说明** [#计费说明]

音视频元信息按调用次数计量，服务定价=音视频元信息价格，定价参考 [智能多媒体服务定价](https://www.qiniu.com/prices/dora) 。


# 普通音视频转码（avthumb） (/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb)



最近更新时间: 2026-08-18 15:25:43

# **简介** [#简介]

音视频转码方便用户对音频、视频资源进行编码和格式转换。

* 支持自定义视频的编码格式、封装格式、分辨率、码率等参数进行转码，从而适用于不同的业务场景、播放终端及网络环境。

* 支持对视频内容进行自适应转码，在不损失画质的情况下降低编码码率和带宽，适用于有降低成本且保证画质清晰度的场景。

注意：接口规格不含任何空格与换行符，下列内容经过格式化以便阅读。

```
avthumb/<Format>
       /vcodec/<VideoCodec>
       /avsmart/<0|1>
       /smtQuality/<Quality>
       /refine/<Refine>
       /maxrate/<Maxrate>
       /r/<FrameRate>
       /ref/<Ref>
       /hr/<HighFrameRate>
       /vb/<VideoBitRate>
       /crf/<Crf>
       /h264Profile/<H264Profile>
       /h264Level/<H264Level>
       /s/<Resolution>
       /s/<Resolution>>
       /s/<Resolution><
       /aspect/<Aspect>
       /autoscale/<Autoscale>
       /padW/<PadW>
       /padH/<PadH>
       /padVideoX/<PadVideoX>
       /padVideoY/<PadVideoY>
       /gop/<GroupOfPictures>
       /colorspace/<ColorSpace>
       /keyFramePosition/<KeyFramePosition>
       /rotate/<Degree>
       /rotateinfo/<Degree>
       /flip/<Flip>
       /compressLevel/<level>
       /ss/<SeekStart>
       /t/<Duration>
       /gifHighColor/<GIFHighColor>
       /deinterlace/<Deinterlace>
       /wmImage/<EncodedKodoScheme>
       /wmVideo/<EncodedKodoScheme>
       /wmGravity/<Gravity>
       /wmScale/<Scale>
       /wmScaleType/<ScaleType>
       /wmVideoOrder/<VideoOrder>
       /wmConstant/<Constant>
       /wmAlpha/<Alpha>
       /wmIgnoreLoop/<WmIgnoreLoop>
       /wmText/<EncodedText>
       /wmGravityText/<GravityText>
       /wmFont/<font>
       /wmFontStyle/<fontStyle>
       /wmFontColor/<fontcolor>
       /wmFontSize/<fontsize>
       /wmOffsetX/<offsetX>
       /wmOffsetY/<offsetY>
       /wmPos/<Position>
       /wmDuration/<Duration>
       /wmShortest/<WmShortest>
       /mosaic/<Mosaic>
       /mosaicGravity/<MosaicGravity>
       /mosaicOffsetX/<MosaicOffsetX>
       /mosaicOffsetY/<MosaicOffsetY>
       /mosaicSize/<MosaicSize>
       /mosaicStart/<MosaicStart>
       /mosaicDuration/<MosaicDuration>
       /stream/<Stream>
       /cut/<Cut>
       /vn/<VideoNo>
       /sn/<SubtitleNo>
       /scodec/<SubtitleCodec>
       /subtitle/<SubtitleURL>
       /stFont/<SubtitleFont>
       /stFontSize/<SubtitleFontSize>
       /stOffsetX/<SubtitleOffsetX>
       /stOffsetY/<SubtitleOffsetY>
       /stripmeta/<StripMeta>
       /meta/<Meta>
       /useMovTags/<UseMovTags>
       /acodec/<AudioCodec>
       /ab/<BitRate>
       /ac/<ChannelNum>
       /ar/<SamplingRate>
       /aq/<AudioQuality>
       /audioProfile/<profile>
       /volume/<Volume>
       /loudnorm/<LoudNorm>
       /loudnormI/<LoudNormI>
       /loudnormLRA/<LoudNormLRA>
       /loudnormTP/<LoudNormTP>
       /loudnormF/<LoudNormF>
       /loudnormG/<LoudNormG>
       /loudnormRefine/<LoudNormRefine
       /an/<AudioNo>
       /speex/<Speex>
       /writeXing/<0|1>
       /amix/<AmixURL>
       /amixOffset/<AmixOffset>
       /amixStart/<AmixStart>
       /amixDuration/<AmixDuration>
       /multiArep/<MultiAudioReplaceURL>
       /multiArepOffset/<MultiAudioReplaceOffset>
       /multiArepStart/<MultiAudioReplaceStart>
       /multiArepDuration/<MultiAudioReplaceDuration>
       /sdr/<SDR>
       /pixFmt/<PixFmt>
       /limitWidth/<LimitWidth>
       /limitHeight/<LimitHeight>
       /limitSize/<LimitSize>
       /limitDuration/<LimitDuration>
```

# **封装参数** [#封装参数]

| 分类                 | 参数名称                             | 类别  | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                 |
| :----------------- | :------------------------------- | :-- | :- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **封装格式**           | `&lt;Format&gt;`                 | A/V | Y  | 封装格式，目标音频（比如 mp3、 m4a 等）或视频（比如 avi 、flv 、mp4、hls等）格式。具体细节请参考[支持转换的封装格式](/faq/dora/av-processing/1320-avthumb-parameters-formats-format-and-explanation)。<br />1、当 format 值为 `hls  `或 `m3u8` 时，除了当前文档支持的参数范围，还有更多音视频切片独有的参数，请参考 [音视频切片(hls)](/products/dora/audio-and-video-processing-api/7-audio-and-video-slice) 文档。<br />2、当 vcodec值设为 `libaom-av1` 时， 封装格式仅支持设置为： mp4、mkv、wmv。 |
| **去除视频流**          | `/vn/&lt;VideoNo&gt;`            | V   | N  | 是否去除视频流，0为保留，1为去除。 默认值为0。                                                                                                                                                                                                                                                                                                                                                          |
| **去除音频流**          | `/an/&lt;AudioNo&gt;`            | A   | N  | 是否去除音频流，0为保留，1为去除。 默认值为0。                                                                                                                                                                                                                                                                                                                                                          |
| **去除字幕流**          | `/sn/&lt;SubtitleNo&gt;`         | V   | N  | 是否去除字幕，0为保留，1为去除。默认值为0。                                                                                                                                                                                                                                                                                                                                                            |
| **保留 or 去除媒体流**    | `/stream/&lt;Stream&gt;`         | A/V | N  | 从输入源中选择要保留的或者要去除的媒体流，假设输入源有 n 个流（编号从 0 开始，n > 2），则保留媒体流的合法参数有 0、(n-1)、0…2、0…0、0,1,2 等，去除媒体流的合法参数有 -0、-(n-1)、-0…(n-2)、-1…1、-1,2 等，其中形如 a…b 表示保留编号为 \[a,b] 流，a,b,c 表示保留编号为 a、b 和 c 的流，-a…b 表示去除编号为 \[a,b] 流，-a,b,c 表示去除编号为 a、b 或 c 的流。流的编号可以通过 [avinfo](/products/dora/audio-and-video-processing-api/2-audio-and-video-metadata-information-avinfo) 来查看。                            |
| **清除文件 metadata**  | `/stripmeta/&lt;StripMeta&gt;`   | A/V | N  | 是否清除文件的 `metadata`，0为保留，1为清除。                                                                                                                                                                                                                                                                                                                                                      |
| **设置文件 metadata**  | `/meta/&lt;Meta&gt;`             | A/V | N  | 设置文件 metadata。格式为 urlsafe\_base64\_encode(\{"k1":"v1","k2":"v2"...})，其中 key:value 即写入一组或者多组 metadata。                                                                                                                                                                                                                                                                              |
| **保留自定义 metadata** | `/useMovTags/&lt;UseMovTags&gt;` | A/V | N  | 输出格式为 MOV/MP4 等格式时，是否支持保留或设置自定义元数据。0为清除，1为保留。默认为0。                                                                                                                                                                                                                                                                                                                                 |

**注意**：不同的封装格式，有默认转码参数值，如果觉得某些参数不适合自己的业务场景，可以在后面加参数覆盖。如： `avthumb/mp3/ab/64k` 会把默认码率128k调整为64k。

| 封装格式  | 视频编码器  | 视频码率 | 音频编码器      | 音频码率   | 音频采样率 |
| ----- | ------ | ---- | ---------- | ------ | ----- |
| flash | flv    | 512k | libmp3lame | 64k    | 44100 |
| webm  | libvpx | 700k | libvorbis  | 128k   | 48k   |
| mp3   | -      | -    | libmp3lame | 128k   | 44100 |
| amr   | -      | -    | amr\_nb    | 12.20k | 8000  |

# **视频参数** [#视频参数]

| 分类             | 参数名称                                         | 类别  | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :------------- | :------------------------------------------- | :-- | :- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **编码格式**       | `/vcodec/&lt;VideoCodec&gt;`                 | V   | N  | 视频编码格式，支持方案：libx264，libx265，libvpx，libvpx-vp9，libaom-av1，libtheora，libxvid等，默认值为 libx264。具体细节请参考 [支持转换的视频编码格式](/faq/dora/av-processing/1385-avthumb-parameter-vcodec-format-and-explanation)。<br />**注意** ：libx264，libx265，libaom-av1三种编码格式的价格有区别，[价格参考](https://www.qiniu.com/prices/dora?source=dora)。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **锐智转码**       | `/avsmart/&lt;avsmart&gt;`                   | V   | N  | 0、是否启用锐智转码，设置为 1 时开启。<br />1、支持使用`libx264`和 `libx265` 编码，默认使用libx264；不支持 `libaom-av1` 编码，同时也不支持`libaom-av1` 解码 （即不支持AV1视频输入）。<br />2、`使用 avsmart 的计费和 avthumb 有区别`，[价格参考](https://www.qiniu.com/prices/dora?source=dora)。<br />3、默认使用锐智转码2.0，[锐智转码2.0](https://www.qiniu.com/products/avsmart) 是基于 锐智转码1.0 的升级版本，1.0和2.0 支持的参数范围详情，建议使用锐智转码1.0的客户咨询客服进行升级。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|                | `/smtMaxvbr/&lt;maxvbr&gt;`                  | V   | N  | 开启 `avsmart`时生效。最大平均码率, 单位：比特每秒（bit/s），常用视频比特率：128k 1.25m 5m 等。小于 1k 会默认使用 1k。暂时对 H.265 无效。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
|                | `/smtQuality/&lt;quality&gt;`                | V   | N  | 开启`avsmart`时生效。瘦身时的转码质量等级，值越大，画质越好。整数，取值范围\[-7,9]。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **GPU转码**      | `/prehw/&lt;PreHW&gt;`                       | V   | N  | 是否倾向启用GPU硬件转码(编码)，设置为 1 时，在GPU环境下开启，默认关闭采用软件转码。<br />1、当前只支持**华东区域**的资源处理 <br />2、AV1编解码不支持<br />3、HDR输入输出不支持<br />4、输出分辨率：最大分辨率H.264 是 4096x4096，H.265是 8192x4320，最小分辨率  150x150<br />5、锐智转码不支持<br />**注意**：当前公测阶段，GPU转码价格跟普通转码收费一样，后续可能会调整价格。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **码率控制**       | `/refine/&lt;Refine&gt;`                     | V   | N  | 是否启用高质量转码，设置为 1 时开启。保证在视频内优化码率分配。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
|                | `/maxrate/&lt;Maxrate&gt;`                   | V   | N  | 1、使用 `/refine/1` 高质量转码时，使用该参数限制输出视频流的峰值码率。当不使用 /vb/\<VideoBitRate> 时，该值不可低于输入视频码率；当使用 /vb/\<VideoBitRate> 时，该值不可低于由 /vb/\<VideoBitRate> 指定的视频码率。<br />2、不使用`/refine/1` 时，无使用限制，但该值不可低于由 /vb/\<VideoBitRate> 指定的视频码率，否则会以 /vb/\<VideoBitRate>为准。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
|                | `/vb/&lt;VideoBitRate&gt;`                   | V   | N  | 1、视频码率，单位：比特每秒（bit/s），取值范围\[1000,50000000]，常用视频码率：128k，1.25m，5m等。<br /> 2、在不改变视频编码格式时，若指定码率大于原视频码率，则使用原视频码率进行转码。 <br />3、参数末尾使用 `!` ，如 128k!，可以强制使用指定码率转码, 使平均码率不高于指定值，会牺牲一些视频播放质量；不使用`!`强制，会在码率与视频质量之间自动平衡。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
|                | `/crf/&lt;Crf&gt;`                           | V   | N  | 1、设置 crf 值，为整数，其不可与 vb 共用；<br /> 2、vcodec 为` libx264` 时取值为范围 \[18,36]，vcodec 为` libx265` 时取值范围为 \[23,41]，默认取值为范围 \[18,36]；vcodec 为` libaom-av1` 时取值范围为 \[23,51]，默认取值为范围 \[18,36]；<br /> 3、其值越小，输出视频质量越好，输出文件可能变大。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **帧率控制**       | `/r/&lt;FrameRate&gt;`                       | V   | N  | 1、视频帧率，每秒显示的帧数，单位：赫兹（Hz），常用帧率：24，25，30 等。 <br />2、默认等于源视频帧率，HighFrameRate=0，取值\[1,30]，超出范围取25帧；HighFrameRate=1时允许高帧率，取值\[1,60]，超出范围取60帧。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
|                | `/ref/&lt;Ref&gt;`                           | V   | N  | 设置参考帧数量，取值范围\[1,16]，默认值为4。<br />&#x2A;*注意:** 暂不支持输出为 `libx265` 和 ` libaom-av1`设置该参数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
|                | `/hr/&lt;HighFrameRate&gt;`                  | V   | N  | 视频高帧率，与`r`配合使用，默认为`HighFrameRate=0`，即常规帧率；`HighFrameRate=1`表示保留高帧率。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **分辨率**        | `/s/&lt;Resolution&gt;`                      | V   | N  | 指定视频目标分辨率，格式：`w`x`h`，指定宽高强制进行缩放，可能会导致视频变形。<br />1、`w` 和 `h` 都为空时，则和原视频保持一致。<br />2、`w`为空，`h`不为空，则按`h`的值对原视频等比例缩放。<br />3、`w`不为空，`h`为空时，则按`w`的值对原视频等比例缩放。<br />4、 `w`、和`h`都不为空时，则根据`w`、`h`来缩放。<br />&#x2A;*取值范围说明：**<br />1、`vcodec`为`libx265` 或 `libx264` 或`libaom-av1`时，长边取值范围\[20,8192]，短边取值范围\[20,4320]；`vcodec`取其他值时,长边范围\[20,3840]，短边取值范围\[20,2160]。<br />2、`/prehw/1/`开启时，在GPU转码情况下，当且仅当该宽高缩放的功能开启时，会经由GPU加速；264长边取值范围\[150,4096]，短边取值范围\[150,4096]。265长边取值范围\[150,8192]，短边取值范围\[150,4320]。                                                                                                                                                                                                                                                                                                                                                                                   |
|                | /s/\<Resolution>>                            | V   | N  | 指定视频目标分辨率，格式：`w`x`h`>，指定宽高强制缩小不放大。取值范围和`/s/&lt;Resolution&gt;`一致。<br />1、`w`不为空且小于原视频宽，`h`为空时，指定宽，高随宽等比缩小；<br />2、`w`为空，`h`不为空且小于原视频高时，指定高，宽随高等比缩小。<br />3、`w` 和 `h` 都为空时，则和原视频保持一致。<br />4、 `w`和`h`都不为空时，且都小于原视频宽高时，则根据`w`、`h`来缩小。<br />**备注**：如果目标宽和高都大于原视频宽和高，则不处理，跟原视频保持一致。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
|                | /s/\<Resolution>\<                           | V   | N  | 指定视频目标分辨率，格式：`w`x`h`\<，指定宽高强制放大不缩小。取值范围和`/s/&lt;Resolution&gt;`一致。<br />1、`w`不为空且大于原视频宽，`h`为空时，指定宽，高随宽等比放大；<br />2、`w`为空，`h`不为空且大于原视频高时，指定高，宽随高等比放大。<br />3、`w` 和 `h` 都为空时，则和原视频保持一致。<br />4、 `w`和`h`都不为空，且都大于原视频宽高时，则根据`w`、`h`来放大。<br />**备注**：如果目标宽和高都小于原视频宽和高，则不处理，跟原视频保持一致。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **GOP长度**      | `/gop/&lt;GroupOfPictures&gt;`               | V   | N  | **GOP参数**，即视频流关键帧间的间隔帧数，取值\[0,3000]的整数。<br />1、不填或者取值为0，表示采用指定视频编码格式的默认GOP值（例如H264格式，默认GOP值为250）。<br /> 2、锐智转码1.0版本不支持该参数。<br />**注意**：GOP取值过小会影响视频编码压缩率，码率变大，过大会使图像群组的时长跨度过大，影响播放随机性，故一般建议采用默认值。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **在播放器中宽高比**   | `/aspect/&lt;Aspect&gt;`                     | V   | N  | 该参数为视频在播放器中显示的宽高比，格式为`&lt;width&gt;:&lt;height&gt;`。例如：取值`3:4`表示视频在播放器中播放是`宽:高`=`3:4`（注：此处取值仅为体现演示效果）。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **视频按比例缩放**    | `/autoscale/&lt;Autoscale&gt;`               | V   | N  | 0、不设置即默认值 `autoscale/0` ，会强制缩放到输出分辨率，原视频比例（A)和输出分辨率比例(B)不等时，可能造成视频变形。<br />1、原视频比例（A)和输出分辨率比例(B)不等时，设置`autoscale/1`，对输出分辨率做相应调整，保证转码后视频不变形：<br />a. 若A\<B，原视频按照输出分辨率的`高`进行缩放 <br />b.  若A>B，原视频按照输出分辨率的`宽`进行缩放<br />2、原视频比例（A)和输出分辨率比例(B)不等时，设置`autoscale/2`，对输出分辨率做相应调整，保证转码后视频不变形：<br />a.  若A\<B，原视频按照输出分辨率的`高`进行缩放，再放到输出分辨率矩形框内，并填充黑色 <br />b.   若A>B，原视频按照输出分辨率的`宽`进行缩放，再放到输出分辨率矩形框内，并填充黑色。 <br />3、原视频是 `m3u8` 格式，且存在不同分辨率时，设置 `autoscale/3`，对输出分辨率做相应调整，保证转码后视频不变形：<br />a. 将视频中途分辨率变化的部分，按照输出分辨率的`宽`或 `高`进行缩放，再放到输出分辨率矩形框内，并填充黑色。 <br /><br />**注意**：  `autoscale/2 ` 和 `autoscale/3`，不能跟 `padW`、`padH`、`padVideoX`、`padVideoY`、`wmImage`、`wmVideo ` 参数共用； `autoscale/1 ` 不能跟 `wmImage`、`wmVideo `  参数共用。<br />**参数使用图示**：![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb/163429-faabb2a72aa3.webp) |
| **编码属性**       | `/compressLevel/&lt;level&gt;`               | V   | N  | 设置视频编码时压缩的等级，选项为1,1.5,2,4，等级越高压缩效果越好，更耗CPU。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
|                | `/h264Profile/&lt;H264Profile&gt;`           | V   | N  | 设置 h264 的 profile等级，支持 baseline、main、high。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|                | `/h264Level/&lt;H264Level&gt;`               | V   | N  | 设置 h264 的 level 值，合法的值有 3.0、3.1、4.0、4.1、4.2，默认值为3.0。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **HDR to SDR** | `/sdr/&lt;SDR&gt;`                           | V   | N  | **是否启用增强 SDR，设置为 “1” 时开启**。<br />1、当输入源为`HDR`时，设置为 “1” 时，转为SDR视频，不支持hdr的设备上也能尽可能还原hdr效果。 <br />2、默认关闭，跟随源视频，即hdr到hdr，sdr到sdr。 <br />**注意**： 不支持hdr的设备播放hdr视频，没有hdr效果。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
|                | `/colorspace/&lt;ColorSpace&gt;`             | V   | N  | **指定 SDR 的色彩空间**。<br />1、暂时只支持取值 bt709，若不设置则输出的色彩空间同输入源。<br />2、若输入源是 HDR 视频，必须设置 `sdr/1` 才会生效。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **SDR to HDR** | `/hdr/&lt;HDR&gt;`                           | V   | N  | **是否启用 SDR 转 HDR，设置为 “1” 时开启**。<br />1、当输入源为`SDR`时，设置为 “1” 且指定输出为 H.265 编码时，才能转为 ` HDR`  视频。<br />2、不能与锐智转码相关参数（avsmart、smtMaxvbr、smtQuality）和 pixFmt 同时使用。<br />**注意**：使用 SDR to HDR 的收费跟普通转码有区别，请参考 [音视频增强](https://www.qiniu.com/prices/dora?source=dora)。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|                | `/maxLuminance/&lt;MaxLuminance&gt;`         | V   | N  | **设置输出 HDR 视频最大亮度**。<br />1、单位 nit，参数范围 500 nit \~ 1000 nit，默认值为 0，即根据视频内容自适应调整。<br />2、必须设置` hdr/1` 才会生效。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **视频颜色格式**     | `/pixFmt/&lt;PixFmt&gt;`                     | V   | N  | 指定视频像素格式，目前仅支持设置yuv420p。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **高画质gif**     | `/gifHighColor/&lt;GIFHighColor&gt;`         | V   | N  | 输出为 gif 时，值为 1 表示选择输出高画质的 gif 文件，默认值为 0。只支持与以下参数共用：`&lt;SeekStart&gt;`、`&lt;Duration&gt;`、`&lt;Resolution&gt;`、`&lt;FrameRate&gt;`、`&lt;Autoscale&gt;`。<br />输出 gif 的帧数最多为 4500。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **去交错**        | `/deinterlace/&lt;Deinterlace&gt;`           | V   | N  | 是否启用去交错功能。 <br />1、 默认值为 1，表示开启，即将视频从隔行扫描调整为逐行扫描。<br />2、值为 0 则表示关闭，即保持原有模式，保留视频为隔行扫描模式。<br />3、不支持将视频从逐行扫描调整为隔行扫描。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **自定义黑框**      | `/padW/&lt;PadW&gt;`                         | V   | N  | 1、用于给视频添加自定义黑框，不能跟 `autoscale/2` 和 `autoscale/3` 共用。<br />2、添加黑框后的视频的宽,取值范围\[20,3840]且取值大于或等于原视频宽, 和 padH 同时有效时启用 pad。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|                | `/padH/&lt;PadH&gt;`                         | V   | N  | 1、用于给视频添加自定义黑框，不能跟 `autoscale/2` 和 `autoscale/3` 共用。 <br />2、添加黑框后的视频高,取值范围\[20,3840]且取值大于或等于原视频宽, 和 padW 同时有效时启用 pad。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|                | `/padVideoX/&lt;PadVideoX&gt;`               | V   | N  | 1、用于给视频添加自定义黑框，不能跟 `autoscale/2` 和 `autoscale/3` 共用。 <br />2、当 padW、padH 有效时生效，添加黑框后的视频中的横向偏移, 即原视频在添加黑框后视频左上角的 x 坐标, 默认0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
|                | `/padVideoY/&lt;PadVideoY&gt;`               | V   | N  | 1、用于给视频添加自定义黑框，不能跟 `autoscale/2` 和 `autoscale/3` 共用。 <br />2、当 padW、padH 有效时生效，添加黑框后的视频中的纵向偏移, 即原视频在添加黑框后视频左上角的 y 坐标, 默认0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
|                | `/keyFramePosition/&lt;KeyFramePosition&gt;` | V   | N  | 设置多个关键帧出现的时间点，以.分隔，个数范围\[1,5]，单位：秒，时间范围\[1,10]，且时间采用增长趋势，例如：keyFramePosition/1.3.5.8.10                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **视频旋转/翻转**    | `/rotate/&lt;Degree&gt;`                     | V   | N  | 指定顺时针旋转的度数，可取值为`90`、`180`、`270`、`auto`，默认为 auto。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
|                | `/rotateinfo/&lt;Degree&gt;`                 | V   | N  | 添加视频播发时画面顺时针旋转的度数信息，该参数仅在`vcodec` 为` copy` 时生效，可取值为0、90、180、270，默认为 0。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|                | `/flip/&lt;Flip&gt;`                         | V   | N  | 视频翻转, 水平翻转 `horizontal`, 垂直翻转 `vertical`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **截取片段**       | `/ss/&lt;SeekStart&gt;`                      | A/V | N  | 指定音视频截取的开始时间，单位：秒，支持精确到毫秒，例如3.345s。用于视频截取，从一段视频中截取一段视频。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
|                | `/t/&lt;Duration&gt;`                        | A/V | N  | 指定音视频截取的长度，单位：秒，支持精确到毫秒，例如1.500s。用于视频截取，从一段视频中截取一段视频。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **去掉多段合成**     | `/cut/&lt;Cut&gt;`                           | A/V | N  | 1、对单个视频去掉多段合成一个视频； <br />2、从输入源中选择要去除的时间段，每个要去除的时间段由起止绝对时间表示，单位为 s，精确到 ms。例如，`0.5,1.0` 表示去除时间范围为 `[0.5,1.0]` 上的音视频； `0.5,1.0;1.5,2.0` 表示去除时间范围为 `[0.5,1.0]`、`[1.5,2.0]` 上的音视频。 <br />3、注意，其中时间范围不可有重叠，且需按起始点的位置顺序组织。参数值需要经过 `urlsafe_base64_encode`，例如 `cut/MC41LDEuMDsxLjUsMi4w` 是合法的。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **加/减速视频**     | `/vspeed/&lt;vspeed&gt;`                     | V   | N  | 加/减速视频，小数，取值范围\[0.01,100]，大于1时表示加速，小于1表示减速，默认为1，源视频速度不变。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **视频马赛克**      | `/mosaic/&lt;Mosaic&gt;`                     | V   | N  | 是否启用马赛克，固定为 `1`,且后续马赛克参数必须连续，支持添加多个马赛克。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
|                | `/mosaicGravity/&lt;MosaicGravity&gt;`       | V   | N  | 马赛克的位置，参考锚点参数表，默认值为`NorthEast`（右上角）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|                | `/mosaicOffsetX/&lt;MosaicOffsetX&gt;`       | V   | N  | 马赛克位置的相对横向偏移量 ，正数则向右偏移，负数向左偏移，当`mosaic/1`时必填                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
|                | `/mosaicOffsetY/&lt;MosaicOffsetY&gt;`       | V   | N  | 马赛克位置的相对纵向偏移量 ，正数则向下偏移，负数向上偏移，当`mosaic/1`时必填                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
|                | `/mosaicSize/&lt;MosaicSize&gt;`             | V   | N  | 马赛克区域大小，即指定马赛克的宽和高，例如：`100x200`, 当`mosaic/1`时必填                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
|                | `/mosaicStart/&lt;MosaicStart&gt;`           | V   | N  | 马赛克起始时间 默认为0 e.g. `12.3`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
|                | `/mosaicDuration/&lt;MosaicDuration&gt;`     | V   | N  | 马赛克持续时间 默认直到片尾 e.g. `21.3`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

# **水印参数** [#水印参数]

支持对视频加多个不同类型的水印。

| 分类          | 参数名称                                 | 类别 | 必填 | 说明                                                                                                                                                                                                                                                           |
| :---------- | :----------------------------------- | :- | :- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **视频/图片水印** | `/wmImage/&lt;EncodedKodoScheme&gt;` | V  | N  | 1、图片水印的源路径，目前支持 kodo 资源。kodo 资源可由 `kodo://&lt;bucketname&gt;/&lt;key&gt;` 表示（此时 bucketname 需要与输入源在同一区域），均需要经过 `urlsafe_base64_encode`。<br /> 2、支持的格式有：图片、部分动图（GIF、APNG）。<br />3、不支持和 `autoscale` 参数同时使用。                                                     |
|             | `/wmVideo/&lt;EncodedKodoScheme&gt;` | V  | N  | 1、视频水印的源路径，目前支持kodo 资源。kodo 资源可由 `kodo://&lt;bucketname&gt;/&lt;key&gt;` 表示（此时 bucketname 需要与输入源在同一区域），均需要经过 `urlsafe_base64_encode`。<br />2、不支持 HLS 格式的视频作为水印。<br />3、不支持和 `autoscale` 、`rotate` 参数同时使用。                                                    |
|             | `/wmScale/&lt;Scale&gt;`             | V  | N  | 指定图片或视频水印的短边、长边、宽、高与输入视频之间的比例，取值为(0,1]，默认值时不进行自适应缩放水印。                                                                                                                                                                                                       |
|             | `/wmScaleType/&lt;ScaleType&gt;`     | V  | N  | 选择图片或视频水印自适应缩放的方式，取值0、1、2、3分别表示为自适应原图的短边、长边、宽、高，默认值为0。                                                                                                                                                                                                       |
|             | `/wmVideoOrder/&lt;VideoOrder&gt;`   | V  | N  | 视频水印的排序方式，默认值0，表示自定义不改变。<br />1、值为1时，表示左右分割，其中视频水印以画中画形式作为正方形画布；<br />2、值为 2时，表示左右分割，并在1的基础上，对原视频根据视频水印的宽进行自适应缩放，并以黑边填充方式放置在左边。<br />3、取值为3，将原视频和水印视频左右分割，对原视频根据水印视频剩余空间进行拉伸填充；<br />4、取值为1、2、3时，原视频和水印视频会进行混音。                                              |
|             | `/wmConstant/&lt;Constant&gt;`       | V  | N  | 用于设置图片或视频水印是否随源视频 DAR（display aspect ratio）变化而产生形变，默认值为0。<br />1、值为 0 时，水印会随源视频 DAR 变化而产生形变；<br />2、值为 1 时，水印保持原有宽高比；<br />3、值为 2 时，在`wmVideoOrder`开启下，视频水印会根据wmScale的宽高作为画布，而进行自适应缩放(会产生黑边)；<br />4、为 3 时，在`wmVideoOrder`开启下，视频水印会根据wmScale的宽高作为画布，并以中心点剪裁。 |
|             | `/wmIgnoreLoop/&lt;WmIgnoreLoop&gt;` | V  | N  | 是否忽略水印动图的循环属性，可取值： `0（使用）`、`1（忽略）`，默认为1。                                                                                                                                                                                                                     |
| **文字水印**    | `/wmText/&lt;EncodedText&gt;`        | V  | N  | 水印文本内容,需要经过`urlsafe_base64_encode`。                                                                                                                                                                                                                          |
|             | `/wmAlpha/&lt;Alpha&gt;`             | V  | N  | 文字水印透明度。范围 (0.0,1.0]，越小越透明。默认值为1.0，即不透明。                                                                                                                                                                                                                     |
|             | `/wmFont/&lt;Font&gt;`               | V  | N  | 文本字体（详见支持[字体列表](/faq/dora/other-dora/1379-image-and-video-text-watermarking-support-font-list) ），需要经过`urlsafe_base64_encode`。存在`/wmText/`时生效。 注意：默认为方正黑体。                                                                                                    |
|             | `/wmFontStyle/&lt;fontStyle&gt;`     | V  | N  | 文本字体样式，（经过URL安全的Base64编码），默认为系统自动选择字体样式，详见支持[字体列表](/faq/dora/other-dora/1379-image-and-video-text-watermarking-support-font-list)。                                                                                                                           |
|             | `/wmFontColor/&lt;FontColor&gt;`     | V  | N  | 水印文字颜色，需要经过`urlsafe_base64_encode`，RGB格式，可以是颜色名称（例如red）或十六进制（例如#FF0000），参考[RGB颜色编码表](https://www.rapidtables.com/web/color/RGB_Color.html)。存在`/wmText/`时生效，默认为黑色。                                                                                            |
|             | `/wmBorderWidth/&lt;BorderWidth&gt;` | V  | N  | 水印文字描边宽度，单位：像素，取值范围\[0,4096]。                                                                                                                                                                                                                                |
|             | `/wmBorderColor/&lt;BorderColor&gt;` | V  | N  | 水印文字描边颜色，需要经过`urlsafe_base64_encode`，RGB格式，可以是颜色名称（例如red）或十六进制（例如 #FF0000），参考[RGB颜色编码表](https://www.rapidtables.com/web/color/RGB_Color.html)。存在`/wmText/`时生效，默认为黑色                                                                                          |
|             | `/wmFontSize&lt;FontSize&gt;`        | V  | N  | 水印文字大小，单位: px。存在`/wmText/`时生效，默认值为16px。                                                                                                                                                                                                                      |
| **水印位置**    | `/wmGravity/&lt;Gravity&gt;`         | V  | N  | 视频或者图片水印位置。存在 `/wmImage/ ` 或` /wmVideo/` 时生效，默认NorthEast。<br />水印锚点参数表如图所示：<br />![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb/20240919-152321-785c7e4c68c1.webp)                  |
|             | `/wmGravityText/&lt;GravityText&gt;` | V  | N  | 文本位置，存在`/wmText/`时生效，默认 NorthEast。<br />水印锚点参数表如图所示：<br />![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb/20240919-152321-785c7e4c68c1.webp)                                         |
|             | `/wmOffsetX/&lt;offsetX&gt;`         | V  | N  | 设置图片、文字、视频水印位置的相对横向偏移量，当值为正数时则向右偏移，反之向左。位置里包含West时，默认有+10的固定偏移，位置里包含East时，默认有-10的固定偏移，中间位置则固定偏移为0。                                                                                                                                                           |
|             | `/wmOffsetY/&lt;offsetY&gt;`         | V  | N  | 设置图片、文字、视频水印位置的相对纵向偏移量，当值为正数时则向下偏移，反之向上。位置里包含North时，默认有+10的固定偏移，位置里包含South时，默认有-10的固定偏移，中间位置则固定偏移为0。                                                                                                                                                         |
| **水印时间线**   | `/wmPos/&lt;Postion&gt;`             | V  | N  | 指定图片、文字、视频水印显示的起始时间，单位：秒，不填表示全时长。支持魔法变量`$(end)表示视频结束时间点`。<br />**注意**：<br />1、需要和wmDuration同时存在。<br />2、`wmVideoOrder`不为0且水印视频包含音频时，`wmPos` 值不能超过10000。                                                                                                      |
|             | `/wmDuration/&lt;Duration&gt;`       | V  | N  | 指定图片、文字、视频水印显示的持续时间，单位：秒，正数表示时间增长方向，负数表示时间递减方向。不填表示全时长。支持魔法变量`$(lte)`(小于wmPos的区间)、`$(gte)`(大于wmPos的区间)。**注意**：<br />1、需要和wmPos同时存在。                                                                                                                          |
|             | `/wmShortest/&lt;WmShortest&gt;`     | V  | N  | wmPos在视频duration内，在添加wmDuration后超出视频duration后是否自动调整wmDuration大小，1 调整到视频duration内，0 不处理, 默认为0。                                                                                                                                                                |

# **音频参数** [#音频参数]

| 分类            | 参数名称                                                    | 类别 | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                    |
| :------------ | :------------------------------------------------------ | :- | :- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **编码格式**      | `/acodec/&lt;AudioCodec&gt;`                            | A  | N  | 音频编码格式，具体细节请参考[支持转换的音频编码格式](/faq/dora/av-processing/1432-avthumb-parameter-acodec-format-and-explanation)。                                                                                                                                                                                                                                                                                            |
| **profile等级** | `/audioProfile/&lt;profile&gt;`                         | A  | N  | 设置音频的profile等级，支持：aac\_he。\*\*注：\*\*需配合 `libfdk_aac` 编码方案使用，如 `avthumb/m4a/acodec/libfdk_aac/audioProfile/aac_he`。                                                                                                                                                                                                                                                                                    |
| **码率控制**      | `/ab/&lt;BitRate&gt;`                                   | A  | N  | 1、音频码率，单位：比特每秒（bit/s），常用码率：64k，128k，192k，256k，320k等。<br /> 2、在不改变音频编码格式时，若指定码率大于原音频码率，则使用原音频码率进行转码。<br /> 3、参数末尾使用 `!`, 可以以强制使用指定码率转码, 如 64k!                                                                                                                                                                                                                                                         |
|               | `/aq/&lt;AudioQuality&gt;`                              | A  | N  | 1、音频质量，取值范围为0-9（mp3），10-500（aac），仅支持mp3和aac，值越小越高。<br /> 2、不能与上述`码率`参数共用。                                                                                                                                                                                                                                                                                                                             |
| **声道数**       | `/ac/&lt;ChannelNum&gt;`                                | A  | N  | 音频声道数量，单位：整数值。<br />1、输出声道数≤源文件声道数，取值范围：<br />● acodec 为 `libfdk_aac `时，支持的声道数量为 1、2、4、5、6、8；<br />● acodec 为 ` aac` 时，支持的声道数量为 1、2、3、4、5、6、7、8；<br />● acodec 为 ` libmp3lame` 时，支持的声道数量为 1、2。<br />2、输出声道数>源文件声道数，取值范围：<br />● acodec 为 `libfdk_aac ` 时，支持的声道数量为2；<br />● acodec 为 ` aac` 时，支持的声道数量为 2；<br />● acodec 为 ` libmp3lame` 时，支持的声道数量为 2。<br />其他数值不合法。                                    |
| **采样率**       | `/ar/&lt;SamplingRate&gt;`                              | A  | N  | 音频采样频率，单位：赫兹（Hz）。<br />1、acodec 为 `libfdk_aac `时，可使用的 `ar` 值为：96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000；<br />2、 acodec 为 `libmp3lame `时，可使用的`ar`值为：48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025；注意：当\<format>为mp4时，ar值不可小于16000；<br />3、acodec 为 `libspeex `时，可使用的`ar`值为：32000, 16000, 8000；<br />4、acodec 为 `libopencore_amrnb`时，可使用的`ar`值为：8000。 |
| **音频响应标准化**   | `/loudnorm/&lt;LoudNorm&gt;`                            | A  | N  | 1. 是否使用音频响度标准化调整，0为不使用，1为使用。默认值为0；<br />2. 不可与`volume`共用。<br />3. 为了更好的音质体验，可以结合 [音频降噪](/products/dora/quality%20enhancement/3-adenoise)一起使用。                                                                                                                                                                                                                                                         |
|               | `/loudnormI/&lt;LoudNormI&gt;`                          | A  | N  | 音频整体响度值，当 loudnorm 为1时有效，取值范围 \[-70.0, -5.0], 默认为 -24.0                                                                                                                                                                                                                                                                                                                                               |
|               | `/loudnormLRA/&lt;LoudNormLRA&gt;`                      | A  | N  | 音频响度范围，当 loudnorm 为1时有效， 取值范围 \[1.0, 20.0], 默认为 7.0                                                                                                                                                                                                                                                                                                                                                   |
|               | `/loudnormTP/&lt;LoudNormTP&gt;`                        | A  | N  | 音频最高峰值，当 loudnorm 为1时有效， 取值范围 \[-9.0, 0.0], 默认为 -2.0                                                                                                                                                                                                                                                                                                                                                  |
| **音量均衡**      | `/loudnormF/&lt;LoudNormF&gt;`                          | A  | N  | 单个文件存在音量忽大忽小时，设置片段时长大小（毫秒），当 loudnorm 为1时有效，取值范围 \[10, 8000]，取值越小拉平越明显，默认为 500。<br />1. 建议与 `loudnormG` 一起使用。<br />2. 为了更好的音质体验，可以结合 [音频降噪](/products/dora/quality%20enhancement/3-adenoise)一起使用。                                                                                                                                                                                                     |
|               | `/loudnormG/&lt;LoudNormG&gt;`                          | A  | N  | 单个文件存在音量忽大忽小时，设置平滑窗口大小（帧），当 loudnorm 为1时有效，取值范围为 \[3, 301]的奇数, 取值越小拉平越明显，默认为 31。<br />1. 建议与 `loudnormF` 一起使用。<br />2. 为了更好的音质体验，可以结合 [音频降噪](/products/dora/quality%20enhancement/3-adenoise)一起使用。                                                                                                                                                                                                    |
| **增强音频响度标准化** | `/loudnormRefine/&lt;LoudNormRefine&gt;`                | A  | N  | 是否使用增强音频响度标准化，0为不使用。<br />1为使用音质优先，2为使用响度优先。默认值为0。<br />推荐使用` loudnormRefine` 时不设置` loudnormLRA` 和` loudnormTP`。                                                                                                                                                                                                                                                                                      |
| **音频音量**      | `/volume/&lt;Volume&gt;`                                | A  | N  | 1、调整音频音量为原音频音量的倍数, 精确到小数点后2位 ，默认值为 1.0, 范围 \[0.01, 3]；<br /> 2、不可与`loudnorm` 共用。                                                                                                                                                                                                                                                                                                                      |
| **音频混音**      | `/amix/&lt;AmixURL&gt;`                                 | A  | N  | 1、期望混音的音视频文件，目前支持kodo 资源。 <br />2、kodo 资源可由 `kodo://&lt;bucketname&gt;/&lt;key&gt;` 表示（此时 bucketname 需要与输入源在同一区域），需要经过 `urlsafe_base64_encode`。<br /> 3、源音视频、混音输入音视频都仅支持单音轨；混音的两个音频的channel数必须一致。                                                                                                                                                                                                     |
|               | `/amixOffset/&lt;AmixOffset&gt;`                        | A  | N  | 混音效果起始位置，相对于混音后视频起始位置计算，单位为秒，精确到毫秒，默认取0，即混音后音视频从起始位置起有混音效果                                                                                                                                                                                                                                                                                                                                            |
|               | `/amixStart/&lt;AmixStart&gt;`                          | A  | N  | 目标混音文件截取的开始时间，单位为秒，精确到毫秒，默认取0，即目标混音文件从起始开始混入源音视频                                                                                                                                                                                                                                                                                                                                                      |
|               | `/amixDuration/&lt;AmixDuration&gt;`                    | A  | N  | 目标混音文件截取的时长，单位为秒，精确到毫秒，默认为目标混音文件音轨原始长度，即全部混入源音视频                                                                                                                                                                                                                                                                                                                                                      |
| **音频替换**      | `/multiArep/&lt;MultiAudioReplaceURL&gt;`               | A  | N  | 1、用于替换原视频中音频的目标音频文件。<br /> 2、目前支持 kodo 资源，kodo 资源可由 `kodo://&lt;bucketname&gt;/&lt;key&gt;` 表示（此时 bucketname 需要与输入源在同一区域），需要经过 `urlsafe_base64_encode`。<br /> 3、多个文件以英文逗号分隔。                                                                                                                                                                                                                          |
|               | `/multiArepOffset/&lt;MultiAudioReplaceOffset&gt;`      | A  | N  | 目标音频相对于原视频的起始位置，相对于原视频视频起始位置计算，单位为秒，精确到毫秒，默认取0，从结果视频的起始位置起有指定音频，多个文件以参数指定使用英文逗号分隔，且必须与multiArep文件顺序对应                                                                                                                                                                                                                                                                                                 |
|               | `/multiArepStart/&lt;MultiAudioReplaceStart&gt;`        | A  | N  | 目标音频文件截取的开始时间，单位为秒，精确到毫秒，默认取0，即目标音频文件从起始开始添加到原视频中，多个文件以参数指定使用英文逗号分隔，且必须与multiArep文件顺序对应                                                                                                                                                                                                                                                                                                               |
|               | `/multiArepDuration /&lt;MultiAudioReplaceDuration&gt;` | A  | N  | 目标音频文件截取的时长，单位为秒，精确到毫秒，默认为目标音频文件音轨原始长度，即全部目标音频替换原视频音频，多个文件以参数指定使用英文逗号分隔，且必须与multiArep文件顺序对应                                                                                                                                                                                                                                                                                                           |
| **支持speex文件** | `/speex/&lt;Speex&gt;`                                  | A  | N  | 取值为1时，把源音频文件作为微信版speex处理，版本为1.2rc1，不支持其他音频格式转speex。默认取值为0。                                                                                                                                                                                                                                                                                                                                            |
| **Xing信息**    | `/writeXing/&lt;Xing&gt;`                               | A  | N  | 转码成mp3时是否写入xing header，默认值为1，表示写入，写入会导致 `file`，`avinfo` 等命令识别出错误的码率。好处是在需要音频时长、帧数的时候只需要获取header。                                                                                                                                                                                                                                                                                                      |

# **字幕参数** [#字幕参数]

| **分类**   | **参数名称**                               | **类别** | **必填** | **说明**                                                                                                                                                                                                     |
| -------- | -------------------------------------- | ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **编码格式** | `/scodec/&lt;SubtitleCodec&gt;`        | V      | N      | 字幕编码方案，支持方案：`mov_text`。该参数仅用于修改带字幕视频的字幕编码。                                                                                                                                                                 |
| **添加字幕** | `/subtitle/&lt;SubtitleURL&gt;`        | S      | N      | 1、添加字幕，支持 srt 格式字幕（uft-8 编码和和 utf-8 BOM编码）、带有字幕的 mkv 文件、embed（将原视频的字幕流嵌入目标视频）。 2、目前支持 kodo 资源。kodo 资源可由 `kodo://&lt;bucketname&gt;/&lt;key&gt;` 表示（此时 bucketname 需要与输入源在同一区域），需要经过 `urlsafe_base64_encode` |
| **字幕字体** | `/stFont/&lt;SubtitleFont&gt;`         | S      | N      | 设置字幕的字体，详见支持[字体列表](/faq/dora/other-dora/1379-image-and-video-text-watermarking-support-font-list) ，需要经过 urlsafe\_base64\_encode。                                                                           |
| **字幕大小** | `/stFontSize/&lt;SubtitleFontSize&gt;` | S      | N      | 设置字幕文字大小。取值为整数，范围 （0,280]，单位：磅。                                                                                                                                                                            |
| **字幕位置** | `/stOffsetX/&lt;SubtitleOffsetX&gt;`   | S      | N      | 设置字幕的左右位置。<br />默认值为居中，取值为整数，值大于0时向右偏移，小于0时向左偏移，单位：px。                                                                                                                                                     |
| **字幕高度** | `/stOffsetY/&lt;SubtitleOffsetY&gt;`   | S      | N      | 设置字幕的高度，与地底边框之间的距离。<br />默认值为10px。 取值为整数，范围 (0,280]，单位：px。                                                                                                                                                 |

# **转码条件参数** [#转码条件参数]

| 分类         | 参数名称                                   | 类别 | 必填 | 说明                                                                                                          |
| ---------- | -------------------------------------- | -- | -- | ----------------------------------------------------------------------------------------------------------- |
| **分辨率宽**   | `/limitWidth/&lt;LimitWidth&gt;`       | V  | N  | 设置分辨率宽作为条件来判断的是否转码(编码)，格式：Width\< 或 Width>。示例：设置为 /limitWidth/1080\< 时，即源视频的宽小于1080，进行转码。                   |
| **分辨率高**   | `/limitHeight/&lt;LimitHeight&gt;`     | V  | N  | 设置分辨率高作为条件来判断的是否转码(编码)，格式：Height\< 或 Height>。示例：设置为 /limitHeight/720\< 时，即源视频的宽小于720，进行转码。                  |
| **视频文件大小** | `/limitSize/&lt;LimitSize&gt;`         | V  | N  | 设置视频文件大小作为条件来判断的是否转码(编码)，格式：Size\< 或 Size>，单位：KB。示例：设置为/limitSize/10> 时，即源视频的文件大于10KB，进行转码。                 |
| **视频时长**   | `/limitDuration/&lt;LimitDuration&gt;` | V  | N  | 设置视频时长作为条件来判断的是否转码(编码)， 格式：Duration\< 或 Duration>，单位：秒（精确到毫秒）。示例：设置为 /limitDuration/90>时，即源视频的时长大于90s，进行转码。 |

# **音视频转封装** [#音视频转封装]

* 当`<VideoCodec>`和`<AudioCodec>`值同时为`copy`，不进行音视频编解码操作，即音视频转封装。以音视频装封装计费。

# **操作方式** [#操作方式]

您可以通过以下几种方式来创建任务：

### **方式一：使用任务触发器** [#方式一使用任务触发器]

* `对符合规则策略的上传文件自动触发`：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 [任务触发器](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/1-tigger)；创建完成后，需要开启 **上传触发开关**，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb/20240924-104416-84b0fd76e29a.webp)

### **方式二：使用[对象存储控制台](https://portal.qiniu.com/kodo/bucket)** [#方式二使用对象存储控制台]

* `上传文件手动触发`：在具体空间下， [上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file) 时，指定工作流模板 。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb/20240924-104626-b4de95907ff6.webp)

* `指定文件手动触发`：有两种指定单个文件创建任务的入口

  * 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

    ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb/20240924-104912-8de5e60349e1.webp)

```
注意：仅对音视频/gif动图/webp动图文件提供该操作。
```

* 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb/20240924-104746-36342fe1033e.webp)

### **方式三：使用API** [#方式三使用api]

* `资源上传时手动触发`：可以在构造[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)时在[上传策略](/products/kodo/development-guidelines/security/1-put-policy)中，设置相关字段，在资源文件上传时触发处理。
* `对已有资源手动触发`：可以在调用 [持久化数据处理(pfop)](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 时，设置相关字段，对已存在空间中的资源文件发起处理。

### **方式四：使用SDK** [#方式四使用sdk]

* 查看各语言 SDK 使用指南中 `持久化数据处理`  章节，可在[七牛官方SDK](/sdk-tools/sdk) 进行下载。

# **操作示例** [#操作示例]

## **使用API** [#使用api]

* 以 `资源上传时手动触发` 形式，将wav音频转换为mp3格式，音频码率为192k：

  ```
  {
        "scope":                "qiniu-ts-demo:sample.wav",
        "deadline":             1390528576,
        "persistentOps":        "avthumb/mp3/ab/192k",
        "persistentNotifyUrl":  "http://fake.com/qiniu/notify"
    }
  ```

* 以 `对已有资源手动触发` 形式，将mp4视频进行锐智转码（即视频瘦身），设置视频编码格式为libx264，分辨率为1920x1080，生成文件名为为`sample_target.mp4`的视频资源：

  ```
  POST /pfop/ HTTP/1.1
  Host: api.qiniu.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Qiniu <AccessToken>

  bucket=qiniu-ts-demo
  &key=thinking-in-go.mp4
  &fops=avthumb/mp4/vcodec/libx264/s/1920x1080/avsmart/1/smtQuality/4|saveas/dGVzdDpzYW1wbGVfdGFyZ2V0Lm1wNA==&notifyURL=http%3A%2F%2Ffake.com%2Fqiniu%2Fnotify
  &notifyURL=http%3A%2F%2Ffake.com%2Fqiniu%2Fnotify
  ```

## **使用SDK** [#使用sdk]

**以Python Sdk为例**

* 在 `文件上传时触发` ，本例中将上传的视频转码为MP4的视频文件，保存到`目标Bucket_Name`,且文件名为`自定义文件key`，原上传视频保存到`bucket_name`空间，且文件名为`key`。

```
from qiniu import Auth, put_file, etag, urlsafe_base64_encode
import qiniu.config

# access_key，secret_key在个人面板的密钥管理处获得，非个人账号密码
access_key = '...'
secret_key = '...'

# 初始化Auth状态
q = Auth(access_key, secret_key)

# 你要测试的空间， 并且这个key在你空间中存在
bucket_name = '...'
key = '...'

# 是使用的队列名称,不设置代表不使用私有队列，使用公有队列。
pipeline = 'your_pipeline'

# 设置转码参数
fops = 'avthumb/mp4/vcodec/libx264'

# 通过添加'|saveas'参数，指定处理后的文件保存的bucket和key，不指定默认保存在当前空间，bucket_saved为目标bucket，bucket_saved为目标key
saveas_key = urlsafe_base64_encode('bucket_saved:bucket_saved')

fops = fops+'|saveas/'+saveas_key

# 在上传策略中指定fobs和pipeline
policy={
  'persistentOps':fops,
  'persistentPipeline':pipeline
 }

token = q.upload_token(bucket_name, key, 3600, policy)

# 视频所在的本地路径
localfile = './python_video.flv'

ret, info = put_file(token, key, localfile)
print(info)
assert ret['key'] == key
assert ret['hash'] == etag(localfile)
```

* 对`已有资源手动触发`，本例将空间名为`bucket_name`中的视频 `key`转码为MP4的视频文件，并且保存到`目标Bucket_Name`,且文件名为`自定义文件key`。

```
from qiniu import Auth, PersistentFop, build_op, op_save, urlsafe_base64_encode

# 对已经上传到七牛的视频发起异步转码操作
# access_key，secret_key在个人面板的密钥管理处获得，非个人账号密码
access_key = '...'
secret_key = '...'
q = Auth(access_key, secret_key)

# 要转码的文件所在的空间和文件名。
bucket_name = '...'
key = '...'

# 是使用的队列名称,不设置代表不使用私有队列，使用公有队列。
pipeline = 'your_pipeline'

# 要进行转码的转码操作。
fops = 'avthumb/mp4/s/640x360/vb/1.25m'

# 可以对转码后的文件进行使用saveas参数自定义命名，当然也可以不指定文件会默认命名并保存在当前空间
saveas_key = urlsafe_base64_encode('目标Bucket_Name:自定义文件key')
fops = fops+'|saveas/'+saveas_key

pfop = PersistentFop(q, bucket_name, pipeline)
ops = []
ops.append(fops)
ret, info = pfop.execute(key, ops, 1)
print(info)
assert ret['persistentId'] is not None

```

# **计费说明** [#计费说明]

#### **转码费用计算公式** [#转码费用计算公式]

* 转码费用 = 输出文件时长 x 转码单价，价格单位： 元／分钟。
* 输出时长：对于每月转码输出文件，按分钟计费，累计总时长不足一分钟不计费
* 输出规格按输出视频分辨率的长边和短边属于输出规格划定的范围进行判定，以普通转码输出HD (1920 x 1080) 规格为例：
  * 输出视频的分辨率长边不大于1920且短边不大于1080，则属于HD输出规格。
  * 输出视频的长边大于1920或输出视频的短边大于1080，该属于更高输出规格。

#### **特定参数计费模式，**[价格参见](https://www.qiniu.com/prices/dora?source=dora) [#特定参数计费模式价格参见]

1. 使用 avthumb 命令时，当 `VideoCodec` 和` AudioCodec` 两个参数值同时设为 copy，服务收费=`音视频转封装价格`。
2. 使用 avthumb 命令时，且不启用锐智转码，当视频实际处理帧率在`(30, 60]`时，服务收费= `普通转码高帧率价格` 。[价格参见](https://www.qiniu.com/prices/dora?source=dora)。
3. 使用 avthumb 命令时，且启用锐智转码，即使用 `avsmart `参数，与普通音视频转码计费有区别，服务价格=`锐智转码价格`。
4. 使用 avthumb 命令时，且同时启用GPU转码，即使用`prehw` 参数，当前公测阶段，GPU转码收费跟`普通转码价格`一样，后续可能会调整价格。
5. 使用 avthumb 命令时，且同时启用SDR转HDR，即使用 `hdr` 参数，服务价格=`SDR to HDR 价格`。
6. 使用 avthumb 命令时，不设置分辨率参数（ `s` ）、或帧率相关参数，那么计费会默认跟随源视频的特性。
   * 示例1：转码不设置分辨率，源视频分辨率为1920\*1080，则计费会按 HD 规格计费；
   * 示例2：转码不设置帧率相关参数，源视频帧率为50，则计费会按高帧计费；

#### **注意** [#注意]

七牛云的数据处理API均支持[管道](/products/dora/processing-mechanism/3-the-pipe)，通过管道操作符 `\|` 实现串行处理，即将一个资源经由多个 `&lt;fop&gt;` 串行处理。

处理规格如下：

```
<fop1>|<fop2>|<fop3>|<fopN>
```

* `<fop>` (File Operation的缩写)，表示数据处理指令及其所需要的参数。
* 整个串行处理中，只要有处理成功的 `fop`，就会有相应的计量计费。


# 私有M3U8（pm3u8） (/products/dora/audio-and-video-processing-api/4-private-m3u8-pm3u8)



最近更新时间: 2024-07-24 16:28:32

# **简介** [#简介]

`pm3u8` 接口，只能用于私有空间中的 m3u8 文件，作用是对 m3u8文件中的 ts 资源进行批量下载授权。通过将 ts 资源的 url 改写成私有 url，以临时获取访问权限。

# **接口规格** [#接口规格]

```
pm3u8/<Mode>
         /expires/<Expires>
        /deadline/<Deadline>
```

| 参数名称                         | 必填 | 说明                                                         |
| :--------------------------- | :- | :--------------------------------------------------------- |
| `/&lt;Mode&gt;`              | 是  | 处理模式，只有一个值0。<br />0表示对所有ts资源的url进行下载授权。                    |
| `/query/&lt;Query&gt;`       |    | 私有ts资源url下载 query 展示，参数值需要经过 `urlsafe_base64_encode`。      |
| `/expires/&lt;Expires&gt;`   |    | 私有ts资源url下载凭证的相对有效期，单位秒。<br />推荐43200秒（12小时）。              |
| `/deadline/&lt;Deadline&gt;` |    | 私有ts资源url下载凭证的绝对有效期(Unix Time)，单位秒。<br />此参数填写后，expires失效。 |

<a id="pm3u8-request-syntax" />

# **操作方式** [#操作方式]

可以通过[同步处理](/products/dora/processing-mechanism/2-synchronous-processing)的方式来调用。即在访问文件URL时，添加一个或多个数据处理指令，以直接获取处理后的结果。

# **示例** [#示例]

原始m3u8链接与内容如下所示：

```
http://7xoucz.com1.z0.glb.clouddn.com/qiniutest.m3u8?e=1449116672&token=GeKdDZhpPh6rxoVNCSrvygimGSdH7jOUvalFGZrp:JCrhZN1XbkSeNBucKRzmx3R-kzY=

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-ALLOW-CACHE:YES
#EXT-X-TARGETDURATION:62
#EXTINF:61.120000,
http://7xoucz.com1.z0.glb.clouddn.com/7ZZYqVpgENDWOEdpmCR3Eg9Rdig=/lhsawSRA9-0L8b0s-cXmojaMhGqn/000000.ts
#EXTINF:59.360000,
http://7xoucz.com1.z0.glb.clouddn.com/7ZZYqVpgENDWOEdpmCR3Eg9Rdig=/lhsawSRA9-0L8b0s-cXmojaMhGqn/000001.ts
#EXTINF:59.640000,
http://7xoucz.com1.z0.glb.clouddn.com/7ZZYqVpgENDWOEdpmCR3Eg9Rdig=/lhsawSRA9-0L8b0s-cXmojaMhGqn/000002.ts
#EXTINF:2.480000,
http://7xoucz.com1.z0.glb.clouddn.com/7ZZYqVpgENDWOEdpmCR3Eg9Rdig=/lhsawSRA9-0L8b0s-cXmojaMhGqn/000003.ts
#EXT-X-ENDLIST
```

对m3u8资源进行私有资源下载授权时指定`pm3u8`接口，可以获取到相应的批量授权下载URL：

```
http://7xoucz.com1.z0.glb.clouddn.com/qiniutest.m3u8?pm3u8/0&e=1449126571&token=GeKdDZhpPh6rxoVNCSrvygimGSdH7jOUvalFGZrp:SGhJE2aC685_YmHMOtJEngduFes=

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-ALLOW-CACHE:YES
#EXT-X-TARGETDURATION:62
#EXTINF:61.120000,
http://7xoucz.com1.z0.glb.clouddn.com/7ZZYqVpgENDWOEdpmCR3Eg9Rdig=/lhsawSRA9-0L8b0s-cXmojaMhGqn/000000.ts?e=1449166183&token=GeKdDZhpPh6rxoVNCSrvygimGSdH7jOUvalFGZrp:ejpJ9vAKYYK1ZSpW6z3uS2pGBlo
#EXTINF:59.360000,
http://7xoucz.com1.z0.glb.clouddn.com/7ZZYqVpgENDWOEdpmCR3Eg9Rdig=/lhsawSRA9-0L8b0s-cXmojaMhGqn/000001.ts?e=1449166183&token=GeKdDZhpPh6rxoVNCSrvygimGSdH7jOUvalFGZrp:Ufr6wcVrUmY7jr8IpRH2fkCo2G0
#EXTINF:59.640000,
http://7xoucz.com1.z0.glb.clouddn.com/7ZZYqVpgENDWOEdpmCR3Eg9Rdig=/lhsawSRA9-0L8b0s-cXmojaMhGqn/000002.ts?e=1449166183&token=GeKdDZhpPh6rxoVNCSrvygimGSdH7jOUvalFGZrp:SfGPTw3-5MGJQk1xN6dECELKjwQ
#EXTINF:2.480000,
http://7xoucz.com1.z0.glb.clouddn.com/7ZZYqVpgENDWOEdpmCR3Eg9Rdig=/lhsawSRA9-0L8b0s-cXmojaMhGqn/000003.ts?e=1449166183&token=GeKdDZhpPh6rxoVNCSrvygimGSdH7jOUvalFGZrp:vriMgesiM95izCCRUrfAMT3bdVs
#EXT-X-ENDLIST
```

对m3u8资源进行私有资源下载授权并`设置query值`时，指定pm3u8接口，可以获取到相应的批量授权下载URL：

```
http://7xoucz.com1.z0.glb.clouddn.com/qiniutest.m3u8?pm3u8/0/query/azE9djEmazI9djImazM9djM=&e=1449126571&token=GeKdDZhpPh6rxoVNCSrvygimGSdH7jOUvalFGZrp:SGhJE2aC685_YmHMOtJEngduFes=

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-ALLOW-CACHE:YES
#EXT-X-TARGETDURATION:62
#EXTINF:61.120000,
http://7xoucz.com1.z0.glb.clouddn.com/7ZZYqVpgENDWOEdpmCR3Eg9Rdig=/lhsawSRA9-0L8b0s-cXmojaMhGqn/000000.ts?k1=v1&k2=v2&k3=v3&e=1449166183&token=GeKdDZhpPh6rxoVNCSrvygimGSdH7jOUvalFGZrp:ejpJ9vAKYYK1ZSpW6z3uS2pGBlo
#EXTINF:59.360000,
http://7xoucz.com1.z0.glb.clouddn.com/7ZZYqVpgENDWOEdpmCR3Eg9Rdig=/lhsawSRA9-0L8b0s-cXmojaMhGqn/000001.ts?k1=v1&k2=v2&k3=v3&e=1449166183&token=GeKdDZhpPh6rxoVNCSrvygimGSdH7jOUvalFGZrp:Ufr6wcVrUmY7jr8IpRH2fkCo2G0
#EXTINF:59.640000,
http://7xoucz.com1.z0.glb.clouddn.com/7ZZYqVpgENDWOEdpmCR3Eg9Rdig=/lhsawSRA9-0L8b0s-cXmojaMhGqn/000002.ts?k1=v1&k2=v2&k3=v3&e=1449166183&token=GeKdDZhpPh6rxoVNCSrvygimGSdH7jOUvalFGZrp:SfGPTw3-5MGJQk1xN6dECELKjwQ
#EXTINF:2.480000,
http://7xoucz.com1.z0.glb.clouddn.com/7ZZYqVpgENDWOEdpmCR3Eg9Rdig=/lhsawSRA9-0L8b0s-cXmojaMhGqn/000003.ts?k1=v1&k2=v2&k3=v3&e=1449166183&token=GeKdDZhpPh6rxoVNCSrvygimGSdH7jOUvalFGZrp:vriMgesiM95izCCRUrfAMT3bdVs
#EXT-X-ENDLIST
```

**注意**:ts资源的原始下载URL必须以`http://`打头。


# 视频单帧缩略图（vframe） (/products/dora/audio-and-video-processing-api/5-video-frame-thumbnails-vframe)



最近更新时间: 2026-08-18 15:25:22

# **简介** [#简介]

视频单帧缩略图接口(vframe)用于从视频流中截取指定时刻的单帧画面并按指定大小缩放成图片。

<a id="specification" />

# **参数说明** [#参数说明]

```
vframe/<Format>
      /offset/<Second>
      /w/<Width>
      /h/<Height>
      /rotate/<Degree>
```

| 参数名称                     | 必填 | 说明                                             |
| :----------------------- | :- | :--------------------------------------------- |
| `&lt;Format&gt;`         | 是  | 输出的目标截图格式，支持`jpg`、`png`等。                      |
| `/offset/&lt;Second&gt;` | 是  | 指定截取视频的时刻，单位：秒，精确到毫秒。                          |
| `/w/&lt;Width&gt;`       | 否  | 缩略图宽度，单位：像素（px）                                |
| `/h/&lt;Height&gt;`      | 否  | 缩略图高度，单位：像素（px）                                |
| `/rotate/&lt;Degree&gt;` | 否  | 指定顺时针旋转的度数，可取值为`90`、`180`、`270`、`auto`，默认为不旋转。 |

**注意：**
1、当指定`w`而不指定`h`时，缩略图的高度将等比缩放；当指定`h`而不指定`w`时，缩略图的宽度将等比缩放。
2、`w` 与 `h` 中，长边取值范围 \[20,3840]，短边取值范围 \[20,2160]。

# **操作方式** [#操作方式]

您可以通过以下几种方式来创建任务：

### **方式一：视频访问链接?参数** [#方式一视频访问链接参数]

* 即通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing) 的方式，即在访问文件URL时，添加数据处理指令，以直接获取处理后的结果。

### **方式二：使用任务触发器** [#方式二使用任务触发器]

* `对符合规则策略的上传文件自动触发`：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 [任务触发器](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/1-tigger)；创建完成后，需要开启 **上传触发开关**，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/5-video-frame-thumbnails-vframe/20240924-104416-84b0fd76e29a.webp)

### **方式三：使用[对象存储控制台](https://portal.qiniu.com/kodo/bucket)** [#方式三使用对象存储控制台]

* `上传文件手动触发`：在具体空间下， [上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file) 时，指定工作流模板 。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/5-video-frame-thumbnails-vframe/20240924-104626-b4de95907ff6.webp)

* `指定文件手动触发`：有两种指定单个文件创建任务的入口

  * 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

    ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/5-video-frame-thumbnails-vframe/20240924-104912-8de5e60349e1.webp)

```
注意：仅对音视频/gif动图/webp动图文件提供该操作。
```

* 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/5-video-frame-thumbnails-vframe/20240924-104746-36342fe1033e.webp)

### **方式四：使用API** [#方式四使用api]

* `资源上传时手动触发`：可以在构造[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)时在[上传策略](/products/kodo/development-guidelines/security/1-put-policy)中，设置相关字段，在资源文件上传时触发处理。
* `对已有资源手动触发`：可以在调用 [持久化数据处理(pfop)](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 时，设置相关字段，对已存在空间中的资源文件发起处理。

### **方式五：使用SDK** [#方式五使用sdk]

* 查看各语言 SDK 使用指南中 `持久化数据处理`  章节，可在[七牛官方SDK](/sdk-tools/sdk) 进行下载。

<a id="samples" />

# **操作示例** [#操作示例]

取视频第7秒的截图，图片格式为jpg，宽度为480px，高度为360px：

[资源上传时手动触发]()：上传的`token`中指定`persistentOps`

```
{
      "scope":                "qiniu-ts-demo:thinking-in-go.mp4",
      "deadline":             1390528576,
      "persistentOps":        "vframe/jpg/offset/7/w/480/h/360",
      "persistentNotifyUrl":  "http://fake.com/qiniu/notify"
}
```

[对已有资源手动触发]()：

```
POST /pfop/ HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>

bucket=qiniu-ts-demo
&key=thinking-in-go.mp4
&fops=vframe%2fjpg%2foffset%2f7%2fw%2f480%2fh%2f360
```

# **计费说明** [#计费说明]

视频单帧缩略图，以 **截取图片总张数** 来计量计费。服务价格=视频截图价格，定价参考 [智能多媒体服务定价](https://www.qiniu.com/prices/dora) 。


# 视频采样缩略图（vsample） (/products/dora/audio-and-video-processing-api/6-video-sampling-thumbnails-vsample)



最近更新时间: 2026-08-18 15:25:04

# **简介** [#简介]

视频采样缩略图接口(vsample)用于从视频文件中截取多帧画面并按指定大小缩放成图片。

<a id="video-sample-specification" />

# **参数说明** [#参数说明]

```
vsample/<Format>
       /ss/<StartTime>
       /t/<Duration>
       /s/<Resolution>
       /rotate/<Degree>
       /interval/<Interval>
       /frames/<Frames>
       /savePattern/<savePattern>
```

| 参数名称                                                              | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| :---------------------------------------------------------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="video-sample-format" />`&lt;Format&gt;`                    | 是  | 输出的目标截图格式，支持`jpg`、`png`等。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| <a id="video-sample-starttime" />`/ss/&lt;StartTime&gt;`          |    | 指定截取视频的开始时刻，单位：秒,精度为 100ms，例如 `/ss/1.1`；默认从片头开始。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| <a id="video-sample-duration" />`/t/&lt;Duration&gt;`             |    | 采样总时长，单位：秒,精度为 100ms，例如 `t/1.1`；默认表示到片尾结束。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| <a id="video-sample-resolution" />`/s/&lt;Resolution&gt;`         |    | 0. 指定截图分辨率，格式为宽 x 高 ，长边取值范围\[20,3840]的整数，短边取值范围\[20,2160]的整数。<br />1. 宽、高都为空时，则和原视频保持一致<br />2. 宽为空，高不为空，则按高的值对原视频等比例缩放<br />3. 宽不为空，高为空时，则按宽的值对原视频等比例缩放<br />4. 宽、高都不为空时，则根据宽、高来缩放                                                                                                                                                                                                                                                                                                                                                                                                                     |
| <a id="video-sample-rotate" />`/rotate/&lt;Degree&gt;`            |    | 指定顺时针旋转的度数，可取值为`90`、`180`、`270`、`auto`。<br />默认为不旋转。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| <a id="video-sample-interval" />`/interval/&lt;Interval&gt;`      |    | 指定截帧间隔时间，单元：秒。<br />默认为5秒,精度为 100ms，例如`/interval/0.1`指定平均截帧，截取的图片数量。 例如`/frames/1`。 <br />&#x2A;*注意：**<br />1. 和 `frames` 参数不能同时设置。<br />2. `frames`  和 `interval` 都不指定的情况，默认使用 `interval`。                                                                                                                                                                                                                                                                                                                                                                                                             |
| `/frames/&lt;Frames&gt;`                                          |    | 指定平均截帧，截取的图片数量。 例如`/frames/10`，截取10张图片。 <br />&#x2A;*注意：**<br />1. 和 `interval` 参数不能同时设置。<br />2. `frames`  和 `interval` 都不指定的情况，默认使用 `interval`。<br />3. 当设置`frames` 值大于源视频帧数时，会按照源视频最大帧数来输出。<br />4. 建议截帧帧率是视频帧率的整数倍。                                                                                                                                                                                                                                                                                                                                                                                 |
| <a id="video-sample-pattern" />`/savePattern/&lt;savePattern&gt;` | 是  | 指定各张截图的资源名格式，需要对设定值做[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。<br />**命名支持使用变量**：<br />1. 可以使用 `$(变量名)`或`${变量名}` 形式求值，魔法变量使用说明，参考 文件名变量 。<br />2. 注意：`$(count)`为必填项，必须存在的六位占位符数字串。<br /><br />**示例**：<br />源文件名：`input.mp4`，cmd为：`vsample/jpg/ss/7/t/600/s/480x360/savePattern/JChrZXliYXNlKSQoY291bnQpLmpwZw==`，其中 `JChrZXliYXNlKSQoY291bnQpLmpwZw==` ，是自定义截图后的文件名， $(keybase)$(count).jpg 的[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。最后得到类似：input000000.jpg,input000001.jpg,……,input000006.jpg 跟源文件命名是关联的的截图文件。<br /> |

# **操作方式** [#操作方式]

您可以通过以下几种方式来创建任务：

### **方式一：使用任务触发器** [#方式一使用任务触发器]

* `对符合规则策略的上传文件自动触发`：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 [任务触发器](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/1-tigger)；创建完成后，需要开启 **上传触发开关**，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/6-video-sampling-thumbnails-vsample/20240924-104416-84b0fd76e29a.webp)

### **方式二：使用[对象存储控制台](https://portal.qiniu.com/kodo/bucket)** [#方式二使用对象存储控制台]

* `上传文件手动触发`：在具体空间下， [上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file) 时，指定工作流模板 。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/6-video-sampling-thumbnails-vsample/20240924-104626-b4de95907ff6.webp)

* `指定文件手动触发`：有两种指定单个文件创建任务的入口

  * 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

    ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/6-video-sampling-thumbnails-vsample/20240924-104912-8de5e60349e1.webp)

```
注意：仅对音视频/gif动图/webp动图文件提供该操作。
```

* 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/6-video-sampling-thumbnails-vsample/20240924-104746-36342fe1033e.webp)

### **方式三：使用API** [#方式三使用api]

* `资源上传时手动触发`：可以在构造[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)时在[上传策略](/products/kodo/development-guidelines/security/1-put-policy)中，设置相关字段，在资源文件上传时触发处理。
* `对已有资源手动触发`：可以在调用 [持久化数据处理(pfop)](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 时，设置相关字段，对已存在空间中的资源文件发起处理。

### **方式四：使用SDK** [#方式四使用sdk]

* 查看各语言 SDK 使用指南中 `持久化数据处理`  章节，可在[七牛官方SDK](/sdk-tools/sdk) 进行下载。

# **操作示例** [#操作示例]

**示例1**

以 [资源上传时手动触发]()，取视频第7秒到第607秒之间，以5秒为间隔的截图（即第7秒、第12秒、第17秒……依此类推），图片格式为jpg，宽度为480px，高度为360px，文件命名模板为` $(keybase) $(count).jpg`：

上传的`token`中指定`persistentOps`

```
{
"scope":                "qiniu-ts-demo:thinking-in-go.mp4",
"deadline":             1390528576,
"persistentOps":      "vsample/jpg/ss/7/t/600/s/480x360/savePattern/JChrZXliYXNlKSAkKGNvdW50KS5qcGc=",
"persistentNotifyUrl":  "http://fake.com/qiniu/notify"
}
```

**示例2**

以 [对已有资源手动触发]()  形式，将一段视频，平均截帧成8张图片，图片宽高和原图保持一致，图片格式为png：

通过 `workflowTemplateID` 字段，指定工作流模板（仅支持V1版本工作流）

```
POST /pfop/ HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>

bucket=qiniu-ts-demo&key=thinking-in-go.mp4&workflowTemplateID=vsample&notifyURL=http://fake.com/qiniu/notify
```

# **计费说明** [#计费说明]

视频采样缩略图，以 **截取图片总张数** 来计量计费。比如视频截取了100张小图，则最终计量是100次。服务价格=视频截图价格，定价参考 [智能多媒体服务定价](https://www.qiniu.com/prices/dora) 。


# 音视频切片（HLS） (/products/dora/audio-and-video-processing-api/7-audio-and-video-slice)



最近更新时间: 2026-08-18 15:24:25

# **简介** [#简介]

音视频切片接口，用于支持[HTTP Live Streaming](https://developer.apple.com/streaming/)播放。HTTP Live Streaming 是由 Apple 提出的基于 HTTP 的流媒体传输协议。它将一整个音频、视频流切割成可由 HTTP 下载的一个个小的音视频流，并生成一个 M3U8 播放列表，客户端只需要获取资源的 M3U8 播放列表即可播放音视频。以下用 HLS 代指 HTTP Live Streaming。

# **参数说明** [#参数说明]

```
avthumb/m3u8 或 hls
            /...
            /noDomain/<NoDomain>
            /domain/<Domain>
            /segtime/<SegSeconds>
            /segFirstTime/<SegSeconds>
            /hlsKey/<HLSKey>
            /hlsKeyType/<HLSKeyType>
            /hlsKeyUrl/<HLSKeyUrl>
            /hlsIVType/<HLSIVType>
            /hlsIV/<HLSIV>
            /hlsDurationModify/<HLSDurationModify>
            /multiAudio/<MultiAudio>
            /segmentType/<SegmentType>
            /segmentInit/<SegmentInit>
            /savePattern/<savePattern>
```

| 参数名称                                           | 类别  | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| :--------------------------------------------- | :-- | :- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `&lt;Format&gt;`                               | A/V | 是  | 输出音视频切片格式，可设置为 `m3u8` 或 `hls`。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `...`                                          | A/V |    | 音频视频切片要使用其他转码参数，请参考 [音视频转码(avthumb)](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `/noDomain/&lt;NoDomain&gt;`                   | A/V |    | 取值 0 或 1，默认为 0，**推荐取值为 1**。表示切片索引中的切片列表，是否使用相对地址，设置为 0 则使用绝对地址，设置为 1 则使用相对地址。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `/domain/&lt;Domain&gt;`                       | A/V |    | 指定ts文件域名、基于base64编码。<br />**注意**：不可与 noDomain/1 同时使用。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `/segtime/&lt;SegSeconds&gt;`                  | A/V |    | 用于 HLS 自定义每一小段视频流及其包含的音频流的播放时间长度，取值范围为: 2 - 120（秒），默认值为 10秒。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `/segFirstTime/&lt;SegSeconds&gt;`             | A/V |    | 用于 HLS 自定义第一段音/视频流的播放时间长度，取值范围为: 1 - 120 （秒）<br />不设置时，第一段ts长度默认遵循 segtime。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `/hlsKey/&lt;HLSKey&gt;`                       | A/V |    | AES128加密视频的秘钥，必须是16个字节。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `/hlsKeyType/&lt;HLSKeyType&gt;`               | A/V |    | 密钥传递给我们的方式，0或不填。1.x(1.0, 1.1, ...)：见下面详细解释。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `/hlsKeyUrl/&lt;HLSKeyUrl&gt;`                 | A/V |    | 密钥的访问ur                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `/hlsIVType/&lt;HLSIVType&gt;`                 | A/V |    | 默认值为 0，使用系统生成的动态 iv 值；值为 1 时，必须使用 hlsIV 指定的固定 iv 值。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `/hlsIV/&lt;HLSIV&gt;`                         | A/V |    | 指定的固定 iv 值，使用 base64\_urlsafe 编码，编码前长度必须为 16 个字节。只有 hlsIVType 为 1 值，才可使用该参数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `/hlsDurationModify/&lt;HLSDurationModify&gt;` | A/V |    | vcodec 方式为 copy 的情况下，是否修正 m3u8 中记录的切片文件时长；可选值为 0 或者 1，当选择为 1 时，计算真实的切片 duration，而不是根据估计帧率计算出的时长；建议运用在视频帧率不稳定的情况。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `/multiAudio/&lt;MultiAudio&gt;`               | A/V |    | 指定支持多音轨，默认为 0，若存在多音轨，则输出只含第一条音轨，置 1 后将保留所有音轨，对于有多条音轨的源视频，本参数会让输出改变。**注意**，与 `segmentType/fmp4` 、 `domain`、`pattern` 参数不兼容。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `/segmentType/&lt;SegmentType&gt;`             | A/V |    | 指定分片的格式，支持 mpegts 与 fmp4，默认为 mpegts。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `/segmentInit/&lt;SegmentInit&gt;`             | A/V |    | 当分片格式为 fmp4 时，指定初始化文件的名称，也即由 EXT-X-MAP 指定的 URI 名称，需要 base64\_urlsafe 编码。**注意**，使用该参数指定的输出文件的文件名后缀如果不是输出文件的真实格式，可能使某些媒体播放器不兼容。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `/savePattern/&lt;savePattern&gt;`             | A/V |    | 为各音视频流ts文件自定义命名。<br />因为一整段音视频流音视频切片后会生成一个M3U8播放列表和多个音视频流ts文件。<br />**命名支持使用变量**：<br />1. 可以使用 `$(变量名)`或`${变量名}` 形式求值，魔法变量使用说明，参考 [文件名变量](/products/dora/1-features_introduction) 。<br />2. 注意：`$(count)`为必填项，必须存在的六位占位符数字串。<br /><br />**示例**：<br />输出的m3u8文件名为：`output.m3u8`，cmd为：`avthumb/m3u8/noDomain/1/savePattern/JHtzYXZlYXMua2V5UHJlZml4fSR7Y291bnR9LnRz` ，其中 `JHtzYXZlYXMua2V5UHJlZml4fSR7Y291bnR9LnRz` 是自定义 ts 文件名，$(saveas.keyPrefix)$(count).ts 的[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。最后得到类似：output000000.ts,output000001.ts,……,output000006.ts 命名的 ts 文件，跟输出的m3u8文件是关联的。<br /> |

**注意**：

* `avthumb` 切片的结果会保存在原文件的空间中，包含多个小的 ts 文件和 m3u8 playlist 文件，但是 m3u8 playlist 文件名按照默认规则生成，为了方便获取切片后的 m3u8 资源链接，建议自定义处理结果资源的名称，请参考 [处理结果另存 (saveas)](/products/dora/1-features_introduction)。

<a id="segtime-samples" />

# **hls加密** [#hls加密]

hls加密是利用AES-128位对每个ts文件进行加密，播放器在取得PlayList文件的时候，会根据里面的`#EXT-X-KEY`标签请求获得解密的URL，再请求解密密钥，之后会用密钥对获取的ts文件解密。用户可以对密钥的URL做cookie验证等方法来对用户做认证。
例子：[PlayList文件](http://ogn0m4it0.bkt.clouddn.com/58IzAY_GglrObBBbbD98wrHIbLk%3D/llhpmYRGVWfZL8dyCPXwCwKovI9R.m3u8) （复制链接，查看文件内容或直接用vlc播放器播放）

**参数解释**：

* `hlsKey`: base64\_urlsafe编码或加密过后的密钥
* `hlsKeyUrl`: 指定了密钥放置的url，经过base64\_urlsafe编码，这是生成m3u8 PlayList会使用到的
* `hlsKeyType`: 指定了传送秘钥的方式
* 不指定或者指定为0，则仅仅是以base64\_urlsafe编码的方式传送。
* 指定为1.x(1.0, 1.1, ...)，以RSA的OAEP加密方式，再以\<urlsafe\_base64\_encode>编码传送密钥，x表示密钥的版本
* 公钥：[1.0](https://dora-doc.qiniu.com/hls_rsa1.0.pub)

# **如何加密RSA** [#如何加密rsa]

可以编程的方法，或者使用`openssl`，下面提供`openssl`的版本：

```
$ echo -n [AES128KEY] | openssl rsautl -encrypt -oaep -inkey [QINIU_PUB_KEY_FILE] -pubin | openssl base64 -A | tr "+/" "-_"
```

**参数解释**：

* AES128Key：HLS\_AES128加解密密钥(用户定义的加解密密钥)
* QINIU\_PUB\_KEY\_FILE：加密上述AES128Key的RSA算法公钥文件（前文七牛提供的公钥1.0）

## 示例 [#示例]

* 不使用rsa加密：

  ```
  avthumb/m3u8/noDomain/1/s/720x480/vb/640k/hlsKey/ZXhhbXBsZWtleTEyMzQ1Ng==/hlsKeyUrl/aHR0cDovL29ndG95d2Q0ZC5ia3QuY2xvdWRkbi5jb20vaGxzMTI4LmtleQ==
  ```

* 使用rsa加密：

  ```
  avthumb/m3u8/noDomain/1/s/720x480/vb/640k/hlsKey/lsLFcVEISp-1iCoKCMRii6EgqAuUJs-f3FupKlFlbYnAjst5tsZ5U5cttUHp6TKIwW3eNMoBjjTgBnFlBoOku_DR0RMmFDgRxADf7vKRaaISSK0-rm3E4PzMiGybIpf9WIGzmQZLNpCcHOG1ThQU_8j3H4qQAX0nd7HxPcPEaPk=/hlsKeyType/1.0/hlsKeyUrl/aHR0cDovL29ndG95d2Q0ZC5ia3QuY2xvdWRkbi5jb20vaGxzMTI4LmtleQ==
  ```

# **操作方式** [#操作方式]

您可以通过以下几种方式来创建任务：

### **方式一：使用任务触发器** [#方式一使用任务触发器]

* `对符合规则策略的上传文件自动触发`：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 [任务触发器](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/1-tigger)；创建完成后，需要开启 **上传触发开关**，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/7-audio-and-video-slice/20240924-104416-84b0fd76e29a.webp)

### **方式二：使用[对象存储控制台](https://portal.qiniu.com/kodo/bucket)** [#方式二使用对象存储控制台]

* `上传文件手动触发`：在具体空间下， [上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file) 时，指定工作流模板 。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/7-audio-and-video-slice/20240924-104626-b4de95907ff6.webp)

* `指定文件手动触发`：有两种指定单个文件创建任务的入口

  * 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

    ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/7-audio-and-video-slice/20240924-104912-8de5e60349e1.webp)

```
注意：仅对音视频/gif动图/webp动图文件提供该操作。
```

* 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/7-audio-and-video-slice/20240924-104746-36342fe1033e.webp)

### **方式三：使用API** [#方式三使用api]

* `资源上传时手动触发`：可以在构造[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)时在[上传策略](/products/kodo/development-guidelines/security/1-put-policy)中，设置相关字段，在资源文件上传时触发处理。
* `对已有资源手动触发`：可以在调用 [持久化数据处理(pfop)](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 时，设置相关字段，对已存在空间中的资源文件发起处理。

### **方式四：使用SDK** [#方式四使用sdk]

* 查看各语言 SDK 使用指南中 `持久化数据处理`  章节，可在[七牛官方SDK](/sdk-tools/sdk) 进行下载。

# **操作示例** [#操作示例]

* 以 [资源上传时手动触发 ]()形式，将 mp4 视频按 vb/240k 预设规格切片（15秒一片）：

  ```
  {
          "scope":                "qiniu-ts-demo:sample.mp4",
          "deadline":             1390528576,
          "persistentOps":        "avthumb/m3u8/noDomain/1/segtime/15/vb/240k",
          "persistentNotifyUrl":  "http://fake.com/qiniu/notify"
  }
  ```

* 以 [对已有资源手动手动触发]() 形式，将 mp4 视频切片，静态码率为 320K，帧率为 24fps：

  ```
  POST /pfop/ HTTP/1.1
  Host: api.qiniu.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Qiniu <AccessToken>

  bucket=qiniu-ts-demo&key=sample.mp4&workflowTemplateID=transcode&notifyURL=http%3A%2F%2Ffake.com%2Fqiniu%2Fnotify
  ```

**注意**：要在 Authorization 头部的`<AccessToken>`前添加 `Qiniu` 和半角空格。

# **计费说明** [#计费说明]

音视频切片价格同 [音视频转码（avthumb）](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb)。


# 音视频分段（segment） (/products/dora/audio-and-video-processing-api/8-dora-segment)



最近更新时间: 2025-04-08 15:58:01

# **简介** [#简介]

音视频分段(segment)，用于按时长或时间点对原视频分段，不改变原音/视频的编码格式、分辨率、码率等，将原音/视频切成多个较小的文件。

**注意**：如果原音视频文件的编码格式无法封装到目标封装格式，那么会返回错误。

# **参数规格** [#参数规格]

```
segment/<Format>
            /segtime/<SegmentTime>
            /savePattern/<savePattern>
```

|                参数名称                |  类别 |  必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| :--------------------------------: | :-: | :-: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|          `&lt;Format&gt;`          | A/V |  是  | 指定分段文件的封装格式，不改变原音/视频的编码情况下可以改变封装格式，如 h264+aac 编码的 mp4文件可以分段为h264+aac 编码的 mkv 小文件。                                                                                                                                                                                                                                                                                                                                                                                                                              |
|   `/segtime/&lt;SegmentTime&gt;`   | A/V |  否  | 自定义分段后每一小段音/视频流的播放时长。单位为秒，最小值为5，默认值为5。                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `/savePattern/&lt;savePattern&gt;` | A/V |  是  | 自定义分段后每一小段音/视频流的文件名称。<br />**命名支持使用变量**：<br />1. 可以使用 `$(变量名)`或`${变量名}` 形式求值，魔法变量使用说明，参考 文件名变量 。<br />2. 注意：`$(count)`为必填项，必须存在的六位占位符数字串。<br /><br />**示例**：<br />源文件名为：`input.mp4`，cmd为：`avthumb/mp4/segtime/10/savePattern/JChrZXliYXNlKSQoY291bnQpLm1wNCA=` ，其中 `JChrZXliYXNlKSQoY291bnQpLm1wNCA=` 是自定义分段后的文件名， $(keybase)$(count).mp4 的[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。最后得到类似：input000000.mp4,input000001.mp4,……,input000006.mp4 命名的文件，跟源文件命名是关联的。<br /> |

# **操作方式** [#操作方式]

您可以通过以下几种方式来创建任务：

### **方式一：使用任务触发器** [#方式一使用任务触发器]

* `对符合规则策略的上传文件自动触发`：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 [任务触发器](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/1-tigger)；创建完成后，需要开启 **上传触发开关**，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/8-dora-segment/20240924-104416-84b0fd76e29a.webp)

### **方式二：使用[对象存储控制台](https://portal.qiniu.com/kodo/bucket)** [#方式二使用对象存储控制台]

* `上传文件手动触发`：在具体空间下， [上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file) 时，指定工作流模板 。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/8-dora-segment/20240924-104626-b4de95907ff6.webp)

* `指定文件手动触发`：有两种指定单个文件创建任务的入口

  * 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

    ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/8-dora-segment/20240924-104912-8de5e60349e1.webp)

```
注意：仅对音视频/gif动图/webp动图文件提供该操作。
```

* 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/8-dora-segment/20240924-104746-36342fe1033e.webp)

# **操作示例** [#操作示例]

用户可以根据需要自定义命令，例如：

`segment/mp4/segtime/10/pattern/cWluaXUtJChmbmFtZSkkKGNvdW50KQ==` 命令的调用将对原音/视频以10秒左右的时间进行分段，最后将生成多个小段音视频文件。

## **响应内容** [#响应内容]

如果请求成功，返回类似如下内容的 JSON 字符串

```json
"result": [
    {
        "index": 0,
        "segment_end_time": "10.857422",
        "segment_filename": "qiniu-000000",
        "segment_start_time": "0.000000"
    },
    {
        "index": 1,
        "segment_end_time": "21.177422",
        "segment_filename": "qiniu-000001",
        "segment_start_time": "10.857422"
    },
    {
        "index": 2,
        "segment_end_time": "21.857422",
        "segment_filename": "qiniu-000002",
        "segment_start_time": "21.177422"
    }
]
```

# **计费说明** [#计费说明]

音视频分段服务涉及转封装但不涉及转码，服务价格=音视频装封装价格，定价参考 [智能多媒体服务定价](https://www.qiniu.com/prices/dora) 。


# 倍速转码（avfast） (/products/dora/audio-and-video-processing-api/9-avfast)



最近更新时间: 2026-08-18 15:24:00

# **简介** [#简介]

倍速转码接口(avfast)加速对视频资源进行编码。
倍速转码不推荐用于转封装、转音频等低开销任务。建议用于时长大于25分钟。

## **使用限制** [#使用限制]

* 若输入文件过小，可能无法达到预期的加速效果，仍按照当前功能计费。
* 输出视频格式，只支持 `mp4` 和 `m3u8`。
* 请不要用于变帧率（Variable Frame Rate, 简称VFR）的文件，这种类型的文件不适合做视频倍速转码。
* 倍速转码仅支持视频转码和视频音频同时转码，其他的基础音视频转码接口（avthumb）提供的功能，比如水印、转封装等，暂不支持。

# **参数说明** [#参数说明]

```
    avfast/<Format>
            /vcodec/<VideoCodec>
            /s/<Resolution>
            /autoscale/<Autoscale>
            /r/<FrameRate>
            /hr/<HighFrameRate>
            /vb/<VideoBitRate>
            /crf/<Crf>
            /gop/<GroupOfPictures>
            /mosaic/<Mosaic>
            /mosaicGravity/<MosaicGravity>
            /mosaicOffsetX/<MosaicOffsetX>
            /mosaicOffsetY/<MosaicOffsetY>
            /mosaicSize/<MosaicSize>
            /mosaicStart/<MosaicStart>
            /mosaicDuration/<MosaicDuration>
            /acodec/<AudioCodec>
            /ab/<BitRate>
            /ar/<SamplingRate>
            /ac/<ChannelNum>
            /cut/<Cut>
            /scodec/<SubtitleCodec>
            /avsmart/<0|1>
            /smtEnhance/<Enhance>
            /smtMaxvbr/<Maxvbr>
            /smtQuality/<Quality>
```

| 参数                                       |  类别 |  必填 | 说明                                                                                                                                                                                                                                                                                                                                                           |
| :--------------------------------------- | :-: | :-: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `&lt;Format&gt;`                         | A/V |  Y  | 要转换输出的目标视频格式。<br />● 输入和输出目前仅支持  `mp4` 和 `m3u8`。                                                                                                                                                                                                                                                                                                             |
| `/vcodec/&lt;VideoCodec&gt;`             |  V  |  N  | 视频编码方案，支持方案：libx264，libx265。                                                                                                                                                                                                                                                                                                                                 |
| `/s/&lt;Resolution&gt;`                  |  V  |  N  | 0、指定目标视频分辨率，格式为`w`x`h`，vcodec 为libx265/libx264时，长边取值范围\[20,8192]，短边取值范围\[20,4320]。vcodec 取其他值时长边范围\[20,3840]，短边取值范围\[20,2160]。<br />1、 w、h 都为空时，则和原视频保持一致。<br />2、 `w`为空，`h`不为空，则按`h`的值对原视频等比例缩放。<br />3、`w`不为空，`h`为空时，则按`w`的值对原视频等比例缩放。<br />4、 `w`、`h`都不为空时，则根据`w`、`h`来缩放。                                                                                 |
| `/autoscale/&lt;Autoscale&gt;`           |  V  |  N  | 配合参数/s/使用，指定为2时，把视频按/s/中指定的比例添加黑框后再等比例缩放到/s/指定到矩形框内，指定为1时，把视频按原始比例缩放到/s/指定的矩形框内，0或者不指定会强制缩放到对应分辨率，可能造成视频变形。                                                                                                                                                                                                                                                  |
| `/vb/&lt;VideoBitRate&gt;`               |  V  |  N  | 视频比特率，单位：比特每秒（bit/s），常用视频比特率：128k 1.25m 5m 等。 默认情况下, 若指定码率大于原视频码率，则使用原视频码率进行转码, 参数末尾使用 `!` 可以以强制使用指定码率转码, 如 `128k!`                                                                                                                                                                                                                                          |
| `/r/&lt;FrameRate&gt;`                   |  V  |  N  | 1、视频帧率，每秒显示的帧数，单位：赫兹（Hz），常用帧率：24，25，30 等。<br />2、默认等于源视频帧率，HighFrameRate=0，取值\[1,30],超出范围取25帧；HighFrameRate=1时允许高帧率，取值\[1,60]，超出范围取60帧。                                                                                                                                                                                                                      |
| `/hr/&lt;HighFrameRate&gt;`              |  V  |  N  | 视频高帧率，与`r`配合使用，默认为 `HighFrameRate=0`，即常规帧率；`HighFrameRate=1`表示保留高帧率。                                                                                                                                                                                                                                                                                         |
| `/crf/&lt;Crf&gt;`                       |  V  |  N  | 1、设置 crf 值，为整数；vcodec 为 libx264 时取值为范围 \[18,28]，vcodec 为 libx265 时取值范围为 \[23,33]，默认取值为范围 \[18,28]。<br />2、其值越小，输出视频质量越好，输出文件可能变大。其不可与 vb 共用 。                                                                                                                                                                                                                |
| `/gop/&lt;GroupOfPictures&gt;`           |  V  |  N  | GOP参数，即视频流关键帧间的间隔帧数，取值\[0,3000]的整数，默认为0表示采用指定视频编码格式的默认GOP值，例如libx264格式默认GOP值为250。GOP取值过小会影响视频编码压缩率，码率变大，过大会使图像群组的时长跨度过大，影响播放随机性，故一般建议采用默认值。                                                                                                                                                                                                                  |
| `/sdr/&lt;SDR&gt;`                       |  V  |  N  | 是否启用HDR转SDR，设置为 "1" 时开启，默认关闭跟随源视频。当输入源为HDR时，设置为 "1" 时，转为 SDR 视频。                                                                                                                                                                                                                                                                                             |
| `/mosaic/&lt;Mosaic&gt;`                 |  V  |  N  | 是否启用马赛克，固定为 `1`,且后续马赛克参数必须连续,可以支持多个马赛克输入,形式如`/mosaic/1/.../mosaic/1/.../mosaic/1/...`                                                                                                                                                                                                                                                                        |
| `/mosaicGravity/&lt;MosaicGravity&gt;`   |  V  |  N  | 打马赛克的位置，默认值为`NorthEast`                                                                                                                                                                                                                                                                                                                                      |
| `/mosaicOffsetX/&lt;MosaicOffsetX&gt;`   |  V  |  N  | 马赛克位置的相对横向偏移量 e.g.  `200`, `-50`                                                                                                                                                                                                                                                                                                                             |
| `/mosaicOffsetY/&lt;MosaicOffsetY&gt;`   |  V  |  N  | 马赛克位置的相对纵向偏移量 e.g.  `150`, `-100`                                                                                                                                                                                                                                                                                                                            |
| `/mosaicSize/&lt;MosaicSize&gt;`         |  V  |  N  | 马赛克区域大小 e.g `100x200`, 当`mosaic/1`时必填                                                                                                                                                                                                                                                                                                                        |
| `/mosaicStart/&lt;MosaicStart&gt;`       |  V  |  N  | 马赛克起始时间 默认为0  e.g. `12.3`                                                                                                                                                                                                                                                                                                                                    |
| `/mosaicDuration/&lt;MosaicDuration&gt;` |  V  |  N  | 马赛克持续时间  默认直到片尾 e.g. `21.3`                                                                                                                                                                                                                                                                                                                                  |
| `/acodec/&lt;AudioCodec&gt;`             |  A  |  N  | 音频编码方案，支持方案：libmp3lame，libfdk\_aac，ac3。                                                                                                                                                                                                                                                                                                                      |
| `/ab/&lt;BitRate&gt;`                    |  A  |  N  | 静态码率（CBR），单位：比特每秒（bit/s），常用码率：320k, 256k, 192k, 128k, 64k 等。 默认情况下, 若指定码率大于原视频码率，则使用原音频码率进行转码, 参数末尾使用 `!` 可以以强制使用指定码率转码, 如 `64k!`                                                                                                                                                                                                                            |
| `/ar/&lt;SamplingRate&gt;`               |  A  |  N  | 音频采样频率，单位：赫兹（Hz），常用音频采样频率有 8000, 11025、12000、16000、22050、24000、32000、44056、44100、47250、48000、50000、64000、88200、96000 等。其它特定限制请参考注意项。                                                                                                                                                                                                                         |
| `/ac/&lt;ChannelNum&gt;`                 |  A  |  N  | 音频声道数量，单位：整数值，不大于输入源的声道数量。<br />1、acodec 为 `libfdk_aac` 时，支持的声道数量为 1、2、4、5、6、8；<br />2、acodec 为 `libmp3lame` 时，支持的声道数量为 1、2；<br />3、acodec 为 `aac `时，支持的声道数量为 1、2、3、4、5、6、7、8；<br />其他数值不合法。                                                                                                                                                                 |
| `/cut/&lt;Cut&gt;`                       | A/V |  N  | 从输入源中选择要去除的时间段。每个要去除的时间段由起止绝对时间表示，单位为 s，精确到 ms。例如，`0.5,1.0` 表示去除时间范围为 `[0.5,1.0]` 上的音视频； `0.5,1.0;1.5,2.0` 表示去除时间范围为 `[0.5,1.0]`、`[1.5,2.0]` 上的音视频。注意，其中时间范围不可有重叠，且需按起始点的位置顺序组织。参数值需要经过 `urlsafe_base64_encode`，例如 `cut/MC41LDEuMDsxLjUsMi4w` 是合法的。                                                                                                          |
| `/scodec/&lt;SubtitleCodec&gt;`          |  S  |  N  | 字幕编码方案，支持方案：mov\_text。                                                                                                                                                                                                                                                                                                                                       |
| `/avsmart/&lt;avsmart&gt;`               |  V  |  N  | 0、是否启用锐智转码，设置为 1 时开启。<br /> 1、支持使用`libx264`和 `libx265` 编码，默认使用libx264；不支持 `libaom-av1` 编码，同时也不支持`libaom-av1` 解码 （即不支持AV1视频输入）。<br /> 2、`使用 avsmart 的计费和 avthumb 有区别`，[价格参考](https://www.qiniu.com/prices/dora?source=dora)。<br />3、默认使用锐智转码2.0，[锐智转码2.0](https://www.qiniu.com/products/avsmart) 是基于 锐智转码1.0 的升级版本，1.0和2.0 支持的参数范围详情，建议使用锐智转码1.0的客户咨询客服进行升级。 |
| `/smtMaxvbr/&lt;maxvbr&gt;`              |  V  |  N  | 开启 `avsmart`时生效。最大平均码率, 单位：比特每秒（bit/s），常用视频比特率：128k 1.25m 5m 等。小于 1k 会默认使用 1k。暂时对 H.265 无效。                                                                                                                                                                                                                                                                  |
| `/smtQuality/&lt;quality&gt;`            |  V  |  N  | 开启`avsmart`时生效。瘦身时的转码质量等级，值越大，画质越好。整数，取值范围\[-7,9]。                                                                                                                                                                                                                                                                                                           |

## **仅限M3U8格式的参数** [#仅限m3u8格式的参数]

常规处理参数与其他格式相同，下面的参数说明仅针对HLS/m3u8格式。

```
    avfast/m3u8
            /segtime/<SegSeconds>
            /pattern/<savePattern>
```

| 参数                            | 类别  | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------- | --- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/segtime/&lt;SegSeconds&gt;` | A/V | N  | 用于 HLS 自定义每一小段音/视频流的播放时间长度，取值范围为: 2 - 120 （秒），默认值为 10（单位:秒）。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `/pattern/&lt;pattern&gt;`    | A/V | N  | 为各音视频流ts文件自定义命名。<br />因为一整段音视频流音视频切片后会生成一个M3U8播放列表和多个音视频流ts文件。<br />**命名支持使用变量**：<br />1. 可以使用 `$(变量名)`或`${变量名}` 形式求值，魔法变量使用说明，参考 文件名变量 。<br />2. 注意：`$(count)`为必填项，必须存在的六位占位符数字串。<br /><br />**示例**：<br />输出的m3u8文件名为：`output.m3u8`，cmd为：`avthumb/m3u8/noDomain/1/savePattern/JChzYXZlYXMua2V5UHJlZml4KSAkKGNvdW50KS50cw==` ，其中 `JChzYXZlYXMua2V5UHJlZml4KSAkKGNvdW50KS50cw==` 是自定义 ts 文件名，$(saveas.keyPrefix) $(count).ts 的[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。最后得到类似：output000000.ts,output000001.ts,……,output000006.ts 命名的 ts 文件，跟输出的m3u8文件是关联的。<br /> |

# **操作方式** [#操作方式]

您可以通过以下几种方式来创建任务：

### **方式一：使用任务触发器** [#方式一使用任务触发器]

* `对符合规则策略的上传文件自动触发`：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 [任务触发器](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/1-tigger)；创建完成后，需要开启 **上传触发开关**，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/9-avfast/20240924-104416-84b0fd76e29a.webp)

### **方式二：使用[对象存储控制台](https://portal.qiniu.com/kodo/bucket)** [#方式二使用对象存储控制台]

* `上传文件手动触发`：在具体空间下， [上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file) 时，指定工作流模板 。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/9-avfast/20240924-104626-b4de95907ff6.webp)

* `指定文件手动触发`：有两种指定单个文件创建任务的入口

  * 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

    ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/9-avfast/20240924-104912-8de5e60349e1.webp)

```
注意：仅对音视频/gif动图/webp动图文件提供该操作。
```

* 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

  ![img](/docs-assets/products/dora/%284-api-docs%29/audio-and-video-processing-api/9-avfast/20240924-104746-36342fe1033e.webp)

### **方式三：使用API** [#方式三使用api]

* `资源上传时手动触发`：可以在构造[上传凭证](/products/kodo/development-guidelines/security/2-upload-token)时在[上传策略](/products/kodo/development-guidelines/security/1-put-policy)中，设置相关字段，在资源文件上传时触发处理。
* `对已有资源手动触发`：可以在调用 [持久化数据处理(pfop)](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) 时，设置相关字段，对已存在空间中的资源文件发起处理。

### **方式四：使用SDK** [#方式四使用sdk]

* 查看各语言 SDK 使用指南中 `持久化数据处理`  章节，可在[七牛官方SDK](/sdk-tools/sdk) 进行下载。

# **计费说明** [#计费说明]

定价参考 [智能多媒体服务定价](https://www.qiniu.com/prices/dora) 。

* 如果不启用锐智转码，服务价格=倍速转码价格
* 如果同时启用锐智转码，即使用 `avsmart ` 参数，服务价格= 倍速转码/启用 avsmart 的价格

#### **转码费用计算公式** [#转码费用计算公式]

* 转码费用 = 输出文件时长 x 转码单价，价格单位： 元／分钟。
* 输出时长：对于每月转码输出文件，按分钟计费，累计总时长不足一分钟不计费
* 输出规格按输出视频分辨率的长边和短边属于输出规格划定的范围进行判定，以倍速转码输出HD (1920 x 1080) 规格为例：
  * 输出视频的分辨率长边不大于1920且短边不大于1080，则属于HD输出规格。
  * 输出视频的长边大于1920或输出视频的短边大于1080，该属于更高输出规格。

#### **注意** [#注意]

七牛云的数据处理API均支持[管道](/products/dora/processing-mechanism/3-the-pipe)，通过管道操作符 `\|` 实现串行处理，即将一个资源经由多个 `&lt;fop&gt;` 串行处理。

处理规格如下：

```
<fop1>|<fop2>|<fopN>
```

* `<fop>` (File Operation的缩写)，表示数据处理指令及其所需要的参数。
* 整个串行处理中，只要有处理成功的 `fop`，就会有相应的计量计费。


# 翻译狗文档翻译 (/products/dora/document-processing/0-dog-document-translation)



最近更新时间: 2021-11-18 18:06:20

# 接口简介 [#接口简介]

翻译狗文档翻译接口提供多格式、多语种、高质量的文档翻译服务，支持pdf、doc、docx、ppt、pptx、xls、xlsx等格式，支持源语言自动检测，只需指定文档链接并指定目标语言、文档格式、需要存储至七牛kodo的bucket等参数，即可在七牛云存储kodo中获取翻译后的文档。

# 调用链路 [#调用链路]

![image.png](/docs-assets/products/dora/%284-api-docs%29/document-processing/0-dog-document-translation/FlZN-t_OiBANPysS44sm2Rd4Zpv9-13daf5d9906a.webp)

# 接口规格 [#接口规格]

## 翻译请求接口 [#翻译请求接口]

**请求URL**: `https://ap-gate-z0.qiniuapi.com/translate/v1/document/translate`

**字符编码格式**: 请求及返回结果都使用 UTF-8 字符集进行编码

**请求方法**: POST

**建议超时时长**: 3s

**请求头部**:

| 字段            | 取值                                                                                                                                                                      |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | application/json                                                                                                                                                        |
| Authorization | Qiniu \&lt;AccessKey>:\&lt;Sign> <br />注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。\&lt;Sign> 的取值请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken) |

**请求参数**: 放在 HTTP Body 中，采用 json 格式，具体参数如下:

| 参数名称             | 类型     | 是否必选 | 说明                                                                                                                                     |
| ---------------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------- |
| url              | string | Y    | 需要翻译的资源的链接<br />注意：<br />1. 文件格式限定为: pdf、doc、docx、ppt、pptx、xls、xlsx\<br>2. 文件最大限制问50M\<br>3. 不支持扫描件、图纸、纯图片文档，加密文件请先去除密码                |
| from             | string | Y    | 源语言，支持自动检测。具体见语言列表                                                                                                                     |
| to               | string | Y    | 目标语言，不支持自动检测。具体见语言列表                                                                                                                   |
| dType            | int    | Y    | 翻译后的文件类型， 取值 2 或者 3\<br>2: 翻译后的pdf文件，支持格式：word、pdf、img\<br>3: 翻译后的word文件（支持格式：word、pdf)；ppt文件（支持格式：img、ppt）；<br /> excel文件（支持格式：excel） |
| bucket           | string | Y    | 翻译后的文件，转存到kodo的哪个bucket                                                                                                                |
| callback         | string | Y    | 翻译完成后的回调，支持http、https                                                                                                                  |
| industryId       | int    | N    | 行业代码。具体见行业列表                                                                                                                           |
| excelMode        | int    | N    | 指定excel翻译模式 <br />0：只翻译当前打开sheet（默认）<br />1：翻译全部sheet（页数按全部sheet字符数来计算）                                                                |
| bilingualControl | int    | N    | 指定翻译模式 <br />0：译文单独为一个文档（默认）<br />1：双语对照（原文和译文在一个文档）                                                                                   |

**返回参数**: 放在 HTTP Body 中，采用 json 格式，具体参数如下:

| 参数名称 | 类型           | 是否必选 | 说明                      |
| ---- | ------------ | ---- | ----------------------- |
| code | int          | Y    | 结果码，100表示调用成功。具体详见状态码列表 |
| msg  | string       | Y    | 结果信息的文本描述               |
| data | json\_object | Y    | 返回数据结果集                 |

其中data的具体内容如下

| 参数名称    | 类型     | 是否必选 | 说明      |
| ------- | ------ | ---- | ------- |
| entryId | string | Y    | 请求的唯一标识 |

## 异步回调获取结果接口 [#异步回调获取结果接口]

**说明**：该接口需要服务调用方实现，对应翻译请求接口中的`callback`参数。七牛服务器会在翻译完成后调用该接口

**字符编码格式：** 请求及返回结果都使用 UTF-8 字符集进行编码

**请求方法：** POST

**回调参数：** 放在 HTTP Body 中，采用 json 格式，具体参数如下：

| 参数名称 | 类型           | 是否必选 | 说明                      |
| ---- | ------------ | ---- | ----------------------- |
| code | int          | Y    | 结果码，200表示调用成功。具体详见状态码列表 |
| msg  | string       | Y    | 结果信息的文本描述               |
| data | json\_object | Y    | 返回数据结果集                 |

其中data的具体内容如下

| 参数名称            | 类型     | 是否必选 | 说明                       |
| --------------- | ------ | ---- | ------------------------ |
| entryId         | string | Y    | 请求的唯一标识                  |
| fileKey         | string | Y    | 翻译后的文件在kodo指定kucket中的key |
| pageCount       | int    | Y    | 翻译的有效页数                  |
| translationDone | bool   | Y    | 翻译是否完成的判断字段              |

## 查询翻译结果接口 [#查询翻译结果接口]

**说明** ：除了接收回调之外，使用者还可以通过该接口主动查询翻译进度和结果

**请求URL**: `https://ap-gate-z0.qiniuapi.com/translate/v1/document/query`

**字符编码格式**: 请求及返回结果都使用 UTF-8 字符集进行编码

**请求方法**: GET

**建议超时时长**: 3s

**请求头部**:

| 字段            | 取值                                                                                                                                                                      |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | application/json                                                                                                                                                        |
| Authorization | Qiniu \&lt;AccessKey>:\&lt;Sign> <br />注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。\&lt;Sign> 的取值请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken) |

**请求参数**: 放在 QueryString 中，具体参数如下:

| 参数名称    | 类型     | 是否必选 | 说明      |
| ------- | ------ | ---- | ------- |
| entryId | string | Y    | 请求的唯一标识 |

**返回参数**: 放在 HTTP Body 中，采用 json 格式，具体参数如下:

| 参数名称 | 类型           | 是否必选 | 说明                                       |
| ---- | ------------ | ---- | ---------------------------------------- |
| code | int          | Y    | 结果码，100表示翻译完成。102代表正在翻译中。<br />具体详见状态码列表 |
| msg  | string       | Y    | 结果信息的文本描述                                |
| data | json\_object | Y    | 返回数据结果集                                  |

其中data的具体内容如下

| 参数名称            | 类型     | 是否必选 | 说明                       |
| --------------- | ------ | ---- | ------------------------ |
| entryId         | string | Y    | 请求的唯一标识                  |
| fileKey         | string | N    | 翻译后的文件在kodo指定kucket中的key |
| pageCount       | int    | N    | 翻译的有效页数                  |
| translationDone | bool   | Y    | 翻译是否完成的判断字段              |

# 示例 [#示例]

## 翻译请求示例 [#翻译请求示例]

```shell
POST /translate/v1/document/translate HTTP/1.1
Host: ap-gate-z0.qiniuapi.com
Content-Type: application/json
Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=

{
    "url": "http://xx.emm/trans-min.docx",
    "dType": 2,
    "from": "auto",
    "to": "en",
    "industryId": 0,
    "excelMode": 0,
    "bilingualControl": 0,
    "bucket": "test-bucket",
    "callback": "http://test.emm/callback"
}
```

## 翻译请求成功返回示例 [#翻译请求成功返回示例]

```shell
HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": 100,
    "msg": "请求成功",
    "data": {
        "entryId": "61446e07000000003a4b6d31703f790c"
    }
}
```

## 查询翻译结果接口示例 [#查询翻译结果接口示例]

```shell
GET /translate/v1/document/query?entryId=61446e07000000003a4b6d31703f790c HTTP/1.1
Host: ap-gate-z0.qiniuapi.com
Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=
```

# 接口规则 [#接口规则]

## 支持的语言列表 [#支持的语言列表]

| 语言代码    | 语言         |
| ------- | ---------- |
| auto    | 自动检测       |
| sq      | 阿尔巴尼亚语     |
| ga      | 爱尔兰语       |
| est     | 爱沙尼亚语      |
| ara     | 阿拉伯语       |
| am      | 阿姆哈拉语      |
| or      | 奥里亚语       |
| az      | 阿塞拜疆语      |
| be      | 白俄罗斯语      |
| bul     | 保加利亚语      |
| ba      | 巴什基尔语      |
| eu      | 巴斯克语       |
| is      | 冰岛语        |
| pl      | 波兰         |
| bs      | 波斯尼亚语      |
| fa      | 波斯语        |
| af      | 布尔语(南非荷兰语) |
| tt      | 鞑靼语        |
| dan     | 丹麦语        |
| de      | 德语         |
| ru      | 俄语         |
| fra     | 法语         |
| fj      | 斐济语        |
| tl      | 菲律宾语       |
| fin     | 芬兰语        |
| fy      | 弗里西语       |
| km      | 高棉语        |
| ka      | 格鲁吉亚语      |
| gu      | 古吉拉特语      |
| ht      | 海地克里奥尔语    |
| kor     | 韩语         |
| ha      | 豪萨语        |
| kk-kz   | 哈萨克语       |
| kk      | 哈萨克语(西里尔)  |
| nl      | 荷兰语        |
| gl      | 加利西亚语      |
| ca      | 加泰罗尼亚语     |
| cs      | 捷克语        |
| ky      | 吉尔吉斯语      |
| kn      | 卡纳达语       |
| otq     | 克雷塔罗奥托米语   |
| tlh     | 克林贡语       |
| hr      | 克罗地亚语      |
| co      | 科西嘉语       |
| ku      | 库尔德语       |
| la      | 拉丁语        |
| lo      | 老挝语        |
| lv      | 拉脱维亚语      |
| lt      | 立陶宛语       |
| rom     | 罗马尼亚语      |
| lb      | 卢森堡语       |
| rw      | 卢旺达语       |
| mg      | 马尔加什语      |
| mt      | 马耳他语       |
| ms      | 马来语        |
| mr      | 马拉提语       |
| ml      | 马拉雅拉姆语     |
| mi      | 毛利语        |
| mk      | 马其顿语       |
| mo      | 蒙古语        |
| mn      | 蒙古语(西里尔)   |
| bn      | 孟加拉语       |
| hmn     | 苗语         |
| xh      | 南非科萨语      |
| zu      | 南非祖鲁语      |
| ne      | 尼泊尔语       |
| no      | 挪威语        |
| pa      | 旁遮普语       |
| pap     | 帕皮阿门托语     |
| ps      | 普什图语       |
| pt      | 葡萄牙语       |
| ny      | 齐切瓦语       |
| jp      | 日语         |
| swe     | 瑞典语        |
| sr-Latn | 塞尔维亚语(拉丁文) |
| sr      | 塞尔维亚语(西里尔) |
| st      | 塞索托语       |
| sm      | 萨摩亚语       |
| si      | 僧加罗语       |
| eo      | 世界语        |
| sk      | 斯洛伐克语      |
| slo     | 斯洛文尼亚语     |
| sw      | 斯瓦希里语      |
| gd      | 苏格兰盖尔语     |
| so      | 索马里语       |
| ceb     | 宿务语        |
| te      | 泰卢固语       |
| ta      | 泰米尔语       |
| th      | 泰语         |
| tg      | 塔吉克语       |
| to      | 汤加语        |
| ty      | 塔希提语       |
| tr      | 土耳其语       |
| tk      | 土库曼语       |
| cy      | 威尔士语       |
| ug      | 维吾尔语       |
| udm     | 乌德穆尔特语     |
| ur      | 乌尔都语       |
| uk      | 乌克兰语       |
| uz      | 乌兹别克语      |
| haw     | 夏威夷语       |
| spa     | 西班牙语       |
| iw      | 希伯来语       |
| el      | 希腊语        |
| sd      | 信德语        |
| hu      | 匈牙利语       |
| sn      | 修纳语        |
| hy      | 亚美尼亚语      |
| ig      | 伊博语        |
| it      | 意大利语       |
| yi      | 意第绪语       |
| hi      | 印地语        |
| en      | 英语         |
| su      | 印尼巽他语      |
| id      | 印尼语        |
| jw      | 印尼爪哇语      |
| ii      | 彝语         |
| yua     | 尤卡坦玛雅语     |
| yo      | 约鲁巴语       |
| vie     | 越南语        |
| zh      | 中文         |
| cht     | 中文繁体       |
| yue     | 中文粤语(繁体)   |
| za      | 壮语         |

## 行业列表 [#行业列表]

| 行业代码 | 行业   |
| ---- | ---- |
| 1    | 法律   |
| 2    | 金融   |
| 3    | 农林牧渔 |
| 4    | 医药卫生 |
| 5    | 建筑建材 |
| 6    | 冶金矿产 |
| 7    | 石油化工 |
| 8    | 水利水电 |
| 9    | 交通运输 |
| 10   | 信息产业 |
| 11   | 机械机电 |
| 12   | 轻工食品 |
| 13   | 服装纺织 |
| 14   | 专业服务 |
| 15   | 安全防护 |
| 16   | 环保绿化 |
| 17   | 旅游休闲 |
| 18   | 办公文教 |
| 19   | 电子电工 |
| 20   | 玩具礼品 |
| 21   | 家居用品 |
| 22   | 物资   |
| 23   | 包装   |
| 24   | 体育   |
| 25   | 办公   |
| 26   | 其他   |

# 状态码列表 [#状态码列表]

| 状态码 | 状态描述 |
| --- | ---- |
| 200 | 请求成功 |
| 400 | 参数错误 |
| 500 | 内部错误 |

# 价格 [#价格]

0.5元/页


# 文本文件合并（concat） (/products/dora/file-processing/0-text-file-merging-concat)



最近更新时间: 2021-07-26 17:38:05

# **简介** [#简介]

文本文件合并接口(concat)用于将数个七牛云上的源文件的二进制内容按指定顺序合并到新文件。

## **限制说明** [#限制说明]

* 不能用于[音视频拼接](/products/dora/1-features_introduction)和图片拼接。
* 本接口只能以 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 形式来使用。

<a id="concat-specification" />

# **接口规格** [#接口规格]

**注意**：接口规格不含任何空格与换行符，下列内容经过格式化以便阅读。

```
Url1?concat/mimeType/<encodedMimeType>
            /<encodedUrl2>
            /<encodedUrl3>
            /<encodedUrl4>
            /...
```

| 参数名称            | 必填 | 说明                                                                                                   |
| :-------------- | :- | :--------------------------------------------------------------------------------------------------- |
| Url1            | 是  | 第一个源文件的完整URL，无需经过URL安全的Base64编码。例如：`http://oano6er4n.bkt.clouddn.com`                                |
| encodedMimeType | 是  | 目标文件的MIME类型，必须填经过[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)的值 |
| encodedUrlN     | 是  | ● 必须是源文件完整的URL经过URL安全的Base64编码的值<br /> ● 所有源文件必须在同一个存储空间<br /> ● 最多可以合并1000个文件<br /> ● 文件内容按照文件名顺序合并 |

# **操作方式** [#操作方式]

文本文件合并，目前只能以 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 形式来使用。

# **示例** [#示例]

以 `对已有资源手动触发` 形式，将多个文本文件拼接成一个（分别是 a.txt、b.txt 和 c.txt 在同一个空间中，并且绑定域名 test.clouddn.com）

```
POST /pfop HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: QBox <AccessToken>

bucket=qiniu-ts-demo
&key=a.txt
&fops=concat/mimeType/dGV4dC9wbGFpbg==/aHR0cDovL3Rlc3QuY2xvdWRkbi5jb20vYi50eHQ=/aHR0cDovL3Rlc3QuY2xvdWRkbi5jb20vYy50eHQ=&notifyURL=http://fake.com/qiniu/notify
```

**注意**：要在 Authorization 头部的 `<AccessToken>` 前添加 QBox 和半角空格。


# MD转HTML（md2html） (/products/dora/file-processing/1-md-html-md2html)



最近更新时间: 2021-07-26 17:38:40

# **简介** [#简介]

七牛云存储支持直接将七牛云存储上的 `Markdown` 类型的资源转为 `HTML`文件并返回。

# **接口规格** [#接口规格]

```
md2html/<Mode>/css/<EncodedCSSURL>
```

| 参数名称                    | 类型     | 说明                                                                   |
| :---------------------- | :----- | :------------------------------------------------------------------- |
| `&lt;Mode&gt;`          | int    | 默认值为 0<br />0: 表示转为完整的 HTML (head + body) 输出<br />1: 表示只转为 HTML Body |
| `&lt;EncodedCSSURL&gt;` | string | CSS 样式的 URL<br />EncodedCSSURL = urlsafe\_base64\_encode(CSSURL)     |

# **操作方式** [#操作方式]

* 可以通过 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 的方式来调用：
  * `资源上传时自动触发`：可以在上传时指定[persistentOps](/products/kodo/development-guidelines/security/1-put-policy#put-policy-persistent-ops-explanation)参数
  * `对已有资源手动手动触发`：调用[pfop]()命令
* 可以通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing) 的方式来调用。


# 文件HASH值（qhash） (/products/dora/file-processing/2-file-hash-value-qhash)



最近更新时间: 2025-03-11 10:06:12

# **简介** [#简介]

文件HASH值(qhash)用于实时得到存储在七牛的文件的HASH值。

## **限制说明** [#限制说明]

* 该功能目前支持华东、华南、华北、北美、东南亚区域的存储 bucket。

# **接口规格** [#接口规格]

**注意：** 接口规格不含任何空格与换行符，下列内容经过格式化以便阅读。

```
qhash/<algorithm>
```

| 参数名称                | 必填 | 说明                                     |
| :------------------ | :- | :------------------------------------- |
| `&lt;algorithm&gt;` | 是  | 计算 hash 的算法。目前支持`sha1`、`md5`、`sha256`。 |

# **示例** [#示例]

**1.按md5算法计算文件的HASH值**

```
https://dora-doc.qiniu.com/gogopher.jpg?qhash/md5
```

返回结果

```
{
    "hash": "6085d57b5ee06ac7f793fa5f0f052cb5",
    "fsize": 214513
}
```

**2.按sha1算法计算文件的HASH值**

```
https://dora-doc.qiniu.com/gogopher.jpg?qhash/sha1
```

返回结果

```
{
    "hash": "1f3156aa1dd8c4359a871f2384b82a944be83f7c",
    "fsize": 214513
}
```

**3.按sha256算法计算文件的HASH值**

```
https://dora-doc.qiniu.com/gogopher.jpg?qhash/sha256
```

返回结果

```
{
    "hash": "9806aa869d6f9d285164b0ce901e49f56cc915791814de231d41759548a2ee28",
    "fsize": 214513
}
```

# **操作方式** [#操作方式]

* 可以通过 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 的方式来调用：
  * `资源上传时自动触发`：可以在上传时指定[persistentOps](/products/kodo/development-guidelines/security/1-put-policy#put-policy-persistent-ops-explanation)参数
  * `对已有资源手动手动触发`：调用[pfop]()命令
* 可以通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing) 的方式来调用。


# 资源下载二维码（qrcode） (/products/dora/file-processing/3-resource-download-the-qr-code-qrcode)



最近更新时间: 2025-03-11 10:06:20

# **简介** [#简介]

资源下载二维码生成功能(qrcode)，用于为存放在七牛云存储上的资源的下载URL或资源内容生成二维码图片，方便用户在各种客户端之间传播资源。
所生成的二维码图片格式为`png`。

**注意**：二维码的内容实际上是文本，却可存储多种类型的内容，参考[具体用例](https://code.google.com/p/zxing/wiki/BarcodeContents)。

<a id="specification" />

# **接口规格** [#接口规格]

```
qrcode/<Mode>/level/<Level>
```

| 参数名称                   | 说明                                                                                                                                | 必填 |
| :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :- |
| `&lt;Mode&gt;`         | 可选值：`0`，为 DownloadURL 本身生成二维码，显示DownloadURL和DownloadURL指向的资源内容。`1`，为 DownloadURL 指向的资源内容生成二维码，只显示资源内容，不显示DownloadURL。<br />默认为`0` |    |
| `/level/&lt;Level&gt;` | 冗余度，可选值`L`（7%）、`M`（15%）、`Q`（25%），`H`（30%），默认为`L`。                                                                                 |    |

其中 `<DownloadURL>` 代表资源的原始下载 URL ，请参考[下载机制](/products/kodo/development-guidelines/download-process)。

**注意：**`L`是最低级别的冗余度，`H`最高。提高冗余度，较大可能会使生成图片总像素变多。

# **操作方式** [#操作方式]

* 可以通过 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 的方式来调用：
  * `资源上传时自动触发`：可以在上传时指定[persistentOps](/products/kodo/development-guidelines/security/1-put-policy#put-policy-persistent-ops-explanation)参数
  * `对已有资源手动手动触发`：调用[pfop]()命令
* 可以通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing) 的方式来调用。

<a id="samples" />

# **示例** [#示例]

**1**.Mode=0时，基于下载URL生成二维码：

```
https://dora-doc.qiniu.com/gogopher.jpg?qrcode
```

![点击察看图片](/docs-assets/products/dora/%284-api-docs%29/file-processing/3-resource-download-the-qr-code-qrcode/gogopher-5d5abaf091d3.webp)

**2**.分别用不同的冗余度生成不同尺寸的二维码：

```
https://dora-doc.qiniu.com/gogopher.jpg?qrcode/0/level/L
```

![点击察看图片](/docs-assets/products/dora/%284-api-docs%29/file-processing/3-resource-download-the-qr-code-qrcode/gogopher-5d5abaf091d3.webp)

```
https://dora-doc.qiniu.com/gogopher.jpg?qrcode/0/level/H
```

![点击察看图片](/docs-assets/products/dora/%284-api-docs%29/file-processing/3-resource-download-the-qr-code-qrcode/gogopher-b255411c19a5.webp)

以上两个二维码图片尺寸不同，但表示的内容相同。

## **高级用法** [#高级用法]

想生成二维码 + Logo，可以使用七牛云存储的[管道](/products/dora/processing-mechanism/3-the-pipe)和[图片水印处理](/products/dora/1-features_introduction)操作实现。例如：

```
https://dora-doc.qiniu.com/gogopher.jpg?qrcode|watermark/1/image/aHR0cHM6Ly9kb3JhLWRvYy5xaW5pdS5jb20vcWluaXUucG5nP2ltYWdlTW9nci90aHVtYm5haWwvMzJ4MzI=/gravity/Center/dx/0/dy/0
```

![QRCode+Logo](/docs-assets/products/dora/%284-api-docs%29/file-processing/3-resource-download-the-qr-code-qrcode/gogopher-185147479e05.webp)


# 多文件压缩（mkzip） (/products/dora/file-processing/4-mkzip)



最近更新时间: 2021-07-26 17:38:23

# **简介** [#简介]

**多文件压缩**，为用户提供了批量文件的压缩存储功能。用户通过指定一系列 URL，即可将若干七牛空间中的资源文件，在七牛服务端压缩后存储。若用户同时指定了[saveas](/products/dora/processing-mechanism/0-processing-results-save-saveas)，则将生成的压缩文件以用户指定的 key 存储到指定的 bucket 中，若未指定 saveas，则以压缩文件的 hash 值作为 key 并存储到当前 bucket 中。

**注意**：

* 不支持压缩打包空文件。

# **少量文件压缩（mode=2）** [#少量文件压缩mode2]

## **接口规格** [#接口规格]

```
POST /pfop/ HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qbox <AccessToken>

bucket=<bucket>&key=<key>&fops=<mkzipArgs>
```

| 参数名称                | 必填 | 说明                                                                                                                                                |
| :------------------ | :- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| `&lt;bucket&gt;`    | 必填 | 存储空间名。                                                                                                                                            |
| `&lt;key&gt;`       | 必填 | 存储空间内指定资源的文件名字。此处的key所指的资源内容对 mkzip 操作本身没有影响，必填是由于 pfop 接口规格要求请求 body 中参数必须包含 bucket 和 key，因此即使未对空间特定资源进行操作，在执行 mkzip 操作时仍然需要指定账号下的特定空间和该空间的已有资源。 |
| `&lt;mkzipArgs&gt;` | 必填 | mkzipArgs 规格说明如下。                                                                                                                                 |

mkzipArgs 规格说明：

```
mkzip/<mode>
     /encoding/<UrlsafeBase64EncodedEncoding>
     /url/<Base64EncodedURL1>[/alias/<Base64EncodedAlias1>]
     /url/<Base64EncodedURL2>[/alias/<Base64EncodedAlias2>]
     ... ...
     /url/<Base64EncodedURLN>[/alias/<Base64EncodedAliasN>]
```

| 参数名称                                             | 必填   | 说明                                                                                                                                       |
| :----------------------------------------------- | :--- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `&lt;Mode&gt;`                                   | 必填   | 值为 2，用于少量文件压缩，mkzipArgs字符串长度不能超过2048字节。                                                                                                  |
| `/encoding/&lt;UrlsafeBase64EncodedEncoding&gt;` | 可选   | 指示压缩包内资源命名的编码，目前支持 gbk 和 utf-8，默认 utf-8。                                                                                                 |
| `/url/&lt;Base64EncodedURLN&gt;`                 | 至少一项 | 需要被压缩资源（这些资源必须处于同一个 bucket 下）的 URL，必须是公网可访问资源，在请求中需要经过[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。 |
| `/alias/&lt;Base64EncodedAliasN&gt;`             | 可选   | 资源在压缩文件中的别名，需要经过[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)，若不指定则为 url 中资源的原文件名。                   |

## **示例** [#示例]

以[持久化数据处理](/products/dora/file-processing/4-mkzip)的形式：

1. 获取以下资源：

* `http://78re52.com1.z0.glb.clouddn.com/resource/gogopher.jpg`
* `http://78re52.com1.z0.glb.clouddn.com/resource/dive-into-golang.pptx`
* `http://78re52.com1.z0.glb.clouddn.com/resource/thinking-in-go.mp4`

2. 将 `http://78re52.com1.z0.glb.clouddn.com/resource/gogopher.jpg` 重命名为 mkziptest；
3. 将 mkziptest、dive-into-golang.pptx 和 thinking-in-go.mp4 打包，并另存为成 resource/mkziptest 保存到空间 qiniu-developer 中：

```
POST /pfop/ HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: QBox <AccessToken>

bucket=qiniu-developer
&key=1.png
&fops=mkzip%2f2%2furl%2faHR0cDovLzc4cmU1Mi5jb20xLnowLmdsYi5jbG91ZGRuLmNvbS9yZXNvdXJjZS9nb2dvcGhlci5qcGc=%2falias%2fbWt6aXB0ZXN0%2furl%2faHR0cDovLzc4cmU1Mi5jb20xLnowLmdsYi5jbG91ZGRuLmNvbS9yZXNvdXJjZS9kaXZlLWludG8tZ29sYW5nLnBwdHg=%2furl%2faHR0cDovLzc4cmU1Mi5jb20xLnowLmdsYi5jbG91ZGRuLmNvbS9yZXNvdXJjZS90aGlua2luZy1pbi1nby5tcDQ=
```

其中，请求 body 中的 key = 1.png 仅仅为符合[pfop](/products/dora/1-features_introduction)操作的接口规格而存在，并没有实际的意义，但需要是操作空间中存在的资源的 key。

# **大量文件压缩（mode=4）** [#大量文件压缩mode4]

**为了将大量文件压缩，可以将待压缩文件URL写入一个索引文件，上传至bucket，再对该索引文件进行的mkzip操作。**

## 索引文件格式为： [#索引文件格式为]

```
/url/<Base64EncodedURL1>[/alias/<Base64EncodedAlias1>]
/url/<Base64EncodedURL2>[/alias/<Base64EncodedAlias2>]
... ...
/url/<Base64EncodedURLN>[/alias/<Base64EncodedAliasN>]
```

| 参数说明                                 | 必填   | 说明                                                                                                                                        |
| :----------------------------------- | :--- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| `/url/&lt;Base64EncodedURLN&gt;`     | 至少一项 | 需要被压缩资源（这些资源必须处于同一个 bucket 下）的 URL，必须是公网可访问资源，在请求中需要经过[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64) 。 |
| `/alias/&lt;Base64EncodedAliasN&gt;` | 可选   | 资源在压缩文件中的别名，需要经过[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)，若不指定则为 url 中资源的原文件名。                    |
| **注意**：                              |      |                                                                                                                                           |

* 每一行填写一个待压缩文件URL及重命名参数
* **索引文件必须和目标资源文件在同一个bucket内**
* 资源总数目不超过3000个，总文件大小不超过45000MB

## **接口规格** [#接口规格-1]

```
POST /pfop/ HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qbox <AccessToken>

bucket=<bucket>&key=<key>&fops=<mkzipArgs>
```

| 参数名称                | 必填 | 说明               |
| :------------------ | :- | :--------------- |
| `&lt;bucket&gt;`    | 必填 | 存储空间名            |
| `&lt;key&gt;`       | 必填 | key即为上面的索引文件     |
| `&lt;mkzipArgs&gt;` | 必填 | mkzipArgs 规格说明如下 |

其中 mkzipArgs 规格为：

```
mkzip/<mode>
     /encoding/<UrlsafeBase64EncodedEncoding>
```

| 参数名称                                             | 必填 | 说明                                       |
| :----------------------------------------------- | :- | :--------------------------------------- |
| `&lt;Mode&gt;`                                   | 必填 | 取值为 4，用于大量文件压缩。                          |
| `/encoding/&lt;UrlsafeBase64EncodedEncoding&gt;` | 可选 | 指示压缩包内资源命名的编码，目前支持 gbk 和 utf-8，默认 utf-8。 |

## **示例** [#示例-1]

以[持久化处理](/products/dora/file-processing/4-mkzip)的形式：

1. 将下列地址的三个文件压缩上传到空间中， 压缩后的文件名字为 `mode4.zip` ：

* `http://ogtoywd4d.bkt.clouddn.com/resource/gogopher.jpg`
* `http://ogtoywd4d.bkt.clouddn.com/resource/dive-into-golang.pptx`
* `http://ogtoywd4d.bkt.clouddn.com/resource/thinking-in-go.mp4`

2. 默认这三个文件在压缩文件中的名字分别为 gogopher.jpg、 dive-into-golang.pptx、thinking-in-go.mp4。
3. 假如我们想将 `http://ogtoywd4d.bkt.clouddn.com/resource/gogopher.jpg`  保存在压缩文件中的名字替换为`mkziptest`。
4. 那么最后的索引文件格式为[mkzip-index.txt](http://ogtoywd4d.bkt.clouddn.com/index)，这个时候我们需要上传改索引文件到您要保存的bucket中， 假如保存在bucket中的文件名字为`mkzip-index.txt`，那么最后的请求命令如下：

```
POST /pfop/ HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: QBox <AccessToken>

bucket=qiniu-developer&key=mkzip-index.txt&fops=mkzip/4/|saveas/cWluaXUtZGV2ZWxvcGVyOm1remlwNC56aXA=
```

其中 cWluaXUtZGV2ZWxvcGVyOm1remlwNC56aXA= 是由 qiniu-developer:mkzip4.zip 经过 URL 安全的 Base64 编码生成。

# **操作方式** [#操作方式]

多文件压缩接口，目前只能以 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 形式来使用。


# HTML转MD（html2md） (/products/dora/file-processing/5-html2md)



最近更新时间: 2026-03-10 16:28:42

# 简介 [#简介]

七牛云智能多媒体服务支持将 HTML 类型的资源转为 Markdown 文件并返回。该接口可对七牛云存储上的 HTML 资源进行在线转换，也可通过管道与其他数据处理接口搭配使用。

# 接口规格 [#接口规格]

**注意：** 接口规格不含任何空格与换行符。

```
html2md
```

该接口无额外参数，直接对输入的 HTML 内容进行转换。

## 请求 [#请求]

### 请求报文格式 [#请求报文格式]

```
GET <DownloadURI>?html2md HTTP/1.1
```

## 响应 [#响应]

### 响应报文格式 [#响应报文格式]

```
HTTP/1.1 200 OK
Content-Type: text/markdown

<Markdown 内容>
```

### 响应头部信息 [#响应头部信息]

| 头部名称         | 说明                                      |
| :----------- | :-------------------------------------- |
| Content-Type | 转换成功时为 `text/markdown`；降级处理时为原始 MIME 类型 |

### 响应状态码 [#响应状态码]

| 状态码 | 说明                    |
| :-- | :-------------------- |
| 200 | 转换成功，或触发降级处理时原样返回输入内容 |
| 570 | 读取输入源失败               |

# 附注 [#附注]

## 支持的输入类型 [#支持的输入类型]

输入 MIME 类型须为 `text/html`（含 charset 参数，如 `text/html; charset=utf-8`）。若输入非 `text/html` 类型，将原样返回输入内容。

## 支持的 HTML 元素 [#支持的-html-元素]

| HTML 元素                                                                        | 转换结果                          |
| :----------------------------------------------------------------------------- | :---------------------------- |
| `&lt;h1&gt;` - `&lt;h6&gt;`                                                    | `#` - `######`（ATX 风格标题）      |
| `&lt;br /&gt;`                                                                 | 段落                            |
| `&lt;strong&gt;` / `&lt;b&gt;`                                                 | `**加粗**`                      |
| `&lt;em&gt;` / `&lt;i&gt;`                                                     | `*斜体*`                        |
| `&lt;a href="url"&gt;`                                                         | `[文字](url)`                   |
| `&lt;img src="url" alt="描述"&gt;`                                               | `![描述](url)`                  |
| `&lt;ul&gt;` / `&lt;ol&gt;`                                                    | 无序列表 (`-`) / 有序列表 (`1.`)      |
| `&lt;code&gt;` / `&lt;var&gt;` / `&lt;samp&gt;` / `&lt;kbd&gt;` / `&lt;tt&gt;` | `` `行内代码` ``                  |
| `&lt;pre&gt;&lt;code&gt;`                                                      | 围栏代码块（支持 `language-xxx` 语言标识） |
| `&lt;blockquote&gt;`                                                           | `> 引用`                        |
| `&lt;table&gt;`                                                                | Markdown 表格                   |
| `&lt;hr&gt;`                                                                   | `* * *`（分隔线）                  |
| `&lt;br&gt;`                                                                   | 两个空格 + 换行                     |

以下 HTML 元素会被**完全移除**（连同其内容）：

`<head>`、`<script>`、`<style>`、`<link>`、`<meta>`、`<iframe>`、`<noscript>`、`<input>`、`<textarea>`、HTML 注释。

## 降级处理 [#降级处理]

该服务对异常情况采用降级策略，不会返回错误，而是原样返回输入内容：

| 场景                      | 行为     |
| :---------------------- | :----- |
| 输入 MIME 类型非 `text/html` | 原样返回输入 |
| 输入大小超过限制（默认 2MB）        | 原样返回输入 |
| 转换超时（默认 30 秒）           | 原样返回输入 |
| 转换过程中出错                 | 原样返回输入 |

仅在无法读取输入源时返回错误码 **570**。

## 计量说明 [#计量说明]

该接口采用**按次计量**方式，仅对实际执行转换处理的请求进行计量。降级场景不计量。
注： beta测试阶段暂不收费。

# 示例 [#示例]

## 示例 1：基本转换 [#示例-1基本转换]

输入 HTML：

```html
<h1>标题</h1>
<p>这是一段<strong>加粗</strong>和<em>斜体</em>文字。</p>
<a href="https://example.com">链接</a>
```

返回 Markdown：

```markdown
# 标题

这是一段**加粗**和*斜体*文字。

[链接](https://example.com)
```

## 示例 2：列表与代码 [#示例-2列表与代码]

输入 HTML：

```html
<ul>
  <li>项目 1</li>
  <li>项目 2</li>
</ul>
<pre><code class="language-python">
def hello():
    print("world")
</code></pre>
```

返回 Markdown：

````markdown
- 项目 1
- 项目 2

```python
def hello():
    print("world")
```
````

## 示例 3：表格 [#示例-3表格]

输入 HTML：

```html


| 姓名 | 年龄 |
| --- | --- |
| Alice | 30 |
| Bob | 25 |


```

返回 Markdown：

```markdown
| 姓名 | 年龄 |
| --- | --- |
| Alice | 30 |
| Bob | 25 |
```

# 操作方式 [#操作方式]

html2md 支持以下两种调用方式：

| 操作方式  | 说明                                    |
| :---- | :------------------------------------ |
| 持久化处理 | 上传时触发（`persistentOps`）或对已有资源手动触发 pfop |
| 同步处理  | 对资源 URL 直接拼接接口规格进行即时转换                |

## 管道调用 [#管道调用]

html2md 可作为管道中的下游处理节点，与其他数据处理接口组合使用：

```
?cmds=<上游接口规格>|html2md&url=<资源URL>
```

例如，先由上游接口输出 HTML 内容，再通过 html2md 转为 Markdown。


# 智能音频流审核 (/products/dora/intelligent-voice/0-intelligent-audio-stream-audit)



最近更新时间: 2022-03-04 15:45:15

# 接口简介 [#接口简介]

音频流审核功能为音频流的内容审核场景提供涉政，国歌，色情，广告，娇喘，音色标签，唱歌等内容的识别，并且可以依据具体的业务场景进行配置，帮助您提前防御内容风险，提高审核效率，净化网络环境，提升用户体验。

# 接口规格 [#接口规格]

## 提交音频流识别请求 [#提交音频流识别请求]

**请求URL**: `https://censor-open.qiniuapi.com/anti_fraud/v2/audiostream`

**字符编码格式**: 请求及返回结果都使用 UTF-8 字符集进行编码

**请求方法**: POST

**建议超时时长**: 3s

**请求头部**:

| 字段            | 取值                                                                                                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Content-Type  | application/json                                                                                                                                                               |
| Authorization | Qiniu\&lt;AccessKey>:\&lt;Sign> <br />&#x2A;*注意:** 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。\&lt;Sign> 的取值请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken) |

**请求参数**: 放在 HTTP Body 中，采用 json 格式，具体参数如下:

| 参数名称     | 类型           | 是否必选 | 说明                                                                                                                                                                                                                        |
| -------- | ------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type     | string       | Y    | 需要识别的违规类型，可选值:<br />POLITICAL:涉政识别<br />ANTHEN:国歌识别<br />PORN:色情识别<br />AD:广告识别<br />MOAN:娇喘识别<br />SING:唱歌识别<br />如需做组合识别，通过下划线连接即可，例如AD\_PORN\_POLITICAL用于广告、色情和涉政识别。<br />DEFAULT: 默认取值<br />POLITICAL\_PORN\_MOAN\_AD |
| data     | json\_object | Y    | 请求数据，最长1MB，详细内容参见下表                                                                                                                                                                                                       |
| callback | string       | Y    | 异步检测结果回调通知您的 URL，支持 HTTP 和 HTTPS                                                                                                                                                                                          |

其中，data的内容如下:

| 参数名称             | 类型           | 是否必选 | 说明                                                                                                    |
| ---------------- | ------------ | ---- | ----------------------------------------------------------------------------------------------------- |
| streamType       | string       | Y    | 流类型:可选择： <br />流地址：NORMAL <br />声网录制：AGORA <br />即构录制：ZEGO <br />腾讯录制：TRTC                            |
| url              | string       | N    | 要检测的音频流 url 地址（当 streamType 为 NORMAL 时必传）                                                             |
| agoraParam       | json\_object | N    | 声网录制参数（当 streamType 为 AGORA 时必传），详见扩展参数                                                               |
| zegoParam        | json\_object | N    | 即构录制参数（当 streamType 为ZEGO时必传），详见扩展参数                                                                  |
| trtcParam        | json\_object | N    | 腾讯录制参数（当 streamType 为 TRTC时必传），详见扩展参数                                                                 |
| tokenId          | string       | Y    | 客户端用户账号唯一标识                                                                                           |
| channel          | string       | Y    | 见下文渠道配置表                                                                                              |
| room             | string       | N    | 房间号，建议传入                                                                                              |
| returnAllText    | bool         | N    | 值为 true 时，返回全量的音频流片段识别结果和文本内容<br />值为 false 时，只返回有风险（riskType 为 REJECT）的音频流片段识别结果和文本内容<br />默认是 false |
| returnPreText    | bool         | N    | 值为 true 时，返回的 content 字段包含违规音频前一分钟文本内容<br />值为 false 时，返回的 content 字段只包含违规音频片段文本内容<br />默认值为 false    |
| returnPreAudio   | bool         | N    | 值为 true时，返回违规音频前一分钟音频链接。<br />值为 false时 ，只返回违规片段音频链接。<br />默认值为 false                                 |
| returnFinishInfo | bool         | N    | 音频流结束通知，可选值：<br />false: 不返回状态码<br />true: 回调参数增加 statCode 状态码<br />默认值为 false                        |
| initDomain       | int          | N    | 当即构客户端初始化传入隔离域名该字段必传<br />可选值： <br />1：客户端初始化有隔离域名                                                    |

其中data.agoraParam内容如下：

| 参数名称            | 类型     | 是否必选 | 说明                                                                                                                                                                                                                              |
| --------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| appId           | string | Y    | 声网提供的 appId                                                                                                                                                                                                                     |
| channel         | string | Y    | 声网提供的频道名                                                                                                                                                                                                                        |
| token           | string | N    | 安全要求较高的用户可以使用Token进行认证，生成方式详见声网文档：<br />[https://docs.agora.io/cn/Interactive%20%20Broadcast/token\_server?platform=All%20Platforms](https://docs.agora.io/cn/Interactive%20%20Broadcast/token_server?platform=All%20Platforms) |
| uid             | int    | N    | 用户id，32位无符号整数。<br />当token存在时，必须提供生成token时所使用的用户ID。<br />注意，此处需要区别实际房间中的用户uid，提供给服务端录制所用的 uid 不允许在房间中存在。                                                                                                                        |
| isMixingEnabled | bool   | N    | 分流/合流录制，默认合流录制<br />值为 true:合流 <br />值为 false:分流 <br />合流是指一个直播房间一路流，分流是指一个麦位一路流                                                                                                                                                |
| channelProfile  | int    | N    | 声网录制的频道模式，取值： <br />0: 通信，即常见的 1 对 1 单聊或群聊，频道内任何用户可以自由说话； <br />1: 直播，有两种主播和观众两种用户角色。 <br />默认值为0，即默认以通信模式录制。                                                                                                                   |

其中data.zegoParam内容如下

| 参数名称     | 类型     | 是否必选 | 说明                                                                                                                  |
| -------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------- |
| tokenId  | string | Y    | zego 提供的身份验证信息，用于 token 登陆                                                                                          |
| streamId | string | N    | 用户设置的音频流编号，唯一对应一路音频流，streamId 与 roomId 至少存在其中之一， 如果 streamId 与 roomId 同时存在， streamId 有效；当 streamId 生效时，服务端以用户为单位拉流。 |
| roomId   | string | N    | 用户设置的房间编号，唯一对应一个房间， streamId 与 roomId 至少存在其中之一，如果 streamId 与 roomId 同时存在，streamId 有效；当 roomId 生效时，服务端以房间为单位拉流。      |
| testEnv  | bool   | Y    | 是否使用 zego 测试环境：<br />值为true 时：测试环境，<br />值为false 时：正式环境。<br />默认值为 false                                            |

其中data.trtcParam内容如下

| 参数名称       | 类型     | 是否必选 | 说明                                                                                                            |
| ---------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------- |
| sdkAppId   | int    | Y    | 腾讯提供的 sdkAppId                                                                                                |
| demoSences | int    | Y    | 录制类型可选值：<br />分流录制：2\<br>合流录制：4                                                                               |
| userId     | string | Y    | 分配给录制段的 userId，限制长度为 32bit，只允许包含（a-z，A-Z），数字(0-9)以及下划线和连词符                                                    |
| userSig    | string | Y    | 录制 userId 对应的验证签名，相当于登录密码                                                                                     |
| roomId     | int    | N    | 房间号码，取值范围：【1-4294967294】<br />roomId 与 strRoomId 必传一个，若两者都有，值优先选用 roomId                                      |
| strRoomId  | string | N    | 房间号码，取值说明：<br />只允许包含（a-z，A-Z），数字(0-9)以及下划线和连词符<br />若您选用 strRoomId ，需注意 strRoomId 和roomId 两者都有时，值优先选用 roomId |

其中，渠道配置表的内容如下：

| 业务场景 | channel取值   | 备注       |
| ---- | ----------- | -------- |
| 语音房  | VOICE\_ROOM | 多人连麦语音房  |
| 直播间  | LIVE\_ROOM  | 视频直播间    |
| 语音聊天 | VOICE\_CHAT | 两人语音聊天通话 |

**返回参数**: 放在 HTTP Body 中，采用 json 格式，具体参数如下：

| 参数名称    | 类型     | 是否必选 | 说明      |
| ------- | ------ | ---- | ------- |
| code    | int    | Y    | 返回码     |
| message | string | Y    | 返回码详情描述 |
| entryId | string | Y    | 请求唯一标识  |

## 异步回调识别结果 [#异步回调识别结果]

**回调策略：** 当用户收到推送结果，并返回 HTTP 状态码为 200 时，表示推送成功；否则系统将进行最多 12 次推送。

**请求方法：** POST

**字符编码格式：** 请求及返回结果都使用 UTF-8 字符集进行编码

**回调参数：** 放在 HTTP Body 中，采用 json 格式，具体参数如下：

| 参数名称      | 类型           | 是否必选 | 说明                                                                                                                            |
| --------- | ------------ | ---- | ----------------------------------------------------------------------------------------------------------------------------- |
| code      | int          | Y    | 返回码                                                                                                                           |
| message   | string       | Y    | 返回码详情描述                                                                                                                       |
| entryId   | string       | Y    | 请求唯一标识                                                                                                                        |
| score     | int          | N    | 风险分数（code 为 1100 且 riskLevel=REJECT时存在）<br />取值范围\[0,1000]，分数越高风险越大                                                           |
| riskLevel | string       | Y    | 风险级别（code 为 1100 时存在） <br />可能返回值：PASS，REVIEW，REJECT <br />PASS：正常内容，建议直接放行 <br />REVIEW：可疑内容，建议人工审核 <br />REJECT：违规内容，建议直接拦截 |
| statCode  | int          | N    | 审核状态：<br />0 : 审核中<br />1 : 审核结束                                                                                              |
| detail    | json\_object | Y    | 风险详情                                                                                                                          |

其中 detail 的内容如下:

| 参数名称              | 类型           | 是否必选 | 说明                                                                                                                                                                                                                          |
| ----------------- | ------------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| beginProcessTime  | int          | Y    | 开始处理的时间（13 位时间戳）                                                                                                                                                                                                            |
| finishProcessTime | int          | Y    | 结束处理的时间（13 位时间戳）                                                                                                                                                                                                            |
| audioUrl          | string       | Y    | 音频片段地址，returnAllText 不传或为 false时只返回违规音频片段地址，<br />returnAllText 为 true 时返回所有音频片段地址                                                                                                                                          |
| preAudioUrl       | string       | N    | 违规内容前 1 分钟音频片段地址（该参数只有在请求参数中 returnPreAudio 是 true 情况下存在）                                                                                                                                                                   |
| audio\_endtime    | string       | Y    | 违规内容结束时间（绝对时间）                                                                                                                                                                                                              |
| audio\_starttime  | string       | Y    | 违规内容开始时间（绝对时间）                                                                                                                                                                                                              |
| audioText         | string       | Y    | 音频片段文本                                                                                                                                                                                                                      |
| content           | string       | N    | returnPreText 为 true 时返回违规内容前一分钟文本和违规内容片段文本                                                                                                                                                                                 |
| description       | string       | Y    | 策略规则风险原因描述<br />注：该参数为旧版 API 返回参数，兼容保留，后续版本将去除，请勿依赖此参数，仅供参考                                                                                                                                                                 |
| descriptionV2     | string       | Y    | 策略规则风险原因描述<br />注：该参数为 API 返回参数，请勿依赖此参数，仅供参考                                                                                                                                                                                |
| matchedItem       | string       | N    | 命中的具体敏感词（该参数仅在命中敏感词时存在）                                                                                                                                                                                                     |
| matchedList       | string       | N    | 命中敏感词所在的名单名称（该参数仅在命中敏感词时存在）                                                                                                                                                                                                 |
| hits              | json\_array  | Y    | 展示风险详情，请勿依赖此参数，仅供参考                                                                                                                                                                                                         |
| model             | string       | Y    | 规则标识，用来标识文本命中的策略规则。<br />注：该参数为旧版 API 返回参数，兼容保留，后续版本将去除，请勿依赖此参数，仅供参考                                                                                                                                                        |
| isSing            | int          | N    | type 取值包含 SING 时存在：<br />取值 0 ：表示检测不存在唱歌片段<br />取值 1 ：表示检测存在唱歌片段                                                                                                                                                            |
| requestParams     | json\_object | Y    | 返回请求参数 data 中的所有字段                                                                                                                                                                                                          |
| riskType          | int          | Y    | 标识风险类型，静音时不返回，可能取值：<br />0：正常<br />100：涉政<br />110: 暴恐<br />120: 国歌<br />200：色情<br />210：辱骂<br />250：娇喘<br />300：广告<br />400：灌水<br />500：无意义<br />600 : 违禁<br />700：其他<br />720：黑账号<br />730：黑 IP\<br>800：高危账号<br />900：自定义 |
| riskTypeDesc      | string       | N    | 风险原因描述                                                                                                                                                                                                                      |
| room              | string       | Y    | 房间号                                                                                                                                                                                                                         |
| userId            | int          | N    | 用户账号标识（仅分流情况下存在）。<br />返回的userId 是实际房间中的用户 id，与请求参数中的 uid 无关。                                                                                                                                                               |
| vadCode           | int          | N    | 静音状态：<br />0 ：静音片段<br />1 ：非静音片段                                                                                                                                                                                            |

code 和 message 的列表如下:

| code | message |
| ---- | ------- |
| 1100 | 成功      |
| 1902 | 参数不合法   |
| 1903 | 服务失败    |
| 9100 | 余额不足    |
| 9101 | 无权限操作   |

## 音频流关闭通知接口 [#音频流关闭通知接口]

**接口描述：** 该接口用于客户端通知服务端某个音频流已关闭

**请求 URL：** `https://censor-open.qiniuapi.com/anti_fraud/v2/finish_audiostream`

**字符编码格式：** 请求及返回结果都使用 UTF-8 字符集进行编码

**请求方法：** POST

**建议超时时长：** 1s

**请求头部**:

| 字段            | 取值                                                                                                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Content-Type  | application/json                                                                                                                                                               |
| Authorization | Qiniu\&lt;AccessKey>:\&lt;Sign> <br />&#x2A;*注意:** 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。\&lt;Sign> 的取值请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken) |

**请求参数：** 放在HTTP Body中，采用json格式，具体参数如下：

| 参数名称    | 类型     | 是否必选 | 说明     |
| ------- | ------ | ---- | ------ |
| entryId | string | Y    | 请求唯一标识 |

**返回参数：** 放在HTTP Body中，采用json格式，具体参数如下：

| 参数名称    | 类型     | 是否必选 | 说明      |
| ------- | ------ | ---- | ------- |
| code    | int    | Y    | 返回码     |
| message | string | Y    | 返回码详细描述 |

# 示例 [#示例]

## 请求示例 [#请求示例]

```js
POST /anti_fraud/v2/audiostream HTTP/1.1
Host: censor-open.qiniuapi.com
Content-Type: application/json
Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=

{
    "type": "POLITICAL_PORN_MOAN_ABUSE_AD",
    "data": {
        "streamType":"NORMAL",
        "url": "rtmp://xxx.co/test/test1?sign=xxx",
        "audioName": "xxxxxx",
        "returnAllText": true
    },
    "callback": "http://xxx.test/audio-stream-callback"
}

```

## 返回示例 [#返回示例]

```js
HTTP/1.1 200 OK
Content-Type: application/json

{
    "code":1100,
    "message":"成功",
    "entryrid":"5564f430ee6a1adb40f06d768b40316b",
}

```

## 回调示例 [#回调示例]

```js
POST /xxxx HTTP/1.1
Host: xxxx
Content-Type: application/json

{
    "code":1100,
    "message":"成功",
    "riskLevel":"PASS",
    "detail":{
        "beginProcessTime":1629773218229,
        "finishProcessTime":1629773218808,
        "audioUrl":"https://xxx.mp3",
        "audio_endtime":"2021-08-24 10:46:48",
        "audio_starttime":"2021-08-24 10:46:38",
        "audioText":"这是音频内容",
        "content":"这是音频内容",
        "description":"正常",
        "hits":[
        ],
        "model":"M1000",
        "requestParams":{
            "audioName":"xxxxxx",
            "returnAllText":true,
            "returnPreAudio":true,
            "returnPreText":true,
            "room":"",
            "streamType":"NORMAL",
            "tokenId":"1234",
            "url":"rtmp://xxx.co/test/test1?sign=xxx"
        },
        "riskTypeDesc":"正常",
        "room":"",
        "userId":0,
        "vadCode":1
    }
}
```

# 错误码 [#错误码]

| code | message |
| ---- | ------- |
| 1100 | 成功      |
| 1902 | 参数不合法   |
| 1903 | 服务失败    |
| 9100 | 余额不足    |
| 9101 | 无权限操作   |

# 价格 [#价格]

1.2元/小时


# 长语音识别 (/products/dora/intelligent-voice/1-long-speech-recognition)



最近更新时间: 2026-04-14 14:11:04

# 长语音识别 [#长语音识别]

长语音识别可对用户指定的语音文件进行识别，针对请求的语音返回文本，可用于会议语音资料转写、客服语音质检等各类场景。

## 使用限制 [#使用限制]

* 支持的音频文件格式：wav、ogg、mp3、mp4
* 支持的音频编码：opus、mp3 或 raw/pcm 格式
* 音频时长不超过 5 小时
* 音频大小不超过 512MB

## 使用方式 [#使用方式]

使用方式分成2步:

1. 提交长语音转写任务
2. 接收回调结果

## 返回延迟 [#返回延迟]

3 小时内返回识别文本

非忙时1小时音频可在12分钟返回识别结果，其他时长等比估算

## 一. 提交长语音转写任务 [#一-提交长语音转写任务]

**请求URL**: `https://yitu-audio.qiniuapi.com/v4/lasr`

**请求方式**: `POST`

**请求 Header**:

| 字段            | 取值                                                                                                                                                                      |
| :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | application/json                                                                                                                                                        |
| Authorization | Qiniu \&lt;AccessKey>:\&lt;Sign> <br />注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。\&lt;Sign> 的取值请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken) |

**请求 Body**:

| 字段           | 类型          | 是否必选 | 说明                         |
| :----------- | :---------- | :--- | :------------------------- |
| audioUrl     | string      | Y    | 音频文件的url                   |
| callback     | string      | N    | 支持http/https, 填写后可通过回调获取结果 |
| filedata     | json object | N    | 设置关于文件的编码和码率等              |
| speechConfig | json object | N    | 转写的相关配置                    |

其中`filedata`结构体为

| 字段              | 类型     | 是否必选 | 说明                       |
| :-------------- | :----- | :--- | :----------------------- |
| aue             | string | N    | 音频编码。参考文档首页的格式。          |
| lang            | string | N    | 文件的语言，默认为MANDARIN，中文普通话。 |
| sampleRateHertz | int    | N    | 采样频率。                    |
| audioName       | string | N    | 用来标识文件的文件名               |

其中`speechConfig`结构体为

| 字段             | 类型     | 是否必选 | 说明                                                                                     |
| :------------- | :----- | :--- | :------------------------------------------------------------------------------------- |
| scene          | string | N    | 场景。默认为GERNERL                                                                          |
| byWords        | bool   | N    | 逐字输出开关。<br />默认false，逐句输出。<br />true，开启后带有逐字模式。                                        |
| addPunctuation | bool   | N    | 标点开关。默认true，表示开启加标点，输出带标点                                                              |
| convertNumber  | bool   | N    | 数字符号统一。<br />默认为true，开启数字为统一为阿拉伯数字。<br />false 为汉字 一二三四五六七八九十。                         |
| numOfSpeakers  | int    | N    | 说话人分离功能<br />默认为1，一位说话人，不返回speakerIds.\<br>0 表示盲分。<br />2-4时，表示指定了说话人的数量，返回speakerIds. |
| disfluency     | bool   | N    | 顺滑标识开关。<br />默认false，关闭顺滑标识。                                                           |

### 请求示例 [#请求示例]

```json
{
    "audioUrl":"https://cdnfile.mp3",
    "callback":"https://callbackurl.com",
    "filedata":{
        "aue":"wav",
        "lang":"MANDARIN",
        "sampleRateHertz":"16000",
        "audioName":"这是一个示例文件.amr"
    },
    "speechConfig":{
        "scene":"GERNERL",
        "byWords":true,
        "addPunctuation":true,
        "numOfSpeakers":1,
        "convertNumber":true
    }
}
```

**返回参数**

| 字段        | 类型     | 是否必选 | 说明                       |
| :-------- | :----- | :--- | :----------------------- |
| rtn       | int    | Y    | 请求处理结果的状态码，0表示成功，否则表示异常。 |
| message   | string | Y    | 请求处理结果的debug提示信息         |
| taskId    | string | Y    | 任务ID,可用来查询和停止任务。         |
| requestId | string | Y    | 请求的唯一标示符                 |

### 返回示例 [#返回示例]

```json
{
    "rtn": 0,
    "message": "ok",
    "taskId": "4a3d3643-1712-4441-a5ae-7a5b26e3afc7",
    "audio": "8754c3a3-de2c-4c6b-a313-34c548681904"
}
```

## 二. 接收回调结果 [#二-接收回调结果]

回调参数以json形式组织，作为请求内容提交

**请求方式**: `POST`

**请求 Header**:

| 字段           | 取值               |
| :----------- | :--------------- |
| Content-Type | application/json |

**请求 Body**:

回调 Body 与查询转写任务 API 的返回参数完全一致。

## 三. 查询转写任务 [#三-查询转写任务]

**请求URL**: `https://yitu-audio.qiniuapi.com/v4/lasr/<taskId>`

**请求方式**: `GET`

**请求 Header**:

| 字段            | 取值                                                                                                                                                                      |
| :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Qiniu \&lt;AccessKey>:\&lt;Sign> <br />注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。\&lt;Sign> 的取值请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken) |

**HTTP PATH 参数**

| 字段     | 类型     | 是否必选 | 说明       |
| :----- | :----- | :--- | :------- |
| taskId | string | Y    | 转写任务的 id |

**返回参数**:

| 字段        | 类型          | 是否必选 | 说明                       |
| :-------- | :---------- | :--- | :----------------------- |
| rtn       | int         | Y    | 请求处理结果的状态码，0表示成功，否则表示异常。 |
| message   | string      | Y    | 请求处理结果的debug提示信息         |
| taskId    | string      | Y    | 任务ID,可用来查询和停止任务。         |
| requestId | string      | Y    | 请求的唯一标示符                 |
| data      | json object | N    | 识别结果。当rtn=0时，此结构存在。      |

其中`data`结构体为

| 字段           | 类型          | 是否必选 | 说明                                                                                                                          |
| :----------- | :---------- | :--- | :-------------------------------------------------------------------------------------------------------------------------- |
| statusCode   | int         | N    | 转写任务状态<br />0-LOADING - 文件加载中。<br />1-QUEUEING - 排队中。<br />2-PROGRESSING - 正在转写。<br />3-TASK\_SUCC - 转写完成。<br />回调时仅可见转写完成。 |
| statusText   | string      | N    | 对应任务状态的文本信息。                                                                                                                |
| speechResult | json object | N    | 转写识别结果。<br />status为转写完成时，此结构存在                                                                                             |

其中`speechResult`结构体为

| 字段         | 类型           | 是否必选 | 说明                |
| :--------- | :----------- | :--- | :---------------- |
| resultText | string       | N    | 转写的结果文本全部输出。      |
| duration   | int          | N    | 音频文件的时长。单位 ms     |
| detail     | object array | N    | 转写输出的句或者字的详细数据信息。 |

其中`detail`结构体为

| 字段         | 类型           | 是否必选 | 说明                                       |
| :--------- | :----------- | :--- | :--------------------------------------- |
| sentences  | string       | N    | 每句的转写结果                                  |
| startTime  | string       | N    | 每句的开始时间。音频起始点为0。单位ms\<br>如果关闭时间戳定位功能，不返回 |
| endTime    | string       | N    | 每字或每句结束时间。<br />如果关闭时间戳定位功能，不返回          |
| speakerId  | string       | Y    | 每句的说话人Id。                                |
| wordsPiece | object array | Y    | 句中所对应的每字信息。开启byWords时，返回wordsPiece部分。    |

其中`wordsPiece`结构体为

| 字段        | 类型     | 是否必选 | 说明           |
| :-------- | :----- | :--- | :----------- |
| words     | string | N    | 每字的文本信息      |
| startTime | string | N    | 每字的开始时间。单位ms |
| endTime   | string | N    | 每字的结束时间。单位ms |

### 返回示例 [#返回示例-1]

```json
{
    "rtn": 0,
    "message": "ok",
    "taskId": "4a3d3643-1712-4441-a5ae-7a5b26e3afc7",
    "requestId": "8754c3a3-de2c-4c6b-a313-34c548681904",
    "data":{
        "statusCode":3,
        "statusText":"TASK_SUCC",
        "speechResult":{
            "resultText":"今天天气真的很不错。说的对！今天天气真的是棒呆了。",
            "duration":34567892,
            "detail":[
                {
                    "sentences":"今天天气真的很不错。",
                    "startTime":"0",
                    "endTime":"1600",
                    "speakerId":"1",
                    "wordsPiece":[
                        {
                            "words":"今",
                            "startTime":"0",
                            "endTime":"200"
                        },
                        {
                            "words":"天",
                            "startTime":"200",
                            "endTime":"400"
                        },
                        {
                            "words":"天",
                            "startTime":"400",
                            "endTime":"600"
                        },
                        {
                            "words":"。",
                            "startTime":"200",
                            "endTime":"400"
                        }
                    ]
                },
                {
                    "sentences":"棒呆了。",
                    "startTime":"0",
                    "endTime":"1600",
                    "speakerId":"2",
                    "wordsPiece":[
                        {
                            "words":"棒",
                            "startTime":"0",
                            "endTime":"200"
                        },
                        {
                            "words":"呆",
                            "startTime":"200",
                            "endTime":"400"
                        },
                        {
                            "words":"了",
                            "startTime":"400",
                            "endTime":"600"
                        },
                        {
                            "words":"。",
                            "startTime":"200",
                            "endTime":"400"
                        }
                    ]
                }
            ]
        }
    }
}
```


# 短语音听写 (/products/dora/intelligent-voice/2-short-dictation)



最近更新时间: 2026-05-25 18:19:35

短语音听写接口可将时长不超过60秒的音频文件转写成文字，可适用于手机语音输入、智能语音交互、语音指令、语音搜索等短语音交互场景。

### 使用限制 [#使用限制]

* 使用前请联系 [技术支持](https://support.qiniu.com/tickets/create) 开通使用权限
* 音频推荐使用wav格式，采样率为16000Hz，声道为单声道; 其他格式会有额外预处理开销，增加响应时间

### 支持格式 [#支持格式]

* 支持的音频文件格式：mp3、wav、ogg、aac、m4a
* 包含音频的视频文件格式：avi、flv、mp4、asf、wmv、mov

### 支持音频文件详情 [#支持音频文件详情]

* 音频时长不超过60秒
* 音频声道：单声道、双声道
* 文件 base64 编码后不超过 10MB
* 采样率：8000/16000/44100/48000 Hz

# 请求参数 [#请求参数]

**请求方式**: POST
**请求URL**: `http://yitu-audio.qiniuapi.com/v2/asr`
**请求 Header**:

| 字段            | 取值                                                                                                                                                                      |
| :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | application/json                                                                                                                                                        |
| Authorization | Qiniu \&lt;AccessKey>:\&lt;Sign> <br />注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。\&lt;Sign> 的取值请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken) |

**请求 Body**:

| 参数名         | 类型     | 是否必须 | 描述                                               |
| :---------- | :----- | :--- | :----------------------------------------------- |
| audioUrl    | string | 否    | audioUrl和audioBase64必须二选一。 音频文件的URL，支持http和https |
| audioBase64 | string | 否    | audioUrl和audioBase64必须二选一。音频数据, 标准的 base64 编码    |
| lang        | string | 否    | 仅支持“MANDARIN”普通话                                 |
| scene       | string | 否    | 通用情景模式GENERAL，即针对不同应用场景的定制模型。当前默认支持GENERAL       |

# 返回参数 [#返回参数]

| 参数名        | 类型      | 说明                      |
| :--------- | :------ | :---------------------- |
| rtn        | integer | 请求处理结果的状态码，0表示成功，否则表示异常 |
| message    | string  | 请求处理结果的debug提示信息        |
| requestId  | string  | 请求的唯一标示符                |
| resultText | string  | 转写结果                    |

# 调用示例-Python [#调用示例-python]

下载依赖:

```
pip install qiniu
pip install requests
```

```
# -*- coding: utf-8 -*-

import json

import requests
import qiniu
from qiniu import QiniuMacAuth, http, config

# Please paste your ak and sk here.
access_key = 'ak'
secret_key = 'sk'
auth = QiniuMacAuth(access_key, secret_key)

def _post_with_qiniu_mac(url, data, auth):
    qn_auth = qiniu.auth.QiniuMacRequestsAuth(auth) if auth is not None else None

    timeout = config.get_default('connection_timeout')

    try:
        r = requests.post(
            url,
            json=data,
            auth=qn_auth,
            timeout=timeout,
            )

        print(r.json())
    except Exception as e:
        return None, http.ResponseInfo(None, e)

    return http.__return_wrapper(r)

def asr_request(data):
    url = "http://yitu-audio.qiniuapi.com/v2/asr"

    body = {
        "audioUrl": data,
    }

    ret, res = _post_with_qiniu_mac(url, body, auth)

    return ret, res

if __name__ == '__main__':

    audio_url = "http://r3dg6y3l0.hd-bkt.clouddn.com/Temp/sample_1.wav"

    ret, res = asr_request(audio_url)

    headers = {"code": res.status_code, "reqid": res.req_id, "xlog": res.x_log}

    print(json.dumps(headers, indent=4, ensure_ascii=False))


```

# 状态码 [#状态码]

| rtn  | 说明                 | message                                                               |
| :--- | :----------------- | :-------------------------------------------------------------------- |
| 1000 | 超时                 | SAAS\_TIME\_OUT                                                       |
| 1101 | 无法解析请求中的Json       | SAAS\_JSON\_CONFIG\_HELPER\_READ\_ERROR                               |
| 1102 | 输入的字段错误，根据提示更换字段参数 | SAAS\_INVALID\_SCENE\_ERROR   SAAS\_INVALID\_PARAMETER\_ERROR         |
| 1103 | 输入中缺少某个域           | SAAS\_JSON\_CONFIG\_HELPER\_GIVEN\_KEY\_NOT\_EXIST\_ERROR             |
| 1999 | 未知错误               | SAAS\_UNEXPECTED\_ERROR                                               |
| 4201 | 音频文件错误             | Audio DownLoad Error   SAAS\_SPEECH\_AUDIOFILE\_INCORRECT             |
| 4202 | 无法下载的文件            | SAAS\_SPEECH\_FILEDOWNLOAD\_ERROR                                     |
| 4203 | 文件处理异常，请联系管理员      | SAAS\_SPEECH\_ASR\_BUSY                                               |
| 4204 | 不支持的编码格式           | SAAS\_AUE\_NOT\_MEET\_REQUIREMENT\_ERROR                              |
| 4208 | 不存在的TASKID         | SAAS\_SPEECH\_INVALID\_TASKID\_ERROR                                  |
| 4209 | 音频片缺失，无法解析         | SAAS\_SPEECH\_MISSING\_SLICE\_ERROR                                   |
| 4210 | 文件长度太大             | audio length too long...SAAS\_SPEECH\_AUDIO\_LENGTH\_TOO\_LONG\_ERROR |
| 4211 | 文件长度过短             | SAAS\_SPEECH\_AUDIO\_LENGTH\_TOO\_SHORT\_ERROR                        |
| 4214 | 无法解析的内容，请联系管理员     | SAAS\_SPEECH\_ASR\_RECOGNI                                            |


# 图片EXIF信息（exif） (/products/dora/image-processing-api/0-photo-exif-information-exif)



最近更新时间: 2025-09-10 17:53:22

# **简介** [#简介]

[EXIF(EXchangeable Image File Format)](http://zh.wikipedia.org/wiki/Exif) 是专门为数码相机的照片设定的可交换图像文件格式。

## **使用限制** [#使用限制]

* 缩略图等经过云处理的新图片不支持 EXIF
* 原图格式为 `avif`、`heif` 不支持 EXIF
* 原图只支持 20MB 以内的图片

# **接口规格** [#接口规格]

**注意**：接口规格不含任何空格与换行符。

```
exif/version/<version>
```

| 参数名称              | 必填 | 说明                       |
| ----------------- | -- | ------------------------ |
| `&lt;version&gt;` | 否  | 仅当定义为 `v2` 时，会获取 exif 信息 |

<br />

# **示例** [#示例]

在Web浏览器中输入以下图片地址：

1.获取不包含EXIF信息的原图示例

```
http://dn-odum9helk.qbox.me/resource/gogopher.jpg?exif
```

返回结果（内容经过格式化以便阅读）：

```
  {
     "DateTime" : {
        "type" : 2,
        "val" : "2011:11:19 17:09:23"
     },
     "ExposureBiasValue" : {
        "type" : 10,
        "val" : "0.33 EV"
     },
     "ExposureTime" : {
        "type" : 5,
        "val" : "1/50 sec."
     },
     "Model" : {
        "type" : 2,
        "val" : "Canon EOS 600D"
     },
     "ISOSpeedRatings" : {
        "type" : 3,
        "val" : "3200"
     },
     "ResolutionUnit" : {
        "type" : 3,
        "val" : " 英寸"
     },
     ...后续内容已省略...
  }
```

2.获取包含 EXIF 信息的原图示例

```
http://dn-odum9helk.qbox.me/resource/gogopher.jpg?exif/version/v2
```

返回结果（内容经过格式化以便阅读）：

```
{
    "DateTime": {
        "val": "2023:01:01 12:00:00",
    },
    "Make": {
        "val": "Apple",
    },
    "Model": {
        "val": "iPhone 14 Pro Max",
    },
    "Orientation": {
        "val": "1",
    },
    "XResolution": {
        "val": "72",
    },
    "YResolution": {
        "val": "72",
    },
    "ResolutionUnit": {
        "val": "2",
    },
    ...
}
```

# **操作方式** [#操作方式]

您可以通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing)、[持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)、[图片样式设置](/products/dora/image-processing-api/12-the-picture-style)、[CDN中间源处理](/products/cdn/configuration-management-fusion/5-image-optimization) 等方式，对图片进行处理，详情介绍请参见[图片处理操作方式](/products/dora/image-processing-api/11-the-image-processing1)。


# 图片平均色调（imageAve） (/products/dora/image-processing-api/1-image-average-hue-imageave)



最近更新时间: 2024-07-24 16:26:46

# **简介** [#简介]

imageAve接口用于计算一幅图片的平均色调，并以`0xRRGGBB`形式返回。

## **限制说明** [#限制说明]

* 同步处理
  * 原图支持 20MB 以内的图片
  * 处理前的图片`w`和`h`参数不能超过10000像素

* 持久化处理
  * 图片文件无大小限制
  * 处理前的图片`w`和`h`参数不能超过10000像素

<a id="imageAve-request" />

# 接口规格 [#接口规格]

`imageAve`

# **示例** [#示例]

在Web浏览器中输入以下图片地址：

```
https://o6nalx2hr.qnssl.com/0.jpg?imageAve
```

返回结果（内容经过格式化以便阅读）：

```
{
    "RGB": "0x85694d"
}
```

# **操作方式** [#操作方式]

您可以通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing)、[持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)、[图片样式设置](/products/dora/image-processing-api/12-the-picture-style)、[CDN中间源处理](/products/cdn/configuration-management-fusion/5-image-optimization) 等方式，对图片进行处理，详情介绍请参见[图片处理操作方式](/products/dora/image-processing-api/11-the-image-processing1)。


# 图片全景拼接（stitch） (/products/dora/image-processing-api/10-panoramic-view-image-splicing-stitch)



最近更新时间: 2025-05-12 10:53:03

# **简介** [#简介]

图片全景拼接服务（stitch），可以帮助您将多张图像拼接起来，拼成一幅大的图像来创建全景图像。

## **限制说明** [#限制说明]

* 原图限制

  * 输入格式仅支持 ` jpg`、`png`
  * 输入图片最大分辨率 3200\*2400
  * 只支持 20MB 以内的图片

* 最多可拼接10张图片（含源文件）

  ​

# **接口规格** [#接口规格]

```
stitch/format/<Format>/images/<image0>/<image1>/...
```

| 参数名称   | 必填 | 说明                                                                                                                                                            |
| ------ | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| format | 是  | 输出文件格式，支持 jpg、png                                                                                                                                             |
| images | 是  | 1、目前支持 kodo 资源。kodo 资源可由 `kodo://&lt;bucketname&gt;/&lt;key&gt; `表示（此时 bucketname 需要与输入源在同一区域），均需要经过`urlsafe_base64_encode`。<br /> 2、需要和源文件一块拼接的多张图片, 最多 9 张。 |

# **示例** [#示例]

```
POST /pfop/ HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: QBox <AccessToken>

bucket=test&key=boat1_1280x720.jpg&fops=stitch/format/jpg/images/a29kbzovL2RldmVsb3Blci1kb2N1bWVudHMtaW1hZ2UvYm9hdDJfMTI4MHg3MjAuanBn/a29kbzovL2RldmVsb3Blci1kb2N1bWVudHMtaW1hZ2UvYm9hdDNfMTI4MHg3MjAuanBn&notifyURL=http://fake.com/qiniu/notify
```

* 原图1：
  ![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/10-panoramic-view-image-splicing-stitch/FjrKdVO3a18Z83thRRgmf13FE0oh-3ca50fcd364e.webp)
* 原图2：
  ![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/10-panoramic-view-image-splicing-stitch/FsKv0MHulo7NB4jadBKDK-B1pE5t-039d02d4a881.webp)
* 原图3：
  ![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/10-panoramic-view-image-splicing-stitch/Fka1rcchu7GuznVVIWvf9m76me-O-f9b6356e0d31.webp)
* 拼接效果图：

```
https://dn-odum9helk.qbox.me/FgrMnstM96oChWztgjcylF4VET1C
```

![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/10-panoramic-view-image-splicing-stitch/FgrMnstM96oChWztgjcylF4VET1C-3555119fef36.webp)
​

# **操作方式** [#操作方式]

您可以通过[持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)，暂不支持`同步处理`，详情介绍请参见[图片处理操作方式](/products/dora/image-processing-api/11-the-image-processing1)。

# **计费说明** [#计费说明]

| 图片规格         | 价格        |
| :----------- | :-------- |
| 800×600 以下   | 0.28 元/百张 |
| 1600×1200 以下 | 0.46 元/百张 |
| 3200×2400 以下 | 1.48 元/百张 |

**计费示例：** 某用户拼接 800×600 以下尺寸的图片1000张，费用为`2.8元= 0.28*10`.


# 图片处理操作方式 (/products/dora/image-processing-api/11-the-image-processing1)



最近更新时间: 2024-07-24 16:26:46

本文介绍可以通过哪些方式对图片进行处理，您可以根据不同场景选择不同的方式来操作。

# **通过同步处理** [#通过同步处理]

适用于计算量较小可以快速返回结果的资源处理场景，使用 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing)。您可以在图片访问URL后添加相应的图片处理参数处理图片。

# **通过持久化处理** [#通过持久化处理]

适用于计算量较大、处理时间较长的资源处理场景，使用 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)。

# **通过图片样式设置处理** [#通过图片样式设置处理]

在对象存储，针对空间设置图片的样式，方便管理不同需求的图片，操作详情查看[图片样式](/products/dora/image-processing-api/12-the-picture-style)。

# **通过CDN中间源处理** [#通过cdn中间源处理]

CDN可直接在回源节点对图片行处理和分发，可减轻源站压力，减少回源链路，节省回源流量。操作详情查看[CDN中间源图片处理](/products/cdn/configuration-management-fusion/5-image-optimization) 。

**注意**：当前只支持部分图片处理功能。

# **管道** [#管道]

适用于对图片按顺序进行多种处理，通过 [管道](/products/dora/processing-mechanism/3-the-pipe) 实现串行处理，即将一次访问中按顺序对图片进行串行处理。

# **保存处理后图片** [#保存处理后图片]

可以通过 [处理结果另存(saveas)](/products/dora/processing-mechanism/0-processing-results-save-saveas)，实时保存图片到指定空间。


# 图片样式 (/products/dora/image-processing-api/12-the-picture-style)



最近更新时间: 2024-07-24 16:26:46

对象存储 Kodo 支持通过控制台提供一键式图片编辑功能，方便您对空间（Bucket）内上传文件（Object）做批量图片处理。

您可在本多媒体样式功能中进行：

* 图片处理：支持对图片进行如剪裁、添加水印、格式变更等的处理。图片样式将冗长的图片数据处理重新定义的一个友好别名，以简洁的方式描述对图片的处理模式。
* 样式分隔符：样式分隔符是用于连接资源链接和图片样式的特殊符号，为防止访问出错，您可自定义样式名中不可出现的分隔符。

<br />

# **说明** [#说明]

* 更多关于图片编辑的操作，请参考七牛云智能多媒体服务的[图片处理](/products/dora/image-processing-api/6-img-directions-for-use)。
* 更多详情请参考[图片样式](/products/kodo/development-guidelines/dev-the-data-processing/1-dev-the-picture-style)。

<br />

# **操作步骤** [#操作步骤]

1. 登录 Kodo 控制台进入[空间管理](https://portal.qiniu.com/kodo/bucket)界面
2. 单击**目标空间名称**进入空间概览，单击**多媒体样式**进入如图1:多媒体样式列表
   图1:
   ![image.png](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/12-the-picture-style/FgzfU35_cVSvxdl8tlxg-CuATDtX-c8546ad5204f.webp)
3. 单击**新建样式**，选择**图片处理**以新建图片处理规则，如图2。
   图2:
   ![image.png](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/12-the-picture-style/Fq_kvmXRdCHk_84XO4SXT4NVQCDx-3ff2fa42a8a7.webp)
   或在如图3，单击**文件管理**，选择指定图片文件，在操作栏**更多**中的**图片样式**点击**新建样式**，以进入样式编辑界面（仅标准存储、低频存储和归档直读存储类型的图片文件支持）。
   图3:
   ![image.png](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/12-the-picture-style/Fjiyf3yKVD4j0rfkl8h5zaxBRfgp-710546cb897a.webp)
   指定规则后，点击**保存样式**提交新建样式请求，已新建的样式将以列表展示。图片处理参数详情请参考智能多媒体服务[图片样式](/products/dora/image-processing-api/12-the-picture-style)。
4. 在图2的样式配置界面中，您可以使用 Kodo 提供的默认图片并点击**预览**进行样式效果预览。
5. 或点击**选择样例文件**，在如图4的文件选择界面中点击**空间内选择**直接选择空间中已有的文件，并点击**预览**进行样式效果预览。
   *注：仅支持选择标准存储、低频存储和归档直读存储的图片类型文件*
6. 或在如图4的文件选择界面点击**上传文件**，支持您直接从本地上传指定文件到您空间，并点击**预览**以使用该文件查看预览效果。
   *注：您上传的文件将存储在您空间中，仅支持上传大小不超过 20MB 的图片文件*
   图4:
   ![image.png](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/12-the-picture-style/FmIlZ_sBjStmVj55HzD5aa2KtUQP-94103097a58e.webp)
7. 点击在列表操作栏中**编辑**，支持对已有样式进行修改。
8. 点击在列表操作栏中**复制**，支持复制已有样式以在当前空间中进行快速新建。您也可以选择单/多个样式，点击**批量操作**选择**复制到其他空间**，快速将当前的样式复制到其他自有空间。如在批量操作中遇到样式名重复，您可以点击**覆盖**或**取消**复制当前样式，如图5。
   图5:
   ![image.png](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/12-the-picture-style/Fk6M-0AU6We5tnuN7Zj0vb6jpLgH-79c9aff1ca10.webp)
9. 点击在列表操作栏中**预览**，可以快速预览样式效果，支持选择指定预览文件查看效果。
10. 点击在列表操作栏中**删除**，删除已有样式。您也可以选择单/多个样式，点击**批量操作**选择**批量删除**完成批量删除样式的操作。

### **访问设置** [#访问设置]

1. 单击**访问设置**，在如图5右侧弹窗中样式分隔符设置界面，单击**请选择样式分隔符**栏获取下拉菜单
   图5:
   ![image.png](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/12-the-picture-style/Fls0XhGh9zuDoWg4bnNrP7lSH69-95fa8c17c711.webp)
2. **单选或多选*&#x2A;指定分隔符，单击 **+添加**，单击**保存**，完成样式分隔符设置。
   &#x2A;注：未设置时默认样式分隔符为 -（中划线）*

<br />

# **具体示例** [#具体示例]

1. 样式名称为 `imageFop`，样式内容为：`imageView2/0/w/48/h/48`，样式分隔符为 `-`
2. 原始图片链接 `http://dn-odum9helk.qbox.me/qiniu-picture1.jpg`
3. 通过访问 `http://dn-odum9helk.qbox.me/qiniu-picture1.jpg-imageFop` 即可获得效果缩放效果
   注意事项：
   * 创建分隔符时，不建议使用在样式名称中出现的符号作为分隔符。
   * 修改分隔符是个危险操作，为保证样式访问链接生效，仅支持新增、不支持删除已设置的样式分隔符。


# 异常图片检测 (/products/dora/image-processing-api/13-abnormal-image-detection)



最近更新时间: 2025-05-15 17:25:47

# **简介** [#简介]

异常图片检测功能作为 avinfo 功能接口的拓展，即通过指定异常图片检测参数，可以检测图片中是否隐含其他类型的可疑文件。

## **限制说明** [#限制说明]

* 支持格式：JPG、JPEG、PNG、BMP、GIF、WEBP，及纯TS视频流（仅更改后缀）。

# **接口规格** [#接口规格]

```
avinfo/imageinspect/<Imageinspect>
```

## 请求参数说明 [#请求参数说明]

| 名称                                   |  必填 | 说明                                                             |
| :----------------------------------- | :-: | :------------------------------------------------------------- |
| `/imageinspect/&lt;Imageinspect&gt;` |  N  | 是否开启图片异常检测功能，取值0或1。<br />默认为0，关闭启图片异常检测；<br />值为1时，开启图片异常检测功能。 |

## 响应参数说明 [#响应参数说明]

| 名称                  | 说明                                                   |
| :------------------ | :--------------------------------------------------- |
| suspicious          | 是否检测到图片中包含图片格式以外的文件，false 为正常图片文件，true 表示含有其他格式的可疑文件 |
| suspiciousBeginByte | 检测到可疑文件的起始字节位置，单位Bytes                               |
| suspiciousSize      | 检测到可疑文件的大小，单位Bytes                                   |
| suspiciousType      | 检测到可疑文件的类型，例如 MPEG-TS                                |

# **操作方式** [#操作方式]

| 使用方式             | 配置类型      | 说明                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 上传到kodo后自动触发检测   | 通过控制台配置使用 | 操作指引详见 [防黑产图片盗刷](/products/dora/0-anti-blackmail-image-theft)                                                                                                                                                                                                                                                                                                                   |
| 对kodo中存量文件进行批量检测 | 通过控制台配置使用 | 操作指引详见 [防黑产图片盗刷](/products/dora/0-anti-blackmail-image-theft)                                                                                                                                                                                                                                                                                                                   |
| 使用接口检测kodo中的单个图片 | 通过API接口使用 | 1. 通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing) 的方式来调用<br />2. 通过 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 的方式来调用<br />a. `资源上传时自动触发`：可以在上传时指定[persistentOps](/products/kodo/development-guidelines/security/1-put-policy#put-policy-persistent-ops-explanation)参数 <br />b. `对已有资源手动手动触发`：调用[pfop]()命令 |

<a id="avinfo-samples" />

# **示例** [#示例]

```
https://dora-doc.qiniu.com/gogopher.jpg?avinfo/imageinspect/1
```

将返回如下元信息（已经经过格式化，以便阅读）：

```
{
streams: [
	{
      index: 0,
          codec_name: "mjpeg",
          codec_long_name: "Motion JPEG",
      profile: "192",
      codec_type: "video",
      codec_time_base: "0/1",
      codec_tag_string: "[0][0][0][0]",
          codec_tag: "0x0000",
      width: 640,
      height: 427,
      coded_width: 640,
      coded_height: 427,
      has_b_frames: 0,
      sample_aspect_ratio: "1:1",
      display_aspect_ratio: "640:427",
      pix_fmt: "yuvj444p",
      level: -99,
      color_range: "pc",
      color_space: "bt470bg",
      chroma_location: "center",
      refs: 1,
      r_frame_rate: "25/1",
      avg_frame_rate: "0/0",
      time_base: "1/25",
      bits_per_raw_sample: "8",
          disposition: {
		default: 0,
		dub: 0,
		original: 0,
		comment: 0,
		lyrics: 0,
		karaoke: 0,
		forced: 0,
		hearing_impaired: 0,
		visual_impaired: 0,
		clean_effects: 0,
		attached_pic: 0,
		timed_thumbnails: 0
    }
  }
],
format: {
    nb_streams: 1,
    nb_programs: 0,
    format_name: "jpeg_pipe",
    format_long_name: "piped jpeg sequence",
    size: "214513",
    probe_score: 51
},
imageinspect: {
    suspicious: false,
    suspiciousBeginByte: " ",
    suspiciousSize: " ",
    suspiciousType: " "
}
}
```

# **服务价格** [#服务价格]

| 类型     | 价格       |
| :----- | :------- |
| 异常图片检测 | 0.1 元/千次 |


# 图片基本信息（imageInfo） (/products/dora/image-processing-api/2-pictures-basic-information-imageinfo)



最近更新时间: 2024-07-24 16:26:46

# **简介** [#简介]

图片基本信息包括图片格式、图片大小、色彩模型。

## **限制说明** [#限制说明]

原图支持20MB以内的图片

* 注意：原图超过20MB，可能会正常返回，但不保证结果是否正确。

# **接口规格** [#接口规格]

```
imageInfo
```

# **示例** [#示例]

在Web浏览器中输入以下图片地址：

```
http://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageInfo
```

返回结果（内容经过格式化以便阅读）：

```
{
size: 214513,
format: "jpeg",
width: 640,
height: 427,
colorModel: "ycbcr",
orientation: "Top-left"
}
```

| 字段名称        | 必填 | 说明                               |
| ----------- | -- | -------------------------------- |
| size        | 是  | 文件大小，单位：Bytes                    |
| format      | 是  | 图片类型，如`png`、`jpeg`、`gif`、`bmp`等。 |
| width       | 是  | 图片宽度，单位：像素(px)。                  |
| height      | 是  | 图片高度，单位：像素(px)。                  |
| colorModel  | 是  | 色彩模型，如`palette16`、`ycbcr`等。      |
| frameNumber |    | 帧数，gif 图片会返回此项。                  |

# **操作方式** [#操作方式]

您可以通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing)、[持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)、[图片样式设置](/products/dora/image-processing-api/12-the-picture-style)、[CDN中间源处理](/products/cdn/configuration-management-fusion/5-image-optimization) 等方式，对图片进行处理，详情介绍请参见[图片处理操作方式](/products/dora/image-processing-api/11-the-image-processing1)。


# 图片瘦身（imageslim） (/products/dora/image-processing-api/3-image-thin-body-imageslim)



最近更新时间: 2024-07-30 14:43:44

# **简介** [#简介]

图片瘦身服务（imageslim）在尽可能不影响画质的情况下，将JPEG、PNG格式的图片实时压缩，瘦身后画质基本没有变化，分辨率不变，格式不变，大幅缩小文件体积：

* 降低CDN分发成本
* 加快客户端图片的加载速度，提升用户体验

## **使用限制** [#使用限制]

* 原图限制
  * 格式支持：` JPEG`、`PNG` 格式
  * 对图片大小/分辨率没有限制，处理异常（处理超时、处理后图片大小大于原图、处理出错等）则返回原图

* jpeg 图片瘦身
  * 同步请求超时限制为 1s
  * 异步请求的超时限制为 10s

* png 图片瘦身
  * 同步请求超时限制为 3s
  * 异步请求的超时限制为 30s。

* 建议「图片瘦身」操作放在所有其他图片处理操作之后。

# 接口规格 [#接口规格]

```
imageslim/zlevel/<zlevel>
```

| 参数名称                     | 必填 | 说明                                                |
| :----------------------- | :- | :------------------------------------------------ |
| `/zlevel/&lt;zlevel&gt;` | 否  | 图片质量损失控制，值越小，质量越好，压缩率越低。<br />默认值为3，取值范围：\[0-10]。 |

# **示例** [#示例]

原图

```
  https://dora-doc.qiniu.com/grape.jpg
```

瘦身后

```
  https://dora-doc.qiniu.com/grape.jpg?imageslim
```

瘦身后并控制质量损失

```
  https://dora-doc.qiniu.com/grape.jpg?imageslim/zlevel/2
```

# **瘦身前后图片对比** [#瘦身前后图片对比]

* 画质基本不变
* 格式不变
* 分辨率不变
* 图片文件体积大幅减少，有助于节省 CDN 流量、提升用户体验

![](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/3-image-thin-body-imageslim/FndAWU-JWbQJzu8E9OsOPTmNHSze-7ca8b79b26be.webp)

# **CDN 中间源处理** [#cdn-中间源处理]

使用七牛融合 CDN 加速的域名，此域名下的 JPEG、PNG 图片 **无需添加任何参数** ，自动瘦身，更加便捷地为您节省流量。

可在新建域名时开启，而已创建的域名默认为\*\*「关闭」\*\*状态，也可一键式快速开启。

## 操作方法 [#操作方法]

### 场景一： 新建域名时开启「图片自动瘦身」功能 [#场景一-新建域名时开启图片自动瘦身功能]

1. 登录 [七牛控制台](https://portal.qiniu.com)
2. 选择 [融合 CDN](https://portal.qiniu.com/domain) （ 如果您还没有加速域名可以参考：[绑定加速域名和域名解析流程](/products/cdn/1-custom-domain-name-binding-process) ）
3. 在域名管理栏，点击 **添加域名** 按钮 ，在创建域名页面，点击展开**高级配置**，找到 图片自动瘦身 栏，选择 开启
4. 配置 图片自动瘦身 功能的范围
5. 点击创建完成

![](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/3-image-thin-body-imageslim/demo1-1f8c88f98c1a.webp)

### 场景二： 为已创建的域名开启「图片自动瘦身」功能 [#场景二-为已创建的域名开启图片自动瘦身功能]

1. 登录七牛控制台，选择融合 CDN，在域名管理-> 域名列表中，找到你想要开启自动图片瘦身功能的域名

![](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/3-image-thin-body-imageslim/demo2-0b4b2ac9a575.webp)

2. 在域名列表的操作栏，点击**配置** ，进入配置页面
3. 在配置页->图片优化栏，找到图片自动瘦身选项，点击\*\*修改配置 \*\*
   ![](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/3-image-thin-body-imageslim/demo3-3d384c23990e.webp)
4. 选择开启，并配置 图片自动瘦身 功能范围，点击**确认**即可
   ![](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/3-image-thin-body-imageslim/demo4-b8c0f4b505b8.webp)

## **功能范围说明** [#功能范围说明]

**图片自动瘦身** 提供指定三种范围：

| 参数    | 范围                                                                      |
| ----- | ----------------------------------------------------------------------- |
| 默认    | 该域名下全部 jpg 和 png 将会自动瘦身                                                 |
| 指定目录  | 该域名该路径下的 jpg 和 png 将会自动瘦身，支持配置多个目录，以 `;` 号分开。如：`/a;/b`                  |
| 正则表达式 | 该域名下符合该匹配规则的 jpg 和 png 将会自动瘦身，支持配置多个正则表达式，以 `;` 号分开,如：`.*\.png;.*\.jpg` |

# **操作方式** [#操作方式]

您可以通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing)、[持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)、[图片样式设置](/products/dora/image-processing-api/12-the-picture-style)、[CDN中间源处理](/products/cdn/configuration-management-fusion/5-image-optimization) 等方式，对图片进行处理，详情介绍请参见[图片处理操作方式](/products/dora/image-processing-api/11-the-image-processing1)。

# **计费说明** [#计费说明]

**0.1 元/千次，按月计量，按月结算**

* 不足千次不收费，如月度计量为 300 次，则不收费；月度计量为 5300 次按 5000 次收费，即 0.5 元。
* 命中 CDN 缓存情况下不计量，未命中 CDN 缓存情况需返回源站调用瘦身服务时计量。


# 图片基本处理（imageView2） (/products/dora/image-processing-api/4-basic-processing-images-imageview2)



最近更新时间: 2026-08-18 15:23:42

# **简介** [#简介]

**imageView2**  提供简单快捷的图片格式转换、缩略、质量变换功能。只需要填写几个参数，即可对图片进行缩略操作，生成各种缩略图。图片处理为收费项，详细的计费说明请参见 [计费与定价](https://www.qiniu.com/prices/dora?source=dora)。

| 功能       | 说明                 |
| -------- | ------------------ |
| [缩略]()   | 等比缩放、设定目标宽高缩放等多种方式 |
| [格式转换]() | 格式转换、GIF 颜色控制      |
| [渐进显示]() | 图片渐进显示             |
| [质量变换]() | 对图片质量进行调节          |

## **限制说明** [#限制说明]

* 原图格式支持： `psd`、`jpeg`、`png`、`gif`、`webp`、`tiff`、`bmp`、`avif`、`heic`
* 同步处理
  * 原图支持 20MB 以内的图片
  * 处理前动图帧数限制：`webp动图` 最大帧数为50，`gif` 最大帧数为 200
  * 处理前体积限制：图片 `w` 和`h`不能超过3万像素，总像素不能超过1.5亿像素
  * 处理后体积限制：图片`w`和`h` 不能超过9999像素，总像素不得超过2500w 像素。以下情况特别说明：
    * 输出为 `avif` 时，图片 `w`和`h` 不能超过9999像素，总像素不能超过768w像素
    * 输出为 `webp静图` 时，图片 `w` 和 `h    ` 不能超过16383像素，总像素不得超过2500w 像素
    * 仅限 `输入为webp动图格式，输出webp动图/gif动图时`，图片 `w` 和 `h    ` 不能超过999像素，总像素（宽x高x帧数）不能超过3150万像素
* 持久化处理
  * 原图支持 512MB 以内的图片
  * 处理前动图帧数限制：`gif`、`webp动图`，最大帧数为 500
  * 处理前体积限制：图片 `w`和`h `不能超过3万像素，总像素不能超过1.5亿像素
  * 处理后体积限制：图片 `w`和`h `不能超过14999像素，总像素不得超过6000w像素。以下情况特别说明：
    * 输出为 `heic`和 `avif` 时，图片 `w`和`h `不能超过9999像素，总像素不能超过3072w像素
    * 输出为 `webp动图和静图` 时，图片 `w` 和 `h    ` 不能超过16383像素，总像素不得超过6000w像素

# **参数说明** [#参数说明]

**注意**：接口规格不含任何空格与换行符。

```
imageView2/<mode>/w/<LongEdge>
                 /h/<ShortEdge>
                 /format/<Format>
                 /interlace/<Interlace>
                 /q/<Quality>
                 /colors/<colors>
                 /ignore-error/<ignoreError>
```

## 参数说明 [#参数说明-1]

| 参数名称                                   | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/mode`                                | 是  | 定义等比缩放、设定目标宽高缩放的多种不同方式，取值范围：\[0,5]的整数，必填项。<br />分为如下几种情况：                                                                                                                                                                                                                                                                                                                                                                      |
|                                        |    | **mode=0**，使用姿势：`/0/w/&lt;LongEdge&gt;/h/&lt;ShortEdge&gt;`<br />1、限定缩略图的长边最多为`&lt;LongEdge&gt;`，短边最多为`&lt;ShortEdge&gt;`，进行等比缩放，不裁剪。<br />2、如果只指定 `w` 参数则表示限定长边（短边自适应），只指定 `h` 参数则表示限定短边（长边自适应）。                                                                                                                                                                                                                              |
|                                        |    | **mode=1**，使用姿势：`/1/w/&lt;Width&gt;/h/&lt;Height&gt;`<br />1、限定缩略图的宽最少为`&lt;Width&gt;`，高最少为`&lt;Height&gt;`，进行等比缩放，居中裁剪。<br />2、转后的缩略图通常恰好是 `&lt;Width&gt;x&lt;Height&gt;` 的大小（有一个边缩放的时候会因为超出矩形框而被裁剪掉多余部分）。<br />3、如果只指定 `w` 参数或只指定 `h` 参数，代表限定为长宽相等的正方图。                                                                                                                                                                      |
|                                        |    | **mode=2**，使用姿势：`/2/w/&lt;Width&gt;/h/&lt;Height&gt;`<br />1、限定缩略图的宽最多为`&lt;Width&gt;`，高最多为`&lt;Height&gt;`，进行等比缩放，不裁剪。<br />2、如果只指定 `w` 参数则表示限定宽（高自适应），只指定 `h` 参数则表示限定高（宽自适应）。<br />3、它和模式0类似，区别是mode=2是限定宽和高，mode=0是限定长边和短边。从应用场景来说，模式0适合移动设备上做缩略图，模式2适合PC上做缩略图。                                                                                                                                                             |
|                                        |    | **mode=3**，使用姿势：`/3/w/&lt;Width&gt;/h/&lt;Height&gt;`<br />1、限定缩略图的宽最少为`&lt;Width&gt;`，高最少为`&lt;Height&gt;`，进行等比缩放，不裁剪。<br />2、如果只指定` w` 参数或只指定` h` 参数，代表长宽限定为同样的值。你可以理解为模式1是模式3的结果再做居中裁剪得到的。                                                                                                                                                                                                                                  |
|                                        |    | **mode=4**，使用姿势：`/4/w/&lt;LongEdge&gt;/h/&lt;ShortEdge&gt;`<br />1、限定缩略图的长边最少为`&lt;LongEdge&gt;`，短边最少为`&lt;ShortEdge&gt;`，进行等比缩放，不裁剪。<br />2、如果只指定 `w` 参数或只指定 `h` 参数，表示长边短边限定为同样的值。这个模式很适合在手持设备做图片的全屏查看（把这里的长边短边分别设为手机屏幕的分辨率即可），生成的图片尺寸刚好充满整个屏幕（某一个边可能会超出屏幕）。                                                                                                                                                                  |
|                                        |    | **mode=5**，使用姿势：`/5/w/&lt;LongEdge&gt;/h/&lt;ShortEdge&gt;`<br />1、限定缩略图的长边最少为`&lt;LongEdge&gt;`，短边最少为`&lt;ShortEdge&gt;`，进行等比缩放，居中裁剪。<br />2、如果只指定 `w` 参数或只指定 `h` 参数，表示长边短边限定为同样的值。同上模式4，但超出限定的矩形部分会被裁剪。                                                                                                                                                                                                                      |
| `/format/&lt;Format&gt;`               | 否  | **图片输出格式**<br />1、取值：`copy`，保持原图格式输出。<br />2、取值：`jpg`，`gif`，`png`，`webp`等，参考[支持转换的图片格式](https://www.imagemagick.org/script/formats.php)。<br />3、取值：`heic` 或 `avif `，属于 [图片高级压缩](/products/dora/image-processing-api/senior-image-compression/0-avif-compression) 格式，按照图片高级压缩收费。<br />**注意**：<br />● 必须指定`mode`参数，否则不生效。<br />● 当原图为`heic` 或 `avif` 时，设置`format/copy` 会保持原图格式不变，且不按照图片高级压缩收费；如果不指定 format 参数，将会输出`jpeg` 。<br /> |
| `/colors/&lt;colors&gt;`               | 否  | **控制图片颜色数量**<br />● 源图片为 `GIF` 时，控制输出 GIF 中不同颜色的数量，取值可为2、4、8、16、32、64、128、256，不使用该参数时的默认值为128。<br />●  输出图片为 `PNG` 时，控制输出 PNG 中不同颜色的数量，取值可为2、4、8、16、32、64、128、256，不使用该参数时默认关闭。<br />**注意**：<br />● 必须指定`mode`参数，否则不生效。<br />● 如果只设置图片颜色数量，不做其他缩放处理，建议使用 [图片高级处理-格式转换](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/3-format-conversion)                                                     |
| `/interlace/&lt;Interlace&gt;`         | 否  | **是否支持渐进显示**<br />取值范围：`1` 支持渐进显示，`0`不支持渐进显示(默认为0)。<br />适用目标格式：`jpg`<br />效果：网速慢时，图片显示由模糊到清晰。新图的输出格式，必须指定`mode`参数，否则不生效。<br />**注意**：<br />● 必须指定`mode`参数，否则不生效。<br />● 如果只设置渐渐显示，不做其他缩放处理，建议使用 [图片高级处理-渐进显示](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/5-progressive-shows)                                                                                                            |
| `/q/&lt;Quality&gt;`                   | 否  | **新图的图片质量**<br />● 取值范围是\[1, 100]\<br>● 输入是 `jpeg`，且不强制指定质量条件下，七牛会根据原图质量算出一个[修正值](#image-quality)，取修正值和指定值中的小值。<br /><br />**注意**：<br />● 必须指定`mode`参数，否则不生效。<br />●  指定值后面可以增加 `!`，表示强制使用指定值，如`100!`。<br />●  heic：默认值35<br />●  avif：默认值50<br />●  其他格式：默认值75<br />●  如果只设置图片质量，不做其他缩放处理，建议使用 [图片高级处理-质量变换](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/4-the-quality-of-transformation) |
| `/ignore-error/&lt;ignoreError&gt;`    | 否  | **设置该参数，取值为1，针对以下场景的处理失败，会直接返回源文件或原输入，而不是报错**：<br />**1**. 图片兼容性问题，导致的处理失败<br />**2**.  触发同步/持久化处理的输入输出限制，如格式、文件大小、宽、高、总像素、帧数，导致的处理失败<br />**注意**：<br />● 不设置此参数，处理失败时返回错误信息；<br />● 当输入文件超过1GB，设置此参数不生效，处理失败时返回错误信息；<br />● 设置 ignore-error/1 生效后，不会计费。                                                                                                                                                                       |
| `/strip`                               | 否  | 去除所有元信息                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `/meta-keep-list/&lt;metaKeepList&gt;` | 否  | 保留指定的元信息，参数格式为 `urlsafebase64("k1,k2,k3")`，当前只支持[部分 exif 子标签](/products/dora/1-features_introduction#exif%E5%86%99%E5%85%83%E6%95%B0%E6%8D%AE%E6%94%AF%E6%8C%81key%E5%88%97%E8%A1%A8)                                                                                                                                                                                                                                          |
| **注意：**                                |    |                                                                                                                                                                                                                                                                                                                                                                                                                                |

* 所有模式都可以只指定`w`参数或只指定`h`参数，并获得合理结果。在`w、h`为限定最大值时，未指定某参数等价于将该参数设置为无穷大（自适应）；在`w、h`为限定最小值时，未指定参数等于给定的参数，也就限定的矩形是正方形。

* 新图的宽/高/长边/短边，不会比原图大，即本接口总是 `缩小图片`。

* 如果原图带有 `EXIF` 信息且包含 `Orientation` 字段且不能被识别出来，`imageView2` 默认根据此字段的值进行自动旋转修正。

* 当一张含有透明区域的图片，转换成不支持透明的格式`jpg`,`bmp`等时，透明区域填充白色。

* `<Quality>`修正值算法：

  * 原图 quality \<= 90：**min\[90, 原图quality\*sqrt**（原图长宽乘积/结果图片长宽乘积）]

  * 原图 quality > 90： **原图quality\*sqrt**（原图长宽乘积/结果图片长宽乘积)

# **示例** [#示例]

* 原图

  ![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/4-basic-processing-images-imageview2/gogopher-caff95e8587b.webp)

* 裁剪正中部分，等比缩小生成200x200缩略图：

  ```
  https://dora-doc.qiniu.com/gogopher.jpg?imageView2/1/w/200/h/200
  ```

  ![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/4-basic-processing-images-imageview2/gogopher-97abdf425087.webp)

* 宽度固定为200px，高度等比缩小，生成200x133缩略图：

  ```
  https://dora-doc.qiniu.com/gogopher.jpg?imageView2/2/w/200
  ```

  ![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/4-basic-processing-images-imageview2/gogopher-2b2c643c24aa.webp)

* 高度固定为200px，宽度等比缩小，生成300x200缩略图：

  ```
  https://dora-doc.qiniu.com/gogopher.jpg?imageView2/2/h/200
  ```

  ![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/4-basic-processing-images-imageview2/gogopher-a2967a7aeace.webp)

* 渐进显示图片：

  ```
  https://dora-doc.qiniu.com/gogopher.jpg?imageView2/1/w/200/h/200/interlace/1
  ```

  ![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/4-basic-processing-images-imageview2/gogopher-97abdf425087.webp)

* 设置图片质量为55：

  ```
  https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageView2/1/w/200/h/200/q/55
  ```

  ![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/4-basic-processing-images-imageview2/gogopher-13e5646e3e42.webp)

* 设置 `ignore-error` 的简单示例，触发同步输出限制，返回原图：输出avif，图片 `w`和`h` 不能超过9999像素，总像素不能超过768w像素。

  ```
  https://dn-dora-document.qbox.me/pexels-clement.jpg?imageView2/1/format/avif/ignore-error/1
  ```

  ![img](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/4-basic-processing-images-imageview2/pexels-clement-79e89c0a44bf.webp)

* 设置 `ignore-error` 的复杂示例，使用 [管道](/products/dora/processing-mechanism/3-the-pipe) ，返回原输入：如果第一步 `加水印` ，处理成功；第二步 `转avif格式`，触发avif格式的同步输出限制，设置 ignore-error 生效后，会返回原输入（即第一步处理结果）。

  ```
  https://dn-dora-document.qbox.me/pexels-clement.jpg?watermark/2/text/5LiD54mb5LqR5a2Y5YKo/fontsize/10000/fill/I0ZGRkZGRg==/ignore-error/1|imageView2/1/format/avif/ignore-error/1
  ```

  ![img](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/4-basic-processing-images-imageview2/pexels-clement-f074b27b4a93.webp)

# **操作方式** [#操作方式]

您可以通过 [同步处理](/products/dora/1-features_introduction)、[持久化处理](/products/dora/1-features_introduction)、[图片样式设置](/products/dora/1-features_introduction)、[CDN中间源处理](/products/cdn/configuration-management-fusion/5-image-optimization) 等方式，对图片进行处理，详情介绍请参见[图片处理操作方式](/products/dora/1-features_introduction)。


# 图片水印处理（watermark） (/products/dora/image-processing-api/5-image-watermarking-processing-watermark)



最近更新时间: 2026-08-18 15:23:21

# **简介** [#简介]

七牛云存储提供四种水印接口：[图片水印](#pic-watermark)、[文字水印](#text-watermark)，[文字平铺水印](#text-Tile-watermark)、[混合水印](#multi-watermark)、[渐变色水印](#Gradient-watermark)。

## **使用限制** [#使用限制]

* 原图格式支持： `psd`、`jpeg`、`png`、`gif`、`webp`、`tiff`、`bmp`、`avif`、`heic`
  * 输入为 `webp动图`、 `gif动图` 时，不适用于`watermark/4` 接口
* 同步处理
  * 原图只支持 20MB 以内的图片
  * 处理前动图帧数限制：`webp动图` 最大帧数为50，`gif` 最大帧数为 200
  * 处理前体积限制：图片 `w` 和`h`不能超过3万像素，总像素不能超过1.5亿像素
  * 处理后体积限制：图片`w`和`h` 不能超过9999像素，总像素不得超过2500w 像素。以下情况特别说明：
    * 输出为 `avif` 时，图片 `w`和`h` 不能超过9999像素，总像素不能超过768w像素
    * 输出为 `webp静图` 时，图片 `w` 和 `h    ` 不能超过16383像素，总像素不得超过2500w 像素
    * 仅限 `输入为webp动图格式，输出webp动图/gif动图时`，图片 `w` 和 `h    ` 不能超过999像素，总像素（宽x高x帧数）不能超过3150万像素
* 持久化处理
  * 原图只支持 512MB 以内的图片
  * 处理前动图帧数限制：`gif`、`webp动图`，最大帧数为 500
  * 处理前体积限制：图片 `w`和`h `不能超过3万像素，总像素不能超过1.5亿像素
  * 处理后体积限制：图片 `w`和`h `不能超过14999像素，总像素不得超过6000w像素。以下情况特别说明：
    * 输出为 `heic`和 `avif` 时，图片 `w`和`h `不能超过9999像素，总像素不能超过3072w像素
    * 输出为 `webp动图和静图` 时，图片 `w` 和 `h    ` 不能超过16383像素，总像素不得超过6000w像素

# **图片水印** [#图片水印]

## 接口规格 [#接口规格]

**注意：** 接口规格不含任何空格与换行符。

```
watermark/1
         /format/<Format>
         /image/<encodedkodocheme>
         /dissolve/<dissolve>
         /gravity/<gravity>
         /dx/<distanceX>
         /dy/<distanceY>
         /ws/<watermarkScale>
         /wst/<watermarkScaleType>
         /tile/<enableTile>
         /uws/<unitWidthScale>
         /uhs/<unitHeightScale>
         /ignore-error/<ignoreError>
```

<a id="pic-watermark-params" />

| 参数名称                               | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                 |
| :--------------------------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/format/&lt;Format&gt;`           |    | **图片输出格式**<br />1、取值：`heic` 或 `avif `，属于 [图片高级压缩](/products/dora/image-processing-api/senior-image-compression/0-avif-compression) 格式，按照图片高级压缩收费，当前仅支持 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 来使用。<br />2、取值：`copy`，保持原图格式输出。<br />**注意**：<br />●  当原图为`heic` 或 `avif` 时，设置`format/copy` 会保持原图格式不变，且不按照图片高级压缩收费；如果不指定 format 参数，将会输出`jpeg` 。<br /> |
| `/image/&lt;encodedkodocheme&gt;`  | 是  | 水印的源路径，目前支持 kodo 资源。kodo 资源可由 `kodo://&lt;bucketname&gt;/&lt;key&gt;` 表示（此时 bucketname 需要与输入源在同一区域），均需要经过`urlsafe_base64_encode`。<br />**注意**：更换图片水印时，建议更换图片的文件名。                                                                                                                                                                                                                                  |
| `/dissolve/&lt;dissolve&gt;`       |    | 透明度，取值范围\[1-100]的整数，默认值为100（完全不透明）。                                                                                                                                                                                                                                                                                                                                                                |
| `/gravity/&lt;gravity&gt;`         |    | 水印位置，参考[水印锚点参数表](#watermark-anchor-spec)，默认值为`SouthEast`（右下角）。                                                                                                                                                                                                                                                                                                                                     |
| `/dx/&lt;distanceX&gt;`            |    | 横轴边距，单位:像素(px)，默认值为10。                                                                                                                                                                                                                                                                                                                                                                             |
| `/dy/&lt;distanceY&gt;`            |    | 纵轴边距，单位:像素(px)，默认值为10。                                                                                                                                                                                                                                                                                                                                                                             |
| `/ws/&lt;watermarkScale&gt;`       |    | 水印图片自适应原图的比例，ws的取值范围为0-1。具体是指水印图片保持原比例，按照自适应原图的类型`wst`，比如默认是按照短边，则水印图片对应原图短边的边=原图短边＊ws。                                                                                                                                                                                                                                                                                                            |
| `/wst/&lt;watermarkScaleType&gt;`  |    | 水印图片自适应原图的类型，取值0、1、2、3分别表示为自适应原图的短边、长边、宽、高，默认值为0。<br />**例如**：<br />1. 原图大小为250x250，水印图片大小为91x61，如果wst=0、ws=0.1，那么最终水印图片的大小为：37.2x25。<br />2. 原图大小为250x250，水印图片大小为91x61，如果wst=1、ws=0.1，那么最终水印图片的大小为：25x16.8。                                                                                                                                                                                       |
| `/tile/&lt;enableTile&gt;`         |    | 是否使用水印平铺，取值 0 表示不使用水印平铺、取值 1 表示使用水印平铺。默认值为 0。<br /> 启用水印平铺后，原 gravity、dx、dy 无效                                                                                                                                                                                                                                                                                                                     |
| `/uws/&lt;unitWidthScale&gt;`      |    | 启用水印平铺时才生效。表示水印单元的宽比例。默认值为1，即无边框                                                                                                                                                                                                                                                                                                                                                                   |
| `/uhs/&lt;unitHeightScale&gt;`     |    | 启用水印平铺时才生效。表示水印单元的高比例。默认值为1，即无边框                                                                                                                                                                                                                                                                                                                                                                   |
| `ignore-error/&lt;ignoreError&gt;` |    | **设置该参数，取值为1，针对以下场景的处理失败，会直接返回源文件或原输入，而不是报错**：<br />**1**. 图片兼容性问题，导致的处理失败<br />**2**.  触发同步/持久化处理的输入输出限制，如格式、文件大小、宽、高、总像素、帧数，导致的处理失败<br />**注意**：<br />● 不设置此参数，处理失败时返回错误信息；<br />● 当输入文件超过1GB，设置此参数不生效，处理失败时返回错误信息 。                                                                                                                                                                             |

<a id="watermark-anchor-spec" />

### 水印锚点参数表 [#水印锚点参数表]

```
NorthWest     |     North      |     NorthEast
              |                |
              |                |
--------------+----------------+--------------
              |                |
West          |     Center     |          East
              |                |
--------------+----------------+--------------
              |                |
              |                |
SouthWest     |     South      |     SouthEast
```

<a id="pic-watermark-request" />

## **使用示例** [#使用示例]

* 水印图片：

  * `kodocheme = kodo://developer-documents-image/qiniuyun.png `
  * `encodedkodocheme = a29kbzovL2RldmVsb3Blci1kb2N1bWVudHMtaW1hZ2UvcWluaXV5dW4ucG5n`

* 水印透明度: 50% (`dissolve=50`)

* 水印位置: 右下角 (`gravity=SouthEast`)

* 横向边距: 20px

* 纵向边距: 20px

* 水印图片自适应短边比例：0.2

```
   https://dora-doc.qiniu.com/gogopher.jpg?watermark/1/image/a29kbzovL2RldmVsb3Blci1kb2N1bWVudHMtaW1hZ2UvcWluaXV5dW4ucG5n/dissolve/50/gravity/SouthEast/dx/20/dy/20/ws/0.2
```

![图片水印](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/5-image-watermarking-processing-watermark/gogopher-23a09d80a35a.webp)

<a id="text-watermark" />

# **文字水印** [#文字水印]

## 接口规格 [#接口规格-1]

**注意：** 接口规格不含任何空格与换行符。

```
watermark/2
         /format/<Format>
         /text/<encodedText>
         /font/<encodedFontName>
         /fontsize/<fontSize>
         /fill/<encodedTextColor>
         /dissolve/<dissolve>
         /gravity/<gravity>
         /dx/<distanceX>
         /dy/<distanceY>
         /ignore-error/<ignoreError>
```

<a id="text-watermark-params" />

| 参数名称                               | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                 |
| :--------------------------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/format/&lt;Format&gt;`           |    | **图片输出格式**<br />1、取值：`heic` 或 `avif `，属于 [图片高级压缩](/products/dora/image-processing-api/senior-image-compression/0-avif-compression) 格式，按照图片高级压缩收费，当前仅支持 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 来使用。<br />2、取值：`copy`，保持原图格式输出。<br />**注意**：<br />●  当原图为`heic` 或 `avif` 时，设置`format/copy` 会保持原图格式不变，且不按照图片高级压缩收费；如果不指定 format 参数，将会输出`jpeg` 。<br /> |
| `/text/&lt;encodedText&gt;`        | 是  | 水印文字内容（经过[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)）                                                                                                                                                                                                                                                                                                        |
| `/font/&lt;encodedFontName&gt;`    |    | 水印文字字体（经过URL安全的Base64编码），默认为`方正黑体`，详见支持[字体列表](/faq/dora/other-dora/11230-image-text-watermarking-support-font-list)\<br>&#x2A;*注意：** 中文水印必须指定中文字体。                                                                                                                                                                                                                                                 |
| `/fontstyle/&lt;fontStyle&gt;`     |    | 水印字体样式（经过URL安全的Base64编码），默认为系统自动选择字体样式，详见支持[字体列表](/faq/dora/other-dora/11230-image-text-watermarking-support-font-list)。                                                                                                                                                                                                                                                                           |
| `/fontsize/&lt;fontSize&gt;`       |    | 水印文字大小，单位: 缇 ，等于1/20磅，默认值是240缇，参考DPI为72。                                                                                                                                                                                                                                                                                                                                                           |
| `/fill/&lt;encodedTextColor&gt;`   |    | 水印文字颜色，RGB格式，可以是颜色名称（例如 red）或十六进制（例如 #FF0000），参考[RGB颜色编码表](http://www.rapidtables.com/web/color/RGB_Color.htm)，默认为黑色。经过URL安全的Base64编码。                                                                                                                                                                                                                                                             |
| `/dissolve/&lt;dissolve&gt;`       |    | 透明度，取值范围为\[1-100]的整数，默认值100（完全不透明）。                                                                                                                                                                                                                                                                                                                                                                |
| `/gravity/&lt;gravity&gt;`         |    | 水印位置，参考水印位置参数表，默认值为`SouthEast`（右下角）。                                                                                                                                                                                                                                                                                                                                                               |
| `/dx/&lt;distanceX&gt;`            |    | 横轴边距，单位:像素(px)，默认值为10。                                                                                                                                                                                                                                                                                                                                                                             |
| `/dy/&lt;distanceY&gt;`            |    | 纵轴边距，单位:像素(px)，默认值为10。                                                                                                                                                                                                                                                                                                                                                                             |
| `ignore-error/&lt;ignoreError&gt;` |    | **设置该参数，取值为1，针对以下场景的处理失败，会直接返回源文件或原输入，而不是报错**：<br />**1**. 图片兼容性问题，导致的处理失败<br />**2**.  触发同步/持久化处理的输入输出限制，如格式、文件大小、宽、高、总像素、帧数，导致的处理失败<br />**注意**：<br />● 不设置此参数，处理失败时返回错误信息；<br />● 当输入文件超过1GB，设置此参数不生效，处理失败时返回错误信息 。                                                                                                                                                                             |

## **使用示例** [#使用示例-1]

* 水印文本：七牛云

* 水印文本字体：方正黑体

* 水印文本字体大小：400

* 水印文本颜色：gray

  ```
  https://dora-doc.qiniu.com/gogopher.jpg?watermark/2/text/5LiD54mb5LqR5a2Y5YKo/fontsize/400
  ```

![文字水印](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/5-image-watermarking-processing-watermark/gogopher-3f59654792dd.webp)

# **混合水印** [#混合水印]

本接口用于同时在一个原图上打多个不同类型的水印。

<a id="multi-watermark-spec" />

## 接口规格 [#接口规格-2]

```
watermark/3
         /format/<Format>
         /text/<textWaterMarkParams1>
         /image/<imageWaterMarkParams1>
         /image/<imageWaterMarkParams2>
         /text/<textWaterMarkParams2>
         ...
```

| 参数名称                                  | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                           |
| :------------------------------------ | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/format/&lt;Format&gt;`              |    | **图片输出格式**<br />1、取值：`heic` 或 `avif `，属于 [图片高级压缩](/products/dora/image-processing-api/senior-image-compression/0-avif-compression) 格式，按照图片高级压缩收费，当前仅支持 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 来使用。<br />2、取值：`copy`，保持原图格式输出。<br />**注意**：<br />●  当原图为`heic` 或 `avif` 时，设置`format/copy` 会保持原图格式不变，且不按照图片高级压缩收费；如果不指定 format 参数，将会输出`jpeg` 。 |
| `/image/&lt;imageWaterMarkParams&gt;` |    | 参考[图片水印参数](#pic-watermark-params)                                                                                                                                                                                                                                                                                                                                                            |
| `/text/&lt;textWaterMarkParams&gt;`   |    | 参考[文字水印参数](#text-watermark-params)                                                                                                                                                                                                                                                                                                                                                           |

**注意：**

* 省略号表示可以附加多个规格参数。
* 图片水印与文字水印的规格可以混写，按给定顺序处理。

## **使用示例** [#使用示例-2]

* 对原图加上多个混合水印，可以通过多个水印 Params 组合`/image/imageWaterMarkParams`，`/text/textWaterMarkParams` 来实现；示例共添加了6个不同图片和文字水印。

  ```
  https://dora-doc.qiniu.com/baidi.png?watermark/3
      /image/aHR0cHM6Ly9kb3JhLWRvYy5xaW5pdS5jb20veGlhb2ppLnBuZw==/gravity/North/dy/-10/dx/0
      /text/5ZCD6L-H54yr5bGx546L77yM5YW25LuW5qa06I6y55qG6Lev5Lq6/gravity/SouthWest/dx/10/dy/180/fontsize/500
      /text/5LuF6ZmQN-WkqSAgMjAxOS4wNC4wMS0yMDE5LjA0LjA3/gravity/SouthWest/dx/30/dy/130/fontsize/300
      /image/aHR0cHM6Ly9kb3JhLWRvYy5xaW5pdS5jb20vcXVhbi5wbmc=/gravity/SouthWest/dx/80/dy/30
  /image/aHR0cHM6Ly9kb3JhLWRvYy5xaW5pdS5jb20v5LqM57u056CBLnBuZw==/gravity/SouthEast/dx/10/dy/30
      /text/5omr56CB6aKG5Y-W5LyY5oOg5Yi4/gravity/SouthEast/dx/50/dy/10/fontsize/300/fill/UmV
  ```

![混合水印](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/5-image-watermarking-processing-watermark/baidi-9ec0e5cf5f22.webp)

<a id="Gradient-watermark" />

# **文字平铺水印** [#文字平铺水印]

**注意：** 输入为 `webp动图`、 `gif动图` 时，不支持文字平铺水印

## 接口规格 [#接口规格-3]

```
watermark/4
         /format/<Format>
         /text/<encodedText>
         /font/<encodedFontName>
         /fontsize/<fontSize>
         /fill/<encodedTextColor>
         /dissolve/<dissolve>
         /rotate/<rotate>
         /uw/<unitW>
         /uh/<unitH>
         /resize/<resize>
         /ignore-error/<ignoreError>
```

<a id="pic-watermark-params" />

| 参数名称                               | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/format/&lt;Format&gt;`           |    | **图片输出格式**<br />1、取值：`heic` 或 `avif `，属于 [图片高级压缩](/products/dora/image-processing-api/senior-image-compression/0-avif-compression) 格式，按照图片高级压缩收费，当前仅支持 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 来使用。<br />2、取值：`copy`，保持原图格式输出。<br />**注意**：<br />●  当原图为`heic` 或 `avif` 时，设置`format/copy` 会保持原图格式不变，且不按照图片高级压缩收费；如果不指定 format 参数，将会输出`jpeg` 。<br /> |
| `/text/&lt;encodedText&gt;`        | 是  | 水印文字内容（经过URL安全的Base64编码）                                                                                                                                                                                                                                                                                                                                                                           |
| `/font/&lt;encodedFontName&gt;`    |    | 水印文字字体（经过URL安全的Base64编码），默认为`方正黑体`，详见支持[字体列表](/faq/dora/other-dora/11230-image-text-watermarking-support-font-list)\<br>**注意**：中文水印必须指定中文字体。                                                                                                                                                                                                                                                       |
| `/fontsize/&lt;fontSize&gt;`       |    | 水印文字大小，单位: 缇，等于1/20磅，取值范围为\[1, 10000)的整数;默认值是240缇，参考DPI为72。                                                                                                                                                                                                                                                                                                                                        |
| `/fill/&lt;encodedTextColor&gt;`   |    | 水印文字颜色，RGB格式，可以是颜色名称（比如red）或十六进制（比如#FF0000），参考RGB颜色编码表，缺省为黑色. （经过URL安全的Base64编码）                                                                                                                                                                                                                                                                                                                   |
| `/dissolve/&lt;dissolve&gt;`       |    | 透明度，取值范围\[1-100]的整数，默认值为100（完全不透明）。                                                                                                                                                                                                                                                                                                                                                                |
| ` /rotate/&lt;rotate&gt;`          |    | 水印文字旋转角度，取值范围为\[-180, 180]的整数， 默认为0。                                                                                                                                                                                                                                                                                                                                                               |
| `/uw/&lt;unitW&gt;`                |    | 水印文字填充单元宽度，默认值为100，数值为大于0的整数。。                                                                                                                                                                                                                                                                                                                                                                     |
| `/uh/&lt;unitH&gt;`                |    | 水印文字填充单元高度，默认值为100，数值为大于0的整数。。                                                                                                                                                                                                                                                                                                                                                                     |
| `/resize/&lt;resize&gt;`           |    | 水印文字填充单元缩放比例，取值范围为\[0.1，10]，小数点保留后一位；默认为1，即不缩放。                                                                                                                                                                                                                                                                                                                                                    |
| `ignore-error/&lt;ignoreError&gt;` |    | **设置该参数，取值为1，针对以下场景的处理失败，会直接返回源文件或原输入，而不是报错**：<br />**1**. 图片兼容性问题，导致的处理失败<br />**2**.  触发同步/持久化处理的输入输出限制，如格式、文件大小、宽、高、总像素、帧数，导致的处理失败<br />**注意**：<br />● 不设置此参数，处理失败时返回错误信息；<br />● 当输入文件超过1GB，设置此参数不生效，处理失败时返回错误信息 。                                                                                                                                                                             |

## **使用示例** [#使用示例-3]

* 水印文本：七牛云存储

* 水印文本字体：方正黑体

* 水印文本字体大小：400

* 水印文本颜色：gray

* 水印文本透明度：50% (dissolve=50)

* 水印文字旋转角度: 30

* 水印文字填充单元宽度：180

* 水印文字填充单元高度：180

* 水印文字填充单元缩放比例： 1

  ```
  https://dora-doc.qiniu.com/gogopher.jpg?watermark/4/text/5LiD54mb5LqR5a2Y5YKo/fontsize/400/fill/Z3JheQ==/dissolve/50/rotate/30/uw/180/uh/180/resize/1
  ```

![文字水印](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/5-image-watermarking-processing-watermark/gogopher-1cbb21c31273.webp)

<a id="multi-watermark" />

# **渐变色水印** [#渐变色水印]

## 接口规格 [#接口规格-4]

```
watermark/7
         /format/<Format>
         /ori/<Orientation>
         /startpos/<StartPosition>
         /stoppos/<StopPosition>
         /startclr/<StartColor>
         /stopclr/<StopColor>
         /ignore-error/<ignoreError>
```

## 请求参数详解 [#请求参数详解]

| 名称                                    | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/format/&lt;Format&gt;`              |    | **图片输出格式**<br />1、取值：`heic` 或 `avif `，属于 [图片高级压缩](/products/dora/image-processing-api/senior-image-compression/0-avif-compression) 格式，按照图片高级压缩收费，当前仅支持 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 来使用。<br />2、取值：`copy`，保持原图格式输出。<br />**注意**：<br />● 当原图为`heic` 或 `avif` 时，设置`format/copy` 会保持原图格式不变，且不按照图片高级压缩收费；如果不指定 format 参数，将会输出`jpeg` 。 |
| `/ori/&lt;orientation&gt;`            | 是  | 渐变色方向，1 (自上而下) 2 (自右向左) 3 (自下而上) 4 (自左向右)                                                                                                                                                                                                                                                                                                                                                   |
| `/startpos/&lt;startPosition&gt;`     | 是  | 渐变开始位置。单位像素（px）, 如 10，数值为大于0的整数。                                                                                                                                                                                                                                                                                                                                                            |
| `/stoppos/&lt;stopPosition&gt;`       | 是  | 渐变结束位置。单位像素（px）, 如 100，数值为大于0的整数。<br />**注意**：渐变结束位置数值必须大于渐变开始位置。                                                                                                                                                                                                                                                                                                                           |
| `/startclr/&lt;encodedStartColor&gt;` | 是  | 开始位置颜色的透明度, 如 #FF0000FF（红色不透明) , 需要经过URL安全的Base64编码                                                                                                                                                                                                                                                                                                                                         |
| `/stopclr/&lt;encodedStopColor&gt;`   | 是  | 结束位置颜色的透明度, 如 #FF000000（红色透明）, 需要经过URL安全的Base64编码                                                                                                                                                                                                                                                                                                                                           |
| `ignore-error/&lt;ignoreError&gt;`    |    | **设置该参数，取值为1，针对以下场景的处理失败，会直接返回源文件或原输入，而不是报错**：<br />**1**. 图片兼容性问题，导致的处理失败<br />**2**.  触发同步/持久化处理的输入输出限制，如格式、文件大小、宽、高、总像素、帧数，导致的处理失败<br />**注意**：<br />● 不设置此参数，处理失败时返回错误信息；<br />● 当输入文件超过1GB，设置此参数不生效，处理失败时返回错误信息 。                                                                                                                                                                      |

## **使用示例** [#使用示例-4]

* 渐变色方向：1 (自上而下)

* 渐变开始位置：0

* 渐变结束位置：100

* 开始位置颜色及透明度：#FF0000FF（红色不透明）

* 结束位置颜色及透明度：#FF000000（红色透明）

  ```
  https://dora-doc.qiniu.com/gogopher.jpg?watermark/7/ori/1/startpos/0/stoppos/100/startclr/I0ZGMDAwMEZG/stopclr/I0ZGMDAwMDAw
  ```

![图片渐变水印](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/5-image-watermarking-processing-watermark/gogopher-29a1150147ba.webp)

# **操作方式** [#操作方式]

您可以通过 [同步处理](/products/dora/1-features_introduction)、[持久化处理](/products/dora/1-features_introduction)、[图片样式设置](/products/dora/1-features_introduction)、[CDN中间源处理](/products/cdn/configuration-management-fusion/5-image-optimization) 等方式，对图片进行处理，详情介绍请参见[图片处理操作方式](/products/dora/1-features_introduction)。

# **返回原图示例** [#返回原图示例]

加水印时设置 `ignore-error/1`，即 `对特定场景下` 的图片处理失败进行兜底，保证图片处理返回原图或原输入，而不是直接报错；一定程度上提高图片处理的可用性，提升用户体验。

### **示例** [#示例]

* 简单示例，触发同步输出限制，返回原图：`转avif格式的同时加水印`，图片 `w`和`h` 不能超过9999像素，总像素不能超过768w像素。

  ```
  https://dn-dora-document.qbox.me/pexels-clement.jpg?watermark/2/format/avif/text/5LiD54mb5LqR5a2Y5YKo/fontsize/10000/fill/I0ZGRkZGRg==/ignore-error/1
  ```

  ![img](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/5-image-watermarking-processing-watermark/pexels-clement-79e89c0a44bf.webp)

* 复杂示例，使用 [管道](/products/dora/processing-mechanism/3-the-pipe) ，返回原输入：如果第一步 `缩放` ，处理成功；第二步 `转avif格式的同时加水印`，触发avif格式的同步输出限制，设置 ignore-error 生效后，会返回原输入（即第一步处理结果）。

  ```
  https://dn-dora-document.qbox.me/pexels-clement.jpg?imageMogr2/thumbnail/4000x6000!/ignore-error/1|watermark/2/format/avif/text/5LiD54mb5LqR5a2Y5YKo/fontsize/10000/fill/I0ZGRkZGRg==/ignore-error/1
  ```

  ![img](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/5-image-watermarking-processing-watermark/pexels-clement-7ddf0806eb49.webp)

### **计费说明** [#计费说明]

设置 ignore-error/1 生效后，不会计费。

* 计费示例：[管道](/products/dora/processing-mechanism/3-the-pipe) 存在时，比如 `A/ignore-error/1\|B/ignore-error/1`，A处理成功，B处理失败（设置，则A计费，B不计费，结果返回A处理结果。


# 图片处理介绍 (/products/dora/image-processing-api/6-img-directions-for-use)



最近更新时间: 2024-07-24 16:26:46

# **介绍** [#介绍]

为七牛云的图片文件提供图片处理服务，例如：

* 对图片进行缩略操作
* 图片缩放、裁剪、旋转
* 获取图片格式、大小、色彩模型信息
* 提供数码相机照片的可交换图像文件格式
* 图片添加图片、文字、图文混合水印、盲水印等
* 计算图片的平均色调
* 图片高级压缩，支持 avif/heif 高压缩比格式

## **限制说明** [#限制说明]

* 每个服务接口的使用限制各有不同，请在接口文档中查看。

<a id="image-interface" />

# **服务详情** [#服务详情]

| 图片处理                                                                                                                            | 参数                       | 简介                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------- |
| [图片瘦身](/products/dora/image-processing-api/3-image-thin-body-imageslim)                                                         | imageslim                | 将存储在七牛的JPEG、PNG格式的图片实时压缩而尽可能不影响画质。                                           |
| [图片基本处理](/products/dora/image-processing-api/4-basic-processing-images-imageview2)                                              | imageView2               | 可对图片进行缩略操作，生成各种缩略图。imageView2 接口可支持处理的原图片格式有 psd、jpeg、png、gif、webp、tiff、bmp。 |
| [图片高级处理- 缩放](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/0-the-zoom)                        | thumbnail                | 将图片缩放至指定大小。                                                                  |
| [图片高级处理- 裁剪](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/1-tailoring)                       | crop                     | 普通裁剪、缩放裁剪                                                                    |
| [图片高级处理- 旋转](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/2-rotating)                        | auto-orient <br />rotate | 自适应旋转、普通旋转。                                                                  |
| [图片高级处理- 格式转换](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/3-format-conversion)             | format<br /> colors      | 格式转换、GIF 颜色控制。                                                               |
| [图片高级处理- 渐进显示](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/5-progressive-shows)             | interlace                | 将图片调整为渐进显示。                                                                  |
| [图片高级处理- 背景色填充](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/9-the-background-color-fill)    | background               | 对图片填充背景颜色                                                                    |
| [图片高级处理- 质量变换](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/4-the-quality-of-transformation) | q                        | 对图片质量进行调节                                                                    |
| [图片高级处理- 高斯模糊](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/6-gaussian-blur)                 | blur                     | 对图片进行模糊处理                                                                    |
| [图片高级处理- 锐化](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/7-sharpen)                         | sharpen                  | 对图片进行锐化处理                                                                    |
| [图片高级处理- 去除元信息](/products/dora/image-processing-api/the-advanced-treatment-of-images-imagemogr2/8-remove-the-meta-information)  | strip                    | 可去除图片元信息，包括 exif 信息                                                          |
| [图片高级压缩- AVIF ](/products/dora/image-processing-api/senior-image-compression/0-avif-compression)                                | format                   | imageView2 和 imageMogr2 支持图片高级压缩功能，可以更加高效地将图片转化为 AVIF 高压缩比格式。                |
| [图片高级压缩- HEIF ](/products/dora/image-processing-api/senior-image-compression/1-heif-compression)                                | format                   | imageView2 和 imageMogr2 支持图片高级压缩功能，可以更加高效地将图片转化为 HEIF 高压缩比格式。                |
| [图片基本信息](/products/dora/1-features_introduction)                                                                                | imageInfo                | 可以获取图片格式、大小、色彩模型信息。                                                          |
| [图片水印处理](/products/dora/1-features_introduction)                                                                                | watermark                | 提供四种水印接口：图片水印、文字水印，文字平铺水印、混合水印。                                              |
| [图片盲水印处理](/products/dora/image-processing-api/9-blind-watermarking-processing)                                                  | watermark                | 为原图添加不可见水印，不影响原图质量。                                                          |
| [图片EXIF信息](/products/dora/1-features_introduction)                                                                              | exif                     | 获取数码相机照片的可交换图像文件格式。                                                          |
| [图片圆角处理](/products/dora/image-processing-api/7-image-rounded-corner)                                                            | roundPic                 | 将图片生成圆角图片，并且可以指定图片的圆角大小。                                                     |
| [图片主色调](/products/dora/1-features_introduction)                                                                                 | imageAve                 | 用于计算一幅图片的平均色调。                                                               |
| [动图合成](/products/dora/image-processing-api/8-animate)                                                                           | animate                  | 用于将数张图片合成 GIF。                                                               |
| [图片全景拼接服务](/products/dora/image-processing-api/10-panoramic-view-image-splicing-stitch)                                         | stitch                   | 可以帮助您将多张图像拼接起来，拼成一幅大的图像来创建全景图像。                                              |

# **操作方式** [#操作方式]

您可以通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing)、[持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)、[图片样式设置](/products/dora/image-processing-api/12-the-picture-style)、[CDN中间源处理](/products/cdn/configuration-management-fusion/5-image-optimization) 等方式，对图片进行处理，详情介绍请参见[图片处理操作方式](/products/dora/image-processing-api/11-the-image-processing1)。

# **计费说明** [#计费说明]

* 部分图片处理按图片原文件的大小计算数据的处理量进行计量，按量付费，每月提供20TB免费额度。
* 部分数据处理按调用次数收费。
* 详细的计费说明请参见 [计费与定价](https://www.qiniu.com/prices/dora?source=dora)。


# 图片圆角处理（roundPic） (/products/dora/image-processing-api/7-image-rounded-corner)



最近更新时间: 2025-01-14 18:29:56

# **简介** [#简介]

`roundPic` 将图片生成圆角图片，并且可以指定图片的圆角大小。

## **使用限制** [#使用限制]

* 原图格式支持：`png`、`jpg`，处理后的图片格式为`png`
* 同步处理
  * 只支持 20MB 以内的图片，超过 20MB 的图片需要使用持久化处理
  * 处理后图片文件大小没有限制
* 持久化处理
  * 图片文件无大小限制

# **接口规格** [#接口规格]

**注意**：接口规格不含任何空格与换行符。

```
roundPic/radius/<radius>
        /radiusx/<radiusx>
        /radiusy/<radiusy>
```

| 参数名称                       | 必填 | 说明                                                                                          |
| :------------------------- | :- | :------------------------------------------------------------------------------------------ |
| `/radius/&lt;radius&gt;`   | 否  | 圆角大小的参数，水平和垂直的值相同。可以使用：像素值（如200）或者百分比（如!25p），均为非负值。<br />**注意**：不能与`radiusx`和`radiusy`同时使用。 |
| `/radiusx/&lt;radiusx&gt;` | 否  | 圆角水平大小的参数，可以使用：像素值（如200）或者百分比（如!25p），均为非负值。<br />**注意**：需要与`radiusy`同时使用，不能和`radius`同时使用。   |
| `/radiusy/&lt;radiusy&gt;` | 否  | 圆角垂直大小的参数，可以使用：像素值（如200）或者百分比（如!25p），均为非负值。<br />**注意**：需要与`radiusx`同时使用，不能和`radius`同时使用。   |

**注意**：其中当像素数大于宽（高）的1/2时取其1/2，百分比大于!50p时，取!50p；

# **示例** [#示例]

* 原图

  ![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/7-image-rounded-corner/gogopher-caff95e8587b.webp)

* 把一张图片变成圆角：

  ```
  https://dora-doc.qiniu.com/gogopher.jpg?roundPic/radius/50
  ```

  ![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/7-image-rounded-corner/gogopher-e14df54d37e4.webp)

# **操作方式** [#操作方式]

您可以通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing)、[持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)、[图片样式设置](/products/dora/image-processing-api/12-the-picture-style)等方式，对图片进行处理，暂不支持`CDN中间源处理`，详情介绍请参见[图片处理操作方式](/products/dora/image-processing-api/11-the-image-processing1)。


# 动图合成（animate） (/products/dora/image-processing-api/8-animate)



最近更新时间: 2024-10-30 10:05:55

# **简介** [#简介]

动图合成接口（animate）用于将多张图片合成 GIF 动图。

## **使用限制** [#使用限制]

* 目前仅适用于存储在七牛的图片
* 原图限制：
  * 支持的格式有 jpeg 和 png
  * 支持的最大帧数为 20
  * 支持的最大图片尺寸为 1080\*1080

# **接口规格** [#接口规格]

```
animate/duration/<duration>
       /merge/key/<encodedImageKey>
             /key/<encodedImageKey>
             ...
       /effect/<effectType>
```

## 参数说明 [#参数说明]

| 名称                                  |  必填 | 说明                                                                                                                    |
| ----------------------------------- | :-: | --------------------------------------------------------------------------------------------------------------------- |
| `duration/&lt;duration&gt;`         |  Y  | GIF动图的每帧间隔时间(单位: 0.01s)，取值要求为大于0的整数。                                                                                  |
| `merge/key/&lt;encodedImageKey&gt;` |  N  | 合成GIF动图的源图片key，需要经过Base64编码，保证所有的图片都来源于同一个bucket。<br />**例如**：Key=upload.png，encodedKey=urlsafe\_base64\_encode(Key)。 |
| `/effect/&lt;effectType&gt;`        |  N  | 定义播放顺序，取值：0，1。（0:正序循环播放；1:倒序循环播放；）默认为0。                                                                               |

# **示例** [#示例]

用3张图片合成GIF动图

```
https://dora-doc.qiniu.com/gogopher.jpg?animate/duration/1/merge/key/cWluaXUucG5n/key/cWluaXUucG5n/key/cWluaXUucG5n
```

# **操作方式** [#操作方式]

您可以通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing)、[持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)、[图片样式设置](/products/dora/image-processing-api/12-the-picture-style) 等方式，暂不支持`CDN中间源处理`，对图片进行处理，详情介绍请参见[图片处理操作方式](/products/dora/image-processing-api/11-the-image-processing1)。

# **服务价格** [#服务价格]

计费方式：按调用次数计费。
价格：0.2元/千次。


# 盲水印处理（watermark） (/products/dora/image-processing-api/9-blind-watermarking-processing)



最近更新时间: 2024-07-24 16:26:46

# **简介** [#简介]

肉眼可见的水印方式，一般用于标志图片的出处或者用于声明版权，会破坏原图，且影响美观。七牛提供盲水印功能，隐蔽性强，在不破坏原始作品的情况下，实现版权的防护与追踪。当图片被盗用后，您可对图片进行盲水印解码，验证版权归属。

七牛提供的盲水印功能有两种类型：

| 水印类型  | 说明             |
| ----- | -------------- |
| 图片盲水印 | 将图片作为盲水印添加到图片中 |
| 文字盲水印 | 将文字作为盲水印添加到图片中 |

## **限制说明** [#限制说明]

* 原图限制：

  ```
  1. 格式支持 jpg、png
  2. 宽高限制为：4096x4096
  3. version为3时，原图的尺寸宽高都需大于512
  ```

* 编码、解码的 version 要相同

* 盲水印主要为CPU密集型任务，处理时间会随着图片文件的增大而增大

* 建议使用 version/3，相较于之前的版本有以下优化：

  ```
  1. 解水印不需要对比原图，去除对原图的依赖
  2. 抗大面积涂抹&裁剪攻击
  ```

# **应用场景** [#应用场景]

**隐形美观**

盲水印是一种肉眼不可见的水印方式，可以保持图片美观的同时，保护您的资源版权。

**版权保护**

对图片资源使用图片盲水印或者文字水印，借此避免数字媒体未经授权的复制和拷贝，可通过对原图进行解码操作，得到水印图来证明版权归属。

**防泄漏**

对于内部分享的图片资源，您可使用盲水印功能，加上不同标识，如果资料被复制、传播可根据解码出的唯一标识得出泄露方信息。

# **图片盲水印** [#图片盲水印]

## **接口规格** [#接口规格]

```
watermark/5
         /version/<version>
         /method/<method>
         /imageKey/<encodedImageKey>
         /orignal/<encodedImage>
```

## **添加水印** [#添加水印]

version 为1或2时，请求参数说明如下：

| 名称                                  |  必填 | 说明                                                                                                                                                                                         |
| ----------------------------------- | :-: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/version/&lt;version&gt;`          |  N  | 接口版本值为1或2 , 默认为 1。                                                                                                                                                                         |
| `/method/&lt;method&gt;`            |  Y  | 盲水印标志位，编码（添加水印）为encode。                                                                                                                                                                    |
| `/imageKey/&lt;encodedImageKey&gt;` |  N  | 水印图片（经过URL安全的Base64编码），图片来源为七牛bucket（需要与输入图片在同一个bucket中）。<br />**例如**：imageKey=upload.png，encodedImageKey=urlsafe\_base64\_encode(imageKey)。<br />**注意**：水印图片宽高分别不超过原图宽高的二分之一，图片为黑底白字效果更佳。 |

version 为3时，请求参数说明如下：

| 名称                                  | 必填 | 说明                                                                                                                                           |
| ----------------------------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `/version/&lt;version&gt;`          | N  | 接口版本值为3，注意：<br />1）原图的宽高都需大于512。<br />2）水印图片的限制，必须是二值图像，且水印的大小为64x64，如果不符合条件， 会缩放和处理图片到服务要求。                                                 |
| `/method/&lt;method&gt;`            | Y  | 盲水印标志位，编码（即添加水印）为encode。                                                                                                                     |
| `/imageKey/&lt;encodedImageKey&gt;` | N  | 水印图片（经过URL安全的Base64编码），图片来源为七牛bucket（需要与输入图片在同一个bucket中）。<br />**例如**：imageKey=upload.png，encodedImageKey=urlsafe\_base64\_encode(imageKey)。 |

## **提取水印** [#提取水印]

version 为1或2时，请求参数说明如下：

| 名称                              | 必填 | 说明                                                          |
| ------------------------------- | -- | ----------------------------------------------------------- |
| `/version/&lt;version&gt;`      | N  | 接口版本值为1或2 , 默认为 1。                                          |
| `/method/&lt;method&gt;`        | Y  | 盲水印标志位，解码（即提取水印）为decode。                                    |
| `/orignal/&lt;encodedImage&gt;` | N  | 解码对比原图（经过URL安全的Base64编码），图片来源为七牛bucket（需要与输入图片在同一个bucket中）。 |

version 为3时，请求参数说明如下：

| 名称                         | 必填 | 说明                       |
| -------------------------- | -- | ------------------------ |
| `/version/&lt;version&gt;` | N  | 接口版本值为3，注意：原图的宽高都需大于512。 |
| `/method/&lt;method&gt;`   | Y  | 盲水印标志位，解码（即提取水印）为decode。 |

## **示例** [#示例]

1-1.编码/ 添加盲水印（version/3)

```
https://dora-doc.qiniu.com/gogopher1.jpg?watermark/5/version/3/method/encode/imageKey/cWluaXUtbG9nby0zLnBuZw==
```

![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/9-blind-watermarking-processing/gogopher1-37d52257fa4f.webp)

1-2.解码/ 提取盲水印（version/3)

```
https://dora-doc.qiniu.com/gogopher1.jpg?watermark/5/version/3/method/encode/imageKey/cWluaXUtbG9nby0zLnBuZw==|watermark/5/version/3/method/decode
```

![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/9-blind-watermarking-processing/gogopher1-ed70b8bfbbc0.webp)

2-1.编码/ 添加盲水印（version/2)

```
https://dora-doc.qiniu.com/gogopher.jpg?watermark/5/version/2/method/encode/imageKey/dXBkYXRlLmpwZw==
```

![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/9-blind-watermarking-processing/gogopher-caff95e8587b.webp)

2-2.解码/ 提取盲水印（version/2)

```
https://dora-doc.qiniu.com/gogopher.jpg?watermark/5/version/2/method/encode/imageKey/dXBkYXRlLmpwZw==|watermark/5/version/2/method/decode/orignal/Z29nb3BoZXIuanBn
```

![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/9-blind-watermarking-processing/gogopher-3bbab346e878.webp)

# **文字盲水印** [#文字盲水印]

## **接口规格** [#接口规格-1]

```
watermark/6
         /version/<version>
         /method/<method>
         /text/<encodedText>
         /orignal/<encodedImage>
```

## **添加水印** [#添加水印-1]

version 为1和2时，请求参数说明如下：

| 名称                          | 必填 | 说明                                                   |
| --------------------------- | -- | ---------------------------------------------------- |
| `/version/&lt;version&gt;`  | N  | 接口版本 可选1、2 , 默认为 1。                                  |
| `/method/&lt;method&gt;`    | Y  | 盲水印标志位，编码（添加水印）为encode。                              |
| `/text/&lt;encodedText&gt;` | N  | 水印文字（经过URL安全的Base64编码）。只支持英文数字字符，不支持中文字符，数量上限分别为 10。 |

version 为3时，请求参数说明如下：

| 名称                          | 必填 | 说明                                                   |
| --------------------------- | -- | ---------------------------------------------------- |
| `/version/&lt;version&gt;`  | N  | 版本为3时，注意：原图的宽高都需大于512。                               |
| `/method/&lt;method&gt;`    | Y  | 盲水印标志位，编码（添加水印）为encode。                              |
| `/text/&lt;encodedText&gt;` | N  | 水印文字（经过URL安全的Base64编码）。只支持英文数字字符，不支持中文字符，数量上限分别为 15。 |

## **提取水印** [#提取水印-1]

version 为1和2时，请求参数说明如下：

| 名称                              | 必填 | 说明                                                          |
| ------------------------------- | -- | ----------------------------------------------------------- |
| `/version/&lt;version&gt;`      | N  | 接口版本 可选1、2 , 默认为 1。                                         |
| `/method/&lt;method&gt;`        | Y  | 盲水印标志位，解码（即提取水印）为decode。                                    |
| `/orignal/&lt;encodedImage&gt;` | N  | 解码对比原图（经过URL安全的Base64编码），图片来源为七牛bucket（需要与输入图片在同一个bucket中）。 |

version 为3时，请求参数说明如下：

| 名称                         | 必填 | 说明                       |
| -------------------------- | -- | ------------------------ |
| `/version/&lt;version&gt;` | N  | 版本为3时，注意：原图的宽高都需大于512。   |
| `/method/&lt;method&gt;`   | Y  | 盲水印标志位，解码（即提取水印）为decode。 |

## **示例** [#示例-1]

1-1.编码/ 添加盲水印（version/3）

```
https://dora-doc.qiniu.com/gogopher1.jpg?watermark/6/version/3/method/encode/text/MTIzNDU2Nzg5
```

![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/9-blind-watermarking-processing/gogopher1-db7a5f5fb5f1.webp)

1-2.解码/ 提取盲水印（version/3）

```
https://dora-doc.qiniu.com/gogopher1.jpg?watermark/6/version/3/method/encode/text/MTIzNDU2Nzg5|watermark/6/version/3/method/decode
```

![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/9-blind-watermarking-processing/gogopher1-136fb268cfee.webp)

2-1.编码/ 添加盲水印（version/2）

```
https://dora-doc.qiniu.com/gogopher.jpg?watermark/6/version/2/method/encode/text/OTAyR0h3cmM=
```

![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/9-blind-watermarking-processing/gogopher-81a555ac9051.webp)

2-2.解码/ 提取盲水印（version/2）

```
https://dora-doc.qiniu.com/gogopher.jpg?watermark/6/version/2/method/encode/text/OTAyR0h3cmM=|watermark/6/version/2/method/decode/orignal/Z29nb3BoZXIuanBn
```

![查看效果图](/docs-assets/products/dora/%284-api-docs%29/image-processing-api/9-blind-watermarking-processing/gogopher-ff9b9a3c034f.webp)

# **操作方式** [#操作方式]

您可以通过 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing)、[持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)、[图片样式设置](/products/dora/image-processing-api/12-the-picture-style)等方式，对图片进行处理，目前盲水印功能不支持 `CDN中间源处理`，详情介绍请参见[图片处理操作方式](/products/dora/image-processing-api/11-the-image-processing1)。

# **计费说明** [#计费说明]

| 处理类型   | 价格     |
| :----- | :----- |
| 盲水印-添加 | 1 元/千次 |
| 盲水印-提取 | 1 元/千次 |


# Open API 介绍 (/products/dora/introduction-to-the-third-party-data-processing/0-the-third-party-data-processing)



最近更新时间: 2021-11-18 16:25:43

<a id="fop-third-party-what" />

# 概述 [#概述]

七牛第三方数据处理是一个开放平台，欢迎各种图片、音视频、以及其他数据处理的第三方应用提供方接入，为七牛云存储中的海量数据，提供增值的数据处理服务。

<a id="fop-third-party-why" />

# 为什么要加入？ [#为什么要加入]

* 七牛云存储海量数据和丰富的用户
* 与七牛现有的数据处理应用无缝连接
* 支持管道处理、持久化、预处理操作等所有特性
* 零运维、随时弹性伸缩
* 支持主流开发语言，提供一键部署服务

<a id="fop-third-party-conditions" />

# 加入条件 [#加入条件]

提供高质量的数据处理服务，能够在七牛海量数据处理请求下，保障服务的可靠运行。

<a id="access-flow" />

# 接入流程 [#接入流程]

1. 参考[自定义数据处理](/products/dora/processing-mechanism/1-directions-for-use-pfop)来构建自定义数据处理应用。
2. 提供文档（[示例](/products/dora/0-dora-product-introduction)，可以是 .md 格式）和 logo（180px\*180px，.ai 格式），并测试。


# 数美视频流审核 (/products/dora/introduction-to-the-third-party-data-processing/1-the-video-review)



最近更新时间: 2021-11-18 16:25:43

# 功能描述 [#功能描述]

本功能基于先进的人工智能技术，精准识别各类场景涉政、色情、暴恐、垃圾广告、Logo水印等违规内容，帮助您提前防御内容风险，提高审核效率，净化网络环境，提升用户体验。

# 接口规格 [#接口规格]

## 提交视频流识别请求 [#提交视频流识别请求]

**请求URL**: `https://censor-open.qiniuapi.com/anti_fraud/v3/videostream`

**字符编码格式**: 请求及返回结果都使用 UTF-8 字符集进行编码

**请求方法**: POST

**建议超时时长**: 3s

### 请求参数 [#请求参数]

放在 HTTP Body 中，采用 Json 格式，具体参数如下:

| 参数名称          | 类型           | 是否必选 | 说明                                                                                                                                                                                                                                                                                                               |
| :------------ | :----------- | :--- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| imgType       | string       | Y    | 视频流截帧识别类型，可选值: <br />DEFAULT:默认识别涉政、色情、广告，取值为POLITICS\_PORN\_AD，DEFAULT只能单独 使用不能连接其他类型，否则DEFAULT失效 <br />POLITICS:涉政识别 <br />PERSON:涉政人物识别 <br />VIOLENCE:暴恐识别 <br />PORN:色情识别 <br />AD:广告识别 <br />LOGO:视频水印logo识别 <br />BEHAVIOR:不良场景识别，支持吸烟、喝酒、赌博、吸毒、避孕套和无意义画面 <br />通过下划线连接，如AD\_PORN\_POLITICS用于广告、色情和涉政组合识别 |
| audioType     | string       | Y    | 视频流中的音频流识别类型，可选值: <br />DEFAULT:默认识别涉政、色情、广告，等价于POLITICAL\_PORN\_AD <br />POLITICAL:涉政识别 <br />PORN:色情识别 <br />AD:广告识别 <br />MOAN:娇喘识别 <br />NONE:不识别音频 <br />如需做组合识别，通过下划线连接即可，例如 POLITICAL\_PORN\_MOAN用于涉政、色情和娇喘识别。                                                                                            |
| imgCallback   | string       | Y    | 图片回调地址，将视频流中截帧图片的检测结 果通过该地址回调给用户。                                                                                                                                                                                                                                                                                |
| audioCallback | string       | N    | 音频回调地址，将视频流中音频的检测结果通 过该地址回调给用户; <br />audioType值不为NONE时必传。                                                                                                                                                                                                                                                       |
| data          | json\_object | Y    | 请求数据，最长1MB，详细内容参见下表                                                                                                                                                                                                                                                                                              |

其中，data的内容如下:

| 参数名称            | 类型     | 是否必选 | 说明                                                                                          |
| :-------------- | :----- | :--- | :------------------------------------------------------------------------------------------ |
| url             | string | Y    | 要检测的视频流url地址，目前仅支持rtmp协议                                                                    |
| tokenId         | string | Y    | 用户账号标识                                                                                      |
| returnAllImg    | int    | N    | 用户可根据需求选择返回不同审核结果的图片，可选值为0 和1，默认值为0。 <br />0:回调reject、review结果的图片审核信息 <br />1:回调所有结果的图片审核信息 |
| streamName      | string | N    | 视频流名称                                                                                       |
| returnAllText   | bool   | N    | 取值为true时返回全量的音频流片段识别结果和文本内容; <br />取值为false时只返回有风险(riskType为REJECT)的音频流片段识别结果和文本内容，默认是false |
| detectFrequency | float  | N    | 视频流截帧频率，取值范围:1-60(秒/帧)，默认为3                                                                 |
| room            | string | N    | 直播间/游戏房间编号，可针对单个房间制定不同的策略;                                                                  |

### 返回参数 [#返回参数]

放在 HTTP Body 中，采用 Json 格式，具体参数如下:

| 参数名称    | 类型     | 是否必选 | 说明                  |
| :------ | :----- | :--- | :------------------ |
| code    | int    | Y    | 返回码                 |
| message | string | Y    | 返回码详情描述             |
| entryId | string | Y    | 请求唯一标识，建议保存可用于关闭视频流 |

## 异步回调识别结果 [#异步回调识别结果]

**支持协议**: HTTP或HTTPS

**字符编码格式**: 请求及返回结果都使用UTF-8字符集进行编码

**请求方法**: POST

**建议超时时长**: 5s

**返回字段**:
放在 HTTP Body 中，采用 Json 格式，具体参数如下:

| 参数名称        | 类型           | 是否必选 | 说明                                                                              |
| :---------- | :----------- | :--- | :------------------------------------------------------------------------------ |
| code        | int          | Y    | 返回码                                                                             |
| message     | string       | Y    | 返回码详情描述                                                                         |
| entryId     | string       | Y    | 请求唯一标识                                                                          |
| riskLevel   | string       | N    | 风险级别(code为1100时存在)，可能返回值: <br />PASS:正常内容 <br />REVIEW:疑似违规内容 <br />REJECT:违规内容 |
| contentType | int          | Y    | 用来区分音频和图片回调，可能取值为1和2。 <br />1:该回调为图片回调 <br />2:该回调为音频回调                         |
| detail      | json\_object | N    | 视频流中截帧图片或者音频片段的风险详 情(code 为 1100 时存在)                                           |

其中，在图片回调(contentType 为 1)时，detail 内容如下

| 参数名称              | 类型          | 是否必选 | 说明                                                                                                                                                                                                        |
| :---------------- | :---------- | :--- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| room              | string      | N    | 房间号，当客户传入时返回该字段                                                                                                                                                                                           |
| requestParams     | json object | Y    | 返回请求参数data中的所有字段                                                                                                                                                                                          |
| imgUrl            | string      | Y    | 截帧图片url地址，有效时间30分钟                                                                                                                                                                                        |
| beginProcessTime  | int         | Y    | 截帧生成时间(13位时间戳)                                                                                                                                                                                            |
| finishProcessTime | int         | Y    | 检测完成时间(13位时间戳)                                                                                                                                                                                            |
| imgTime           | string      | Y    | 视频流截帧图片违规发生的时间(绝对时间)                                                                                                                                                                                      |
| riskType          | int         | Y    | 标识风险类型，可能取值: <br />0: 正常 <br />100:涉政 <br />200:色情 <br />210:性感 <br />300:广告 <br />310:二维码 <br />320:水印 <br />400:暴恐 <br />500:违规 <br />510:不良场景 <br />700:黑名单 <br />710:白名单 <br />800:高危账号 <br />900:自定义 |
| model             | string      | Y    | 策略规则标识，用来标识命中的策略规则                                                                                                                                                                                        |
| descriptionV2     | string      | N    | 新版策略规则风险原因描述                                                                                                                                                                                              |
| matchedItem       | string      | N    | 命中的具体敏感词(该参数仅在命中敏感词时存在)                                                                                                                                                                                   |
| matchedList       | string      | N    | 命中敏感词所在的名单名称(该参数仅在命中敏感词时存在)                                                                                                                                                                               |
| matchedDetail     | string      | N    | 命中的敏感词详请                                                                                                                                                                                                  |
| imgText           | string      | N    | 视频中画面识别出的文字内容                                                                                                                                                                                             |

其中，在音频回调(contentType 为 2)时，detail 内容如下:

| 参数名称          | 类型           | 是否必选 | 说明                         |
| :------------ | :----------- | :--- | :------------------------- |
| audioText     | string       | Y    | 音频转译文本结果                   |
| audioTime     | int          | N    | 整段音频的音频时长，单位秒，code为1100时存在 |
| labels        | string       | N    | 音频片段风险原因汇总                 |
| detail        | json\_array  | N    | 风险详情                       |
| gender        | json\_object | N    | 性别标签与概率值                   |
| tags          | json\_array  | N    | 音色标签与概率值列表                 |
| callbackParam | json\_object | Y    | 客户传入的透传字段                  |

detail 数组中每一项的具体参数如下:

| 参数名称           | 类型          | 是否必选 | 说明                                                                                                                              |
| :------------- | :---------- | :--- | :------------------------------------------------------------------------------------------------------------------------------ |
| room           | string      | N    | 房间号，当客户传入时返回该字段                                                                                                                 |
| requestParams  | json object | Y    | 返回请求参数data中的所有字段                                                                                                                |
| audioUrl       | string      | Y    | 视频流中音频流片段的url地址，有效时间30分钟                                                                                                        |
| audioStartTime | string      | Y    | 视频流中音频违规内容开始时间(绝对时间)                                                                                                            |
| audioEndTime   | string      | Y    | 视频流中音频违规内容结束时间(绝对时间)                                                                                                            |
| riskType       | int         | Y    | 风险类型，可能取值: <br />0:正常 <br />100:涉政 <br />120:国歌 <br />200:色情 <br />210:辱骂 <br />250:娇喘 <br />300:广告 <br />700:黑名单 <br />900:自定义 |
| matchedItem    | string      | N    | 音频中可能出现的敏感词                                                                                                                     |
| descriptionV2  | string      | Y    | 风险原因描述                                                                                                                          |
| isSing         | int         | N    | type取值包含SING时存在，取值0表示检测不存在唱歌片段，取值1表示检测存在唱歌片段                                                                                    |
| language       | json\_array | N    | 语种标签与概率值列表                                                                                                                      |
| audioText      | string      | Y    | 音频片段对应的文本内容                                                                                                                     |

language 数组中每一项具体参数如下:

| 参数名称       | 类型  | 是否必选 | 说明                                               |
| :--------- | :-- | :--- | :----------------------------------------------- |
| label      | int | Y    | 语种识别类别标识，可能取值: <br />0:普通话 <br />1:英语 <br />2:粤语 |
| confidence | int | Y    | 对应语种标签可能性大小，取值0-100，数值越高表示概率越大。                  |

## 关闭视频流识别 [#关闭视频流识别]

**请求URL**: `https://censor-open.qiniuapi.com/anti_fraud/v3/finish_videostream`

**字符编码格式**: 请求及返回结果都使用UTF-8字符集进行编码

**请求方法**: POST

**建议超时时长**: 5s

## 请求参数 [#请求参数-1]

放在 HTTP Body 中，采用 Json 格式，具体参数如下:

| 参数名称    | 类型     | 是否必选 | 说明              |
| :------ | :----- | :--- | :-------------- |
| entryId | string | Y    | 音频唯一标识，用于查询识别结果 |

# 示例 [#示例]

## 请求示例 [#请求示例]

```
POST /anti_fraud/v3/videostream HTTP/1.1
Host: censor-open.qiniuapi.com
Content-Type: application/json
Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=

{
    "audioCallback": "http://xxx",
    "audioType": "PORN",
    "data":{
        "channel": "VIDEOSTREAM",
        "returnAllImg": 1,
        "returnAllText": true,
        "room": "001",
        "tokenId": "1157893895",
        "url": "rtmp://xxxx"
    },
    "imgCallback":"http://xxxxxxxxx",
    "imgType": "DEFAULT"
}
```

## 返回示例 [#返回示例]

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "code":1100,
    "message":"成功",
    "entryrid":"5564f430ee6a1adb40f06d768b40316b",
}
```

## 回调示例（图像内容) [#回调示例图像内容]

```
POST /xxxx HTTP/1.1
Host: xxxx
Content-Type: application/json

{
    "code":1100,
    "message":"成功",
    "entryId":"b891cf2d82e214de45df33fc2bea4875",
    "riskLevel":"REJECT",
    "contentType":1,
    "detail":{
        "descriptionV2":"正常",
        "imgText":"ocr123 你好",
        "imgTime":"2019-09-20 14:53:25",
        "imgUrl":"http://yyyyyyyyyyyyyyyyy.jpg",
        "matchedDetail":"[{"listId":"0b5d2ed695d40c0aa51e2b35fb51763d","matchedFiled":["text"],"name":"涉政测试","organization":"RlokQwRlVjUrTUlkIqOg","words":[" 你好"]}]",
        "matchedItem":"你好",
        "matchedList":"涉政测试",
        "model":"M02601",
        "polityName":"你好",
        "requestParams":{
            "channel":"VIDEOSTREAM",
            "returnAllImg":1,
            "returnAllText":true,
            "room":"001",
            "tokenId":"1157893895",
            "url":"rtmp://xxxxxxx"
        },
        "riskType":100,
        "room":"001"
    }
}
```

## 回调示例（音频内容) [#回调示例音频内容]

```
POST /xxxx HTTP/1.1
Host: xxxx
Content-Type: application/json

{
    "code":1100,
    "message":"成功",
    "entryId":"b891cf2d82e214de45df33fc2bea4875",
    "riskLevel":"REJECT",
    "contentType":2,
    "detail":{
        "audioEndTime":"2019-09-20 15:27:35",
        "audioStartTime":"2019-09-20 15:27:25",
        "audioText":"老婆",
        "audioUrl":"http://xxxxxxxxxxx.mp3",
        "model":"M02101",
        "requestParams":{
            "channel":"VIDEOSTREAM",
            "returnAllImg":1,
            "returnAllText":true,
            "room":"001",
            "tokenId":"1157893895",
            "url":"rtmp://xxxxxxx"
        },
        "riskType":200,
        "room":"001"
    }
}
```

# 错误码 [#错误码]

| Code | Message |
| :--: | :-----: |
| 1100 |    成功   |
| 1901 |  QPS受限  |
| 1902 |  参数不合法  |
| 1903 |   服务失败  |
| 1911 |   下载超时  |
| 91xx |   内部错误  |


# 数美音频文件审核 (/products/dora/introduction-to-the-third-party-data-processing/2-number-of-audio-files-to-review)



最近更新时间: 2021-11-18 16:25:43

# 功能描述 [#功能描述]

音频文件审核功能为音频文件的内容审核场景提供涉政，国歌，色情，广告，娇喘，音色标签，唱歌等内容的识别，并且可以依据具体的业务场景进行配置，帮助您提前防御内容风险，提高审核效率，净化网络环境，提升用户体验。

# 接口规格 [#接口规格]

## 提交音频识别请求 [#提交音频识别请求]

**请求URL**: `https://censor-open.qiniuapi.com/anti_fraud/v2/audio`

**字符编码格式**: 请求及返回结果都使用 UTF-8 字符集进行编码

**请求方法**: POST

**建议超时时长**: 3s

#### 请求参数 [#请求参数]

放在 HTTP Body 中，采用 Json 格式，具体参数如下:

| 参数名称          | 类型           | 是否必选 | 说明                                                                                                                                                                                                                            |
| :------------ | :----------- | :--- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type          | string       | Y    | 需要识别的违规类型，可选值: <br />POLITICAL:涉政识别 <br />ANTHEN:国歌识别 <br />PORN:色情识别 <br />AD:广告识别 <br />MOAN:娇喘识别  <br />SING:唱歌识别 <br />如需做组合识别，通过下划线连接即可，例如AD\_PORN\_POLITICAL用于广告、色情和涉政识别。<br />DEFAULT: 默认取值<br />POLITICAL\_PORN\_MOAN |
| data          | json\_object | Y    | 请求数据，最长1MB，详细内容参见下表                                                                                                                                                                                                           |
| callback      | string       | N    | 异步检测结果回调通知您的URL，支持HTTP和HTTPS。字段为空时，您必须通过查询接口主动查询结果。                                                                                                                                                                           |
| callbackParam | json\_object | N    | 透传字段，当callback存在时可选，发送回调请求时服务将该字段内容同音频结果一起返回                                                                                                                                                                                  |

其中，data的内容如下:

| 参数名称          | 类型     | 是否必选 | 说明                                                                                         |
| :------------ | :----- | :--- | :----------------------------------------------------------------------------------------- |
| url           | string | Y    | 待识别音频url地址                                                                                 |
| audioName     | string | N    | 音频文件名称                                                                                     |
| tokenId       | string | N    | 用户账号标识                                                                                     |
| channel       | string | N    | 业务场景名称，见channel字段说明                                                                        |
| returnAllText | bool   | N    | 取值为true时，返回所有音频片段识别结果(每10秒一个音频片段);取值为false 时，返回风险片段(riskLevel为REJECT或REVIEW)识别结果。默认为false。 |
| nickname      | string | N    | 用户昵称                                                                                       |
| timestamp     | int    | N    | 时间戳(毫秒级)                                                                                   |
| room          | string | N    | 房间号                                                                                        |

channel字段说明

根据客户不同业务场景，配置不同的渠道(channel)，制定针对性的拦截策略，同时也方便客户针对不同业务场景的数据进行筛选、分析。业务场景和渠道取值对应表如下:

| 业务场景 |   channel 取值   |    备注    |
| :--: | :------------: | :------: |
| 群聊语音 |   GROUP\_CHAT  | 群聊中的语音消息 |
| 私聊语音 |     MESSAGE    | 私聊中的语音消息 |
| 录播语音 | AUDIO\_PROFILE |  语音录播文件  |

#### 返回参数 [#返回参数]

放在 HTTP Body 中，采用 Json 格式，具体参数如下:

| 参数名称    | 类型     | 是否必选 | 说明      |
| :------ | :----- | :--- | :------ |
| code    | int    | Y    | 返回码     |
| message | string | Y    | 返回码详情描述 |
| entryId | string | Y    | 请求唯一标识  |

### 异步回调识别结果 [#异步回调识别结果]

用户如果需要服务端主动对音频检测结果进行回调，则需要在请求参数中传入callback参数，服务端审核完成后将识别结果主动回调到该地址。

**支持协议**: HTTP或HTTPS

**字符编码格式**: 请求及返回结果都使用UTF-8字符集进行编码

**请求方法**: POST

**建议超时时长**: 5s

**返回字段**:
放在 HTTP Body 中，采用 Json 格式，具体参数如下:

| 参数名称          | 类型           | 是否必选 | 说明                                                                |
| :------------ | :----------- | :--- | :---------------------------------------------------------------- |
| code          | int          | Y    | 返回码                                                               |
| message       | string       | Y    | 返回码详情描述                                                           |
| entryId       | string       | Y    | 请求唯一标识                                                            |
| audioText     | string       | Y    | 音频转译文本结果                                                          |
| audioTime     | int          | N    | 整段音频的音频时长，单位秒，code为1100时存在                                        |
| labels        | string       | N    | 音频片段风险原因汇总                                                        |
| riskLevel     | string       | N    | 识别结果，可能返回值: <br />PASS:正常内容 <br />REVIEW:疑似违规内容 <br />REJECT:违规内容 |
| detail        | json\_array  | N    | 风险详情                                                              |
| gender        | json\_object | N    | 性别标签与概率值                                                          |
| isSing        | int          | N    | 表示该条音频文件是否唱歌，0表示没有唱歌，1表示唱歌。 <br />仅当type传入值包含SING时返回。             |
| language      | json\_array  | N    | 语种标签与概率值列表                                                        |
| tags          | json\_array  | N    | 音色标签与概率值列表                                                        |
| callbackParam | json\_object | Y    | 客户传入的透传字段                                                         |

detail 数组中每一项的具体参数如下:

| 参数名称             | 类型     | 是否必选 | 说明                                                                                                                              |
| :--------------- | :----- | :--- | :------------------------------------------------------------------------------------------------------------------------------ |
| audioStarttime   | int    | Y    | 风险音频片段在音频中的起始时间，单位秒                                                                                                             |
| audioEndtime     | int    | Y    | 风险音频片段在音频中的结束时间，单位秒                                                                                                             |
| audioUrl         | string | Y    | 风险音频片段地址                                                                                                                        |
| audioText        | string | Y    | 音频片段对应的文本内容                                                                                                                     |
| riskLevel        | string | Y    | 识别结果，可能返回值: <br />REJECT:违规内容 <br />REVIEW:疑似违规内容                                                                               |
| riskType         | int    | N    | 风险类型，可能取值: <br />0:正常 <br />100:涉政 <br />120:国歌 <br />200:色情 <br />210:辱骂 <br />250:娇喘 <br />300:广告 <br />700:黑名单 <br />900:自定义 |
| audioMatchedItem | string | N    | 音频中可能出现的敏感词                                                                                                                     |
| description      | string | Y    | 风险原因描述                                                                                                                          |

gender 参数结构如下:

| 参数名称       | 类型     | 是否必选 | 说明                             |
| :--------- | :----- | :--- | :----------------------------- |
| label      | string | Y    | 性别标签名称，可能取值: <br />男性 <br />女性 |
| confidence | int    | Y    | 对应性别可能性大小，取值0-100，数值越高表示概率越大。  |

language 数组中每一项具体参数如下:

| 参数名称       | 类型  | 是否必选 | 说明                                               |
| :--------- | :-- | :--- | :----------------------------------------------- |
| label      | int | Y    | 语种识别类别标识，可能取值: <br />0:普通话 <br />1:英语 <br />2:粤语 |
| confidence | int | Y    | 对应语种标签可能性大小，取值0-100，数值越高表示概率越大。                  |

tags 数组中每一项具体参数如下:

| 参数名称       | 类型     | 是否必选 | 说明                                                                                                     |
| :--------- | :----- | :--- | :----------------------------------------------------------------------------------------------------- |
| label      | string | Y    | 音色标签类别，可能取值: <br />大叔音 <br />青年音 <br />正太音 <br />老年音 <br />女王音 <br />御姐音 <br />少女音 <br />萝莉音 <br />大妈音 |
| confidence | int    | Y    | 对应音色标签可能性大小，取值0-100，数值越高表示概率越大。                                                                        |

## 查询识别结果 [#查询识别结果]

**请求URL**: `https://censor-open.qiniuapi.com/anti_fraud/v2/query_audio`

**字符编码格式**: 请求及返回结果都使用UTF-8字符集进行编码

**请求方法**: POST

**建议超时时长**: 5s

#### 请求参数: [#请求参数-1]

放在 HTTP Body 中，采用 Json 格式，具体参数如下:

| 参数名称    | 类型     | 是否必选 | 说明              |
| :------ | :----- | :--- | :-------------- |
| entryId | string | Y    | 音频唯一标识，用于查询识别结果 |

#### 返回参数: [#返回参数-1]

放在 HTTP Body 中，采用 Json 格式，具体参数如下:

| 参数名称          | 类型           | 是否必选 | 说明                                                                |
| :------------ | :----------- | :--- | :---------------------------------------------------------------- |
| code          | int          | Y    | 返回码                                                               |
| message       | string       | Y    | 返回码详情描述                                                           |
| entryId       | string       | Y    | 请求唯一标识                                                            |
| audioText     | string       | Y    | 音频转译文本结果                                                          |
| audioTime     | int          | N    | 整段音频的音频时长，单位秒，code为1100时存在                                        |
| labels        | string       | N    | 音频片段风险原因汇总                                                        |
| riskLevel     | string       | N    | 识别结果，可能返回值: <br />PASS:正常内容 <br />REVIEW:疑似违规内容 <br />REJECT:违规内容 |
| detail        | json\_array  | N    | 风险详情                                                              |
| gender        | json\_object | N    | 性别标签与概率值                                                          |
| isSing        | int          | N    | 表示该条音频文件是否唱歌，0表示没有唱歌，1表示唱歌。 <br />仅当type传入值包含SING时返回。             |
| language      | json\_array  | N    | 语种标签与概率值列表                                                        |
| tags          | json\_array  | N    | 音色标签与概率值列表                                                        |
| callbackParam | json\_object | Y    | 客户传入的透传字段                                                         |

detail 数组中每一项的具体参数如下:

| 参数名称             | 类型     | 是否必选 | 说明                                                                                                                              |
| :--------------- | :----- | :--- | :------------------------------------------------------------------------------------------------------------------------------ |
| audioStarttime   | int    | Y    | 风险音频片段在音频中的起始时间，单位秒                                                                                                             |
| audioEndtime     | int    | Y    | 风险音频片段在音频中的结束时间，单位秒                                                                                                             |
| audioUrl         | string | Y    | 风险音频片段地址                                                                                                                        |
| audioText        | string | Y    | 音频片段对应的文本内容                                                                                                                     |
| riskLevel        | string | Y    | 识别结果，可能返回值: <br />REJECT:违规内容 <br />REVIEW:疑似违规内容                                                                               |
| riskType         | int    | N    | 风险类型，可能取值: <br />0:正常 <br />100:涉政 <br />120:国歌 <br />200:色情 <br />210:辱骂 <br />250:娇喘 <br />300:广告 <br />700:黑名单 <br />900:自定义 |
| audioMatchedItem | string | N    | 音频中可能出现的敏感词                                                                                                                     |
| description      | string | Y    | 风险原因描述                                                                                                                          |

gender 参数结构如下:

| 参数名称       | 类型     | 是否必选 | 说明                             |
| :--------- | :----- | :--- | :----------------------------- |
| label      | string | Y    | 性别标签名称，可能取值: <br />男性 <br />女性 |
| confidence | int    | Y    | 对应性别可能性大小，取值0-100，数值越高表示概率越大。  |

language 数组中每一项具体参数如下:

| 参数名称       | 类型  | 是否必选 | 说明                                               |
| :--------- | :-- | :--- | :----------------------------------------------- |
| label      | int | Y    | 语种识别类别标识，可能取值: <br />0:普通话 <br />1:英语 <br />2:粤语 |
| confidence | int | Y    | 对应语种标签可能性大小，取值0-100，数值越高表示概率越大。                  |

tags 数组中每一项具体参数如下:

| 参数名称       | 类型     | 是否必选 | 说明                                                                                                     |
| :--------- | :----- | :--- | :----------------------------------------------------------------------------------------------------- |
| label      | string | Y    | 音色标签类别，可能取值: <br />大叔音 <br />青年音 <br />正太音 <br />老年音 <br />女王音 <br />御姐音 <br />少女音 <br />萝莉音 <br />大妈音 |
| confidence | int    | Y    | 对应音色标签可能性大小，取值0-100，数值越高表示概率越大。                                                                        |

# 示例 [#示例]

## 请求示例 [#请求示例]

```
POST /anti_fraud/v2/audio HTTP/1.1
Host: censor-open.qiniuapi.com
Content-Type: application/json
Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=

{
    "type":"DEFAULT",
    "data":{
        "tokenId":"test_01",
        "url":"http://xxxxxxxx.mp3",
        "channel":"IM_MESSAGE",
        "returnAllText":true
    },
    "callback":"http://xxxxxxxxx",
    "callbackParam":{
        "param1":1,
        "param2":"qew",
        "param3":true
    }
}
```

## 返回示例 [#返回示例]

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "code":1100,
    "message":"成功",
    "entryrid":"5564f430ee6a1adb40f06d768b40316b",
}
```

## 回调示例 [#回调示例]

```
POST /xxxx HTTP/1.1
Host: xxxx
Content-Type: application/json

{
    "code":1100,
    "message":"成功",
    "entryId":"b891cf2d82e214de45df33fc2bea4875",
    "riskLevel":"REJECT",
    "audioText":"法轮大法好",
    "labels":"涉政-音频",
    "detail":[{
        "audioStarttime":10,
        "audioEndtime":20,
        "audioUrl":"http://xxxxxxxx.wav",
        "audioText":"法轮大法好",
        "riskLevel":"REJECT",
        "audioMatchedItem":"法轮",
        "riskType":100,
        "description":"涉政-音频"
    }],
    "tags":[
        {
            "label":"男性",
            "confidence":90
        },
        {
            "label":"大叔音",
            "confidence”:91
        },
        {
            "label":"正太音",
            "confidence":21
        },
        {
            "label":"老年音",
            "confidence":11
        },
        {
            "label":"青年音",
            "confidence":31
        }
    ],
    "callbackParam":{
        "param1":1,
        "param2":"qew",
        "param3":true
    }
}
```

# 错误码 [#错误码]

| Code | Message |
| :--: | :-----: |
| 1100 |    成功   |
| 1901 |  QPS受限  |
| 1902 |  参数不合法  |
| 1903 |   服务失败  |
| 1911 |   下载超时  |
| 91xx |   内部错误  |


# 数美图片审核 (/products/dora/introduction-to-the-third-party-data-processing/3-several-beautiful-photos-review)



最近更新时间: 2021-11-18 16:25:43

# 功能描述 [#功能描述]

图片审核功能基于先进的人工智能技术，精准高效识别涉政、色情、暴恐、广告、水印logo，不良场景等违规内容，帮助您提前防御内容风险，提高审核效率，净化网络环境，提升用户体验。

# 请求参数 [#请求参数]

**请求URL**: `https://censor-open.qiniuapi.com/anti_fraud/v2/img`

**字符编码格式**: 请求及返回结果都使用 UTF-8 字符集进行编码

**请求方法**: POST

**建议超时时长**: 5s

放在 HTTP Body 中，采用 Json 格式，具体参数如下:

| 参数名称          | 类型           | 是否必选 | 说明                                                                                                                                                                                                                                                                                                                   |
| ------------- | ------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type          | string       | Y    | 选择识别类型，可选值: <br />POLITICS:涉政识别 <br />PORN:色情识别 <br />OCR:图片中的OCR文字识别 <br />AD:广告识别 <br />LOGO:视频水印logo识别 <br />BEHAVIOR:不良场景识别，支持识别吸烟、喝酒、赌博、吸毒、避孕套和无意义画面 <br />通过下划线连接，如AD\_PORN\_POLITICS用于广告、色情和涉政组合识别 <br />**注意**这里POLITICS实际上等价于以下两个类型:PERSON:涉政人脸识别，VIOLENCE:暴恐识别 <br />**建议**传入:POLITICS\_PORN\_AD\_BEHAVIOR |
| data          | json\_object | Y    | 请求数据内容，最长10MB                                                                                                                                                                                                                                                                                                        |
| 其中，data的内容如下: |              |      |                                                                                                                                                                                                                                                                                                                      |

| 参数名称           | 类型     | 是否必选 | 说明                                                                                                                    |
| :------------- | :----- | :--- | :-------------------------------------------------------------------------------------------------------------------- |
| img            | string | Y    | 要检测的图片，使用图片的url链接 <br />支持格式:jpg，jpeg，jp2，png，webp， gif，bmp，tiff，tif，dib，ppm，pgm，pbm， hdr，pic <br />建议图片像素不小于256\*256 |
| tokenId        | string | Y    | 客户端用户唯一标识，用于用户行为分析，建议传入用户UID <br />注:不同用户务必传入不同的tokenId对其进行唯一标识                                                       |
| channel        | string | N    | 见channel字段说明                                                                                                          |
| registerTime   | int    | N    | 帐号注册时间，强烈建议传递此参数，新注册帐号的异常操作风险较高，毫秒级时间戳                                                                                |
| friendNum      | int    | N    | 帐号好友数，社交场景强烈推荐传此参数，标识用户质量                                                                                             |
| fansNum        | int    | N    | 帐号粉丝数，直播/社区场景强烈推荐传此参数，标识用户质量                                                                                          |
| isPremiumUser  | int    | N    | 是否优质(如付费)用户，配置不同等级，标识用户质量 <br />1为优质用户，0为默认值                                                                          |
| ip             | string | N    | 客户端IP，该参数用于IP维度的用户行为分析，同时可用于比对IP黑库                                                                                    |
| receiveTokenId | string | N    | 接收者的tokenId，私聊场景必选                                                                                                    |
| sex            | int    | N    | 用户的性别，可选值: <br />0:女性 <br />1:男性                                                                                      |
| age            | int    | N    | 用户的年龄，可选值: <br />0:青年(大约 18-45 岁) <br />1:中年(大约 45-60 岁) <br />2:老年(大于 60 岁)                                          |
| level          | int    | N    | 用户等级，针对不同等级的用户可配置不同拦截策略                                                                                               |
| role           | string | N    | 用户角色，对不同角色可配置不同策略。 <br />直播领域"ADMIN"表示房管，"HOST"表示主播，"SYSTEM"系统角色 <br />游戏领域"ADMIN"表示管理员，"USER"表示普通用户，缺失或者"USER"默认普通用户 |
| topic          | string | N    | 讨论的话题编号，可为书评区编号、论坛帖子编号                                                                                                |
| phone          | string | N    | 用户手机号，可用于比对手机号黑库                                                                                                      |
| deviceId       | string | N    | 强烈建议传入，设备指纹标识，用于用户行为分析。当恶意用户篡改mac、imei等设备信息时，使用deviceId能够发现和识别此类恶意行为，同时可用于比对设备指纹黑名单                                   |
| imeimac        | string | N    | 用户android设备唯一标识，相比tokenId和IP，imei和mac更难被更换，当恶意用户使用多个不同账户和IP进作恶时，通过imei和mac能够有效关联识别此类恶意行为，同时可用于比对设备黑名单。                |
| idfvidfa       | string | N    | 用户iOS应用唯一标识，相比tokenId和IP，idfv不能被修改，当恶意用户使用多个不同账户和IP进行恶意行为时，使用idfv能够发现和识别此类恶意行为                                        |
| maxFrame       | int    | N    | 最大截帧数量，GIF图检测专用，默认值为20。当interval\*maxFrame小于该图片所包含的图片数量时，截帧间隔会自动修改为该图片所包含的图片数/maxFrame，以提高整体检测效果。                     |
| interval       | int    | N    | 截帧频率，GIF图检测专用，默认值为1。每interval张图片抽取一张进行检测。                                                                             |

channel字段说明：

根据客户不同业务场景，配置不同的渠道(channel)，制定针对性的拦截策略，同时也方便客户针对不同业务场景的数据进行筛选、分析。业务场景和渠道取值对应表如下:

| 业务场景 |   channel 取值  |          备注         |
| :--: | :-----------: | :-----------------: |
|  头像  |   HEAD\_IMG   |         用户头像        |
|  相册  |      IMGS     |         用户相册        |
|  动态  |    DYNAMIC    |      社交平台的动态配图      |
| 文章配图 |    ARTICLE    |      博客、文章中的配图      |
| 评论插图 |    COMMENT    |       评论里面的配图       |
|  封面  |     COVER     |     相册中的封面或者背景图     |
| 商品图片 |    PRODUCT    |      电商平台的商品图片      |
| 群聊图片 |  GROUP\_CHAT  |      群聊里面的图片消息      |
| 私聊图片 |    MESSAGE    |      私聊里面的图片消息      |
| 离线测试 | OFFLINE\_TEST | 关闭了画像和行为相关策略，离线测试专用 |

# 返回参数 [#返回参数]

放在 HTTP Body 中，采用 Json 格式，具体参数如下:

| 参数名称      | 类型           | 是否必选 | 说明                                                                                                                         |
| :-------- | :----------- | :--- | :------------------------------------------------------------------------------------------------------------------------- |
| code      | int          | Y    | 返回码                                                                                                                        |
| message   | string       | Y    | 返回码详情描述                                                                                                                    |
| entryId   | string       | Y    | 请求唯一标识，后续可用于数据查询                                                                                                           |
| score     | int          | N    | 风险分数(code为1100时存在) <br />取值范围\[0,1000]，分数越高风险越大                                                                            |
| riskLevel | string       | N    | 风险级别(code为1100时存在) <br />可能返回值:PASS，REVIEW，REJECT <br />PASS:正常内容，建议直接放行 <br />REVIEW:可疑内容，建议人工审核 <br />REJECT:违规内容，建议直接拦截 |
| status    | int          | Y    | 提示服务是否超时 <br />0:正常 <br />501:超时                                                                                           |
| detail    | json\_object | N    | 风险详情(code为1100时存在)                                                                                                         |

其中，detail的内容如下:

| 参数名称            | 类型          | 是否必选 | 说明                                                                                                                                                                                                                       |
| :-------------- | :---------- | :--- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| riskType        | int         | Y    | 标识风险类型，可能取值: <br />0: 正常 <br />100:涉政 <br />200:色情 <br />210:性感 <br />300:广告 <br />310:二维码 <br />320:水印 <br />400:暴恐 <br />500:违规 <br />510:不良场景 <br />520:未成年人 <br />700:黑名单 <br />710:白名单 <br />800:高危账号 <br />900:自定义 |
| model           | string      | Y    | 策略规则标识，用来标识命中的策略规则                                                                                                                                                                                                       |
| description     | string      | Y    | 拦截的风险原因解释 <br />仅供人了解风险原因时作为参考，程序请勿依赖该参数的值做逻辑处理                                                                                                                                                                          |
| descriptionV2   | string      | N    | 新版策略规则风险原因描述 <br />注:该参数为新版API返回参数，过渡阶段只有新策略才会返回                                                                                                                                                                         |
| text            | string      | N    | OCR识别出的文字，可根据需求返回该参数                                                                                                                                                                                                     |
| matchedItem     | string      | N    | 命中的具体敏感词(该参数仅在命中敏感词时存在)，可根据需求返回该参数                                                                                                                                                                                       |
| matchedList     | string      | N    | 命中敏感词所在的名单名称(该参数仅在命中敏感词时存在)，可根据需求返回该参数                                                                                                                                                                                   |
| matchedDetail   | string      | N    | 命中的敏感词详细信息，可以反序列化为json\_array，可根据需求返回该参数                                                                                                                                                                                 |
| pornLabel       | string      | N    | 色情识别标签，标识色情识别结果; <br />开启色情识别后可根据需求选择是否返回该参数; <br />可选值:"色情"、"性感"、"正常"                                                                                                                                                   |
| pornRate        | float       | N    | 色情图片概率，可根据需求返回该参数                                                                                                                                                                                                        |
| sexyRate        | float       | N    | 性感图片概率，可根据需求返回该参数                                                                                                                                                                                                        |
| normalRate      | float       | N    | 正常图片概率，可根据需求返回该参数                                                                                                                                                                                                        |
| polityName      | string      | N    | 开启涉政人物识别后可根据需求选择是否 <br />返回该参数; <br />返回值为最相似的涉政人物名称                                                                                                                                                                     |
| polityRate      | float       | N    | 最相似的涉政人物概率，可根据需求返回该参数                                                                                                                                                                                                    |
| violenceLabel   | string      | N    | 暴恐识别标签，标识暴恐识别结果; <br />开启暴恐识别后可根据需求选择是否返回该参数; <br />可选值:"暴乱场景"、"国旗国徽"、"军装"、"恐怖组织"、"枪支刀具"、"血腥场景"、"游戏枪支刀具"、"中国地图"、"坦克"、"蜡烛"、"制服"、"正常"                                                                                      |
| rebelRate       | float       | N    | 暴乱场景概率，可根据需求返回该参数                                                                                                                                                                                                        |
| flagRate        | float       | N    | 国旗国徽概率，可根据需求返回该参数                                                                                                                                                                                                        |
| armyRate        | float       | N    | 军装概率，可根据需求返回该参数                                                                                                                                                                                                          |
| terrorismRate   | float       | N    | 恐怖组织概率，可根据需求返回该参数                                                                                                                                                                                                        |
| weaponRate      | float       | N    | 枪支刀具概率，可根据需求返回该参数                                                                                                                                                                                                        |
| bloodRate       | float       | N    | 血腥场景概率，可根据需求返回该参数                                                                                                                                                                                                        |
| gameWeaponRate  | float       | N    | 游戏枪支刀具概率，可根据需求返回该参数                                                                                                                                                                                                      |
| chinamapRate    | float       | N    | 中国地图概率，可根据需求返回该参数                                                                                                                                                                                                        |
| tankRate        | float       | N    | 坦克概率，可根据需求返回该参数                                                                                                                                                                                                          |
| candleRate      | float       | N    | 蜡烛概率，可根据需求返回该参数                                                                                                                                                                                                          |
| uniformRate     | float       | N    | 制服概率，可根据需求返回该参数                                                                                                                                                                                                          |
| nonViolenceRate | float       | N    | 非暴恐图片概率，可根据需求返回该参数                                                                                                                                                                                                       |
| segments        | int         | N    | 实际处理的片段数量，当检测的图片为GIF图或长图时，会返回该参数                                                                                                                                                                                         |
| logos           | json\_array | N    | 返回图片识别出来的logo结果                                                                                                                                                                                                          |

# 示例 [#示例]

## 请求示例 [#请求示例]

```
POST /anti_fraud/v2/img HTTP/1.1
Host: censor-open.qiniuapi.com
Content-Type: application/json
Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=

{
    "type":"POLITICS_PORN_AD",
    "data":{
        "img":"http://www.leilingfushi.com/UpFiles/Article/2017/5/11/2017051152012237.jpg",
        "tokenId":"test"
    }
}
```

## 返回示例 [#返回示例]

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "code":1100,
    "message":"成功",
    "entryrid":"5564f430ee6a1adb40f06d768b40316b",
    "score":700,
    "riskLevel":"REJECT",
    "detail":{
        "description":"暴恐图片",
        "model":"M010118",
        "riskType":400,
        "text":""
    },
    "status":0
}
```

# 错误码 [#错误码]

| Code | Message |
| :--: | :-----: |
| 1100 |    成功   |
| 1901 |  QPS受限  |
| 1902 |  参数不合法  |
| 1903 |   服务失败  |
| 1911 |   下载超时  |
| 91xx |   内部错误  |


# 翻译狗文档翻译 (/products/dora/introduction-to-the-third-party-data-processing/4-to-translate-documents)



最近更新时间: 2021-11-18 18:06:02

# 接口简介 [#接口简介]

翻译狗文档翻译接口提供多格式、多语种、高质量的文档翻译服务，支持pdf、doc、docx、ppt、pptx、xls、xlsx等格式，支持源语言自动检测，只需指定文档链接并指定目标语言、文档格式、需要存储至七牛kodo的bucket等参数，即可在七牛云存储kodo中获取翻译后的文档。

# 调用链路 [#调用链路]

![image.png](/docs-assets/products/dora/%284-api-docs%29/introduction-to-the-third-party-data-processing/4-to-translate-documents/FlZN-t_OiBANPysS44sm2Rd4Zpv9-13daf5d9906a.webp)

# 接口规格 [#接口规格]

## 翻译请求接口 [#翻译请求接口]

**请求URL**: `https://ap-gate-z0.qiniuapi.com/translate/v1/document/translate`

**字符编码格式**: 请求及返回结果都使用 UTF-8 字符集进行编码

**请求方法**: POST

**建议超时时长**: 3s

**请求头部**:

| 字段            | 取值                                                                                                                                                                      |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | application/json                                                                                                                                                        |
| Authorization | Qiniu \&lt;AccessKey>:\&lt;Sign> <br />注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。\&lt;Sign> 的取值请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken) |

**请求参数**: 放在 HTTP Body 中，采用 json 格式，具体参数如下:

| 参数名称             | 类型     | 是否必选 | 说明                                                                                                                                     |
| ---------------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------- |
| url              | string | Y    | 需要翻译的资源的链接<br />注意：<br />1. 文件格式限定为: pdf、doc、docx、ppt、pptx、xls、xlsx\<br>2. 文件最大限制问50M\<br>3. 不支持扫描件、图纸、纯图片文档，加密文件请先去除密码                |
| from             | string | Y    | 源语言，支持自动检测。具体见语言列表                                                                                                                     |
| to               | string | Y    | 目标语言，不支持自动检测。具体见语言列表                                                                                                                   |
| dType            | int    | Y    | 翻译后的文件类型， 取值 2 或者 3\<br>2: 翻译后的pdf文件，支持格式：word、pdf、img\<br>3: 翻译后的word文件（支持格式：word、pdf)；ppt文件（支持格式：img、ppt）；<br /> excel文件（支持格式：excel） |
| bucket           | string | Y    | 翻译后的文件，转存到kodo的哪个bucket                                                                                                                |
| callback         | string | Y    | 翻译完成后的回调，支持http、https                                                                                                                  |
| industryId       | int    | N    | 行业代码。具体见行业列表                                                                                                                           |
| excelMode        | int    | N    | 指定excel翻译模式 <br />0：只翻译当前打开sheet（默认）<br />1：翻译全部sheet（页数按全部sheet字符数来计算）                                                                |
| bilingualControl | int    | N    | 指定翻译模式 <br />0：译文单独为一个文档（默认）<br />1：双语对照（原文和译文在一个文档）                                                                                   |

**返回参数**: 放在 HTTP Body 中，采用 json 格式，具体参数如下:

| 参数名称 | 类型           | 是否必选 | 说明                      |
| ---- | ------------ | ---- | ----------------------- |
| code | int          | Y    | 结果码，100表示调用成功。具体详见状态码列表 |
| msg  | string       | Y    | 结果信息的文本描述               |
| data | json\_object | Y    | 返回数据结果集                 |

其中data的具体内容如下

| 参数名称    | 类型     | 是否必选 | 说明      |
| ------- | ------ | ---- | ------- |
| entryId | string | Y    | 请求的唯一标识 |

## 异步回调获取结果接口 [#异步回调获取结果接口]

**说明**：该接口需要服务调用方实现，对应翻译请求接口中的`callback`参数。七牛服务器会在翻译完成后调用该接口

**字符编码格式：** 请求及返回结果都使用 UTF-8 字符集进行编码

**请求方法：** POST

**回调参数：** 放在 HTTP Body 中，采用 json 格式，具体参数如下：

| 参数名称 | 类型           | 是否必选 | 说明                      |
| ---- | ------------ | ---- | ----------------------- |
| code | int          | Y    | 结果码，200表示调用成功。具体详见状态码列表 |
| msg  | string       | Y    | 结果信息的文本描述               |
| data | json\_object | Y    | 返回数据结果集                 |

其中data的具体内容如下

| 参数名称            | 类型     | 是否必选 | 说明                       |
| --------------- | ------ | ---- | ------------------------ |
| entryId         | string | Y    | 请求的唯一标识                  |
| fileKey         | string | Y    | 翻译后的文件在kodo指定kucket中的key |
| pageCount       | int    | Y    | 翻译的有效页数                  |
| translationDone | bool   | Y    | 翻译是否完成的判断字段              |

## 查询翻译结果接口 [#查询翻译结果接口]

**说明** ：除了接收回调之外，使用者还可以通过该接口主动查询翻译进度和结果

**请求URL**: `https://ap-gate-z0.qiniuapi.com/translate/v1/document/query`

**字符编码格式**: 请求及返回结果都使用 UTF-8 字符集进行编码

**请求方法**: GET

**建议超时时长**: 3s

**请求头部**:

| 字段            | 取值                                                                                                                                                                      |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | application/json                                                                                                                                                        |
| Authorization | Qiniu \&lt;AccessKey>:\&lt;Sign> <br />注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。\&lt;Sign> 的取值请参考[七牛鉴权](/faq/kodo/the-common-problems-in-the-sdk/3702-QiniuToken) |

**请求参数**: 放在 QueryString 中，具体参数如下:

| 参数名称    | 类型     | 是否必选 | 说明      |
| ------- | ------ | ---- | ------- |
| entryId | string | Y    | 请求的唯一标识 |

**返回参数**: 放在 HTTP Body 中，采用 json 格式，具体参数如下:

| 参数名称 | 类型           | 是否必选 | 说明                                       |
| ---- | ------------ | ---- | ---------------------------------------- |
| code | int          | Y    | 结果码，100表示翻译完成。102代表正在翻译中。<br />具体详见状态码列表 |
| msg  | string       | Y    | 结果信息的文本描述                                |
| data | json\_object | Y    | 返回数据结果集                                  |

其中data的具体内容如下

| 参数名称            | 类型     | 是否必选 | 说明                       |
| --------------- | ------ | ---- | ------------------------ |
| entryId         | string | Y    | 请求的唯一标识                  |
| fileKey         | string | N    | 翻译后的文件在kodo指定kucket中的key |
| pageCount       | int    | N    | 翻译的有效页数                  |
| translationDone | bool   | Y    | 翻译是否完成的判断字段              |

# 示例 [#示例]

## 翻译请求示例 [#翻译请求示例]

```shell
POST /translate/v1/document/translate HTTP/1.1
Host: ap-gate-z0.qiniuapi.com
Content-Type: application/json
Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=

{
    "url": "http://xx.emm/trans-min.docx",
    "dType": 2,
    "from": "auto",
    "to": "en",
    "industryId": 0,
    "excelMode": 0,
    "bilingualControl": 0,
    "bucket": "test-bucket",
    "callback": "http://test.emm/callback"
}
```

## 翻译请求成功返回示例 [#翻译请求成功返回示例]

```shell
HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": 100,
    "msg": "请求成功",
    "data": {
        "entryId": "61446e07000000003a4b6d31703f790c"
    }
}
```

## 查询翻译结果接口示例 [#查询翻译结果接口示例]

```shell
GET /translate/v1/document/query?entryId=61446e07000000003a4b6d31703f790c HTTP/1.1
Host: ap-gate-z0.qiniuapi.com
Authorization: Qiniu YnxrxOSvGotRZpqkZnMzl_euuoqRzOKUd6zwbRju:r6a-o2UpBg6A4puIMnkCExH8lE8=
```

# 接口规则 [#接口规则]

## 支持的语言列表 [#支持的语言列表]

| 语言代码    | 语言         |
| ------- | ---------- |
| auto    | 自动检测       |
| sq      | 阿尔巴尼亚语     |
| ga      | 爱尔兰语       |
| est     | 爱沙尼亚语      |
| ara     | 阿拉伯语       |
| am      | 阿姆哈拉语      |
| or      | 奥里亚语       |
| az      | 阿塞拜疆语      |
| be      | 白俄罗斯语      |
| bul     | 保加利亚语      |
| ba      | 巴什基尔语      |
| eu      | 巴斯克语       |
| is      | 冰岛语        |
| pl      | 波兰         |
| bs      | 波斯尼亚语      |
| fa      | 波斯语        |
| af      | 布尔语(南非荷兰语) |
| tt      | 鞑靼语        |
| dan     | 丹麦语        |
| de      | 德语         |
| ru      | 俄语         |
| fra     | 法语         |
| fj      | 斐济语        |
| tl      | 菲律宾语       |
| fin     | 芬兰语        |
| fy      | 弗里西语       |
| km      | 高棉语        |
| ka      | 格鲁吉亚语      |
| gu      | 古吉拉特语      |
| ht      | 海地克里奥尔语    |
| kor     | 韩语         |
| ha      | 豪萨语        |
| kk-kz   | 哈萨克语       |
| kk      | 哈萨克语(西里尔)  |
| nl      | 荷兰语        |
| gl      | 加利西亚语      |
| ca      | 加泰罗尼亚语     |
| cs      | 捷克语        |
| ky      | 吉尔吉斯语      |
| kn      | 卡纳达语       |
| otq     | 克雷塔罗奥托米语   |
| tlh     | 克林贡语       |
| hr      | 克罗地亚语      |
| co      | 科西嘉语       |
| ku      | 库尔德语       |
| la      | 拉丁语        |
| lo      | 老挝语        |
| lv      | 拉脱维亚语      |
| lt      | 立陶宛语       |
| rom     | 罗马尼亚语      |
| lb      | 卢森堡语       |
| rw      | 卢旺达语       |
| mg      | 马尔加什语      |
| mt      | 马耳他语       |
| ms      | 马来语        |
| mr      | 马拉提语       |
| ml      | 马拉雅拉姆语     |
| mi      | 毛利语        |
| mk      | 马其顿语       |
| mo      | 蒙古语        |
| mn      | 蒙古语(西里尔)   |
| bn      | 孟加拉语       |
| hmn     | 苗语         |
| xh      | 南非科萨语      |
| zu      | 南非祖鲁语      |
| ne      | 尼泊尔语       |
| no      | 挪威语        |
| pa      | 旁遮普语       |
| pap     | 帕皮阿门托语     |
| ps      | 普什图语       |
| pt      | 葡萄牙语       |
| ny      | 齐切瓦语       |
| jp      | 日语         |
| swe     | 瑞典语        |
| sr-Latn | 塞尔维亚语(拉丁文) |
| sr      | 塞尔维亚语(西里尔) |
| st      | 塞索托语       |
| sm      | 萨摩亚语       |
| si      | 僧加罗语       |
| eo      | 世界语        |
| sk      | 斯洛伐克语      |
| slo     | 斯洛文尼亚语     |
| sw      | 斯瓦希里语      |
| gd      | 苏格兰盖尔语     |
| so      | 索马里语       |
| ceb     | 宿务语        |
| te      | 泰卢固语       |
| ta      | 泰米尔语       |
| th      | 泰语         |
| tg      | 塔吉克语       |
| to      | 汤加语        |
| ty      | 塔希提语       |
| tr      | 土耳其语       |
| tk      | 土库曼语       |
| cy      | 威尔士语       |
| ug      | 维吾尔语       |
| udm     | 乌德穆尔特语     |
| ur      | 乌尔都语       |
| uk      | 乌克兰语       |
| uz      | 乌兹别克语      |
| haw     | 夏威夷语       |
| spa     | 西班牙语       |
| iw      | 希伯来语       |
| el      | 希腊语        |
| sd      | 信德语        |
| hu      | 匈牙利语       |
| sn      | 修纳语        |
| hy      | 亚美尼亚语      |
| ig      | 伊博语        |
| it      | 意大利语       |
| yi      | 意第绪语       |
| hi      | 印地语        |
| en      | 英语         |
| su      | 印尼巽他语      |
| id      | 印尼语        |
| jw      | 印尼爪哇语      |
| ii      | 彝语         |
| yua     | 尤卡坦玛雅语     |
| yo      | 约鲁巴语       |
| vie     | 越南语        |
| zh      | 中文         |
| cht     | 中文繁体       |
| yue     | 中文粤语(繁体)   |
| za      | 壮语         |

## 行业列表 [#行业列表]

| 行业代码 | 行业   |
| ---- | ---- |
| 1    | 法律   |
| 2    | 金融   |
| 3    | 农林牧渔 |
| 4    | 医药卫生 |
| 5    | 建筑建材 |
| 6    | 冶金矿产 |
| 7    | 石油化工 |
| 8    | 水利水电 |
| 9    | 交通运输 |
| 10   | 信息产业 |
| 11   | 机械机电 |
| 12   | 轻工食品 |
| 13   | 服装纺织 |
| 14   | 专业服务 |
| 15   | 安全防护 |
| 16   | 环保绿化 |
| 17   | 旅游休闲 |
| 18   | 办公文教 |
| 19   | 电子电工 |
| 20   | 玩具礼品 |
| 21   | 家居用品 |
| 22   | 物资   |
| 23   | 包装   |
| 24   | 体育   |
| 25   | 办公   |
| 26   | 其他   |

# 状态码列表 [#状态码列表]

| 状态码 | 状态描述 |
| --- | ---- |
| 200 | 请求成功 |
| 400 | 参数错误 |
| 500 | 内部错误 |

# 价格 [#价格]

0.5元/页


# 处理结果另存（saveas） (/products/dora/processing-mechanism/0-processing-results-save-saveas)



最近更新时间: 2024-12-02 15:33:20

# **简介** [#简介]

我们提供名为`saveas` 的数据处理接口，将处理结果作为资源保存到指定空间内，并赋以指定 Key。保存成功后，下一次可直接通过指定 Key 来访问该资源，以达到提升下载速度的效果。

## **限制说明** [#限制说明]

* 源Bucket和目标Bucket必须在同一区域，即 `处理结果不能跨区域另存`，例如华东Bucket内的文件经处理后结果无法另存到华北的Bucket。

* 支持`同步调用`和`持久化(pfop)调用`，两者调用方式有轻微的差异。大多数使用场景下，建议使用 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 来实现处理结果存储，避免使用同步操作的 saveas 接口，提升访问速度。

  * **注意**：当持久化处理(pfop)调用，不用`saveas`接口时，系统会默认生成输出结果文件，输出空间默认跟随源文件，结果文件命名根据源文件hash和处理命令生成一个唯一标识的文件名。

* urlsafe\_base64\_encode() 函数按照标准的RFC 4648实现，开发者可以参考github.com/qiniu上各 SDK 的样例代码。

* 当持久化保存的 fop 耗时较长的时候，saveas 请求会返回 CDN 超时，但是只要保证发送的 saveas 请求合法，七牛服务器还是会对请求做正确处理。

* 此处签名内容不包含 Scheme 部分，与 DownloadToken 签名不一样。

* c# http 库发送请求的时候会把 | 转成 %7c，由于签名签的是 | ，导致报 400 错误。可以在发送请求的时候，把 url 中的 | 改为 %7c，或者签名的时候签 %7c。

# **持久化调用** [#持久化调用]

## **接口规格** [#接口规格]

```
saveas/<EncodedEntryURI>/deleteAfterDays/<deleteAfterDays>
```

|            参数名称            |  必填 |   类型   | 说明                                                                                                                                                                                                                                                           |
| :------------------------: | :-: | :----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ` &lt;EncodedEntryURI&gt;` |  是  | string | 以 [EncodedEntryURI](/products/kodo/0-data-format) 格式组织的目标 Bucket 与 Key；其中bucket 必填，key 非必填。                                                                                                                                                                  |
| ` &lt;deleteAfterDays&gt;` |  否  |   int  | 最小单位为天，数值 >= 1。表示从保存数据开始算起多少天之后自动从 bucket 删除文件。不设置表示资源不会被自动删除                                                                                                                                                                                                |
|        `savePattern`       |  否  |        | 自定义输出文件资源名，变量值都是 `基于输入文件获取`，需要经过 `urlsafe_base64_encode`。<br />支持文件名变量，包括：`bucket、key、etag、fname、fsize、mimeType、endUser、ext、fprefix、keybase`。<br />**注意**：<br />1. 和`saveKey` 互斥，不能共用；<br />2. 和 `&lt;EncodedEntryURI&gt;` 指定 key 时一起存在时，优先使用 `savePattern`。 |
|          `saveKey`         |  否  |        | 自定义输出文件资源名，变量值都是 `基于输出文件获取`，需要经过 `urlsafe_base64_encode`。<br />可使用文件名变量，包括：`etag, year, mon, day, hour, min, sec`。<br />**注意**：<br />1. 和`savePattern` 互斥，不能共用；<br />2. 仅当` &lt;EncodedEntryURI&gt;`没有指定 key 时起作用，不能同时指定。                                    |

在 [持久化处理(pfop)](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)调用中设置，直接在命令后跟 `\|saveas/SafeBase64(bucket:key)/deleteAfterDays/&lt; deleteAfterDays &gt;` 即可。

* 上传时自动触发，设置  `persistentOps` 字段：

  ```
  "persistentOps":"avthumb/mp3/ab/192k|saveas/dGVzdDoxLm1wMw==/deleteAfterDays/3"
  ```

* 已有资源主动触发，设置`fops`字段：

  ```
  "fops":"avthumb/mp3/ab/192k|saveas/dGVzdDoxLm1wMw==/deleteAfterDays/3"
  ```

表示处理后的数据名称为指定的 key 并且上传到指定的 bucket，在 3 天之后会从 bucket 自动删除。

# **同步调用** [#同步调用]

同步调用需要签名。

## **接口规格** [#接口规格-1]

```
saveas/<EncodedEntryURI>/sign/<Sign>/deleteAfterDays/<deleteAfterDays>
```

|            参数名称            |  必填 |   类型   | 说明                                                                                                                                                                                                                                 |
| :------------------------: | :-: | :----: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `&lt;EncodedEntryURI&gt; ` |  是  | string | 以 [EncodedEntryURI](/products/kodo/0-data-format) 格式组织的目标 Bucket 与 Key                                                                                                                                                             |
|       `&lt;Sign&gt;`       |  是  | string | 请求签名部分，算法见下方，在 pfop 操作中不用指定该参数                                                                                                                                                                                                     |
|  `&lt;deleteAfterDays&gt;` |  否  |   int  | 多少天之后自动从 bucket 删除文件，从保存数据开始算起                                                                                                                                                                                                     |
|        `savePattern`       |  否  |        | 自定义输出文件资源名，变量值都是 `基于输入文件获取`，需要经过 `urlsafe_base64_encode`。<br />支持文件名变量，包括：`bucket、key、etag、fsize、mimeType、keybase`。<br />**注意**：<br />1. 和`saveKey` 互斥，不能共用；<br />2. 和 `&lt;EncodedEntryURI&gt;` 指定 key 时一起存在时，优先使用 `savePattern`。 |
|          `saveKey`         |  否  |        | 自定义输出文件资源名，变量值都是 `基于输出文件获取`，需要经过 `urlsafe_base64_encode`。<br />可使用文件名变量，包括：`etag, year, mon, day, hour, min, sec`。<br />**注意**：<br />1. 和`savePattern` 互斥，不能共用；<br />2. 仅当` &lt;EncodedEntryURI&gt;`没有指定 key 时起作用，不能同时指定。          |

## **签名算法** [#签名算法]

1.在下载 URL（不含 Scheme 部分，即去除 http : //）后附加 saveas 接口（不含签名部分）：

```
NewURL = URL + "|saveas/<EncodedEntryURI>"
```

2.使用 SecretKey 对新的下载 URL 进行HMAC1-SHA1签名：

```
Sign = hmac_sha1(SecretKey, NewURL)
```

3.对签名进行URL安全的Base64编码：

```
EncodedSign = urlsafe_base64_encode(Sign)
```

4.在新的下载 URL 后拼接签名参数：

```
FinalURL = NewURL + "/sign/<AccessKey>:<EncodedSign>"
```

**同步调用 saveas 算法示例，生成 saveas 请求的完整 Go 代码如下：**

```
func makeSaveasUrl(URL, accessKey string, secretKey []byte, saveBucket, saveKey string) string {
      encodedEntryURI := base64.URLEncoding.EncodeToString([]byte(saveBucket+":"+saveKey))
      URL += "|saveas/" + encodedEntryURI
      h := hmac.New(sha1.New, secretKey)
      // 签名内容不包括Scheme，仅含如下部分：
    // <Domain>/<Path>?<Query>
      u, _ := url.Parse(URL)
      io.WriteString(h, u.Host + u.RequestURI())
      d := h.Sum(nil)
      sign := accessKey + ":" + base64.URLEncoding.EncodeToString(d)
      return URL + "/sign/" + sign
}
```

# **文件名变量** [#文件名变量]

文件名变量是一组预先定义的变量，可以使用 `$(变量名)`或`${变量名}` 形式求值。

**1. savePattern** 参数，可用变量如下:

| 变量名      | 变量说明                                                                                                                      | 适用范围                                                                                                                                                                                                                                                |
| -------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bucket   | 获得上传的目标空间名。                                                                                                               | 持久化调用<br />同步调用                                                                                                                                                                                                                                     |
| key      | 获得文件保存在空间中的资源名。                                                                                                           | 持久化调用<br />同步调用                                                                                                                                                                                                                                     |
| etag     | 文件上传成功后的 HTTP[ETag](/products/dora/processing-mechanism/0-processing-results-save-saveas#etag)。若上传时未指定资源ID，Etag将作为资源ID使用。 | 持久化调用<br />同步调用                                                                                                                                                                                                                                     |
| fsize    | 资源尺寸，单位为字节。                                                                                                               | 持久化调用<br />同步调用                                                                                                                                                                                                                                     |
| mimeType | 资源类型，例如JPG图片的资源类型为`image/jpg`。                                                                                            | 持久化调用<br />同步调用                                                                                                                                                                                                                                     |
| keybase  | 获得空间资源名忽略后缀，即$(key) 忽略 $(ext) 。                                                                                           | 持久化调用<br />同步调用                                                                                                                                                                                                                                     |
| fname    | 上传的原始文件名。                                                                                                                 | 持久化调用<br />●适用于[上传策略中手动触发数据处理](/products/kodo/development-guidelines/security/1-put-policy)，persistentOps或persistentWorkflowTemplateID\<br>●适用于[对象存储控制台->文件管理](/products/kodo/kodo-console-guide/file-management/0-upload-a-file)，上传文件时指定工作流模板      |
| fprefix  | 获得上传原始文件名忽略后缀，即$(fname) 忽略 $(ext) 。                                                                                       | 持久化调用<br />●适用于[上传策略中手动触发数据处理](/products/kodo/development-guidelines/security/1-put-policy)，，persistentOps 或persistentWorkflowTemplateID 中<br />●适用于[对象存储控制台->文件管理](/products/kodo/kodo-console-guide/file-management/0-upload-a-file)，上传文件时指定工作流模板 |
| ext      | 上传资源的后缀名，通过 $(fname) 的后缀或者自动检测的 mimeType 来获取。优先使用 $(fname) 的后缀                                                            | 持久化调用<br />●适用于[上传策略中手动触发数据处理](/products/kodo/development-guidelines/security/1-put-policy)，persistentOps 或persistentWorkflowTemplateID 中<br />●适用于[对象存储控制台->文件管理](/products/kodo/kodo-console-guide/file-management/0-upload-a-file)，上传文件时指定工作流模板  |
| endUser  | 上传时指定的`endUser`字段，通常用于区分不同终端用户的请求。                                                                                        | 持久化调用<br />●适用于[上传策略中手动触发数据处理](/products/kodo/development-guidelines/security/1-put-policy)，persistentOps 或persistentWorkflowTemplateID 中<br />●适用于[对象存储控制台->文件管理](/products/kodo/kodo-console-guide/file-management/0-upload-a-file)，上传文件时指定工作流模板  |

**2. saveKey** 参数，可用变量如下:

| 变量名  | 变量说明                                                                                                                        | 适用范围            |
| ---- | --------------------------------------------------------------------------------------------------------------------------- | --------------- |
| etag | 输出文件上传成功后的 HTTP[ETag](/products/dora/processing-mechanism/0-processing-results-save-saveas#etag)。若上传时未指定资源ID，Etag将作为资源ID使用。 | 持久化调用<br />同步调用 |
| year | 输出文件上传时的年份。                                                                                                                 | 持久化调用<br />同步调用 |
| mon  | 输出文件上传时的月份。                                                                                                                 | 持久化调用<br />同步调用 |
| day  | 输出文件上传时的日期。                                                                                                                 | 持久化调用<br />同步调用 |
| hour | 输出文件上传时的小时。                                                                                                                 | 持久化调用<br />同步调用 |
| min  | 输出文件上传时的分钟。                                                                                                                 | 持久化调用<br />同步调用 |
| sec  | 输出文件上传时的秒钟。                                                                                                                 | 持久化调用<br />同步调用 |

### **求值示例** [#求值示例]

输入文件上传原始文件名=demo.mp4

输入文件空间资源名= file.mp4

输出文件上传日期=2024.06.05 12:30:50

输出文件etag=FukjnhlamMYsy-SvkpxsDzQBP0\_9

savePattern 填写如下文件名变量，输出结果文件会是：

> * savePattern=trancode$\{fname} ，结果文件=trancodedemo.mp4
> * savePattern=$\{keybase}.m3u8，结果文件=file.m3u8

saveKey 填写如下文件名变量，输出结果文件会是：

> * saveKey=file$\{year}$\{.mon}$\{day}$\{hour}$\{min}.m3u8， 结果文件为=file202406051230.m3u8
> * saveKey=$\{etag}.m3u8， 结果文件为=FukjnhlamMYsy-SvkpxsDzQBP0\_9.m3u8

# **EncodedEntryURI 格式** [#encodedentryuri-格式]

本格式用于在 URI中指定目标资源空间与目标资源名，格式如下：

```
entry = '<Bucket>:<Key>'
encodedEntryURI = urlsafe_base64_encode(entry)
```

假设 **entry** 为 `qiniuphotos:gogopher.jpg` ，则对应的 **encodedEntryURI** 为 `cWluaXVwaG90b3M6Z29nb3BoZXIuanBn=` 。

## **URL安全的Base64编码** [#url安全的base64编码]

URL安全的Base64编码适用于以URL方式传递Base64编码结果的场景。该编码方式的基本过程是先将内容以Base64格式编码为字符串，然后检查该结果字符串，将字符串中的加号`+`换成中划线`-`，并且将斜杠`/`换成下划线`_`。

# **示例** [#示例]

1.原资源是一个名为 resource/Ship.jpg 的图片：

```
http://78re52.com1.z0.glb.clouddn.com/resource/Ship.jpg
```

2.将图片做缩略处理：

```
http://78re52.com1.z0.glb.clouddn.com/resource/Ship.jpg?imageView2/2/w/200/h/200
```

3.对上述云处理结果进行持久化保存：

```
# 另存操作的目标空间与资源名
entryURI = "qiniu-developer:Ship-thumb-200.jpg"
#编码结果
encodedEntryURI = "cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAwLmpwZw=="
#需要签名的部分
signingStr = "78re52.com1.z0.glb.clouddn.com/resource/Ship.jpg?imageView2/2/w/200/h/200|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAwLmpwZw=="
#签名结果
sign = "bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAuJYXZDDf:jGo09Pmq5vyG4c-rRb4qF3_dH1g="
```

4.最终得到的完整下载 URL：

```
http://78re52.com1.z0.glb.clouddn.com/resource/Ship.jpg?imageView2/2/w/200/h/200|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAwLmpwZw==/sign/bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAuJYXZDDf:jGo09Pmq5vyG4c-rRb4qF3_dH1g=
```

5.保存转码后资源可通过如下 URL 访问：

```
http://78re52.com1.z0.glb.clouddn.com/Ship-thumb-200.jpg
```


# 数据处理机制介绍 (/products/dora/processing-mechanism/1-directions-for-use-pfop)



最近更新时间: 2024-09-24 10:24:26

# 简介 [#简介]

七牛云存储内建了一个非常高效易用的`数据处理框架`。数据处理框架可以对存储在七牛云上的文件执行一系列符合规范的数据处理操作。

**数据处理框架** 对于资源类型没有限制，但是特定的数据处理操作则会有各自适合的处理对象；例如对非图片类型的资源进行缩略图操作，可能会返回错误的结果。

数据处理机制，分为以下三种触发场景：

| 触发场景       | 处理类别  | 说明                                                                                                                                                                                                                               |
| ---------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 访问资源时      | 同步处理  | 只需要在资源URL后加上具体数据操作指令和参数。                                                                                                                                                                                                         |
| 对已有资源，手动触发 | 持久化处理 | 针对已存在空间中的资源手动触发处理流程，与上传时的数据处理支持相同，这个过程也为异步且可查询操作进度。具体请参考[状态查询](/products/dora/processing-mechanism/persist/1-persistent-processing-status-query-prefop)。                                                                         |
| 资源上传时，自动触发 | 持久化处理 | 上传过程中自动触发数据处理，可在上传策略中设置 `persistentOps` 和` persistentNotifyUrl` 字段，在资源上传完成后七牛云存储会以异步的方式执行数据处理操作，并持久化存储数据处理结果。支持查询数据处理操作的进度。具体请参考[状态查询](/products/dora/processing-mechanism/persist/1-persistent-processing-status-query-prefop)。 |

下面分别描述这两种数据处理的区别：

* 同步处理：收到处理请求后立刻进行实时计算并返回处理结果, 适用于计算量较小可以快速返回结果的任务。
* 持久化处理：收到处理请求后立刻创建一个异步任务并返回该异步任务ID, 该任务会根据调度策略被最终调度执行完毕, 适用于计算量较大需要较长处理时间的任务。

# **同步处理** [#同步处理]

适用于计算量较小可以快速返回结果的资源处理场景，使用 [同步处理](/products/dora/processing-mechanism/2-synchronous-processing)。

# **持久化处理** [#持久化处理]

适用于计算量较大、处理时间较长的资源处理场景，使用 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)。

# **管道** [#管道]

数据处理命令后，可以使用 [管道](/products/dora/processing-mechanism/3-the-pipe) 实现串行处理，即将一个资源经由多个 `<fop>` 串行处理。

# **处理结果另存** [#处理结果另存]

可以通过 [处理结果另存(saveas)](/products/dora/processing-mechanism/0-processing-results-save-saveas)，实时保存图片到指定空间。


# 同步处理 (/products/dora/processing-mechanism/2-synchronous-processing)



最近更新时间: 2024-09-24 10:24:26

# **简介** [#简介]

**同步处理**，用于计算量较小可以快速返回结果的资源处理场景，很适合图片资源、文件资源的处理。您可以在 `访问文件URL时` ，添加一个或多个数据处理指令，以直接获取处理后的结果。

* 比较典型的一个场景是 `图片查看`，客户端可以上传一张高精度的图片，然后在查看图片的时候根据屏幕规格生成缩略图。这样既可以明显降低网络流量，而且可以提高图片显示速度，还能降低移动设备的内存占用。

下面描述同步处理的详细用法。

# **请求报文** [#请求报文]

<a id="imagemogr2-request-syn" />

## 请求语法 [#请求语法]

```
GET <imageDownloadURI>?<接口规格> HTTP/1.1
Host: <imageDownloadHost>
```

<a id="imagemogr2-request-header" />

## 头部信息 [#头部信息]

| 头部名称 | 必填 | 说明                                                                                  |
| ---- | -- | ----------------------------------------------------------------------------------- |
| Host | 是  | 下载服务器域名，可为七牛三级域名或自定义二级域名，参考[七牛自定义域名绑定流程](https://support.qiniu.com/question/68977)。 |

<a id="imagemogr2-response" />

# **响应报文** [#响应报文]

<a id="imagemogr2-rsponse-syn" />

## 响应语法 [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: <imageMimeType>

<imageBinaryData>
```

<a id="imagemogr2-response-header" />

## 头部信息 [#头部信息-1]

| 头部名称          | 必填 | 说明                                         |
| ------------- | -- | ------------------------------------------ |
| Content-Type  | 是  | MIME类型，成功时为图片的MIME类型，失败时为application/json。 |
| Cache-Control |    | 缓存控制，失败时为no-store，不缓存。                     |

<a id="imagemogr2-response-content" />

## 响应内容 [#响应内容]

* 如果请求成功，返回图片的二进制数据。
* 如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "code":     <HttpCode  int>,
    "error":   "<ErrMsg    string>",
}
```

| 字段名称  | 必填 | 说明                                             |
| ----- | -- | ---------------------------------------------- |
| code  | 是  | HTTP状态码，请参考[响应状态码](#imagemogr2-response-code)。 |
| error | 是  | 与HTTP状态码对应的消息文本。                               |

<a id="imagemogr2-response-code" />

## 响应状态码 [#响应状态码]

| HTTP状态码 | 含义                                                                                           |
| ------- | -------------------------------------------------------------------------------------------- |
| 200     | 处理成功。                                                                                        |
| 400     | 请求报文格式错误。                                                                                    |
| 404     | 资源不存在。                                                                                       |
| 599     | 服务端操作失败。如遇此错误，请将完整错误信息（包括所有的HTTP响应头部）[提交工单](https://support.qiniu.com/tickets/category) 给我们。 |

# **示例** [#示例]

**原图**

```
https://dn-odum9helk.qbox.me/resource/gogopher.jpg
```

![img](/docs-assets/products/dora/%284-api-docs%29/processing-mechanism/2-synchronous-processing/gogopher-caff95e8587b.webp)

**针对该原图生成一张480x320大小的缩略图**

```
https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageView2/2/w/320/h/480
```

![img](/docs-assets/products/dora/%284-api-docs%29/processing-mechanism/2-synchronous-processing/gogopher-a19e82594155.webp)


# 管道 (/products/dora/processing-mechanism/3-the-pipe)



最近更新时间: 2024-09-24 10:24:26

# **简介** [#简介]

七牛云的数据处理 API 接口，均支持通过管道操作符 `\|`  实现串行处理，即将一个资源经由多个 `&lt;fop&gt;` 串行处理。

**备注**：

* 管道数量限制为30个。

# **接口形式** [#接口形式]

处理规格如下：

```
<fop1>|<fop2>|<fop3>|<fopN>
```

* `<fop>` (File Operation的缩写)，表示数据处理指令及其所需要的参数。
* 各 `&lt;fop&gt;` 之间用`\|`分割，我们称之为`管道`(pipeline)。

可以看到每一步的输出都是下一步的输入，而最后一步的输出即为最终下载到的资源内容。每调用一次这类串行化接口，就必须实时地按序执行所有接口，有可能引起不必要的计算耗时。

# **示例** [#示例]

将一个原图缩略，然后在缩略图上打上另外一个图片作为水印：

* **基于原图生成缩略图并打上水印**

  ```
  https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageView/2/h/200|watermark/1/image/aHR0cHM6Ly9kb3JhLWRvYy5xaW5pdS5jb20vcWluaXV5dW4ucG5n/ws/0.2
  ```

  ![链接](/docs-assets/products/dora/%284-api-docs%29/processing-mechanism/3-the-pipe/gogopher-fa41526a1650.webp)

* **对音视频进行转码，并对转码后的结果另存**

  ```
  "persistentOps":"avthumb/mp3/ab/192k|saveas/dGVzdDoxLm1wMw=="
  ```

# **计费说明** [#计费说明]

管道使用规格示例：

```
<fop1>|<fop2>|<fop3>|<fopN>
```

整个串行处理中，只要有处理成功的 `fop`，就会有相应的计量计费。


# 视频超分 (/products/dora/quality%20enhancement/0-video-super-resolution)



最近更新时间: 2024-10-29 17:52:27

# **简介** [#简介]

视频超分辨能力可以将输入视频的宽高放大2倍尺寸输出，基于深度学习算法，提高视频的清晰度、画质和主观质量，从而提高播放和观影体验。

## **应用场景** [#应用场景]

* **升级老旧片源**：针对画质不理想的老片源进行升级，基于深度学习的视频超分辨算法，可将低分辨率的视频，增强转化为高分辨视频。
* **短视频增强**：针对低分辨率视频，不适应如今对高分辨率影片的要求，通过视频超分辨算法对影片细节进行增强修复，利用AI模型达到高分辨率输出的同时有效细节更清晰。
* **视频转清晰度**：以视频超分辨率重构技术为基础，辅以丰富的图像增强工具，实现标清转高清、高清转 4K 等画质提升应用场景。

## **使用限制** [#使用限制]

* 输入分辨率限制，仅支持小于等于1920x1080
* 视频输出帧率默认等于源视频帧率，取值范围为\[1,60]，超出范围取60帧
* 当前仅支持 **华东区域** 的资源处理

# **参数说明** [#参数说明]

```
aicvt/format/<Format>
     /vcodec/<VideoCodec>
     /srMode/<SRMode>
     /superResolution/<SuperResolution>
```

| 参数名称                                | 类别  | 必填 | 说明                                                                                                                                           |
| ----------------------------------- | --- | -- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| /format/\<Format>                   | A/V | Y  | 必填，输出封装格式，具体细节请参考[支持转换的封装格式](https://support.qiniu.com/hc/kb/article/182125/?from=draft)。<br />暂不支持m3u8                                      |
| /vcodec/\<VideoCodec>               | V   | N  | 视频编码格式，具体细节请参考[支持转换的视频编码格式](/faq/dora/av-processing/1385-avthumb-parameter-vcodec-format-and-explanation)。<br />支持使用H.264和H.265编码，默认使用H.264。 |
| /srMode/\<SRMode>                   | V   | N  | 视频超分模式，默认为 ` base` 模式。<br />1. `base`：基础版，稳定的超分辨率效果；<br />2. `faceEnhance`：人脸增强版，采用了独有的人脸增强模块，智能识别并优化人脸区域。                                   |
| /superResolution/\<SuperResolution> | V   | N  | 开启超分辨率功能（AI功能），取值范围为：\[2,3]的整数，按照源视频的宽高2倍或3倍尺寸输出。                                                                                            |

# **操作方式** [#操作方式]

可以通过 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 的方式来调用：

* `资源上传时自动触发`：可以在上传时指定 [persistentOps](/products/kodo/development-guidelines/security/1-put-policy#put-policy-persistent-ops-explanation) 参数
* `对已有资源手动手动触发`：调用 [pfop](/products/dora/audio-and-video-processing-api/1-audio-and-video-stitching-avconcat) 命令

# **示例** [#示例]

* 以`对已有资源手动触发`  的形式，将thinking-in-go.mov进行视频超分，转化为mp4格式，设置2倍尺寸输出：

  ```
  POST /pfop/ HTTP/1.1
  Host: api.qiniu.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Qiniu <AccessToken>

  bucket=qiniu-ts-demo&key=thinking-in-go.mov&fops=aicvt/format/mp4/superResolution/2=&notifyURL=http://fake.com/qiniu/notify
  ```

  **注意**：要在`Authorization`头部的`<AccessToken>`前添加`Qiniu`和半角空格。访问权限，见[管理凭证](/products/kodo/development-guidelines/security/access-token)方式。数据处理命令 `fops` ，将其设置为：

  ```
  fops = aicvt/format/mp4/superResolution/2
  ```

* 以 `资源上传时自动触发` 形式，将thinking-in-go.mov进行视频超分，转化为mp4格式，设置2倍尺寸输出：

  ```
   {
        "scope":                "qiniu-ts-demo:thinking-in-go.mov",
        "deadline":             1390528576,
        "persistentOps":        "aicvt/format/mp4/superResolution/2",
        "persistentNotifyUrl":  "http://fake.com/qiniu/notify"
    }
  ```

**注意**:
其他语言 Sdk 可在[官方 Sdks ](/sdk-tools/sdk)下载，可以通过查看 Sdk 使用指南中 `对已有资源手动触发`，`资源上传时自动触发`使用。

# **计费说明** [#计费说明]

视频超分定价，参考 [智能多媒体服务定价->画质增强->视频超分](https://www.qiniu.com/prices/dora) 。

* 视频超分费用 = 输出文件时长 x 单价。
* 输出时长：按分钟计费，累计总时长不足一分钟不计费
* 输出规格按输出视频分辨率的长边和短边属于输出规格划定的范围进行判定，以视频超分输出HD (1920 x 1080) 规格为例：
  * 输出视频的分辨率长边不大于2560且短边不大于1440，则属于2K输出规格。


# 图像超分 (/products/dora/quality%20enhancement/1-image-super-resolution)



最近更新时间: 2025-06-17 16:35:08

# **简介** [#简介]

图像超分能力，支持2、4倍分辨率放大，支持多种超分模型达到不同效果的输出。基于深度学习算法，可以有效地恢复图像中的细节和纹理、降低图像模糊、噪声，提高图像质量，使图像看起来更加清晰。

## **应用场景** [#应用场景]

只要需要提高图像清晰度和质量的场景都可以考虑使用图像超分服务。

* **照片清晰度提升**：**网站图片**、**手机相册图片**、**视频封面**的图像质量，对压缩后变模糊的图片进行智能去噪，增强图像纹理细节，使画质更加清晰锐利。

* **设计素材优化**：可用于**打印工作室**、**定制商品商家**（如售卖可印刷照片的定制T恤、手机壳等）、**照相馆**在彩印前美化图片，提升印刷品质量。

* **监控图像质量提升**：可用于**家庭**、**商用**、**公司**或**车载**等场景下，因天气、光照、湿度所影响的监控素材进行画面质量提升，重获更清晰的监控图像。

* **电商产品图片优化**：展示清晰的产品图片可以提升用户购买意愿。

## **使用限制** [#使用限制]

* 输出支持倍数：2倍、4倍

* 原图分辨率限制：仅支持小于等于 1920x1080

* 原图格式：仅支持 jpg、png、bmp

* 当前仅支持 **华东区域** 的资源处理

# **参数说明** [#参数说明]

```
aicvt/format/<Format>
     /superResolution/<SuperResolution>
     /srMode/<SRMode>
```

| 参数名称                                | 类别  | 必填 | 说明                                                                                                    |
| ----------------------------------- | --- | -- | ----------------------------------------------------------------------------------------------------- |
| /format/\<Format>                   | A/V | Y  | 必填，输出格式支持：jpg、png、bmp。                                                                                |
| /srMode/\<SRMode>                   | V   | N  | 超分模式，默认为：base。<br />1. 值为`base`：普通版，稳定的超分辨率效果；<br />2. 值为 `enhance`：增强版，相比普通超分模式，具有更好的增强的效果，进一步提高清晰度。 |
| /superResolution/\<SuperResolution> | V   | N  | 超分辨率功能（AI功能）。<br />1. `srMode/base`情况下 ，取值支持 2；<br />2. `srMode/enhance`情况下， 取值支持 2、4                 |

## **效果展示** [#效果展示]

* 原图

  ```
  https://dora-doc.qiniu.com/p04.png
  ```

  ![img](/docs-assets/products/dora/%284-api-docs%29/quality%20enhancement/1-image-super-resolution/p04-948442f9974f.webp)

* 普通版2倍输出

  ```
  https://dora-doc.qiniu.com/p04_qiniu_basex2.png
  ```

  ![img](/docs-assets/products/dora/%284-api-docs%29/quality%20enhancement/1-image-super-resolution/p04_qiniu_basex2-218127ac076d.webp)

* 增强版2倍输出

  ```
  https://dora-doc.qiniu.com/p04_qiniu_enhancex2.png
  ```

  ![img](/docs-assets/products/dora/%284-api-docs%29/quality%20enhancement/1-image-super-resolution/p04_qiniu_enhancex2-fd49f5c7e3c4.webp)

* 增强版4倍输出

  ```
  https://dora-doc.qiniu.com/p04_qiniu_enhancex4.png
  ```

  ![img](/docs-assets/products/dora/%284-api-docs%29/quality%20enhancement/1-image-super-resolution/p04_qiniu_enhancex4-500ad0eea013.webp)

# **操作方式** [#操作方式]

可以通过 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 的方式来调用：

* `资源上传时自动触发`：可以在上传时指定[persistentOps](/products/kodo/development-guidelines/security/1-put-policy#put-policy-persistent-ops-explanation)参数
* `对已有资源手动手动触发`：调用[pfop](/products/dora/audio-and-video-processing-api/1-audio-and-video-stitching-avconcat)命令

# **示例** [#示例]

* 以`对已有资源手动触发`  的形式，将 gogopher2.jpg进行图像超分，设置普通版2倍输出：

  ```
  POST /pfop/ HTTP/1.1
  Host: api.qiniu.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Qiniu <AccessToken>

  bucket=qiniu-ts-demo&key=gogopher2.jpg&fops=aicvt/format/jpg/srMode/base/superResolution/2=&notifyURL=http://fake.com/qiniu/notify
  ```

  **注意**：要在`Authorization`头部的`<AccessToken>`前添加`Qiniu`和半角空格。访问权限，见[管理凭证](/products/kodo/development-guidelines/security/access-token)方式。数据处理命令 `fops` ，将其设置为：

  ```
  fops = aicvt/format/jpg/srMode/base/superResolution/2
  ```

* 以 `资源上传时自动触发` 形式，将 gogopher2.jpg进行图像超分，设置增强版4倍输出：

  ```
   {
        "scope":                "qiniu-ts-demo:gogopher2.jpg",
        "deadline":             1390528576,
        "persistentOps":        "aicvt/format/jpg/srMode/enhance/superResolution/4",
        "persistentNotifyUrl":  "http://fake.com/qiniu/notify"
    }
  ```

**注意**:
其他语言 Sdk 可在[官方 Sdks ](/sdk-tools/sdk)下载，可以通过查看 Sdk 使用指南中 `对已有资源手动触发`，`资源上传时自动触发`使用。

# **计费说明** [#计费说明]

| 类型        | **价格**   |
| --------- | -------- |
| 图像超分（增强版） | 0.1 元/次  |
| 图像超分（普通版） | 0.04 元/次 |


# 视频色彩增强 (/products/dora/quality%20enhancement/2-videocolorenhancement)



最近更新时间: 2024-10-29 17:52:27

# **简介** [#简介]

**视频色彩增强**，人眼对色彩是非常敏感，很大程度上会影响用户的主观感受，在色域上增强技术分SDR域和HDR域的算法，比如SDR转HDR、SDR增强等算法，都是对色彩进行处理的算法，实现视频宽色域、高位深、HDR高动态范围等色彩增强。

* **SDR 增强**：针对HDR输入视频，转为SDR视频，尽可能保留了HDR的高亮度和宽色域信息，色彩更接近原始HDR视频，提升视频色彩质量。如果不设置SDR增强，会导致转码后丢失HDR色域，导致转码前后色彩差距大。

* **SDR转HDR**：基于智能算法将 SDR 视频转换为 HDR 视频，色域提升至BT2020，色深提升至10bit，亮度提升至最高1000nit，从而提升视频的对比度，色彩丰富度，实现更好的视觉效果。

# **应用场景** [#应用场景]

* 视频网站SDR片源色彩优化：对HDR格式尽量保留还原，让视频获得更好的色彩表达与视觉质量提升。

* 升级HDR电影、电视剧等视频：将SDR格式的电影、电视剧视频，通过基于深度学习的SDR转HDR算法功能，即可获得宽色域、展现更多色彩细节的HDR格式视频。

# **接口规格** [#接口规格]

```
avthumb/<format>
       /sdr/<SDR>
       /colorspace/<ColorSpace>
       /hdr/<HDR>
       /maxLuminance/<MaxLuminance>
       /...
```

| 参数名称                                 | 类别  | 必填 | 说明                                                                                                                                                                                                                                                            |
| :----------------------------------- | --- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `&lt;Format&gt;`                     | A/V | Y  | **封装格式**，目标音频（比如 mp3 m4a 等）或视频（比如 avi 、flv 、mp4等）格式。具体细节请参考 [支持转换的封装格式](https://support.qiniu.com/hc/kb/article/182125/?from=draft)。<br />**注意**：视频编码格式为`libaom-av1`时， 仅支持封装格式为 mp4、mkv、wmv。                                                                  |
| `/sdr/&lt;SDR&gt;`                   | V   | N  | **是否启用增强 SDR，设置为 “1” 时开启**。<br />1、当输入源为`HDR`时，设置为 “1” 时，转为SDR视频，不支持hdr的设备上也能尽可能还原hdr效果。 <br />2、默认关闭，跟随源视频，即hdr到hdr，sdr到sdr。 <br />**注意**： 不支持hdr的设备播放hdr视频，没有hdr效果。                                                                                         |
| `/colorspace/&lt;ColorSpace&gt;`     | V   | N  | **指定 SDR 的色彩空间**。<br />1、暂时只支持取值 bt709，若不设置则输出的色彩空间同输入源。<br />2、若输入源是 HDR 视频，必须设置 `sdr/1` 才会生效。                                                                                                                                                               |
| `/hdr/&lt;HDR&gt;`                   | V   | N  | **是否启用 SDR 转 HDR，设置为 “1” 时开启**。<br />1、当输入源为`SDR`时，设置为 “1” 且指定输出为 H.265 编码时，才能转为 ` HDR`  视频。<br />2、不能与锐智转码相关参数（avsmart、smtMaxvbr、smtQuality）和 pixFmt 同时使用。<br />**注意**：使用 SDR to HDR 的收费跟普通转码有区别，请参考 [音视频增强](https://www.qiniu.com/prices/dora?source=dora)。 |
| `/maxLuminance/&lt;MaxLuminance&gt;` | V   | N  | **设置输出 HDR 视频最大亮度**。<br />1、单位 nit，参数范围 500 nit \~ 1000 nit，默认值为 0，即根据视频内容自适应调整。<br />2、必须设置` hdr/1` 才会生效。                                                                                                                                                    |
| `...`                                |     |    | 其他参数使用，请参考 [普通音视频转码（avthumb）](/products/dora/1-features_introduction)                                                                                                                                                                                         |

# **示例** [#示例]

**1.SDR增强效果**

![img](/docs-assets/products/dora/%284-api-docs%29/quality%20enhancement/2-videocolorenhancement/sdr1-bcd455bd1318.webp)

**2.SDR转HDR效果**

![img](/docs-assets/products/dora/%284-api-docs%29/quality%20enhancement/2-videocolorenhancement/hdr1-ffd69d01c41f.webp)

## 接口响应 [#接口响应]

锐智转码为异步处理，因此响应分为2步：

1. 创建异步处理任务，如成功，返回异步处理任务 ID。示例：16864pauo1vc9nhp12;
2. 返回异步处理结果；

**异步处理返回码**:

| 返回码 | 含义        |
| :-- | :-------- |
| 0   | 成功。       |
| 1   | 等待处理      |
| 2   | 正在处理      |
| 3   | 处理失败      |
| 4   | 处理成功但通知失败 |

**注意**：如果处理失败，可通过 [持久化处理状态查询](/products/dora/processing-mechanism/persist/1-persistent-processing-status-query-prefop) 查看具体失败原因。

# **操作方式** [#操作方式]

* **API方式**：可以通过 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 的方式来调用：
  * `资源上传时自动触发`：可以在上传时指定[persistentOps](/products/kodo/development-guidelines/security/1-put-policy#put-policy-persistent-ops-explanation)参数
  * `对已有资源手动手动触发`：调用[pfop]()命令

* **控制台方式**：您可以使用[智能多媒体平台](https://portal.qiniu.com/dora/media-gate)，可视化创建任务，使用详情请参考 [任务](/products/dora/console-guide/1-task-01)。


# 音频降噪 (/products/dora/quality%20enhancement/3-adenoise)



最近更新时间: 2024-10-29 17:52:27

本文主要介绍音频降噪功能。

<a id="realTimeTranscoding" />

# **简介** [#简介]

通过 AI 算法去杂音技术为音频降噪，精准将背景噪音从音轨中移除，以达到线上去杂音的效果，保证人声和背景音乐无损伤的前提下，更好地抑制噪声。

## **应用场景** [#应用场景]

* **网课后期制作**：录制环境往往会受到各种噪音的干扰，这些噪音会严重影响音频的听感和质量，进而影响教学体验。音频降噪处理能够有效地识别和去除这些噪音，使音频更加清晰、纯净，从而提升整体音质。
* **UGC内容创作**：降低或消除音频噪音，使得主要音频内容更加突出，便于后期智能识别添加字幕，优化成品音频质量。在音频后期制作过程中，降噪处理也是不可或缺的一环。

## **使用限制** [#使用限制]

* 当前仅支持 `华东区域` 的资源处理
* 输入分辨率限制，不能大于2560x1440

# **参数说明** [#参数说明]

注意：接口规格不含任何空格与换行符，下列内容经过格式化以便阅读。

```
aicvtAudio/format/<Format>
          /adenoise/<AudioDenoiseNo>
```

| 参数名称                        | 类别  | 必填 | 说明                                                  |
| --------------------------- | --- | -- | --------------------------------------------------- |
| /format/\<Format>           | A/V | Y  | 必填，输出封装格式，当前只支持mp4。                                 |
| /adenoise/\<AudioDenoiseNo> | A   | Y  | 是否启用音频降噪，设置为 1 开启；<br />开启降噪后音频输出单声道、16000HZ、aac编码。 |

为了更好的音质体验，可以结合`音频响度标准化 ` 和 `音量均衡 `参数一起使用，对降噪后的文件进行 [音视频转码](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb#5) 处理，设置以下相关参数：

* 响度标准化：使整体响度水平保持一致，播放时听起来具有相似的音量，避免出现过于响亮或过于安静的问题，提供更好的听觉体验。
* 音量均衡：音量忽大忽小时，平滑过渡响亮的音频片段，避免出现音量突变的问题，提供更平稳的听觉体验。
* 使用姿势为：音频降噪 `\|` 普通转码，示例：`aicvtAudio/format/mp4/adenoise/1\|avthumb/mp4/loudnorm/1/loudnormI/-15/loudnormLRA/11.0/loudnormTP/-0.5/loudnormF/20/loudnormG/7`

# **操作方式** [#操作方式]

可以通过 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 的方式来调用：

* `资源上传时自动触发`：可以在上传时指定[persistentOps](/products/kodo/development-guidelines/security/1-put-policy#put-policy-persistent-ops-explanation)参数
* `对已有资源手动手动触发`：调用[pfop](/products/dora/audio-and-video-processing-api/1-audio-and-video-stitching-avconcat)命令

# **示例** [#示例]

* 以`对已有资源手动触发`  的形式，需要对源文件thinking-in-go.mov，进行音频降噪：

  ```
  POST /pfop/ HTTP/1.1
  Host: api.qiniu.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Qiniu <AccessToken>

  bucket=qiniu-ts-demo&key=thinking-in-go.mov&fops= aicvtAudio/format/mp4/adenoise/1=&notifyURL=http://fake.com/qiniu/notify
  ```

  **注意**：要在`Authorization`头部的`<AccessToken>`前添加`Qiniu`和半角空格。访问权限，见[管理凭证](/products/kodo/development-guidelines/security/access-token)方式。数据处理命令 `fops` ，将其设置为：

  ```
  fops =aicvtAudio/format/mp4/adenoise/1
  ```

* 以 `资源上传时自动触发` 形式，将thinking-in-go.mov进行视频超分，转化为mp4格式，设置2倍尺寸输出：

  ```
   {
        "scope":                "qiniu-ts-demo:thinking-in-go.mov",
        "deadline":             1390528576,
        "persistentOps":        "aicvtAudio/format/mp4/adenoise/1",
        "persistentNotifyUrl":  "http://fake.com/qiniu/notify"
    }
  ```

**注意**:
其他语言 Sdk 可在[官方 Sdks ](/sdk-tools/sdk)下载，可以通过查看 Sdk 使用指南中 `对已有资源手动触发`，`资源上传时自动触发`使用。

# **计费说明** [#计费说明]

| 类型   | **价格**   |
| ---- | -------- |
| 音频降噪 | 0.1 元/分钟 |


# 倍速视频超分 (/products/dora/quality%20enhancement/4-aifast)



最近更新时间: 2024-11-01 16:21:33

# **简介** [#简介]

倍速视频超分，即加速对视频资源进行视频超分处理。视频超分处理，可以将输入视频的宽高放大2-3倍尺寸输出，基于深度学习算法，提高视频的清晰度、画质和主观质量，从而提高播放和观影体验。

## **应用场景** [#应用场景]

* **升级老旧片源**：针对画质不理想的老片源进行升级，基于深度学习的视频超分辨算法，可将低分辨率的视频，增强转化为高分辨视频。
* **短视频增强**：针对低分辨率视频，不适应如今对高分辨率影片的要求，通过视频超分辨算法对影片细节进行增强修复，利用AI模型达到高分辨率输出的同时有效细节更清晰。
* **视频转清晰度**：以视频超分辨率重构技术为基础，辅以丰富的图像增强工具，实现标清转高清、高清转 4K 等画质提升应用场景。

## **使用限制** [#使用限制]

* 当前仅支持  `华东区域` 的资源处理
* 输入分辨率限制，仅支持小于等于1920x1080
* 视频输出帧率，默认等于源视频帧率，取值范围为\[1,60]，超出范围取60帧
* 输出视频格式，只支持 `mp4` 和 `m3u8`
* 若输入文件过小，可能无法达到预期的加速效果，仍按照当前功能计费；建议用于时长大于5分钟的视频

# **接口规格** [#接口规格]

**注意**：接口规格不含任何空格与换行符，下列内容经过格式化以便阅读。

```
    aifast/<Format>
            /vcodec/<VideoCodec>
            /superResolution/<SuperResolution>
            /srMode/<SRMode>
            /faceFilter/<FaceFilter>
```

| 参数                                         |  类别 |  必填 | 说明                                                                           |
| :----------------------------------------- | :-: | :-: | :--------------------------------------------------------------------------- |
| `&lt;Format&gt;`                           | A/V |  Y  | 要转换输出的目标视频格式。<br />● 输出目前仅支持  `mp4` 和 `m3u8`。                                |
| `/vcodec/&lt;VideoCodec&gt;`               |  V  |  N  | 视频编码方案，支持方案：`libx264` 和 `libx265`，默认使用 `libx264`。                            |
| `/superResolution/&lt;SuperResolution&gt;` |  V  |  N  | 开启超分辨率功能（AI功能），取值范围为：\[2,3]的整数，按照源视频的宽高2倍或3倍尺寸输出。                            |
| `/srMode/&lt;SRMode&gt;`                   |  V  |  N  | 超分模式，默认为base，可取值：base、faceEnhance，其中faceEnhance：采用了独有的人脸增强模块，智能识别并优化人脸区域。    |
| `/faceFilter/&lt;FaceFilter&gt;`           |  V  |  N  | 是否开启人脸过滤，默认不开启。<br />设置 faceFilter/1 才会生效，即过滤掉faceEnhance模式下人脸过小和人脸角度太大的人脸增强 |

# M3U8相关接口 [#m3u8相关接口]

**注意：** 常规处理参数与其他格式相同，后续接口说明仅针对HLS/m3u8格式。

```
    aifast/m3u8
            /...
            /segtime/<SegSeconds>
            /savePattern/<Pattern>
```

| 参数                             | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/segtime/&lt;SegSeconds&gt;`  | 用于 HLS 自定义每一小段音/视频流的播放时间长度，取值范围为: 2 - 120 （秒），默认值为 10（单位:秒）。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `/savePattern/&lt;Pattern&gt;` | 仅当设置为 `aifast/m3u8` 时，选择使用。<br />为各音视频流ts文件自定义命名。<br />因为一整段音视频流音视频切片后会生成一个M3U8播放列表和多个默认命名的音视频流ts文件。<br />**命名支持使用变量**：<br />1. 可以使用 `$(变量名)`或`${变量名}` 形式求值，魔法变量使用说明，参考 文件名变量 。<br />2. 注意：`$(count)`为必填项，必须存在的六位占位符数字串。<br /><br />**示例**：<br />输出的m3u8文件名为：`output.m3u8`，cmd为：`aifast/m3u8/superResolution/2/noDomain/1/savePattern/JChzYXZlYXMua2V5UHJlZml4KSAkKGNvdW50KS50cw==` ，其中 `JChzYXZlYXMua2V5UHJlZml4KSAkKGNvdW50KS50cw==` 是自定义 ts 文件名，$(saveas.keyPrefix) $(count).ts 的[URL安全的Base64编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。最后得到类似：output000000.ts,output000001.ts,……,output000006.ts 命名的 ts 文件，跟输出的m3u8文件是关联的。<br /> |

# **操作方式** [#操作方式]

可以通过 [持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 的方式来调用：

* `资源上传时自动触发`：可以在上传时指定[persistentOps](/products/kodo/development-guidelines/security/1-put-policy#put-policy-persistent-ops-explanation)参数
* `对已有资源手动手动触发`：调用[pfop]()命令

# **计费说明** [#计费说明]

倍速视频超分定价，参考 [智能多媒体服务定价->画质增强->倍速视频超分](https://www.qiniu.com/prices/dora) 。

* 倍速视频超分费用 = 输出文件时长 x 单价。
* 输出时长：按分钟计费，累计总时长不足一分钟不计费
* 输出规格按输出视频分辨率的长边和短边属于输出规格划定的范围进行判定，以视频超分输出HD (1920 x 1080) 规格为例：
  * 输出视频的分辨率长边不大于2560且短边不大于1440，则属于2K输出规格。


# 定价 (/products/dora/the-face-of-a-check/6875-pricing)



最近更新时间: 2025-10-17 10:56:46

# 按调用次数计费（后付费） [#按调用次数计费后付费]

| API     | 简介                                  | 单价（元/次） |
| :------ | :---------------------------------- | :------ |
| 动作活体检测  | 通过微动作（注视、点头、摇头）分辨出活体，防止伪造照片、视频、人脸面具 | 0.12    |
| 防翻拍活体检测 | 检测单张静态图片中的人脸是否为活体                   | 0.12    |
| 人脸比对    | 比对两张图片中人脸的相似度，并返回相似度分值              | 0.006   |
| 权威人脸核验  | 将用户人脸照片和权威证件库进行比对，实人核验              | 1       |
| 身份证OCR  | 识别身份证上的姓名、身份证号等关键信息                 | 0.03    |
| 身份证二要素  | 核验姓名、身份证号的一致性                       | 0.3     |
| 手机号三要素  | 核验姓名、身份证号、手机号的一致性                   | 0.4     |
| 银行卡四要素  | 核验姓名、身份证号、银行卡、预留手机号的一致性             | 0.5     |

# 资源包（预付费） [#资源包预付费]

[点击前往云商城](https://qmall.qiniu.com/template/MTI1?spec_combo=MzQ4Nw)


# 营业执照 OCR (/products/dora/ticket-automatic-recognition-ocr/0-business-license-of-ocr)



最近更新时间: 2022-11-22 16:17:47

# 接口简介 [#接口简介]

检测营业执照的图片，返回 OCR 识别结果。

**注意**

* 接口超时时间为 30 秒
* 资源的 Mime 文件格式仅支持图片类型：image/\*，如：image/jpeg、image/png。
* 请求接口为标准的HTTP/HTTPS 协议。

# 请求语法 [#请求语法]

```
POST /ocr/bs HTTP/1.1
Host: ocr-bs.qiniuapi.com
Content-Type: application/json
Authorization: QiniuToken
```

# 头部信息 [#头部信息]

| 头部名称          | 必填 | 说明                                                                                                                                                               |
| ------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Host          | 是  | 固定为  ocr-bs.qiniuapi.com                                                                                                                                         |
| Content-Type  | 是  | 固定为 application/json                                                                                                                                             |
| Authorization | 是  | 该参数应严格按照[管理凭证](/products/kodo/development-guidelines/security/access-token)格式进行填充，否则会返回 401 错误码。一个合法的 Authorization 值应类似于：`Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |

# 请求body [#请求body]

| 字段    | 是否必填 | 类型     | 说明                          |
| ----- | ---- | ------ | --------------------------- |
| image | Y    | string | base64编码的图片数据, JPG 或 PNG 格式 |
| uuid  | N    | string | 唯一会话 id                     |

## 返回 [#返回]

| 字段        | 类型         | 说明                                            |
| --------- | ---------- | --------------------------------------------- |
| uuid      | string     | 请求中的 uuid 字符串，如果请求 中没有发送 uuid 参数，那么这里 的值为空字符串 |
| errorcode | int        | 返回状态码                                         |
| items     | jsonObject | OCR 结果                                        |

### items [#items]

| 字段                    | 类型     | 说明                 |
| --------------------- | ------ | ------------------ |
| has\_head             | bool   | 是否含有“营业执照”四字       |
| has\_tail             | bool   | 是否含有“登记机关”四字       |
| is\_copy              | bool   | 是否副本               |
| credit\_code          | string | 统一社会信用代码           |
| name                  | string | 名称                 |
| type                  | string | 类型                 |
| address               | string | 住所、经营场所、营业场所       |
| legal\_representative | string | 经营者、投资人、负责人、 法定代表人 |
| found\_date           | string | 成立日期、注册日期          |
| operation\_term       | string | 经营期限、营业期限          |
| registered\_capital   | string | 注册资本、成员出资总额        |
| business\_scope       | string | 经营范围               |

# 示例 [#示例]

```
POST /ocr/bs HTTP/1.1
Host: ocr-bs.qiniuapi.com
Authorization: Qiniu aWQ6lF1Zxxse43jB6V7lsdfaadf:7cWZPxxxxxasdffed60zkI8=
Content-Type: application/json
{
    "image": IMAGE_DATA
}
```

## 返回示例 [#返回示例]

```
{
"errorcode": 0,
"errormsg": "OK",
"session_id": "7800000015836645854820154824909",
"ocr_result": {
"has_head": true,
"has_tail": true,
"is_copy": false,
"credit_code": {
"value": "9133****95366C",
"pos": {
"x": 1802,
"y": 1395,
"width": 413,
"height": 65
}
},
"name": {
"value": "*****有限公司",
"pos": {
"x": 1277,
"y": 1628,
"width": 574,
"height": 51
}
},
"type": {
"value": "有限责任公司(自然人投资或控股)",
"pos": {
"x": 1277,
"y": 1724,
"width": 749,
"height": 65
}
},
"address": {
"value": "上海市浦东新区博霞路66号",
"pos": {
"x": 1277,
"y": 1833,
"width": 763,
"height": 51
}
},
"legal_representative": {
"value": "葛*儒",
"pos": {
"x": 1277,
"y": 1956,
"width": 144,
"height": 51
}
},
"found_date": {
"value": "2015 年 05 月 08 日",
"pos": {
"x": 1277,
"y": 2175,
"width": 400,
"height": 51
}
},
"operation_term": {
"value": "2015 年 05 月 08 日至 2035 年 05 月 07 日",
"pos": {
"x": 1277,
"y": 2271,
"width": 897,
"height": 51
}
},
"registered_capital": {
"value": "壹仟万元整",
"pos": {
"x": 1277,
"y": 2066,
"width": 238,
"height": 51
}
},
"business_scope": {
"value": "服务:环保设备、节能设备、水处理设备、计算机软硬件的技术开发、技术服务、技术咨询、成果转让: 批发、 零售: 环保产品， 环保材料， 机械设备， 环保设备， 水处理设备， 化工原料(除化学危险品及易制毒化 学品)(依法须经批准的项目， 经相关部门批准店方可开展经营活动)",
"pos": {
"x": 1277,
"y": 2353,
"width": 991,
"height": 51
}
}
}
}
```

## 错误码 [#错误码]

| 错误码   | 错误信息     | HTTP 状态码 |
| ----- | -------- | -------- |
| 10001 | 请求解析失败   | 400      |
| 10002 | 鉴权失败     | 400      |
| 10003 | 图像解码错误   | 400      |
| 10004 | 请求超时     | 408      |
| 10005 | OCR 内部错误 | 500      |
| 10006 | 未知错误     | 500      |

## 价格 [#价格]

0.05元/次


# 驾驶证 OCR (/products/dora/ticket-automatic-recognition-ocr/1-driving-license-ocr)



最近更新时间: 2026-08-18 15:21:04

# 接口说明 [#接口说明]

驾驶证识别支持对驾驶证上所有字段的自动定位与识别。

## 限制条件 [#限制条件]

1. 文件格式：支持JPG、JPEG、PNG、BMP、PDF等常见格式，建议使用JPG格式。
2. 图片像素尺寸：为了保证文字识别效果，推荐图片中驾驶证最短边长不低于256像素。
3. 输入文件大小：要求Base64编码和urlencode之后不超过 8 MB。驾驶证主体尽量占据图片主要区域。
4. 输入文件过大时，返回的HttpCode如下：400/413/502。
5. 注意图片质量：保证驾驶证图片足够清晰，不应该有因为压缩导致的噪声，避免对驾驶证正反面的遮挡、不当的光照（强光、暗光、逆光）等，否则会降低结果准确度。
6. 图片需要有版权，有肖像权，没有法律或者政策风险的。相关风险请注意评估。
7. 驾驶证图片不可以是复印件、翻拍件、PS件等。
8. 输入多页PDF时，默认只识别第一页。

# 请求 [#请求]

## 请求地址 [#请求地址]

| 名称          | 值                                                                                                          |
| :---------- | :--------------------------------------------------------------------------------------------------------- |
| HTTP URL    | [https://ap-gate-z0.qiniuapi.com/ocr/driving/license](https://ap-gate-z0.qiniuapi.com/ocr/driving/license) |
| HTTP Method | POST                                                                                                       |

## 请求头 [#请求头]

| 名称            | 必填 | 说明                                                                                                                                                               |
| :------------ | :- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Host          | 是  | 固定值ap-gate-z0.qiniuapi.com                                                                                                                                       |
| Authorization | 是  | 该参数应严格按照[管理凭证格式](/products/kodo/development-guidelines/security/access-token)进行填充，否则会返回 401 错误码。一个合法的 Authorization 值应类似于：Qiniu QNJi\_bYJlmO5LeY08FfoNj9w\_r7... |
| Content-Type  | 是  | 固定值application/json                                                                                                                                              |

## 请求参数 [#请求参数]

| 字段            | 必填 | 类型     | 说明                                                                                |
| :------------ | :- | :----- | :-------------------------------------------------------------------------------- |
| image\_base64 | 否  | string | 驾驶证图片文件，base64编码                                                                  |
| image\_url    | 否  | string | 图片/PDF文件的URL链接<br />注意: 要求image\_base64与image\_url二选一，如果2个字段都有，优先解析image\_base64。 |

## 请求示例 [#请求示例]

```plaintext
POST /ocr/driving/license
Host: ap-gate-z0.qiniuapi.com
Authorization: <no value>
Content-Type: application/json

{
  "image_base64": "base64"
}
```

# 响应 [#响应]

## 响应头 [#响应头]

| 名称           | 必填 | 说明                  |
| :----------- | :- | :------------------ |
| Content-Type | 是  | 固定值application/json |

## 响应参数 [#响应参数]

| 字段            | 必填 | 类型          | 说明     |
| :------------ | :- | :---------- | :----- |
| message       | 是  | string      | 错误信息   |
| request\_id   | 是  | string      | 请求唯一ID |
| time\_elapsed | 是  | string      | 请求耗时   |
| code          | 是  | number      | 错误码    |
| data          | 否  | object data |        |

其中，*data* 参数

| 字段            | 必填 | 类型                   | 说明 |
| :------------ | :- | :------------------- | :- |
| license\_main | 否  | object license\_main |    |

其中，*license\_main* 参数

| 字段                          | 必填 | 类型                            | 说明     |
| :-------------------------- | :- | :---------------------------- | :----- |
| id\_photo\_location         | 否  | \[]object id\_photo\_location | 相片位置   |
| valid\_begin                | 否  | string                        | 有效期起   |
| valid\_end                  | 否  | string                        | 有效期止   |
| class                       | 否  | string                        | 准驾车型   |
| date\_of\_birth             | 否  | string                        | 出生日期   |
| date\_of\_first\_issue      | 否  | string                        | 初次领证日期 |
| nationality                 | 否  | string                        | 国籍     |
| id\_number                  | 否  | string                        | 证号     |
| record                      | 否  | string                        | 记录     |
| sex                         | 否  | string                        | 性别     |
| address                     | 否  | string                        | 住址     |
| document\_id                | 否  | string                        | 档案编号   |
| licence\_issuing\_authority | 否  | string                        | 发证机关   |
| name                        | 否  | string                        | 姓名     |

其中，*id\_photo\_location* 参数

| 字段 | 必填 | 类型     | 说明 |
| :- | :- | :----- | :- |
| x0 | 否  | number |    |
| x1 | 否  | number |    |
| x3 | 否  | number |    |
| y0 | 否  | number |    |
| y2 | 否  | number |    |
| y4 | 否  | number |    |
| x2 | 否  | number |    |
| x4 | 否  | number |    |
| y1 | 否  | number |    |
| y3 | 否  | number |    |

## 响应示例 [#响应示例]

```plaintext
200 OK
Content-Type: application/json

{
  "code": 10000,
  "data": {
    "license_main": {
      "address": "山东省XX市XX镇XX村XX",
      "class": "C1",
      "date_of_birth": "1900-01-01",
      "date_of_first_issue": "2016-01-01",
      "id_number": "370XXX19000101XXXX",
      "name": "张三",
      "nationality": "中国",
      "sex": "女",
      "valid_begin": "2016-01-01",
      "valid_end": "2022-01-01"
    }
  },
  "message": "Success",
  "request_id": "6838889517957515275",
  "time_elapsed": "41.897331ms"
}
```


# 行驶证 OCR (/products/dora/ticket-automatic-recognition-ocr/2-vehicle-license-ocr)



最近更新时间: 2026-08-18 15:20:39

# 接口说明 [#接口说明]

行驶证识别支持对行驶证上所有字段的自动定位与识别。

## 限制条件 [#限制条件]

1. 文件格式：支持JPG、JPEG、PNG、BMP、PDF等常见格式，建议使用JPG格式。
2. 图片像素尺寸：最小 256 x 256 像素，最大 2048 x 2048 像素。为了保证文字识别效果，推荐图片中行驶证最短边长不低于256像素。
3. 文件大小：
   a.要求Base64编码和urlencode之后不超过 8 MB。行驶证主体尽量占据图片主要区域，不支持黑白图片。
   b.如果传图片及PDF完整URL，URL对应文件大小建议不要超过8MB。
4. 输入文件过大时，返回的HttpCode如下：400/413/502。
5. 注意图片质量：保证行驶证图片足够清晰，不应该有因为压缩导致的噪声，避免对行驶证正反面的遮挡、不当的光照（强光、暗光、逆光）等，否则会降低结果准确度。
6. 图片需要有版权，有肖像权，没有法律或者政策风险的。相关风险请注意评估。
7. 行驶证图片不可以是复印件、翻拍件、PS件等。
8. 输入多页PDF时，默认只识别第一页。

# 请求 [#请求]

## 请求地址 [#请求地址]

| 名称          | 值                                                                                                          |
| :---------- | :--------------------------------------------------------------------------------------------------------- |
| HTTP URL    | [https://ap-gate-z0.qiniuapi.com/ocr/vehicle/license](https://ap-gate-z0.qiniuapi.com/ocr/vehicle/license) |
| HTTP Method | POST                                                                                                       |

## 请求头 [#请求头]

| 名称            | 必填 | 说明                                                                                                                                                               |
| :------------ | :- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Host          | 是  | 固定值ap-gate-z0.qiniuapi.com                                                                                                                                       |
| Authorization | 是  | 该参数应严格按照[管理凭证格式](/products/kodo/development-guidelines/security/access-token)进行填充，否则会返回 401 错误码。一个合法的 Authorization 值应类似于：Qiniu QNJi\_bYJlmO5LeY08FfoNj9w\_r7... |
| Content-Type  | 是  | 固定值application/json                                                                                                                                              |

## 请求参数 [#请求参数]

| 字段            | 必填 | 类型     | 说明                                                                                |
| :------------ | :- | :----- | :-------------------------------------------------------------------------------- |
| image\_base64 | 否  | string | 身份证图片文件，base64编码                                                                  |
| image\_url    | 否  | string | 图片/PDF文件的URL链接<br />注意: 要求image\_base64与image\_url二选一，如果2个字段都有，优先解析image\_base64。 |

## 请求示例 [#请求示例]

```plaintext
POST /ocr/vehicle/license
Host: ap-gate-z0.qiniuapi.com
Authorization: <no value>
Content-Type: application/json

{
  "image_base64": "base64"
}
```

# 响应 [#响应]

## 响应头 [#响应头]

| 名称           | 必填 | 说明                  |
| :----------- | :- | :------------------ |
| Content-Type | 是  | 固定值application/json |

## 响应参数 [#响应参数]

| 字段            | 必填 | 类型          | 说明     |
| :------------ | :- | :---------- | :----- |
| data          | 否  | object data |        |
| message       | 是  | string      | 错误信息   |
| request\_id   | 是  | string      | 请求唯一ID |
| time\_elapsed | 是  | string      | 请求耗时   |
| code          | 是  | number      | 错误码    |

其中，*data* 参数

| 字段            | 必填 | 类型                   | 说明 |
| :------------ | :- | :------------------- | :- |
| license\_main | 否  | object license\_main |    |

其中，*license\_main* 参数

| 字段                             | 必填 | 类型     | 说明                                                                                    |
| :----------------------------- | :- | :----- | :------------------------------------------------------------------------------------ |
| address                        | 否  | string | 住址                                                                                    |
| issue\_date                    | 否  | string | 发证日期                                                                                  |
| plate\_number                  | 否  | string | 号牌号码<br />行驶证正、副页均有"号牌号码"字段<br />如果图片中同时存在正副页，则输出结果优先以正页结果为准（即图片中不存在正页号牌号码时，才会输出副页结果） |
| register\_date                 | 否  | string | 注册日期                                                                                  |
| curb\_weight                   | 否  | string | 整备质量                                                                                  |
| licence\_issuing\_authority    | 否  | string | 发证机关                                                                                  |
| traction\_mass                 | 否  | string | 准牵引总质量                                                                                |
| document\_id                   | 否  | string | 档案编号                                                                                  |
| engine\_number                 | 否  | string | 发动机号码                                                                                 |
| model                          | 否  | string | 品牌型号                                                                                  |
| ratified\_load\_capacity       | 否  | string | 核定载质量                                                                                 |
| total\_mass                    | 否  | string | 总质量                                                                                   |
| vin                            | 否  | string | 车辆识别代号                                                                                |
| approved\_passengers\_capacity | 否  | string | 核定载人数                                                                                 |
| gabarite                       | 否  | string | 外廓尺寸                                                                                  |
| inspection\_record             | 否  | string | 检验记录                                                                                  |
| owner                          | 否  | string | 所有人                                                                                   |
| remarks                        | 否  | string | 备注                                                                                    |
| use\_character                 | 否  | string | 使用性质                                                                                  |
| vehicle\_type                  | 否  | string | 车辆信息                                                                                  |

## 响应示例 [#响应示例]

```plaintext
200 OK
Content-Type: application/json

{
  "code": 10000,
  "data": {
    "license_main": {
      "address": "某某省某某县某某路",
      "approved_passengers_capacity": "XXXX",
      "curb_weight": "XXX",
      "document_id": "XXX",
      "engine_number": "ABCDEF123456",
      "gabarite": "XXX",
      "inspection_record": "XXX",
      "issue_date": "2014.01.01",
      "licence_issuing_authority": "某某省某某市公安局交通警察支队",
      "model": "桑塔纳12345ABCDE",
      "owner": "张三",
      "plate_number": "京ABCDEF",
      "ratified_load_capacity": "",
      "register_date": "2011.01.01",
      "remarks": "XXX",
      "total_mass": "XXX",
      "traction_mass": "XXX",
      "use_character": "非营运",
      "vehicle_type": "小型轿车",
      "vin": "ABCDCHGH123456789"
    }
  },
  "message": "Success",
  "request_id": "6838889517957515275",
  "time_elapsed": "41.897331ms"
}
```


# 增值税发票 OCR (/products/dora/ticket-automatic-recognition-ocr/3-the-vat-invoice-ocr)



最近更新时间: 2026-08-18 15:20:11

# 接口说明 [#接口说明]

增值税发票文字识别，结构化输出增值税发票上的字段文字信息。

## 限制条件 [#限制条件]

1. 文件格式：支持JPG、JPEG、PNG、BMP、PDF、OFD等常见格式，建议使用JPG格式。
2. 图片像素尺寸：最小 256 x 256 像素，最大 2048 x 2048 像素。为了保证文字识别效果，推荐图片中增值税发票最短边长不低于256像素。
3. 文件大小：
   a.要求Base64编码和urlencode之后不超过 8 MB。增值税发票主体尽量占据图片主要区域，不支持黑白图片。
   b.如果传图片及PDF完整URL，URL对应文件大小建议不要超过8MB。
4. 输入文件过大时，返回的HttpCode如下：400/413/502。
5. 注意图片质量：保证增值税发票图片足够清晰，不应该有因为压缩导致的噪声，避免对增值税发票正反面的遮挡、不当的光照（强光、暗光、逆光）等，否则会降低结果准确度。
6. 图片需要有版权，有肖像权，没有法律或者政策风险的。相关风险请注意评估。
7. 增值税发票图片不可以是复印件、翻拍件、PS件等。
8. 输入多页PDF时，默认只识别第一页。

# 请求 [#请求]

## 请求地址 [#请求地址]

| 名称          | 值                                                                                                  |
| :---------- | :------------------------------------------------------------------------------------------------- |
| HTTP URL    | [https://ap-gate-z0.qiniuapi.com/ocr/vat/invoice](https://ap-gate-z0.qiniuapi.com/ocr/vat/invoice) |
| HTTP Method | POST                                                                                               |

## 请求头 [#请求头]

| 名称            | 必填 | 说明                                                                                                                                                               |
| :------------ | :- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Host          | 是  | 固定值ap-gate-z0.qiniuapi.com                                                                                                                                       |
| Authorization | 是  | 该参数应严格按照[管理凭证格式](/products/kodo/development-guidelines/security/access-token)进行填充，否则会返回 401 错误码。一个合法的 Authorization 值应类似于：Qiniu QNJi\_bYJlmO5LeY08FfoNj9w\_r7... |
| Content-Type  | 是  | 固定值application/json                                                                                                                                              |

## 请求参数 [#请求参数]

| 字段            | 必填 | 类型     | 说明                                                                                |
| :------------ | :- | :----- | :-------------------------------------------------------------------------------- |
| image\_base64 | 否  | string | 增值税发票图片文件，base64编码                                                                |
| image\_url    | 否  | string | 图片/PDF文件的URL链接<br />注意: 要求image\_base64与image\_url二选一，如果2个字段都有，优先解析image\_base64。 |

## 请求示例 [#请求示例]

```plaintext
POST /ocr/vat/invoice
Host: ap-gate-z0.qiniuapi.com
Authorization: <no value>
Content-Type: application/json

{
  "image_base64": "base64"
}
```

# 响应 [#响应]

## 响应头 [#响应头]

| 名称           | 必填 | 说明                  |
| :----------- | :- | :------------------ |
| Content-Type | 是  | 固定值application/json |

## 响应参数 [#响应参数]

| 字段            | 必填 | 类型          | 说明     |
| :------------ | :- | :---------- | :----- |
| message       | 是  | string      | 错误信息   |
| request\_id   | 是  | string      | 请求唯一ID |
| time\_elapsed | 是  | string      | 请求耗时   |
| code          | 是  | number      | 错误码    |
| data          | 否  | object data |        |

其中，*data* 参数

| 字段            | 必填 | 类型                   | 说明 |
| :------------ | :- | :------------------- | :- |
| license\_main | 否  | object license\_main |    |

其中，*license\_main* 参数

| 字段                             | 必填 | 类型              | 说明         |
| :----------------------------- | :- | :-------------- | :--------- |
| payee                          | 否  | string          | 收款人        |
| seller\_taxpayer\_no\_in\_seal | 否  | string          | 盖章公司纳税人识别号 |
| check\_code                    | 否  | string          | 校验码        |
| total\_tax                     | 否  | string          | 税额         |
| invoice\_code                  | 否  | string          | 发票代码       |
| invoice\_name                  | 否  | string          | 发票名称       |
| sheet\_name                    | 否  | string          | 发票联次       |
| big\_total\_price\_and\_tax    | 否  | string          | 大写金额（价税合计） |
| drawer                         | 否  | string          | 开票人        |
| is\_secret\_out\_bound         | 否  | string          | 密码区是否出界    |
| seller\_account                | 否  | string          | 销售方开户行&账号  |
| seller\_address\_phone         | 否  | string          | 销售方地址&电话   |
| seller\_name                   | 否  | string          | 销售方        |
| seller\_name\_in\_seal         | 否  | string          | 盖章公司名称     |
| total\_price                   | 否  | string          | 金额         |
| buyer\_taxpayer\_no            | 否  | string          | 购买方纳税人识别号  |
| entry                          | 否  | \[]object entry | 相片位置       |
| typed\_invoice\_no             | 否  | string          | 机打发票号码     |
| buyer\_account                 | 否  | string          | 购买方开户行&账号  |
| machine\_num                   | 否  | string          | 机器编号       |
| total\_price\_and\_tax         | 否  | string          | 小写金额（价税合计） |
| invoice\_no                    | 否  | string          | 发票号码       |
| invoice\_special\_seal         | 否  | string          | 发票专用章      |
| is\_sealed                     | 否  | string          | 是否加盖章      |
| reviewer                       | 否  | string          | 复核         |
| seller\_taxpayer\_no           | 否  | string          | 销售方识别号     |
| sub\_type                      | 否  | string          | 增值税发票类别    |
| buyer\_address\_phone          | 否  | string          | 购买方地址&电话   |
| invoice\_date                  | 否  | string          | 开票日期       |
| typed\_invoice\_code           | 否  | string          | 机打发票代码     |
| beizhu                         | 否  | string          | 备注         |
| buyer\_name                    | 否  | string          | 购买方名称      |

其中，*entry* 参数

| 字段            | 必填 | 类型     | 说明           |
| :------------ | :- | :----- | :----------- |
| quantity      | 否  | string | 数量           |
| tax\_amount   | 否  | string | 税额           |
| tax\_rate     | 否  | string | 税率           |
| uint          | 否  | string | 单位           |
| unit\_price   | 否  | string | 单价(不含税)      |
| xinghao       | 否  | string | 型号           |
| entry\_name   | 否  | string | 货物或应税劳务、服务名称 |
| price\_amount | 否  | string | 金额           |

*sub\_type* 发票类别字段说明

| 字段                     | 类型     | 说明        |
| :--------------------- | :----- | :-------- |
| ele\_vat               | string | 增值税电子普通发票 |
| ele\_special\_vat      | string | 增值税电子专票   |
| print\_vat             | string | 增值税纸质普票   |
| special\_vat           | string | 增值税纸质专票   |
| other\_vat             | string | 其他电子发票    |
| quandian\_special\_vat | string | 全电专票      |
| quandian\_vat          | string | 全电普票      |
| unknown\_vat           | string | 未知票       |

## 响应示例 [#响应示例]

```plaintext
200 OK
Content-Type: application/json

{
  "code": 10000,
  "data": {
    "license_main": {
      "big_total_price_and_tax": "柒拾叁圆玖角贰分",
      "buyer_name": "北京字跳网络技术有限公司",
      "buyer_taxpayer_no": "91110108MA01F2L25J",
      "check_code": "16649652847559064366",
      "drawer": "杜洪亮",
      "entry": [
        {
          "entry_name": "*运输服务*客运服务费",
          "price_amount": "73.92",
          "quantity": "1",
          "tax_amount": "***",
          "tax_rate": "免税",
          "unit": "次",
          "unit_prict": "73.92",
          "xinghao": "无"
        }
      ],
      "invoice_code": "011002000611",
      "invoice_date": "2020年12月14日",
      "invoice_name": "XX增值税电子普通发票",
      "invoice_no": "10178760",
      "invoice_special_seal": "发票专用章",
      "is_sealed": "true",
      "machine_num": "499098491560",
      "payee": "张雪丽",
      "reviewer": "蔡静",
      "seller_account": "招商银行股份有限公司北京东三环支行110936504210806",
      "seller_address_phone": "北京市海淀区东北旺西路8号院34号楼二层208号010-62682929",
      "seller_name": "北京滴滴出行科技有限公司",
      "seller_name_in_seal": "北京滴滴出行科技有限公司",
      "seller_taxpayer_no": "91110108MA01G0FB09",
      "seller_taxpayer_no_in_seal": "91110108MA01G0FB09",
      "sub_type": "ele_vat",
      "total_price": "73.92",
      "total_price_and_tax": "73.92",
      "total_tax": "***"
    }
  },
  "message": "Success",
  "request_id": "6838889517957515275",
  "time_elapsed": "41.897331ms"
}
```


# 图片内容审核 (/products/dora/content-censor/0-image-review)



最近更新时间: 2023-01-16 14:11:30

图片内容审核接口提供图片鉴黄、图片鉴暴恐和敏感人物识别三项功能，主要返回图片每一类识别的分类结果、置信度和是否需要人工审核的判断，客户可以根据具体的识别结果来判断文件内容是违规、疑似（需要人工复核）或正常。为了能减少客户的工作，直接获取某个文件是否违规、疑似（需要人工复核）和正常的结果，我们提供了新的图片内容审核接口：

# 新的图片内容审核接口文档 [#新的图片内容审核接口文档]

* [图片内容审核接口](/products/censor/image-censor)


# 视频内容审核 (/products/dora/content-censor/1-video-pulp)



最近更新时间: 2023-01-16 14:11:41

视频内容审核接口提供视频鉴黄、视频鉴暴恐和敏感人物识别三项功能，主要返回视频每一类识别的分类结果、置信度和是否需要人工审核的判断，客户可以根据具体的识别结果来判断文件内容是违规、疑似（需要人工复核）或正常。为了能减少客户的工作，直接获取某个文件是否违规、疑似（需要人工复核）和正常的结果，我们提供了新的视频内容审核接口：

# 新的视频内容审核接口文档 [#新的视频内容审核接口文档]

* [视频内容审核接口](/products/censor/video-censor)


# 智能分层存储简介 (/products/kodo/kodo-category/0-storage-class-intelligent-tiering)



最近更新时间: 2026-05-08 17:46:38

# **简介** [#简介]

七牛智能分层存储类型（INTELLIGENT\_TIERING）自动将对象存储在三个访问层中：一个针对频繁访问进行了优化的层（频繁访问层），一个针对不频繁访问进行了优化的更低成本的层（不频繁访问层），以及一个针对很少访问的数据优化的极低成本层（归档直读访问层）。每月只需支付少量的对象监控和自动化费用，智能分层即可将连续 30 天未访问的对象移动到不频繁访问层，实现约 40% 的节省 （参考[官网价格](https://www.qiniu.com/prices/kodo)），并在 90 天未访问之后，将对象移动到归档直读访问层，实现约 66% 的节省（参考[官网价格](https://www.qiniu.com/prices/kodo)）。如果稍后访问了对象，会自动将该对象移回频繁访问层。

不同的自动访问层，当对象在访问层之间移动时，存储类保持不变。

## 频繁访问层 (FREQUENT\_ACCESS) [#频繁访问层-frequent_access]

这是任何对象创建或转换为智能分层存储类型的对象开始其生命周期的默认访问层。只要对象被访问，对象就会保留在此层中。频繁访问层提供低延迟和高吞吐量性能。

## 不频繁访问层 (INFREQUENT\_ACCESS) [#不频繁访问层-infrequent_access]

如果对象在连续 30 天内仍未被访问，对象会转换到“不频繁访问层”。不频繁访问层提供低延迟和高吞吐量性能。

## 归档直读访问层 (INSTANT\_ACCESS) [#归档直读访问层-instant_access]

如果一个对象连续 90 天未被访问，该对象就会被移到“归档直读访问层”。归档直读访问层提供低延迟和高吞吐量性能。

智能分层存储适用于访问模式不固定或者无法预估访问模式的数据，服务端会监控对象的访问情况，存储费用将按照数据实际存储的层级收费。用户可以按照自身业务需求，将访问模式不固定的数据转换为智能分层存储类型，降低存储成本。

`提示：智能分层存储类型为独立的存储类型，使用时将产生智能分层存储容量费用和智能分层对象监控和自动化费用。`更多计费信息请参见 [计量项与计费项](/products/kodo/1-metering-and-billing)

# **优势** [#优势]

通过数据冷热分层存储，智能分层能够自动化地帮助用户在存储成本和读写性能之间寻找平衡点。使用智能分层存储具有以下优势：

* 成本集约：冷热多层存储层智能转移，节约存储成本。而且智能分层存储类型还参与对象存储生命周期流程，用户可以按需将智能分层存储沉降到归档存储中，进一步降低数据存储成本。在智能分层存储类中的访问层之间移动对象时，不会产生额外的分层费用。智能分层无最短存储时间要求。
* 稳定持久：智能分层存储提供与标准存储一致的低时延和高吞吐体验。同时，智能分层存储采提供了 99.999999999 %（11个9）的数据可靠性，99 % 的业务可用性。
* 便捷易用：只需为数据指定对象存储类型，即可应用智能分层存储特性。智能分层存储作为一种存储类型，天然适配已经提供的 API、SDK、工具等，方便用户按需管理在云上的数据。

<a id="working principle" />

# **工作原理** [#工作原理]

服务端周期性监控对象访问情况，并将持续 30 天未访问对象时自动移动到不频繁访问层。在不访问 90 天后，对象将移动到归档直读访问层，而不会影响性能或运营开销。如果稍后访问不频繁访问层或归档直读访问层中的对象，则自动将其移回频繁访问层。在智能分层存储类中的访问层之间移动对象时，不会产生额外的分层费用。

以下操作构成了自动将对象从不频繁访问层或归档直读访问层移回频繁访问层的访问：

* 上传，[upload](/products/kodo/rs/8-upload)、[mkfile](/products/kodo/rs/shard-to-upload/2-mkfile)、[completeMultipartUpload](/products/kodo/rs/multipartupload-interface/3-complete-multipart-upload)、[listParts](/products/kodo/rs/multipartupload-interface/4-listparts)、[prefetch](/products/kodo/rs/6-prefetch)、[sisyphus/fetch](/products/kodo/rs/10-asynch-fetch)
* 下载，[getObject](/products/kodo/development-guidelines/download-process)
* 修改存储类型，[chtype](/products/kodo/rs/9-modify-the-file-storage-type)
* 修改对象的 MIME 类型信息，[chgm](/products/kodo/rs/1-chgm)
* 复制 [copy](/products/kodo/rs/2-copy) / 移动 [move](/products/kodo/rs/5-move) 对象， 在这些情况下，复制操作的源对象是分层的
* 以上操作的批量操作 ，[batch](/products/kodo/rs/0-batch)

其他操作`不`构成自动将对象从不频繁访问层或归档直读访问层移回频繁访问层的访问，以下是此类操作的示例：

* head 对象 / [stat](/products/kodo/rs/7-stat) 查询元数据
* [list](/products/kodo/rs/4-list) 列举空间中对象条目
* [chstatus](/products/kodo/rs/11-modify-the-file-status) 修改对象的启用/禁用状态，
* 设置对象过期删除，[deleteAfterDays](/products/kodo/rs/9-update-file-lifecycle)

`注意：如果对象大小小于 64 KB，则不会受监控，且不符合自动分层条件。较小的对象始终存储在频繁访问层中。因此小于 64 KB 的文件推荐按需直接上传标准/低频/归档直读/归档/深度归档等存储类型，这样能够降低成本。`

# **使用方法** [#使用方法]

智能分层存储类型是独立存储类型，支持所有对象存储功能。有两种方法可以将数据保存到智能分层存储类型中。

## 1、增量上传对象时设置为智能分层存储 [#1增量上传对象时设置为智能分层存储]

* [上传策略](/products/kodo/development-guidelines/security/1-put-policy) 指定存储类型 为 `fileType` 为 5 ，表示指定为智能分层存储类型。上传成功之后，处在智能分层存储的频繁访问层。
* 设置 [生命周期](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management)，对规则创建或修改后空间内新上传的对象生效。可以根据设置规则，自动转为智能分层存储。

## 2、存量数据转换为智能分层 [#2存量数据转换为智能分层]

* 将存储类型修改为智能分层存储类，[chtype](/products/kodo/rs/9-modify-the-file-storage-type) 修改存储类型；
* 使用生命周期将已存在的数据批量从标准存储或低频存储转换到智能分层存储，该能力处于测试阶段，您需要 [提交工单](https://support.qiniu.com/tickets/new/?ref=developer.qiniu.com\&s_path=%2Fkodo%2F2528%2Fupload-webtest) 申请使用。

# **常见问题** [#常见问题]

1. 智能分层存储如何计费？
   * 智能分层存储包含智能分层存储容量费用和智能分层对象监控费用。其中：
     * 智能分层存储容量费用会根据所处的存储层收取不同的存储费用，具体定价请参见 [产品定价](https://www.qiniu.com/prices/kodo?ref=developer.qiniu.com\&s_path=%2Fkodo%2F6379%2Fmetering-and-billing)
     * 智能分层对象监控费用按存储的文件数来计算，小于 64KB 的文件不收取，具体定价请参见 [产品定价](https://www.qiniu.com/prices/kodo?ref=developer.qiniu.com\&s_path=%2Fkodo%2F6379%2Fmetering-and-billing)
     * 上传和下载文件过程中还会产生请求费用和流量费用，这些费用计算示例请参见 [计费案例](/products/kodo/1-metering-and-billing)

2. 智能分层适用于什么场景？
   * 智能分层存储适用于音视频等平均文件较大，且访问模式不固定的文件。平均文件容量越大，意味着您平均每 GB 文件需要付出的监控费用越少；
   * 如果您的业务访问模式比较固定，则意味着您可以通过生命周期配置好指定时间沉降到低频 / 归档直读 / 归档 / 深度归档等存储类型存储上，而不需要使用智能分层存储；
   * 如果您的文件很小，小于 64 KB的数据，智能分层只能持久存储于频繁访问层中，推荐按需直接上传标准/低频/归档直读/归档/深度归档等存储类型；
   * 数据足够“冷”，或者**两次访问间隔尽可能长**。如果要对数据进行多次读写，建议集中在某窗口内（例如一个月）内集中完成数次读写，然后剩下的时间由智能分层自动的降低存储级别节省费用；

3. 如何验证对象的访问层？
   * 要获取对象及其相应元数据的列表，包括智能分层访问层，您可以使用清单导出。清单导出（该能力处于测试阶段，您需要 [提交工单](https://support.qiniu.com/tickets/new/?ref=developer.qiniu.com\&s_path=%2Fkodo%2F2528%2Fupload-webtest) 申请使用）旨在列出您的对象及其相应元数据的 CSV 输出文件。CSV 内容大致如下，具体情况和您选择的导出字段相关，下图仅供参考：
   * ![截屏2024-08-12 16.13.36.png](/docs-assets/products/kodo/%281-product-introduction%29/kodo-category/0-storage-class-intelligent-tiering/FmEcpTPxCxwO8k8A3oM9IfS8MiXe-0a614905c30e.webp)
   * 其中 tier 字段，表示智能分层存储类型 INTELLIGENT\_TIERING 具体访问层：
     * 频繁访问层， FREQUENT\_ACCESS
     * 不频繁访问层， INFREQUENT\_ACCESS
     * 归档直读访问层， INSTANT\_ACCESS


# 存储类型 (/products/kodo/kodo-category)



最近更新时间: 2026-05-08 17:42:33

七牛云对象存储提供标准、低频、智能分层、归档直读、归档、深度归档六种存储类型，支持多种冷、热数据存储场景，满足客户业务对存储性能、成本的不同诉求。

各存储类型定价信息参见 [七牛云对象存储价格表](https://www.qiniu.com/prices?source=kodo) 。具体的计费方式说明参见 [计量项与计费项](/products/kodo/1-metering-and-billing)

<a id="standard" />

# **标准存储类型** [#标准存储类型]

七牛标准存储 STANDARD 提供高可靠、高可用和高性能的对象存储服务，能够支持频繁的数据读取。标准存储高吞吐和低延时的服务能力，适用于各种类型热点数据的访问场景，包括各种社交图片、分享类的音视频、移动应用以及大数据分析。
关键特性：

* 高吞吐、低延时的访问性能
* 支持对象自动迁移的生命周期管理
* 支持数据的跨区域同步

<a id="IA" />

# **低频存储类型** [#低频存储类型]

七牛低频存储 Infrequent Access（IA）适合长期保存不频繁访问的数据（平均每月访问频率1到2次）。相比于标准存储，低频存储具有相同的数据可靠性、吞吐量和访问时延，可用性略低，但是单价更低、存储成本更优，非常适合不频繁访问（平均一年少于12次）但在需要时也能快速实时访问数据的业务场景，比如网盘存储，各类移动应用、智能设备、企业数据的长期备份，监控数据存储等。低频存储类型的Object有最短存储时间，存储时间短于 30 天的Object提前被删除会产生一定费用。低频存储 Object 有最小计量空间要求，Object 大小不足 64KB ，会按照 64KB计 算存储空间。数据获取会产生数据取回费用。
关键特性：

* 支持数据的实时访问
* 支持对象自动迁移的生命周期管理
* 支持数据的跨区域同步
* 有最短存储时间（30天）和最小计量空间（64KB）的要求

<a id="INT" />

# **智能分层存储类型** [#智能分层存储类型]

七牛智能分层存储 INTELLIGENT TIERING 为数据提供了冷热分层机制，能够根据用户数据的访问模式，自动地转换（需要收取智能分层监控和自动化费用）数据的冷热层级，从而降低用户数据的存储成本。智能分层存储适用于访问模式不固定或者无法预估访问模式的数据，服务端会监控对象的访问情况，存储费用将按照数据实际存储的层级收费（当前支持，频繁访问层、不频繁访问层以及归档直读层）。用户可以按照自身业务需求，将访问模式不固定的数据转换为智能分层存储类型，降低存储成本。

关键特性：

* 随着访问模式的变化，自动优化数据的存储成本
* 支持数据的实时访问
* 支持对象自动迁移的生命周期管理
* 无最短存储时间限制
* 无最小计量空间要求，但是 Object 大小不足 64KB，会一直留在频繁访问层，并不收取智能分层监控费用
* 每月​支付少量的监控和自动分层费用
* 无运营开销、生命周期费用和检索费用

<a id="archive_ir" />

# **归档直读存储类型** [#归档直读存储类型]

七牛归档直读存储 Archive Instant Retrieval（ARCHIVE\_IR）适合长期保存、但需要实时读取的极低频访问的数据（平均一年访问频率少于3次），比如数据湖、云相册、媒体资产归档等数据，归档直读存储能够满足极低频访问数据的实时读取需求，同时兼顾低存储成本与实时访问能力。相比于低频存储，存储单价更低、但是访问成本更高。归档直读存储类型的Object有最短存储时间，存储时间短于60天的Object提前被删除会产生一定费用。归档直读存储Object有最小计量空间要求，Object大小不足64KB，会按照64KB计算存储空间。数据获取会产生数据取回费用。
关键特性：

* 支持数据的实时访问
* 支持对象自动迁移的生命周期管理
* 支持数据的跨区域同步
* 有最短存储时间（60天）和最小计量空间（64KB）的要求

<a id="archive" />

# **归档存储类型** [#归档存储类型]

七牛云归档存储 ARCHIVE 适合需要长期保存、但在存储周期内很少需要被访问的数据存储场景，比如档案数据、医疗影像、科学资料、长期备份数据等。归档数据不支持实时访问，数据进入到可读取状态需要1～5分钟的解冻时间，但是存储安全、持久且成本很低。归档存储类型的Object有最短存储时间，存储时间短于60天的Object提前删除会产生一定费用。归档类型存储Object有最小计量空间要求，Object大小低于64KB，会按照64KB计算存储空间。数据获取会产生数据取回费用。
关键特性：

* 数据解冻为可读取状态需要1～5分钟的等待时间
* 支持对象自动迁移的生命周期管理
* 有最短存储时间（60天）和最小计量空间（64KB）的要求
* 暂时不支持数据的跨区域同步

<a id="deep_archive" />

# **深度归档存储类型** [#深度归档存储类型]

七牛云深度归档存储 DEEP ARCHIVE 单价最低，适合存放需要保留超长时间、但访问非常少的极冷数据，比如因合规要求需要长期留存的数据、大数据等领域长期积累的原始数据、长期留存的媒体资源等；成本比归档存储更低，但数据解冻完成时间更长、需要5～12小时左右。深度归档存储类型的Object有最短存储时间，存储时间短于180天的Object提前删除会产生一定费用。深度归档类型存储Object有最小计量空间要求，Object大小不足64KB，会按照64KB计算存储空间。数据获取会产生数据取回费用。
关键特性：

* 数据解冻为可读取状态需要约5～12小时的等待时间
* 支持对象自动删除的生命周期管理
* 有最短存储时间（180天）和最小计量空间（64KB）的要求
* 暂时不支持数据的跨区域同步

<a id="compare" />

# **存储类型对比** [#存储类型对比]

| 对比项        | 标准存储                       | 低频存储                  | 智能分层存储                                  | 归档直读存储                  | 归档存储                 | 深度归档存储                 |
| ---------- | -------------------------- | --------------------- | --------------------------------------- | ----------------------- | -------------------- | ---------------------- |
| 特性         | 高可靠、高可用和高性能的对象存储服务         | 高可靠、高性能、较低成本的实时访问存储服务 | 高可靠、支持根据访问模式自动节约成本存储服务                  | 高可靠、低成本、支持实时访问的归档数据存储服务 | 低成本的高可靠归档数据存储服务      | 单价最低的高可靠深度归档数据存储服务     |
| 应用场景       | 云应用、数据/内容分析、大数据等热点数据的存储和访问 | 网盘存储、政企数据备份，监控数据存储    | 访问模式未知或不断变化的数据，比如数据湖、数据分析、新应用程序和用户生成的内容 | 数据湖、云相册、媒体资产归档等数据       | 档案数据、医疗影像、视频素材存储     | 合规数据冷归档、媒体资源超长留存       |
| 数据设计可靠性    | 99.999999999%（11个9）        | 99.999999999%（11个9）   | 99.999999999%（11个9）                     | 99.999999999%（11个9）     | 99.999999999%（11个9）  | 99.999999999%（11个9）    |
| SLA承诺服务可用性 | 99.9%                      | 99%                   | 99%                                     | 99%                     | 99%                  | 99%                    |
| 数据访问       | 实时访问ms级延迟                  | 实时访问ms级延迟             | 实时访问ms级延迟                               | 实时访问ms级延迟               | 数据需先解冻才能访问，解冻过程1～5分钟 | 数据需先解冻才能访问，解冻过程约5～12小时 |
| 最短存储时间     | 无要求                        | 30天                   | 无要求                                     | 60天                     | 60天                  | 180天                   |
| 最小计量空间     | 无要求                        | 64KB                  | 无要求                                     | 64KB                    | 64KB                 | 64KB                   |
| 数据取回       | 免费                         | 按实际读取的数据量收费，单位 GB     | 免费                                      | 按实际读取的数据量收费，单位 GB       | 按实际解冻的数据量收费，单位 GB    | 按实际解冻的数据量收费，单位 GB      |

六种存储类型的详细定价请查阅[七牛云对象存储价格表](https://www.qiniu.com/prices?source=kodo)，详细的计量计费说明参见 [计量项与计费项](/products/kodo/1-metering-and-billing)

<a id="compare" />

# **存储类型转换** [#存储类型转换]

客户可以在上传文件的时候，指定文件的存储类型；也可以

* 通过 [生命周期规则](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management) 实现从热到冷、不同存储类型的自动转换;
* 调用 [修改文件存储类型](/products/kodo/rs/9-modify-the-file-storage-type) 接口，变更文件的存储类型。
* 调用 [qshell](/products/kodo/0-qshell)工具，批量列举文件后进行变更文件的存储类型。


# 控制台概览 (/products/kodo/kodo-console-guide/0-an-overview-of-the-console)



最近更新时间: 2024-08-12 15:30:39

对象存储 Kodo 控制台的概览页面简单直观地展示了用户当前所有存储的概况，内容包含该账号下：

* 所有存储空间总数、空间所在的区域分布及对应区域的空间总数；
* 各存储类型对应的存储用量、文件数、API 请求数及流量。

<br />

# **操作步骤** [#操作步骤]

<br />

1. 登录 Kodo 控制台界面进入[概览](http://portal.qiniu.com/kodo/overview)界面
2. 如图1，在概览界面，左侧图表展示了本账号下所有存储空间总量、空间使用的区域及对应区域的空间总数。右侧图表，可在**存储量**查看了本账号下 Top5 存储量的空间及对应用量，切换至**对象数**查看本账号下 Top5 对象数的空间及对应数量。
   图1：
   ![image.png](/docs-assets/products/kodo/%284-development-guidelines%29/kodo-console-guide/0-an-overview-of-the-console/FhqyAkjIVoHO_EcJOWgrCA4eocFI-07f8302c7d80.webp)
3. 如图2，在空间概览界面，您可单击**标准存储/低频存储/智能分层存储/归档直读存储/归档存储/深度归档存储**切换显示不同存储类型，以本账号下所有空间对应选择存储类型的今日和昨日的存储量、文件数，本月和上月的 API 请求次数（GET/PUT）、外网下载流量、CDN 回源流量；
4. 您还可以单击**时间选择键**，选择 7 天、15 天或自选日期以查看对应存储类型的存储量变化。
   图2:
   ![企业微信截图\_5a7f6807-8358-45dd-96d9-760d01d5085a.png](/docs-assets/products/kodo/%284-development-guidelines%29/kodo-console-guide/0-an-overview-of-the-console/FkfHUQ2FRkgZDNBhwNMNv0gH3lOe-9b66530c2b7f.webp)


# 统计分析 (/products/kodo/kodo-console-guide/1-statistical-analysis)



最近更新时间: 2024-08-12 15:26:30

您可以在对象存储 Kodo 控制台统计分析界面查看您账户下所有已使用的资源，包括不同存储类型、区域、空间在自定义时间段（支持 2018-01-01 号及之后的时间）内的：

* 存储量、提前删除量、智能监控文件数、文件数
* 空间流量：流出、流入、CDN 回源
* 空间带宽：流出、流入、CDN 回源
* API 请求：GET、PUT
* 跨区域同步的流量、带宽

<br />

# **操作步骤** [#操作步骤]

1. 登录 Kodo 控制台界面进入[统计分析](https://portal.qiniu.com/kodo/dashboard/storage)界面，展示如图1
   图1:
   ![截屏2021-08-12 下午5.42.46.png](/docs-assets/products/kodo/%284-development-guidelines%29/kodo-console-guide/1-statistical-analysis/FphkqcLRUiLPQ4H_fF3vSg28kpj7-5753195ac844.webp)
2. 如图1，展示了当前标准存储在全部区域全部空间的存储量、文件数，并以图表形式展现了近 7 天中每天的存储量
3. 单击**存储类型**，获取下拉菜单，选择 **标准存储/低频存储/智能分层存储/归档直读存储/归档存储/深度归档存储**，以显示不同存储类型的信息 （外网流入及跨区域同步栏无此分类）
4. 单击**区域**，获取下拉菜单，选择 **全部/华东/华南/华北/北美/东南亚/华东-浙江2**，以显示不同区域对应存储类型的信息（跨区域同步栏默认全部）
5. 单击**空间**，获取下拉菜单，选择 **全部/其他自定义空间名**，以显示对应区域下指定空间内指定存储类型的信息（跨区域同步栏默认全部）
6. 单击 **7天/15天/本月/上月/自选时间区间**，以显示并在图表中查看指定日期区间内的相关信息
7. 单击**导出 CSV**，即可导出对应图表中的数值

<br />

## **查看存储量、文件数** [#查看存储量文件数]

1. 单击 **存储**，如图1
2. 在指定存储类型/区域/空间/时间范围内，单击选择**存储量**（时间单位为天），即查看当前存储量、文件数，及所选时间段内平均存储量、平均文件数和存储量变化图；仅针对**智能分层存储**，提供**频繁访问层**、**不频繁访问层**、**归档直读层**，分层查看存储容量。
3. 仅针对**低频存储**或**归档直读存储**或**归档存储**或**深度归档存储**类型，在指定区域/空间/时间范围内，单击选择**提前删除量**（时间单位为天），即查看所选时间段内累计的提前删除量；
4. 仅针对**智能分层存储**，在指定区域/空间/时间范围内，单击选择&#x2A;*智能监控文件数（时间单位为天）**，即可查看所选时间段内智能分层监控文件数量，小于 64KB 的智能分层对象，不会被监控，一直处于智能分层的频繁访问层；
5. 在指定存储类型/区域/空间/时间范围内，单击选择**上传文件数**（时间单位为天），即查看当日上传文件数，及所选时间段内平均上传文件数和上传文件数变化图。

<br />

## **查看空间流量** [#查看空间流量]

1. 单击 **空间流量**，如图2
   图2:
   ![企业微信截图\_8747b2ab-4ddc-435b-91e0-91ce6938ee54.png](/docs-assets/products/kodo/%284-development-guidelines%29/kodo-console-guide/1-statistical-analysis/FrarDnKkBL1whPhlqBg90C3Lc2kP-3fd62266ef21.webp)
2. 在指定存储类型/区域/空间/时间范围内，单击切换选择**流出/CDN 回源**，单击切换选择计算的时间粒度 **5分钟/小时/天**，即可查看对应的当前累计访问总流量、平均流量和流量最大空间，及所选时间段内各空间累计的访问总流量变化图。
3. 在指定区域/空间/时间范围内，单击选择**流入**，单击切换选择计算的时间粒度 **5分钟/小时/天**，即可查看对应的当前累计访问总流量、平均流量和流量最大空间，及所选时间段内各空间累计的访问总流量变化图。
4. 如开启[传输加速](/products/kodo/development-guidelines/1-transfer-acceleration)，可在**流出/流入**选项之后的**加速用量**栏，单击切换选择计算的时间粒度 **5分钟/小时/天**，即可查看对应的当前累计访问总流量、平均流量，及所选时间段内各空间累计的访问总流量变化图。如图3:
   图3:
   ![企业微信截图\_5ad59427-2e0f-4d96-aaf9-199a4832253d.png](/docs-assets/products/kodo/%284-development-guidelines%29/kodo-console-guide/1-statistical-analysis/FqpZvE30Ahp7N2i4uv__oQHgffJ8-40ed0f90a3df.webp)

<br />

## **查看空间带宽** [#查看空间带宽]

1. 单击 **空间带宽**，如图4
   图4:
   ![截屏2021-08-26 下午2.10.55.png](/docs-assets/products/kodo/%284-development-guidelines%29/kodo-console-guide/1-statistical-analysis/Fo5zypIFEKIaULWjwNu4fYr9hhyM-5ee02c9798f3.webp)
2. 在指定存储类型/区域/空间/时间范围内，单击切换选择**流出/CDN 回源**，单击切换选择计算的时间粒度 **5分钟/天**，即可查看对应当前所选时间段内带宽峰值、出现时间（精确至所选时间粒度）和所属空间，及各空间带宽峰值的变化图（以 95 峰值为基准）。
3. 在指定区域/空间/时间范围内，单击选择**流入**，单击切换选择计算的时间粒度 **5分钟/天**，即可查看对应当前所选时间段内带宽峰值、出现时间（精确至所选时间粒度）和所属空间，及各空间带宽峰值的变化图（以 95 峰值为基准）。
   *注：日带宽数据不支持堆叠展示*

<br />

## **查看API请求** [#查看api请求]

1. 单击 **API 请求**，如图5
   图5:
   ![截屏2021-08-12 下午7.16.55.png](/docs-assets/products/kodo/%284-development-guidelines%29/kodo-console-guide/1-statistical-analysis/Fr0z68AXqjPMfzxZDOB90hWWAqDt-82897dc2bc3a.webp)
2. 在指定存储类型/区域/空间/时间范围内，单击切换选择计算的时间粒度 **5分钟/小时/天**，即可查看对应的当前所选时间段内 GET/PUT 请求总次数和平均次数，及 GET/PUT 请求总次数变化图。

<br />

## **查看跨区域同步** [#查看跨区域同步]

1. 单击 **跨区域同步**，如图6
   图6:
   ![截屏2021-08-12 下午7.23.08.png](/docs-assets/products/kodo/%284-development-guidelines%29/kodo-console-guide/1-statistical-analysis/Fq0g4JnImN9Wft2MYo0CvPsW6Bw-184c978f0d95.webp)
2. 在指定时间范围内，单击选择**流量**，单击切换选择计算的时间粒度 **5分钟/天**，即查看当前所选时间段内全部区域/空间的访问总流量、访问平均流量、和总流量变化图；
3. 在指定时间范围内，单击选择**带宽**，单击切换选择计算的时间粒度 **5分钟/天**，即查看当前所选时间段内国内/海外带宽峰值、出现时间和带宽峰值变化图；


# 设置跨区域同步 (/products/kodo/kodo-console-guide/2-set-the-cross-regional-synchronization)



最近更新时间: 2026-07-28 17:23:38

对象存储 Kodo 支持跨区域同步功能，将跨不同区域的存储空间（Bucket）之间自动、异步复制文件（Object），并将源存储空间的对象的改动（除删除操作）复制到不同区域的目标存储空间。

您可直接通过控制台设置跨区域同步任务，以保障您的业务需求。

<br />

# **跨境数据传输合规提示** [#跨境数据传输合规提示]

七牛云 Kodo 提醒您，在使用相关功能前，请自行确认相关数据来源、内容及处理行为的合法合规性，包括但不限于遵守适用的个人信息保护、数据安全及数据跨境传输等法律法规、监管政策要求。您应确保对相关数据具有合法、充分的处理及处置权限，并已取得必要授权；采取必要、合理的数据安全保护措施；并确保相关数据跨境传输或其他数据处理行为符合适用法律法规及监管政策要求。

如您违反上述声明与保证开展相关数据处理或数据跨境传输活动，由此产生的一切法律责任均由您自行承担；如因此给七牛云造成任何损失的，您还应承担相应的赔偿责任。

<br />

# **说明** [#说明]

* 目前支持华东-浙江、华东-浙江2、华北-河北、华南-广东、北美-洛杉矶、亚太-新加坡存储区域的跨区域同步。
* 目前支持将指定空间的所有数据（暂不支持归档、深度归档存储类型），包括新增、更新操作（暂不支持删除操作）同步到另一个区域的目标空间。
* 在创建跨区域同步任务时，您可以选择是否将源存储空间的历史数据复制至目标存储空间。
* 源空间中的数据可以跨区域同步到多个目标空间。源空间可以在新的任务规则中被指定为目标空间，反之，目标空间也可以在新的任务规则中被指定为源空间。
* 更多关于跨区域同步的详情，请参考[跨区域同步](/products/kodo/development-guidelines/management-of-storage-space/10-dev-cross-regional-synchronization)。
* 使用限制：
  * 同步任务的目标存储空间被删除后，源存储空间中新产生的文件改动，将不再被同步。
* 费用说明：计费详情请参考[七牛云官网价格](https://www.qiniu.com/prices/kodo)
  * 跨区域同步功能会产生存储量、流量和请求次数的费用。
  * 文件同步后会在源空间和目标空间分别产生一份存储量费用。
  * 跨区域同步产生的请求次数合并计入各存储类型的 PUT／DELETE 请求 和 GET 请求次数中，共享用户请求次数的免费额度，超出部分将按照七牛云官网价格中的 PUT／DELETE 请求 和 GET 请求单价进行计费。

<br />

# **操作步骤** [#操作步骤]

1. 登录 Kodo 控制台界面进入[跨区域同步](https://portal.qiniu.com/kodo/transfer)界面，展示如图1跨区域同步-同步任务列表，
   图1:跨区域同步-同步任务列表
   ![image.png](/docs-assets/products/kodo/%284-development-guidelines%29/kodo-console-guide/2-set-the-cross-regional-synchronization/Fone3bdWAfJ-Ir6cT7XcKeB09s-N-b049797280ac.webp&#x29;2. 单击 **+创建任务**，右侧将弹出如图2:创建任务界面如
   图2: 创建任务
   ![image.png](/docs-assets/products/kodo/%284-development-guidelines%29/kodo-console-guide/2-set-the-cross-regional-synchronization/FhHrcvRTZz33gn_D6MIIhJY2Kv6U-f191cd66aac1.webp)
2. 在创建任务界面，按如下说明配置各项参数：
   | 操作名称     | 说明                  | 规则描述                                                                    |
   | -------- | ------------------- | ----------------------------------------------------------------------- |
   | 同步任务名称   | 请自定义当前同步任务的名称       | - 字母开头，4 \~ 63 个字符长 ，可包含 字母、数字、中划线<br /> - 不可重复命名                       |
   | 源存储区域    | 请按需选择需要同步的源存储空间所在区域 | - 可选区域：华东-浙江、华东-浙江2、华北-河北、华南-广东、北美-洛杉矶、亚太-新加坡 <br /> - 不支持相同区域的空间内容同步   |
   | 源存储空间    | 请按需选择需要同步的源存储空间     | - 选择下拉列表中已存在的空间                                                         |
   | 目标存储区域   | 请按需选择目标存储空间所在区域     | - 可选区域：华东-浙江、华东-浙江2、华北-河北、华南-广东、北美-洛杉矶、亚太-新加坡 <br /> - 不支持相同区域的空间内容同步   |
   | 目标存储空间   | 请按需选择目标存储空间         | - 如果目标存储空间为非空存储空间，在 Key 相同的情况下，文件会被覆盖。                                  |
   | 同步范围     | 请按需选择同步范围           | - 默认选择同步空间内所有文件<br />- 支持同步指定前缀的文件                                      |
   | 是否同步历史数据 | 请按需选择开启/关闭是否同步历史数据  | - 若开启，会将源存储空间的数据同步到目标存储空间。<br /> - 若关闭，同步任务开启后，仅同步开启该功能时间点后的数据，历史数据不同步。 |
3. 单击**确定**，完成创建跨域同步任务。
4. 新建同步任务成功后，您可在如图1：跨区域同步-同步任务列表，单击目标任务栏的**查看**，即可查看该同步任务的详情信息，如图3。
   图3:任务详情
   ![image.png](/docs-assets/products/kodo/%284-development-guidelines%29/kodo-console-guide/2-set-the-cross-regional-synchronization/Ft72sAdwPVZARsajQI1fLuJPPSe8-b6ab50ad09ad.webp)
5. 如图1，您可单击目标任务栏的**暂停/开始**，暂停或重启该任务。
6. 如图1，您可单击目标任务栏的**删除**，删除该任务。


# 控制台指南 (/products/kodo/kodo-console-guide)



最近更新时间: 2024-05-08 18:08:26

对象存储 Kodo 控制台是界面形式的 Web 应用程序，给您提供直观、简单使用的操作平台。通过 Kodo 控制台您可以对您的存储空间、文件等执行相关操作。

您将在本操作指南中，了解以下内容：

| 控制台操作                                                                                 | 子操作                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [控制台概览](/products/kodo/kodo-console-guide/0-an-overview-of-the-console)               |                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [空间管理](/products/kodo/kodo-console-guide/bucket-management)                           | <br />- 新建空间<br />-  空间列表管理<br />- 空间概览   <br />- 空间设置 <br />- 设置访问控制<br />- 设置静态页面<br />- 设置空间备注<br />- 设置文件客户端缓存<br />- 设置重定向<br />- 设置标签管理<br />- 设置空间授权<br />- 设置Referer防盗链<br />- 设置跨域资源共享<br />- 设置生命周期<br />- 设置事件通知<br />- 设置镜像回源<br />- 设置对象锁定<br />- 设置空间日志<br />- 设置空间内容审核<br />- 删除存储空间 <br />- 域名管理  <br />- 设置自定义 CDN 加速域名 <br />- 设置自定义源站域名     <br />- 数据处理  <br />- 图片样式 <br />- 转码样式 <br />- 设置原图保护 |
| [文件管理](/products/kodo/kodo-console-guide/file-management)                             | <br />- 上传文件<br />- 创建目录<br />- 搜索文件<br />- 修改文件名<br />- 修改文件类型<br />- 查看文件信息<br />- 设置文件元信息<br />- 下载文件<br />- 分享文件<br />- 刷新 CDN 缓存<br />- 移动文件<br />- 删除文件<br />- 删除目录<br />- 修改文件存储类型<br />- 解冻文件<br />- 任务中心                                                                                                                                                                                                     |
| [设置跨区域同步](/products/kodo/kodo-console-guide/2-set-the-cross-regional-synchronization) |                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [统计分析](/products/kodo/kodo-console-guide/1-statistical-analysis)                      |                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [存储安全](/products/kodo/kodo-console-guide/object-storage-safety)                       | <br />- 内容审核<br />- 违规列表                                                                                                                                                                                                                                                                                                                                                                                              |
| [设置数据迁移](/products/kodo/kodo-console-guide/set-data-migration)                        |                                                                                                                                                                                                                                                                                                                                                                                                                       |

<br />

另外，您可以按需参考关于对象存储 Kodo 产品的部分文档：

| 参见文档                                          | 说明                     |
| --------------------------------------------- | ---------------------- |
| [产品简介](/faq/kodo)                             | 功能介绍和应用场景              |
| [购买指南](/products/kodo/1-metering-and-billing) | 详细的计费和购买类信息            |
| [快速入门](/products/kodo/0-console-quickstart)   | 简单快速的入门知识              |
| [开发指南](/products/kodo/development-guidelines) | 更详细的概念、功能、原理介绍和可用工具等信息 |


# 附录 (/products/kodo/development-guidelines/0-appendix)



最近更新时间: 2026-08-21 14:37:20

<a id="domain-binding" />

# 域名绑定 [#域名绑定]

每个空间都可以绑定一个到多个自定义域名，以便于更方便的访问资源。

例如`www.qiniu.com`的所有静态资源均存放于一个叫`qiniu-resources`的公开空间中。并将该空间绑定到一个二级域名`i1.qiniu.com`，那么如果要在一个HTML页面中引用该空间的`logo.png`资源，大概的写法如下：

```
<img source="http://i1.qiniu.com/logo.png"></img>
```

这样一定程度上隐藏了正在使用<span id="Productname">七牛云存储</span>的事实，更大的好处是如果需要从一个云存储迁移到另一个云存储，只需要修改域名DNS的CNAME设置，而无需更新网页源代码。

<a id="urlsafe-base64" />

# URL安全的Base64编码 [#url安全的base64编码]

URL安全的Base64编码适用于以URL方式传递Base64编码结果的场景。该编码方式的基本过程是先将内容以Base64格式编码为字符串，然后检查该结果字符串，将字符串中的加号`+`换成中划线`-`，并且将斜杠`/`换成下划线`_`。

详细编码规范请参考[RFC4648](http://www.ietf.org/rfc/rfc4648.txt)标准中的相关描述。


# 传输加速 (/products/kodo/development-guidelines/1-transfer-acceleration)



最近更新时间: 2026-08-21 14:37:20

如果您希望实现远距离数据传输加速，例如从非中国内地向中国内地的空间请求上传或下载文件，您可以开启传输加速。传输加速利用全球分布的云机房，将全球各地用户对您存储空间的访问，经过智能路由解析至就近的接入点，使用优化后的网络及协议，为云存储互联网的上传、下载提供端到端的加速方案。

# **具体说明** [#具体说明]

* 当前七牛云存储传输加速，仅支持上传链路加速。您可以开启传输加速，使用七牛云提供的传输加速域名做上传，可以为互联网的上传提供端到端的加速效果。通过传输加速域名上传数据时，会产生加速上传流量。更多信息，请参见 [计量项与计费项](/products/kodo/1-metering-and-billing)。
* 访问域名。开启传输加速后，您可以通过两种域名访问您空间的文件：
  * **默认源站上传域名**，格式如 `up-*.qiniup.com` ，详情见 [存储区域](/products/kodo/2-region-endpoint-fq)，可以指定 HTTP / HTTPS 传输协议。通过该域名上传对象时，您的请求会被直接转发至七牛云对应区域存储机房，如果外网链路长，可能存在传输不稳定的情况；通过该域名上传对象时，不需要收取上传流量费用。
  * **空间级别传输加速域名**，格式如 `*.kodo-accelerate.*.qiniucs.com`，可以指定 HTTP / HTTPS 传输协议。通过该域名上传对象时，会根据网络状况为您智能解析并就近接入，使用优化后的网络及协议，实现加速的效果。通过该域名上传对象时，会产生加速上传流量。
* 使用限制：亚太-河内、亚太-胡志明 区域暂不支持启用空间级别传输加速域名

<br />

# **使用案例** [#使用案例]

* 跨境数据传输需求
  您的业务场景要求是将文件上传至国内华东-浙江区域，终端对传输成功率要求极高，海量全球分布终端用户每天需要从世界各地，比如新加坡和美国，上传数据到华东-浙江；
* 大文件传输加速需求
  您的业务场景要求是将音视频文件、高清图片、压缩包等快速高效的上传，需要从办公室每天上传 GB 级别大小的文件上至国内华东-浙江区域

<br />

# **操作方式** [#操作方式]

Kodo 支持使用通过控制台开启或关闭传输加速。

| 支持的操作方式 | 参考文档                                                                                                      |
| ------- | --------------------------------------------------------------------------------------------------------- |
| 控制台     | [设置传输加速](/products/kodo/kodo-console-guide/bucket-management/space-settings/16-set-transfer-acceleration) |

<br />

# **使用方式** [#使用方式]

Kodo 支持通过 SDK 、命令行工具、图形化管理工具等使用加速域名。

| 支持的使用入口 | 具体使用方式                     | 详细参考文档                                                                                                                                                                                                                                                                                                      |
| ------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 控制台     | 上传时指定使用传输加速域名              | 开启传输加速后，即可通过控制台在上传文件时按需选择加速域名上传，参考[上传文件](/products/kodo/kodo-console-guide/file-management/0-upload-a-file)                                                                                                                                                                                                 |
| SDK     | 指定传输加速域名                   | 下述 SDK 现已支持，可参考各 SDK 使用文档: [Android SDK](/products/kodo/android#4)、[Go SDK](/products/kodo/go#upload-transfer-acceleration)、[Node.js SDK](/products/kodo/nodejs#upload-transfer-acceleration)、[Objective C SDK](/products/kodo/1-objc#4)、[Python SDK](/products/kodo/2-python#upload-transfer-acceleration) |
| 命令行工具   | 配置文件指定传输加速域名或者上传命令指定传输加速域名 | [Qshell 使用文档](/products/kodo/0-qshell)，比如`fput`的上传命令指定参数 `--up-host`，指定上传域名为传输加速域名                                                                                                                                                                                                                          |
| 图形化管理工具 | 配置文件指定传输加速域名               | 开启传输加速后，即可在上传文件时按需选择加速域名上传，参考[上传文件](/products/kodo/1-kodo-browser#3)                                                                                                                                                                                                                                        |

<br />

# **测试传输加速效果** [#测试传输加速效果]

* 您可以通过 [上传测速工具](/products/kodo/diagnostic-tools/0-upload-webtest) 测试对比您本地访问七牛存储全球各地数据中心时，开启传输加速与未开启传输加速的访问速度；
* 通过在 Qshell 命令对比测试使用默认源站上传域名和传输加速域名上传文件所需时间以及访问速度；
  ![1.png](/docs-assets/products/kodo/%284-development-guidelines%29/development-guidelines/1-transfer-acceleration/Fu2AhAGWi3YG4SHLP7aLmMZFAJNZ-6d8018ef16cb.webp)


# 开发指南 (/products/kodo/development-guidelines)



最近更新时间: 2022-11-08 12:11:01

本开发指南将引导您理解和使用对象存储 Kodo。
您将在本开发指南中，了解以下内容：

| 开发操作                                                                                | 子操作                                                                                                                                                                                                                 |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [安全机制](/products/kodo/development-guidelines/security)                              | <br />- 上传策略 <br />- 上传凭证 <br />- 下载凭证 <br />- 管理凭证<br />- 管理凭证历史文档                                                                                                                                                 |
| [上传资源](/products/kodo/development-guidelines/upload-types)                          | <br />- 表单上传<br />- 分片上传 v1<br />- 分片上传 v2<br />- 简单反馈<br />- 回调通知<br />- 303 重定向<br />- 异步数据预处理<br />- 自定义响应内容<br />- 变量                                                                                           |
| [下载资源](/products/kodo/development-guidelines/download-process)                      | <br />- 公开资源下载<br />- 私有资源下载<br />- 下载设置<br />- 高级下载                                                                                                                                                                |
| [管理存储空间](/products/kodo/development-guidelines/management-of-storage-space)         | <br />- 绑定源站域名 <br />- 访问控制 <br />- 静态页面管理<br />- 空间备注 <br />- 文件客户端缓存<br />- 重定向 <br />- 空间授权 <br />- 空间标签 <br />- 跨域资源共享 <br />- 生命周期管理 <br />- 事件通知 <br />- 设置镜像回源 <br />- 设置跨区域同步 <br />- 空间访问日志 <br />- 删除存储空间 |
| [数据安全](/products/kodo/development-guidelines/dev-data-security)                     | <br />- Referer 防盗链 <br />- 对象锁定                                                                                                                                                                                    |
| [数据处理](/products/kodo/development-guidelines/dev-the-data-processing)               | <br />- 图片样式 <br />- 转码样式 <br />- 设置原图保护                                                                                                                                                                            |
| [AWS S3 兼容](/products/kodo/development-guidelines/aws-s3-compatible/3-storage-type) | <br />- 存储类型<br />- 服务域名<br />- 签名认证<br />- 临时安全凭证<br />- 兼容公共头<br />- 兼容 API<br />- 使用 Bucket Policy 授权 <br />- 兼容工具示例                                                                                             |
| [附录](/products/kodo/development-guidelines/0-appendix)                              |                                                                                                                                                                                                                     |


# space (/products/kodo/statistic-interface/3908-statistic-space)



最近更新时间: 2026-08-19 15:14:58

<a id="space-description" />

# **描述** [#描述]

该接口可以获取标准存储的当前存储量。可查询当天计量，统计延迟大概 5 分钟。

<br />

<a id="space-requests" />

# **请求** [#请求]

<br />

<a id="space-requests-syntax" />

### **语法** [#语法]

```
GET /v6/space?begin=<BeginTime>&end=<EndTime>&g=day HTTP/1.1
Host: api.qiniuapi.com
Content-Type:application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

<br />

<a id="space-request-parameters" />

### **请求参数** [#请求参数]

| 参数名称   | 必填 | 说明                                                               |
| ------ | -- | ---------------------------------------------------------------- |
| bucket | 否  | 存储空间名称，是一个条件请求参数                                                 |
| begin  | 是  | 起始日期字符串，闭区间，例如： 20060102150405                                   |
| end    | 是  | 结束日期字符串，开区间，例如： 20060102150405                                   |
| g      | 是  | 时间粒度，支持 `day`；当天支持`5min`、`hour`、`day`                            |
| region | 否  | 存储区域 ID, 七牛对象存储支持的 [存储区域列表](/products/kodo/2-region-endpoint-fq) |

<br />

<a id="space-request-headers" />

### **请求头** [#请求头]

该请求操作的实现使用了所有操作的公共请求头。有关详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

<br />

<a id="space-responses" />

# **响应** [#响应]

<br />

<a id="space-response-headers" />

### **响应头** [#响应头]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

<br />

<a id="space-response-elements" />

### **响应元素** [#响应元素]

| 名称    | 说明                              |
| ----- | ------------------------------- |
| times | Unix 时间戳，单位为秒<br /><br /> 类型：数组 |
| datas | 存储量大小，单位为 Byte\<br><br /> 类型：数组 |

<br />

<a id="space-special-errors" />

### **特殊错误** [#特殊错误]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误响应](/products/kodo/3928-error-responses)。

<br />

<a id="space-examples" />

# **示例** [#示例]

<br />

<a id="space-request-examples" />

### **请求示例** [#请求示例]

```
GET /v6/space?bucket=test07&region=z0&begin=20170818140000&end=20170818150000&g=day HTTP/1.1
Host: api.qiniuapi.com
User-Agent: Go-http-client/1.1
Content-Type:application/x-www-form-urlencoded
X-Qiniu-Date: 20170818T064943Z
Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:XSOBjcnxSaffg04WlT8PKgDjMFw=
Accept-Encoding: gzip
```

<br />

<a id="space-response-examples" />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Content-Length: 40
Connection: keep-alive
Content-Type: application/json
Date: Fri, 18 Aug 2017 06:49:43 GMT
Server: nginx
X-Log: COUNTER;CT:2;S:5;STAT:5;MERGEAPI:6;MERGEAPI:6;APIS:11
X-Reqid: xxwAAGenzgz-3dsU

{
  "times": [
    1502985600
  ],
  "datas": [
    7772448
  ]
}
```


# count (/products/kodo/statistic-interface/3914-count)



最近更新时间: 2026-08-19 15:14:43

<a id="count-description" />

# **描述** [#描述]

该接口可以获取标准存储的文件数量。可查询当天计量，统计延迟大概 5 分钟。

<br />

<a id="count-requests" />

# **请求** [#请求]

<br />

<a id="count-requests-syntax" />

### **语法** [#语法]

```
GET /v6/count?begin=<BeginTime>&end=<EndTime>&g=day HTTP/1.1
Host: api.qiniuapi.com
Content-Type:application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

<br />

<a id="count-request-parameters" />

### **请求参数** [#请求参数]

| 参数名称   | 必填 | 说明                                                               |
| ------ | -- | ---------------------------------------------------------------- |
| bucket | 否  | 存储空间名称                                                           |
| begin  | 是  | 起始日期字符串，格式为 20060102150405，闭区间                                   |
| end    | 是  | 结束日期字符串，格式为 20060102150405，开区间                                   |
| g      | 是  | 时间粒度，支持`day`；当天支持`5min`、`hour`、`day`                             |
| region | 否  | 存储区域 ID, 七牛对象存储支持的 [存储区域列表](/products/kodo/2-region-endpoint-fq) |

<br />

<a id="count-request-headers" />

### **请求头** [#请求头]

该请求操作的实现使用了所有操作的公共请求头。有关详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

<br />

<a id="count-responses" />

# **响应** [#响应]

<br />

<a id="count-response-headers" />

### **响应头** [#响应头]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

<br />

<a id="count-response-elements" />

### **响应元素** [#响应元素]

| 名称    | 说明                              |
| ----- | ------------------------------- |
| times | Unix 时间戳，单位为秒<br /><br /> 类型：数组 |
| datas | 文件数量大小，单位为个<br /><br /> 类型：数组   |

<br />

<a id="count-special-errors" />

### **特殊错误** [#特殊错误]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误响应](/products/kodo/3928-error-responses)。

<br />

<a id="count-examples" />

# **示例** [#示例]

<br />

<a id="count-request-examples" />

### **请求示例** [#请求示例]

```
GET /v6/count?bucket=test07&begin=20170818140000&end=20170818151000&g=day HTTP/1.1
Host: api.qiniuapi.com
User-Agent: Go-http-client/1.1
Content-Type:application/x-www-form-urlencoded
X-Qiniu-Date: 20170818T071102Z
Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:Zm5BbTRF8h6tpv9ZADAPOBPYmbg=
Accept-Encoding: gzip
```

<br />

<a id="count-response-examples" />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Content-Length: 34
Connection: keep-alive
Content-Type: application/json
Date: Fri, 18 Aug 2017 07:11:02 GMT
Server: nginx
X-Log: COUNTER;CT:2;S:4;STAT:4;MERGEAPI:5;S:1;STAT:1;APIS:2;COUNTER;CT:48;S:3;STAT:3;APIS:4;S:132;STAT:132;MERGEAPI:133;COUNTER:1;CT:34;S:36;STAT:36;MERGEAPI:38;COUNTER;CT:505;S:507;STAT:507;MERGEAPI:509;MERGEAPI:686;APIS:1695
X-Reqid: xxwAAPFkzXMn39sU

{
  "times": [
    1502985600
  ],
  "datas": [
    2
  ]
}
```


# 批量操作 (/products/kodo/rs/0-batch)



最近更新时间: 2022-06-10 12:01:53

## 描述 [#描述]

本接口用于执行批量操作。\
批量操作意指在单一请求中执行多次（最大限制1000次） [查询元信息](/products/kodo/rs/7-stat) 、 [修改元信息](/products/kodo/rs/1-chgm) 、 [移动](/products/kodo/rs/5-move) 、 [复制](/products/kodo/rs/2-copy) 、 [删除](/products/kodo/rs/3-delete) 、 [修改状态](/products/kodo/rs/11-modify-the-file-status) 、 [修改存储类型](/products/kodo/2-chtype-billing-item-changes) 、 [修改生命周期](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management) 和 [解冻](/products/kodo/rs/12-restore-archive) 操作，极大提高资源管理效率。 其中，解冻操作仅针对归档/深度归档存储文件有效。

## 请求 [#请求]

### 请求语法 [#请求语法]

```
POST /batch HTTP/1.1
Host:           rs.qiniuapi.com
Content-Type:   application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>

op=<Operation>&op=<Operation>&...
```

使用说明：

* 要在 Authorization 头部的 `&lt;AccessToken&gt;` 前添加 Qiniu 和半角空格。
* `op=&lt;Operation&gt;` 是单一文件管理指令（如： `/stat/&lt;EncodeEntryURI&gt;` ， `/delete/&lt;EncodeEntryURI&gt;` 等）。

### 请求参数 [#请求参数]

将根据具体 `op=&lt;Operation&gt;` 文件管理指令，使用相应参数。\
常用参数 `EncodeEntryURI` 、 `EncodedEntryURISrc` 与 `EncodedEntryURIDest` 经过 Base64 编码，具体请参考 请参考 [EncodedEntryURI](/products/kodo/0-data-format) 。

### 请求头 [#请求头]

| 头部名称          | 必填 | 说明                                                                                                                                                                   |
| ------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type  | 是  | 固定为 application/x-www-form-urlencoded                                                                                                                                |
| Authorization | 是  | 该参数应严格按照 [管理凭证](/products/kodo/development-guidelines/security/access-token) 格式进行填充，否则会返回 401 错误码  一个合法的 Authorization 值应类似于： `Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他            |    | 请查阅 [公共请求头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header)                                                                          |

### 请求内容 [#请求内容]

```
#批量获取元信息
op=/stat/<EncodedEntryURI>&op=/stat/<EncodedEntryURI>&...

#批量复制资源
op=/copy/<EncodedEntryURISrc>/<EncodedEntryURIDest>&op=/copy/<EncodedEntryURISrc>/<EncodedEntryURIDest>&.../force/<true|false> 

#批量移动资源
op=/move/<EncodedEntryURISrc>/<EncodedEntryURIDest>&op=/move/<EncodedEntryURISrc>/<EncodedEntryURIDest>&.../force/<true|false> 

#批量删除资源
op=/delete/<EncodedEntryURI>&op=/delete/<EncodedEntryURI>&...
    
#批量解冻资源
op=/restoreAr/<EncodedEntryURI>/freezeAfterDays/<FreezeAfterDays>&...

#批量修改元信息
……
#批量修改存储类型
……
#批量修改状态
……
#批量修改生命周期
……

#混合多种操作
op=/stat/<EncodedEntryURI>&op=/copy/<EncodedEntryURISrc>/<EncodedEntryURIDest>/force/<true|false>&op=/move/<EncodedEntryURISrc>/<EncodedEntryURIDest>/force/<true|false> &op=/delete/<EncodedEntryURI>&op=/restoreAr/<EncodedEntryURI>/freezeAfterDays/<FreezeAfterDays>&...
```

*注：copy 和 move 操作需为每个文件指定force参数。*

## 响应 [#响应]

### 响应语法 [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
```

### 响应头 [#响应头]

| 头部名称         | 必填 | 说明                                                                                                        |
| ------------ | -- | --------------------------------------------------------------------------------------------------------- |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json` ，表示返回 JSON 格式的文本信息。                                                        |
| 其他           |    | 其它可能返回的头部信息，请参考 [公共响应头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header) 。 |

### 响应内容 [#响应内容]

```
#批量获取元信息
[
    { "code": <HttpCode int>, "data": <Data> },
    { "code": <HttpCode int>, "data": <Data> },
    { "code": <HttpCode int>, "data": { "error": "<ErrorMessage string>" } },
    ...
]

#批量复制资源
[
    { "code": <HttpCode int> },
    { "code": <HttpCode int> },
    { "code": <HttpCode int>, "data": { "error": "<ErrorMessage string>" } },
    ...
]

#批量移动资源
[
    { "code": <HttpCode int> },
    { "code": <HttpCode int> },
    { "code": <HttpCode int>, "data": { "error": "<ErrorMessage string>" } },
    ...
]

#批量删除资源
[
    { "code": <HttpCode int> },
    { "code": <HttpCode int> },
    { "code": <HttpCode int>, "data": { "error": "<ErrorMessage string>" } },
    ...
]
    
#批量解冻资源
[
    { "code": <HttpCode int> },
    { "code": <HttpCode int> },
    { "code": <HttpCode int>, "data": { "error": "<ErrorMessage string>" } },
    ...
]

#混合多种操作
[
    { "code": <HttpCode int>, "data": <Data> },
    { "code": <HttpCode int> },
    { "code": <HttpCode int> },
    { "code": <HttpCode int> },
    { "code": <HttpCode int>, "data": { "error": "<ErrorMessage string>" } },
    ...
]
```

### 响应状态码 [#响应状态码]

| HTTP状态码 | 含义                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 200     | 所有请求操作都已成功完成                                                                                                                         |
| 298     | 部分或所有请求操作失败（出错信息参看上述响应内容）                                                                                                            |
| 400     | 请求报文格式错误                                                                                                                             |
| 401     | 管理凭证无效                                                                                                                               |
| 403     | 禁止操作   当非归档/深度归档存储类型 Object 调用此接口指定 op=restoreAr 时，返回 `403 Fobbiden {"error": "operation only allowed for archive or deep archive"}` |
| 599     | 服务端操作失败                                                                                                                              |
| 其他错误码   | 请查阅 [错误响应](/products/kodo/development-guidelines/upload-types/3-simple-response)                                                     |

如遇 599 错误，请将完整错误信息（包括所有 HTTP 响应头部） [提交工单](https://support.qiniu.com/tickets/category) 给我们。


# 资源元信息修改 (/products/kodo/rs/1-chgm)



最近更新时间: 2025-12-16 16:02:14

## 描述 [#描述]

本接口用于修改文件的 MIME 类型信息。

## 请求 [#请求]

### 请求语法 [#请求语法]

```
POST /chgm/<EncodedEntryURI>/mime/<EncodedMimeType>/x-qn-meta-<meta_key>/<EncodedMetaValue>/cacheControl/<EncodedCacheControl>/contentDisposition/<EncodedContentDisposition>/contentLanguage/<EncodedContentLanguage>/contentEncoding/<EncodedContentEncoding>/expires/<EncodedExpires>/cond/<Encodedcond> HTTP/1.1
Host:           rs.qiniuapi.com
Content-Type:   application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

使用说明：

* 归档/深度归档存储文件，只有解冻状态时可以修改 MIME 类型信息

### 请求参数 [#请求参数]

| 参数名称                      | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| EncodedEntryURI           | 是  | 指定文件信息，具体请参考 [EncodedEntryURI](/products/kodo/0-data-format)                                                                                                                                                                                                                                                                                       |
| EncodedMimeType           | 否  | 自定义新的 mimeType，需要经过 Base64 编码，具体请参考 [EncodedEntryURI](/products/kodo/0-data-format)   `mimetype` 命名规则：   - 支持包括如下字符集： `a-z`, `A-Z`, `0-9`, `.`, `+`, `/`, `-`, `;`, `=`, `,`, `_` 和空格   - 最大长度为 200 字节   - `mimetype` 为空这里认为合法，因为如果为空后面会进一步检测并设置   - `mimetype` 可以包括空格，例如： `text/plain`; `charset=iso-8859-1`   - 禁止转义，如 `%0A` 表示 `\n` ，所以禁止出现 `%` |
| meta\_key                 | 否  | 自定义新的 meta\_key   命名规则：   - 支持字母、数字、下划线、减号组成   - 最大长度限制 50 字节   - 单个文件 meta\_key 和 metaValue 总和大小不能超过 1024 字节   - 可以同时修改多个 meta 字段                                                                                                                                                                                                                 |
| EncodedMetaValue          | 否  | 自定义元数据信息，需要经过 Base64 编码，具体请参考 [EncodedEntryURI](/products/kodo/0-data-format)   命名规则：   - metaValue 规则和 mimeType 相同   - 单个文件 meta\_key 和 metaValue 总和大小不能超过 1024 字节   - 可以同时修改多个 meta 字段                                                                                                                                                           |
| Encodedcond               | 否  | 自定义条件信息，需要经过 Base64 编码，具体请参考 [EncodedEntryURI](/products/kodo/0-data-format)   当前支持设置 hash、mime、fsize、putTime 条件，只有条件匹配才会执行修改操作   cond 支持 condKey1=condVal1\&condKey2=condVal2 格式                                                                                                                                                                  |
| EncodedCacheControl       | 否  | 指定文件下载时的缓存行为。详见 [Cache-Control](https://www.rfc-editor.org/rfc/rfc9111#section-5.2)                                                                                                                                                                                                                                                                |
| EncodedContentLanguage    | 否  | 描述文件所用的语言                                                                                                                                                                                                                                                                                                                                          |
| EncodedContentEncoding    | 否  | 声明文件的编码方式。必须按照文件的实际编码类型填写，否则可能造成客户端解析失败或下载失败。若文件未编码，请置空此项。详见 [Content-Encoding](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-encoding)                                                                                                                                                                                                |
| EncodedContentDisposition | 否  | 指定文件的展示形式。详见 [Content-Disposition](https://www.rfc-editor.org/rfc/rfc6266#section-4)                                                                                                                                                                                                                                                               |
| EncodedExpires            | 否  | RFC2616 中定义的缓存失效时间。详见 [Expires](https://www.rfc-editor.org/rfc/rfc7234#section-5.3)                                                                                                                                                                                                                                                                |

### 请求头 [#请求头]

| 头部名称            | 必填 | 说明                                                                                                                                                               |
| --------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | 是  | 该参数应严格按照 [管理凭证](/products/kodo/development-guidelines/security/access-token) 格式进行填充，否则会返回401错误码  一个合法的Authorization值应类似于： `Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他有关详细信息        |    | 请查阅 [公共请求头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header)                                                                      |

### 请求内容 [#请求内容]

该请求操作的请求体为空。

## 响应 [#响应]

### 响应语法 [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
```

### 响应头 [#响应头]

| 头部名称         | 必填 | 说明                                                                                                        |
| ------------ | -- | --------------------------------------------------------------------------------------------------------- |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json` ，表示返回 JSON 格式的文本信息。                                                        |
| 其他           |    | 其它可能返回的头部信息，请参考 [公共响应头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header) 。 |

### 响应内容 [#响应内容]

如果请求成功，不返回任何内容。\
如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "error":   "<errMsg    string>",
}
```

| 字段名称  | 必填 | 说明                |
| ----- | -- | ----------------- |
| error | 是  | 与 HTTP 状态码对应的消息文本 |

### 响应状态码 [#响应状态码]

| HTTP状态码 | 含义                                                                                                                                                                                                                                                                      |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200     | 更改成功                                                                                                                                                                                                                                                                    |
| 400     | 请求报文格式错误   当 `&lt;EncodedEntryURI&gt;` 解析失败，返回 `400 Bad Request {"error":"invalid argument"}`   当 `&lt;EncodedEntryURI&gt;` 不符合UTF-8编码，返回 `400 Bad Request {"error":"key must be utf8 encoding"}`   当 `mimeType` 不合法时，返回 `400 Bad Request {"error":"Invalid mimeType"}` |
| 401     | 管理凭证无效                                                                                                                                                                                                                                                                  |
| 403     | 禁止操作   当归档存储文件未解冻完成调用接口会返回 `403 ArchiveUnrestored {"error":"archive unrestored"}`   当深度归档存储文件未解冻完成调用接口会返回 `403 DeepArchiveUnrestored {"error":"deep archive unrestored"}`                                                                                               |
| 612     | 目标资源不存在                                                                                                                                                                                                                                                                 |
| 613     | 当 `cond` 条件不满足时，返回 `613 {"error": "cond not match"}`                                                                                                                                                                                                                    |
| 599     | 服务端操作失败                                                                                                                                                                                                                                                                 |
| 其他错误码   | 请查阅 [错误响应](/products/kodo/development-guidelines/upload-types/3-simple-response)                                                                                                                                                                                        |

如遇 599 错误，请将完整错误信息（包括所有 HTTP 响应头部） [提交工单](https://support.qiniu.com/tickets/category) 给我们。

## 示例 [#示例]

### 请求示例 [#请求示例]

```
POST /chgm/YnVja2V0OmtleQ==/x-qn-meta-meta_key/bWV0YV92YWx1ZQ==/cond/ZnNpemU9Ng==  HTTP/1.1
Host: rs.qiniuapi.com
User-Agent: Go-http-client/1.1
Content-Length: 0
Authorization: Qiniu EmEtww5prO5pe8ts_mG.......1tXlEQ9hoG4:LuGCwpfK-rM=
X-Qiniu-Date: 20060102T150405Z
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip
```

*注：要在 `Authorization` 头部的 `&lt;AccessToken&gt;` 前添加 `Qiniu` 和半角空格。*

### 响应示例 [#响应示例]

```
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 02 Jan 2006 15:04:05 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
X-Reqid: -nIAABnfaeIlucoU
```


# 异步第三方资源抓取 (/products/kodo/rs/10-asynch-fetch)



最近更新时间: 2025-12-26 18:56:43

# **描述** [#描述]

本接口用于从指定 URL 抓取资源，并将该资源存储到指定空间中。每次只抓取一个文件，抓取时可以指定保存空间名和最终资源名。

<br />

# **发起任务:** [#发起任务]

# **请求** [#请求]

### **请求语法** [#请求语法]

```
POST /sisyphus/fetch HTTP/1.1
Host:           api-<Region>.qiniuapi.com
Content-Type:   application/json
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
Body:
{
    "url" : "<url>",
    "host" : "<host>",
    "bucket": "<bucket>",
    "key": "<key>",
    "md5": "<md5>",
    "callbackurl": "<callbackurl>",
    "callbackbody": "<callbackbody>",
    "callbackbodytype": "<callbackbodytype>",
    "file_type":<file_type>
    ...
}
```

使用说明：

* 抓取动作是异步操作，接受到抓取请求后服务端直接返回成功，资源会在后台进行抓取后存入存储，并产生一个回调请求通知业务服务器（如果存在回调参数）。
* 因为各种原因抓取失败时会产生一个 json 格式&#x7684;&#x2A;**特殊回调***&#x901A;知业务服务器。
* 如果被抓取的源站屏蔽（屏蔽可能是抓取源站有 IP、UA 等限制策略）来自七牛的抓取操作，那么不能确保一定可以抓取成功。

<br />

### **请求参数** [#请求参数]

该请求操作的参数为空，请参考操作内容中的参数。

<br />

### **请求头** [#请求头]

| 头部名称          | 必填 | 说明                                                                                                                                                                    |
| :------------ | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Host          | 是  | `api-&lt;Region&gt;.qiniuapi.com` 中的 `&lt;Region&gt;` 为七牛各区域 ID，请参考七牛支持的 [区域列表](/products/kodo/2-region-endpoint-fq)                                                  |
| Authorization | 是  | 该参数应严格按照[管理凭证](/products/kodo/development-guidelines/security/access-token)格式进行填充，否则会返回 401 错误码<br />一个合法的 Authorization 值应类似于：`Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他            |    | 请查阅[公共请求头](/products/kodo/3924-common-request-headers)                                                                                                                |

<br />

### **请求内容** [#请求内容]

| 参数名称              | 类型     | 默认值   | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------- | ------ | ----- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| url               | string | N/A   | 是  | 需要抓取的 url,支持设置多个用于高可用,以';'分隔,当指定多个 url 时可以在前一个 url 抓取失败时重试下一个                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| bucket            | string | N/A   | 是  | \<Zone> 所在区域的 bucket                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| host              | string | 空     | 否  | 从指定 url 下载数据时使用的 Host                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| key               | string | 空     | 否  | 文件存储的 key,不传则使用文件 hash 作为 key                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| md5               | string | 空     | 否  | 文件 md5,传入以后会在存入存储时对文件做校验，校验失败则不存入指定空间                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| etag              | string | 空     | 否  | 文件 etag,传入以后会在存入存储时对文件做校验，校验失败则不存入指定空间,相关算法参考 [https://github.com/qiniu/qetag](https://github.com/qiniu/qetag)                                                                                                                                                                                                                                                                                                                                                                                              |
| callbackurl       | string | 空     | 否  | 回调 URL，详细解释请参考上传策略中的[callbackUrl](/products/kodo/development-guidelines/security/1-put-policy#put-policy-callback-url)                                                                                                                                                                                                                                                                                                                                                                                      |
| callbackbody      | string | 空     | 否  | 回调 Body，如果 callbackurl 不为空则必须指定。上传成功后，七牛云向业务服务器发送 Content-Type: application/x-www-form-urlencoded 的 POST 请求。业务服务器可以通过直接读取请求的 query 来获得该字段，支持[魔法变量](/products/kodo/development-guidelines/upload-types/0-vars#magicvar)、但不支持自定义变量。callbackBody 要求是合法的 url query string。例如 key=$(key)\&hash=$(etag)\&w=$(imageInfo.width)\&h=$(imageInfo.height)。如果 callbackBodyType 指定为 application/json，则 callbackBody 应为 json 格式，例如:\{"key":"$(key)","hash":"$(etag)","w":"$(imageInfo.width)","h":"$(imageInfo.height)"}。 |
| callbackbodytype  | string | 空     | 否  | 回调 Body 内容类型,默认为"application/x-www-form-urlencoded"，详细解释请参考上传策略中的[callbackBodyType](/products/kodo/development-guidelines/security/1-put-policy#put-policy-callback-body-type)。                                                                                                                                                                                                                                                                                                                             |
| callbackhost      | string | 空     | 否  | 回调时使用的 Host                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| file\_type        | int    | 0     | 否  | 存储文件类型 0:标准存储(默认), 1:低频存储, 2:归档存储, 3:深度归档存储, 4:归档直读存储, 5:智能分层存储                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| mode              | string | 空     | 否  | 可选填⼊ m3u8，此时会解析 m3u8 并下载对应 ts 落存储, 必须指定 key。m3u8 文件的解析，只支持相对路径模式：ts 文件和 m3u8 文件将保存在指定的同一目录下。                                                                                                                                                                                                                                                                                                                                                                                                                |
| ignore\_same\_key | bool   | false | 否  | 如果已存在同名⽂会重试抓取。当为 true 时，如果空间中已经存在同名文件则放弃本次抓取(仅对比 key，不校验文件内容)。                                                                                                                                                                                                                                                                                                                                                                                                                                              |

<br />

<br />

# **响应** [#响应]

### **响应语法** [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Body:
{
}
```

<br />

### **响应头** [#响应头]

| 头部名称         | 必填 | 说明                                                                  |
| :----------- | :- | :------------------------------------------------------------------ |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json`，表示返回 JSON 格式的文本信息。                   |
| 其他           |    | 其它可能返回的头部信息，请参考[公共响应头](/products/kodo/3924-common-request-headers)。 |

<br />

### **响应内容** [#响应内容]

如果请求成功，则返回

```
{"id":"<ID>","wait":<Wait>}
```

\| 参数名称  | 说明
\| ---- | --- | ---
|id        | 异步任务Id
|wait       | 当前任务前面的排队任务数量,0表示当前任务正在进行,-1表示任务已经至少被处理过一次（可能会进入重试逻辑）

如果抓取失败，则返回特殊回调消息体格式 （特殊回调消息体包含发起请求时的参数和错误信息,示例不包含所有参数）

```
{
    "url" : "<url>",
    "bucket": "<bucket>",
    "key": "<key>",
    "md5": "<md5>",
    "callbackurl": "<callbackurl>",
    "callbackbody": "<callbackbody>",
    "callbackbodytype": "<callbackbodytype>",
    "file_type":<file_type>,
    "err":"<err>",
    "code":<code>
}
```

\| 参数名称  | 说明
\| ---- | --- | ---
|err        | 错误信息
|code       | 错误码

<br />

### **响应状态码** [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误响应](/products/kodo/3928-error-responses)。

<br />

# **示例** [#示例]

### **请求** [#请求-1]

**发起异步任务**

```
POST /sisyphus/fetch HTTP/1.1
Host:           api-z0.qiniuapi.com
Content-Type:   application/json
User-Agent: Go-http-client/1.1
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:FwliyUEz-rL1rb9qVkd0xYosBng=
Body:
{
    "url" : "http://www.qiniu.com",
    "bucket": "test",
    "key": "qiniu",
    "callbackurl": "http://www.qiniu.com/callback",
    "callbackbody": "$(bucket)"
}
```

*注：要在 `Authorization` 头部的 `<AccessToken>` 前添加 `Qiniu` 和半角空格。*

<br />

### **响应** [#响应-1]

```
HTTP/1.1 200 OK
Content-Length: 94
Connection: keep-alive
Content-Type: application/json
Date: Mon, 02 Jan 2006 15:04:05 GMT
Server: nginx
X-Reqid: jXwAAH8259lkr-UU
Body:
{"id":"eyJ6b25lIjoiejAiLCJwYXJ0X2lkIjo2Mywib2Zmc2V0IjowfQ==","wait":-1}

```

<br />

# **查询任务** [#查询任务]

# **请求** [#请求-2]

### **请求语法** [#请求语法-1]

```
GET /sisyphus/fetch?id=<ID> HTTP/1.1
Host:           api-<Region>.qiniuapi.com
Authorization:  Qiniu <AccessToken>
```

### **请求参数** [#请求参数-1]

| 参数名称 | 必填 | 说明      |
| ---- | -- | ------- |
| ID   | 是  | 异步任务 ID |

<br />

# **响应** [#响应-2]

### **响应内容** [#响应内容-1]

```
{"id":"<ID>","wait":<Wait>}
```


# 修改文件状态 (/products/kodo/rs/11-modify-the-file-status)



最近更新时间: 2023-03-02 18:59:11

# **描述** [#描述]

本接口用于修改文件的存储状态，即禁用和启用状态间的的互相转换。
处于禁用状态的文件将只能通过签发 Token 的方式访问 [下载凭证](/products/kodo/development-guidelines/security/0-download-token)。

<br />

# **请求** [#请求]

### **请求语法** [#请求语法]

```
POST /chstatus/<EncodedEntryURI>/status/<status> HTTP/1.1
Host:           rs.qiniuapi.com
Content-Type:   application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

<br />

### **请求参数** [#请求参数]

| 参数名称            | 必填 | 说明                                                          |
| --------------- | -- | ----------------------------------------------------------- |
| EncodedEntryURI | 是  | 指定文件信息，详情请参考[EncodedEntryURI](/products/kodo/0-data-format) |
| status          | 是  | 值为数字，0表示启用，1表示禁用                                            |

<br />

### **请求头** [#请求头]

| 头部名称          | 必填 | 说明                                                                                                                                                                    |
| :------------ | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | 是  | 该参数应严格按照[管理凭证](/products/kodo/development-guidelines/security/access-token)格式进行填充，否则会返回 401 错误码<br />一个合法的 Authorization 值应类似于：`Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他            |    | 请查阅[公共请求头](/products/kodo/3924-common-request-headers)                                                                                                                |

<br />

<a id="chgm-response" />

### **请求内容** [#请求内容]

该请求操作的请求体为空。

<br />

# **响应** [#响应]

### **响应语法** [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
```

<a id="chtype-response-headers" />

### **响应头** [#响应头]

| 头部名称         | 必填 | 说明                                                                  |
| :----------- | :- | :------------------------------------------------------------------ |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json`，表示返回 JSON 格式的文本信息。                   |
| 其他           |    | 其它可能返回的头部信息，请参考[公共响应头](/products/kodo/3924-common-request-headers)。 |

<br />

### **响应内容** [#响应内容]

如果请求成功，不返回任何内容。
如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "error":   "<errMsg    string>",
}
```

| 字段名称  | 必填 | 说明                |
| :---- | :- | :---------------- |
| error | 是  | 与 HTTP 状态码对应的消息文本 |

<br />

<a id="chtype-response-status" />

### **响应状态码** [#响应状态码]

| HTTP状态码 | 含义                                                                                                                                                                                                                                                                                             |
| :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200     | 更改成功                                                                                                                                                                                                                                                                                           |
| 400     | 请求报文格式错误<br />当`&lt;EncodedEntryURI&gt;`解析失败，返回 `400 Bad Request {"error":"invalid argument"}`<br />当`&lt;EncodedEntryURI&gt;`不符合 UTF-8 编码，返回 `400 Bad Request {"error":"key must be utf8 encoding"}`<br />当文件当前状态和设置的状态已经一致，返回 `{"error":"already enabled"}` 或 `{"error":"already disabled"}` |
| 401     | 管理凭证无效                                                                                                                                                                                                                                                                                         |
| 612     | 目标文件不存在                                                                                                                                                                                                                                                                                        |
| 599     | 服务端操作失败<br />                                                                                                                                                                                                                                                                                  |
| 其他错误码   | 请查阅[错误响应](/products/kodo/3928-error-responses)                                                                                                                                                                                                                                                 |

如遇 599 错误，请将完整错误信息（包括所有 HTTP 响应头部）[提交工单](https://support.qiniu.com/tickets/category) 给我们。

<br />

<a id="chtype-samples" />

# **示例** [#示例]

### **请求示例** [#请求示例]

```
POST /chstatus/aXRpc2F0ZXN0OmdvZ29waGVyLmpwZw==/status/1 HTTP/1.1
User-Agent: curl/7.30.0
Host: rs.qiniuapi.com
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu bt500PzCG9tV0bccCOdnrmCHPXCPLieGSDEprB7M:4wG...(过长已省略)
```

*注：要在`Authorization`头部的`<AccessToken>`前添加`Qiniu`和半角空格。*

<br />

<a id="chgm-example1-response" />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Server: nginx/1.4.4
Date: Mon, 02 Jan 2006 15:04:05 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
X-Reqid: vDEAAG2lN7zSqpQT
```


# 解冻归档/深度归档存储文件 (/products/kodo/rs/12-restore-archive)



最近更新时间: 2023-03-02 18:59:42

# **描述** [#描述]

本接口用于解冻归档/深度归档存储类型的文件，可设置解冻有效期1～7天。
归档存储文件完成解冻通常需要1～5分钟，深度归档存储文件完成解冻需要5～12小时。

<br />

# **请求** [#请求]

### **请求语法** [#请求语法]

```
POST /restoreAr/<EncodedEntryURI>/freezeAfterDays/<FreezeAfterDays> HTTP/1.1
Host:           rs.qiniuapi.com
Content-Type:   application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

<br />

### **请求参数** [#请求参数]

| 参数名称            | 必填 | 说明                                                           |
| --------------- | -- | ------------------------------------------------------------ |
| EncodedEntryURI | 是  | 指定文件信息，详情请参考 [EncodedEntryURI](/products/kodo/0-data-format) |
| FreezeAfterDays | 是  | 解冻有效时长，取值范围 1～7                                              |

<br />

### **请求头** [#请求头]

| 头部名称          | 必填 | 说明                                                                                                                                                                    |
| :------------ | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | 是  | 该参数应严格按照[管理凭证](/products/kodo/development-guidelines/security/access-token)格式进行填充，否则会返回 401 错误码<br />一个合法的 Authorization 值应类似于：`Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他            |    | 请查阅[公共请求头](/products/kodo/3924-common-request-headers)                                                                                                                |

<br />

### **请求内容** [#请求内容]

该请求操作的请求体为空。

<br />

# **响应** [#响应]

### **响应头** [#响应头]

| 头部名称         | 必填 | 说明                                                                  |
| :----------- | :- | :------------------------------------------------------------------ |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json`，表示返回 JSON 格式的文本信息。                   |
| 其他           |    | 其它可能返回的头部信息，请参考[公共响应头](/products/kodo/3924-common-request-headers)。 |

<br />

### **响应内容** [#响应内容]

如果请求成功，不返回任何内容。
如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "error":   "<errMsg    string>",
}
```

| 字段名称  | 必填 | 说明                |
| :---- | :- | :---------------- |
| error | 是  | 与 HTTP 状态码对应的消息文本 |

<br />

### **响应状态码** [#响应状态码]

| HTTP状态码                                                                                   | 含义                                                                                                                                                                                                                                                                                                                                                            |
| :---------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 200                                                                                       | 更改成功                                                                                                                                                                                                                                                                                                                                                          |
| 400                                                                                       | 请求报文格式错误<br />当 `Bucket` 为空时，返回 `400 Bad Request {"error":"invalid argument"}`<br />当 `Object` 不符合 UTF-8 编码，返回 `400 Bad Request {"error":"key must be utf8 encoding"}`<br />当 `Object` 已经处于解冻状态时，返回 `400 Bad Request {"error":"archive already restored"}`<br />当 `&lt;FreezeAfterDays&gt;` 不符合要求时，返回 `400 Bad Request {"error":"invalid freeze after days"}` |
| 401                                                                                       | 管理凭证无效                                                                                                                                                                                                                                                                                                                                                        |
| 403                                                                                       | 禁止操作<br />当非归档/深度归档存储类型 Object 调用此接口时，返回 `403 Fobbiden {"error": "operation only allowed for archive or deep archive"}`                                                                                                                                                                                                                                       |
| 612                                                                                       | 目标资源不存在                                                                                                                                                                                                                                                                                                                                                       |
| 599                                                                                       | 服务端操作失败                                                                                                                                                                                                                                                                                                                                                       |
| 其他错误码                                                                                     | 请查阅[错误响应](/products/kodo/3928-error-responses)                                                                                                                                                                                                                                                                                                                |
| 如遇 599 错误，请将完整错误信息（包括所有 HTTP 响应头部）[提交工单](https://support.qiniu.com/tickets/category) 给我们。 |                                                                                                                                                                                                                                                                                                                                                               |

<br />

# **示例** [#示例]

### **请求示例** [#请求示例]

```
POST /restoreAr/YnVja2V0LW1rdDNqbGNtemsyc2V2N3Rlb2ZjOktPRE8tS0VZLVRFU1QtYXJjaGl2ZS1UYmNZUEN0c3Ay/freezeAfterDays/1  HTTP/1.1
Host: rs.qiniuapi.com
User-Agent: Go-http-client/1.1
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:dkV6wjnPOasNG-WPDvbttUlYWaw=
Content-Type:   application/x-www-form-urlencoded
```

*注：要在 `Authorization` 头部的 `<AccessToken>` 前添加 `Qiniu` 和半角空格。*

<br />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Date: Mon, 02 Jan 2006 15:04:05 GMT
Content-Type: application/json
Connection: keep-alive
X-Reqid: ZhUAACe10_2tVfYV
```


# 资源复制 (/products/kodo/rs/2-copy)



最近更新时间: 2023-03-02 18:58:09

## 描述 [#描述]

本接口用于将指定文件复制为新命名文件。

## 请求 [#请求]

### 请求语法 [#请求语法]

```
POST /copy/<EncodedEntryURISrc>/<EncodedEntryURIDest>/force/<true|false> 
HTTP/1.1
Host:           rs.qiniuapi.com
Content-Type:   application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

使用说明：

* 源空间和目标空间必须属于相同账号，跨账号复制文件不支持。
* 文件不支持跨存储区域复制。
* 归档/深度归档存储文件，只有解冻状态时可以复制。copy 获得的目标文件为冻结状态。

### 请求参数 [#请求参数]

| 参数名称                | 必填 | 说明                                                                        |
| ------------------- | -- | ------------------------------------------------------------------------- |
| EncodedEntryURISrc  | 是  | 源文件，需要经过 Base64 编码，具体请参考 [EncodedEntryURI](/products/kodo/0-data-format)  |
| EncodedEntryURIDest | 是  | 目标文件，需要经过 Base64 编码，具体请参考 [EncodedEntryURI](/products/kodo/0-data-format) |
| force               | 否  | bool 类型，默认 false。如果目标文件名已被占用，则返回错误码 614，且不做任何覆盖操作；如果指定为 true，会强制覆盖目标文件    |

### 请求头 [#请求头]

| 头部名称            | 必填 | 说明                                                                                                                                                                   |
| --------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | 是  | 该参数应严格按照 [管理凭证](/products/kodo/development-guidelines/security/access-token) 格式进行填充，否则会返回 401 错误码  一个合法的 Authorization 值应类似于： `Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他              |    | 该请求操作的实现使用了所有操作的公共请求头。详情请查阅 [公共请求头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header)                                                  |

### 请求内容 [#请求内容]

该请求操作的请求体为空。

## 响应 [#响应]

### 响应语法 [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
```

### 响应头 [#响应头]

| 头部名称         | 必填 | 说明                                                                                                                    |
| ------------ | -- | --------------------------------------------------------------------------------------------------------------------- |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json` ，表示返回 JSON 格式的文本信息。                                                                    |
| 其他           |    | 该请求操作的实现使用了所有操作的公共响应头。详情请查阅 [公共响应头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header) 。 |

### 响应内容 [#响应内容]

如果请求成功，不返回任何内容。\
如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "error":   "<errMsg    string>",
}
```

| 字段名称  | 必填 | 说明                |
| ----- | -- | ----------------- |
| error | 是  | 与 HTTP 状态码对应的消息文本 |

### 响应状态码 [#响应状态码]

| HTTP状态码 | 含义                                                                                                                                                                          |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200     | 复制成功                                                                                                                                                                        |
| 400     | 请求报文格式错误                                                                                                                                                                    |
| 401     | 管理凭证无效                                                                                                                                                                      |
| 403     | 禁止操作   当归档存储文件未解冻完成时调用接口会返回 `403 ArchiveUnrestored {"error":"archive unrestored"}`   当深度归档存储文件未解冻完成时调用接口会返回 `403 DeepArchiveUnrestored {"error":"deep archive unrestored"}` |
| 599     | 服务端操作失败                                                                                                                                                                     |
| 612     | 待复制文件不存在                                                                                                                                                                    |
| 614     | 目标文件已存在                                                                                                                                                                     |
| 其他错误码   | 请查阅 [错误响应](/products/kodo/development-guidelines/upload-types/3-simple-response)                                                                                            |

如遇599错误，请将完整错误信息（包括所有HTTP响应头部） [提交工单](https://support.qiniu.com/tickets/category) 给我们。

## 示例 [#示例]

### 请求示例 [#请求示例]

```
POST /copy/bmV3ZG9jczpmaW5kX21hbi50eHQ=/bmV3ZG9jczpmaW5kLm1hbi50eHQ= HTTP/1.1
User-Agent: curl/7.30.0
Host: rs.qinuapi.com
Accept: */*
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...(过长已省略)
```

*注: 要在 `Authorization` 头部的 `&lt;AccessToken&gt;` 前添加 `Qiniu` 和半角空格。*

### 响应示例 [#响应示例]

```
HTTP/1.1 200 OK
Server: nginx/1.0.8
Date: Mon, 02 Jan 2006 15:04:05 GMT
Content-Type: application/json
Connection: keep-alive
Content-Length: 0
X-Reqid: wxIAAD3btw-v3TwT
```


# 资源删除 (/products/kodo/rs/3-delete)



最近更新时间: 2023-03-02 18:58:19

## 描述 [#描述]

本接口用于删除指定文件。

## 请求 [#请求]

### 请求语法 [#请求语法]

```
POST /delete/<EncodedEntryURI> HTTP/1.1
Host:           rs.qiniuapi.com
Content-Type:   application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

### 请求参数 [#请求参数]

| 参数名称            | 必填 | 说明                                                           |
| --------------- | -- | ------------------------------------------------------------ |
| EncodedEntryURI | 是  | 指定文件信息，详情请参考 [EncodedEntryURI](/products/kodo/0-data-format) |

### 请求头 [#请求头]

| 头部名称            | 必填 | 说明                                                                                                                                                               |
| --------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | 是  | 该参数应严格按照 [管理凭证](/products/kodo/development-guidelines/security/access-token) 格式进行填充，否则会返回401错误码  一个合法的Authorization值应类似于： `Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他              |    | 该请求操作的实现使用了所有操作的公共请求头。详情请查阅 [公共请求头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header)                                              |

## 响应 [#响应]

## 响应语法 [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
```

### 响应头 [#响应头]

| 头部名称         | 必填 | 说明                                                                                                        |
| ------------ | -- | --------------------------------------------------------------------------------------------------------- |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json` ，表示返回 JSON 格式的文本信息。                                                        |
| 其他           |    | 其它可能返回的头部信息，请参考 [公共响应头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header) 。 |

### 响应内容 [#响应内容]

如果请求成功，不返回任何内容。\
如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "error":   "<errMsg    string>",
}
```

| 字段名称  | 必填 | 说明                |
| ----- | -- | ----------------- |
| error | 是  | 与 HTTP 状态码对应的消息文本 |

### 响应状态码 [#响应状态码]

| HTTP状态码 | 含义                                                                               |
| ------- | -------------------------------------------------------------------------------- |
| 200     | 删除成功                                                                             |
| 400     | 请求报文格式错误                                                                         |
| 401     | 管理凭证无效                                                                           |
| 599     | 服务端操作失败                                                                          |
| 612     | 待删除文件不存在                                                                         |
| 其他错误码   | 请查阅 [错误响应](/products/kodo/development-guidelines/upload-types/3-simple-response) |

如遇599错误，请将完整错误信息（包括所有HTTP响应头部） [提交工单](https://support.qiniu.com/tickets/category) 给我们。

## 示例 [#示例]

## 请求示例 [#请求示例]

```
POST /delete/bmV3ZG9jczpmaW5kX21hbi50eHQ= HTTP/1.1
User-Agent: curl/7.30.0
Host: rs.qiniuapi.com
Accept: */*
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...(过长已省略)
```

*注：要在 `Authorization` 头部的 `&lt;AccessToken&gt;` 前添加 `Qiniu` 和半角空格。*

### 响应示例 [#响应示例]

```
HTTP/1.1 200 OK
Server: nginx/1.0.8
Date: Mon, 02 Jan 2006 15:04:05 GMT
Content-Type: application/json
Connection: keep-alive
Content-Length: 0
X-Reqid: wxIAAD3btw-v3TwT
```


# 资源列举 (/products/kodo/rs/4-list)



最近更新时间: 2025-07-21 17:42:46

## 描述 [#描述]

本接口用于列举指定空间里的所有文件条目。

## 请求 [#请求]

### 请求语法 [#请求语法]

```
GET /list?bucket=<Bucket>&marker=<Marker>&limit=<Limit>&prefix=<UrlEncodedPrefix>&delimiter=<UrlEncodedDelimiter> HTTP/1.1
Host:           rsf.qiniuapi.com
Content-Type:   application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

### 请求参数 [#请求参数]

| 参数名称      | 必填 | 说明                                     |
| --------- | -- | -------------------------------------- |
| bucket    | 是  | 指定空间。                                  |
| marker    | 否  | 上一次列举返回的位置标记，作为本次列举的起点信息。  默认值为空字符串。   |
| limit     | 否  | 本次列举的条目数，范围为1-1000。  默认值为1000。         |
| prefix    | 否  | 指定前缀，只有资源名匹配该前缀的资源会被列出。  默认值为空字符串。     |
| delimiter | 否  | 指定目录分隔符，列出所有公共前缀（模拟列出目录效果）。  默认值为空字符串。 |

### 请求头 [#请求头]

| 头部名称            | 必填 | 说明                                                                                                                                                               |
| --------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | 是  | 该参数应严格按照 [管理凭证](/products/kodo/development-guidelines/security/access-token) 格式进行填充，否则会返回401错误码  一个合法的Authorization值应类似于： `Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他              |    | 该请求操作的实现使用了所有操作的公共请求头。详情请查阅 [公共请求头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header)                                              |

### 请求内容 [#请求内容]

该请求操作的请求体为空。

## 响应 [#响应]

### 响应头 [#响应头]

| 头部名称         | 必填 | 说明                                                                                                                    |
| ------------ | -- | --------------------------------------------------------------------------------------------------------------------- |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json` ，表示返回 JSON 格式的文本信息。                                                                    |
| 其他           |    | 该请求实现使用了所有操作的公共响应头。详细信息，请查阅 [公共响应头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header) 。 |

### 响应内容 [#响应内容]

| 字段名称           | 必响应项目 | 说明                                                                                                                                                                                                                                                                                                                 |
| -------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| marker         | 是     | 起始条目标记，将作为下一次列举的参数传入。  如果没有剩余条目则返回空字符串。      类型：字符串                                                                                                                                                                                                                                                                |
| commonPrefixes | 是     | 返回目录名的数组，如没有指定 `delimiter` 参数则返回空。      类型：数组                                                                                                                                                                                                                                                                      |
| items          | 是     | 返回条目的数组。不能用来判断是否还有剩余条目。      类型：数组                                                                                                                                                                                                                                                                                 |
| key            | 是     | 资源名。      类型：字符串                                                                                                                                                                                                                                                                                                   |
| putTime        | 是     | 上传时间，单位：100纳秒，其值去掉低七位即为 [Unix时间戳](/products/kodo/3-u) 。      类型：数字                                                                                                                                                                                                                                                 |
| lastModify     | 是     | 文件修改时间，文件上传（含覆盖写）或修改元数据（含文件类型）、存储类型的时间。      类型：数字                                                                                                                                                                                                                                                                 |
| hash           | 是     | 文件的 `HASH` 值，暨文件的七牛 ETag 值。      类型：字符串                                                                                                                                                                                                                                                                            |
| fsize          | 是     | 资源内容的大小，单位：字节。      类型：数字                                                                                                                                                                                                                                                                                          |
| mimeType       | 是     | 资源的 MIME 类型。      类型：字符串                                                                                                                                                                                                                                                                                           |
| endUser        | 否     | 资源内容的唯一属主标识，请参考 [上传策略 (PutPolicy)](/products/kodo/development-guidelines/security/1-put-policy) 。      类型：字符串                                                                                                                                                                                                      |
| type           | 是     | 资源的存储类型， `0` 表示标准存储， `1` 表示 [低频存储](/products/kodo/kodo-category#IA) ， `2` 表示 [归档存储](/products/kodo/kodo-category#archive) ， `3` 表示 [深度归档存储](/products/kodo/kodo-category#deep_archive) ， `4` 表示 [归档直读存储](/products/kodo/kodo-category#archive_ir) ， `5` 表示 [智能分层存储](/products/kodo/kodo-category#INT) 。      类型：数字 |
| status         | 是     | 文件的存储状态，即禁用状态和启用状态间的的互相转换， `0` 表示启用， `1` 表示禁用，请参考： [文件状态](/products/kodo/rs/11-modify-the-file-status) 。      类型：数字                                                                                                                                                                                                |
| md5            | 否     | 文件 `md5` 值，32位16进制组成的字符串，只有通过直传文件和追加文件API上传的文件，服务端确保有该字段返回，如请求时服务端没有返回md5字段，可以通过请求qhash/md5 方法来获取，比如 [http://test.com/test.mp4?qhash/md5](http://test.com/test.mp4?qhash/md5)                                                                                                                                      |

### 响应状态码 [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅 [错误响应](/products/kodo/development-guidelines/upload-types/3-simple-response) 。

## 示例 [#示例]

### 列出所有 00 打头的资源 [#列出所有-00-打头的资源]

### 请求示例 [#请求示例]

```
GET /list?bucket=test02&prefix=00 HTTP/1.1
Host: rsf.qiniuapi.com
User-Agent: Go-http-client/1.1
X-Qiniu-Date: 20171122T014120Z
Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:XvRh0ABLViTohBkgKqa0upyiug0=
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip
```

*注：要在 `Authorization` 头部的 `&lt;AccessToken&gt;` 前添加 `Qiniu` 和半角空格。*

### 响应示例 [#响应示例]

```
HTTP/1.1 200 OK
Content-Length: 739
Connection: keep-alive
Content-Type: application/json
Date: Wed, 22 Nov 2017 01:41:20 GMT
Server: nginx
X-Reqid: QBUAAKUcoGrgRPkU
X-Reqid: QBUAAKUcoGrgRPkU
X-Reqid: QBUAAKUcoGrgRPkU.peer

{
  "items": [
    {
      "key": "000001.pdf", 
      "hash": "Fs3oFOyOFDUp5CEODM8J6xquSq3s", 
      "fsize": 452584, 
      "mimeType": "application/pdf", 
      "putTime": 15112568720620784, 
      "md5": "e41714a18899cf59c200a9bddfa78b95",
      "type": 0, 
      "status": 0
    }, 
    {
      "key": "000002.ico", 
      "hash": "FpGrGHQOjETYnwxmSF3uXmFpmZIb", 
      "fsize": 5686, 
      "mimeType": "image/x-icon", 
      "putTime": 15112568850754920, 
      "type": 0, 
      "status": 0
    }, 
    {
      "key": "000003.png", 
      "hash": "FreZ58OmkQe5ZRUktRsO3zoqRaHi", 
      "fsize": 21741, 
      "mimeType": "image/png", 
      "putTime": 15112568948976712, 
      "type": 0, 
      "status": 0
    }, 
    {
      "key": "000004.png", 
      "hash": "FreZ58OmkQe5ZRUktRsO3zoqRaHi", 
      "fsize": 21741, 
      "mimeType": "image/png", 
      "putTime": 15112569033603324, 
      "type": 0, 
      "status": 0
    }
  ]
}
```

### 列出所有 00 打头的资源并每批 2 个 [#列出所有-00-打头的资源并每批-2-个]

### 请求示例 [#请求示例-1]

```
GET /list?bucket=test02&prefix=00&limit=2 HTTP/1.1
Host: rsf.qiniuapi.com
User-Agent: Go-http-client/1.1
Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:m-2lEHcnRVwgYBqJdC5SW7groT8=
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip
```

*注：要在 `Authorization` 头部的 `&lt;AccessToken&gt;` 前添加 `Qiniu` 和半角空格。*

### 响应示例 [#响应示例-1]

```
HTTP/1.1 200 OK
Content-Length: 352
Connection: keep-alive
Content-Type: application/json
Date: Wed, 22 Nov 2017 01:46:58 GMT
Server: nginx
X-Log: TBLMGR:10;UC:21;CFGG:22;RSF:90;RSF:92;ZONEPROXY:148
X-Reqid: pEYAABGkVfAuRfkU
X-Reqid: pEYAABGkVfAuRfkU
X-Reqid: pEYAABGkVfAuRfkU.peer

{
  "marker": "eyJjIjowLCJrIjoiMDAwMDAyLmljbyJ9", 
  "items": [
    {
      "key": "000001.pdf", 
      "hash": "Fs3oFOyOFDUp5CEODM8J6xquSq3s", 
      "fsize": 452584, 
      "mimeType": "application/pdf", 
      "putTime": 15112568720620784, 
      "type": 0, 
      "status": 0
    }, 
    {
      "key": "000002.ico", 
      "hash": "FpGrGHQOjETYnwxmSF3uXmFpmZIb", 
      "fsize": 5686, 
      "mimeType": "image/x-icon", 
      "putTime": 15112568850754920, 
      "type": 0, 
      "status": 0
    }
  ]
}
```


# 资源移动／重命名 (/products/kodo/rs/5-move)



最近更新时间: 2025-09-15 11:46:11

## 描述 [#描述]

本接口用于将源空间的指定文件移动到目标空间，或在同一空间内对文件重命名。

## 请求 [#请求]

### 请求语法 [#请求语法]

```
POST /move/<EncodedEntryURISrc>/<EncodedEntryURIDest>/force/<true|false>  
HTTP/1.1
Host:           rs.qiniuapi.com
Content-Type:   application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

使用说明:

* 源空间和目标空间必须属于相同账号，不支持跨账号移动文件
* 文件不支持跨存储区域 move
* 归档/深度归档存储文件，只有解冻状态才允许调用本接口。move 获得的目标文件为冻结状态。
* 如对 `未存满最短存储时间` 的低频/归档直读/归档/深度归档存储类型的文件 move， `将涉及提前删除费用` 。

### 请求参数 [#请求参数]

| 参数名称                | 必填 | 说明                                                                        |
| ------------------- | -- | ------------------------------------------------------------------------- |
| EncodedEntryURISrc  | 是  | 源文件，需要经过 Base64 编码，具体请参考 [EncodedEntryURI](/products/kodo/0-data-format)  |
| EncodedEntryURIDest | 是  | 目标文件，需要经过 Base64 编码，具体请参考 [EncodedEntryURI](/products/kodo/0-data-format) |
| force               | 否  | bool 类型，默认 false。如果目标文件名已被占用，则返回错误码 614，且不做任何覆盖操作；如果指定为 true，会强制覆盖目标文件    |

### 请求头 [#请求头]

| 头部名称            | 必填 | 说明                                                                                                                                                               |
| --------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | 是  | 该参数应严格按照 [管理凭证](/products/kodo/development-guidelines/security/access-token) 格式进行填充，否则会返回401错误码  一个合法的Authorization值应类似于： `Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他              |    | 该请求操作的实现使用了所有操作的公共请求头。详情请查阅 [公共请求头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header)                                              |

### 请求内容 [#请求内容]

该请求操作的请求体为空。

## 响应 [#响应]

### 响应语法 [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
```

### 响应头 [#响应头]

| 头部名称         | 必填 | 说明                                                                                                                    |
| ------------ | -- | --------------------------------------------------------------------------------------------------------------------- |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json` ，表示返回 JSON 格式的文本信息。                                                                    |
| 其他           |    | 该请求实现使用了所有操作的公共响应头。详细信息，请查阅 [公共响应头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header) 。 |

### 响应内容 [#响应内容]

如果请求成功，不返回任何内容。\
如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "error":   "<errMsg    string>",
}
```

| 字段名称  | 必填 | 说明                |
| ----- | -- | ----------------- |
| error | 是  | 与 HTTP 状态码对应的消息文本 |

### 响应状态码 [#响应状态码]

| HTTP状态码 | 含义                                                                                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200     | 移动成功                                                                                                                                                                      |
| 400     | 请求报文格式错误                                                                                                                                                                  |
| 401     | 管理凭证无效                                                                                                                                                                    |
| 403     | 禁止操作   当归档存储文件未解冻完成调用接口会返回 `403 ArchiveUnrestored {"error":"archive unrestored"}`   当深度归档存储文件未解冻完成调用接口会返回 `403 DeepArchiveUnrestored {"error":"deep archive unrestored"}` |
| 599     | 服务端操作失败                                                                                                                                                                   |
| 612     | 待移动文件不存在                                                                                                                                                                  |
| 614     | 目标文件已存在                                                                                                                                                                   |
| 其他错误码   | 请查阅 [错误响应](/products/kodo/development-guidelines/upload-types/3-simple-response)                                                                                          |

如遇 599 错误，请将完整错误信息（包括所有 HTTP 响应头部） [提交工单](https://support.qiniu.com/tickets/category) 给我们。

## 示例 [#示例]

### 请求示例 [#请求示例]

```
POST /move/bmV3ZG9jczpmaW5kX21hbi50eHQ=/bmV3ZG9jczpmaW5kLm1hbi50eHQ= HTTP/1.1
User-Agent: curl/7.30.0
Host: rs.qiniuapi.com
Accept: */*
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...(过长已省略)
```

*注：要在 `Authorization` 头部的 `&lt;AccessToken&gt;` 前添加 `Qiniu` 和半角空格。*

### 响应示例 [#响应示例]

```
HTTP/1.1 200 OK
Server: nginx/1.0.8
Date: Mon, 02 Jan 2006 15:04:05 GMT
Content-Type: application/json
Connection: keep-alive
Content-Length: 0
X-Reqid: wxIAAD3btw-v3TwT
```


# 镜像资源更新 (/products/kodo/rs/6-prefetch)



最近更新时间: 2023-03-02 19:00:13

## 描述 [#描述]

对设置了镜像存储的空间，使用本接口将镜像源站抓取指定名称的文件并存储到该空间中。\
如果该空间中已存在该名称的文件，则会将镜像源站的文件覆盖空间中相同名称的文件。

## 请求 [#请求]

### 请求语法 [#请求语法]

```
POST /prefetch/<EncodedEntryURI>
Host:           iovip-<Region>.qiniuio.com
Content-Type:   application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

### 请求参数 [#请求参数]

| 参数名称            | 必填 | 说明                                                           |
| --------------- | -- | ------------------------------------------------------------ |
| EncodedEntryURI | 是  | 指定文件信息，详情请参考 [EncodedEntryURI](/products/kodo/0-data-format) |

### 请求头 [#请求头]

| 头部名称          | 必填 | 说明                                                                                                                                                                   |
| ------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Host          | 是  | `iovip-&lt;Region&gt;.qiniuio.com` 中的 `&lt;Region&gt;` 为七牛各区域 ID，请参考七牛支持的 [区域列表](/products/kodo/2-region-endpoint-fq) 查看具体域名。                                        |
| Authorization | 是  | 该参数应严格按照 [管理凭证](/products/kodo/development-guidelines/security/access-token) 格式进行填充，否则会返回 401 错误码  一个合法的 Authorization 值应类似于： `Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他            |    | 请查阅 [公共请求头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header)                                                                          |

### 请求内容 [#请求内容]

该请求操作的请求体为空。

## 响应 [#响应]

### 响应语法 [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
```

### 响应头 [#响应头]

| 头部名称         | 必填 | 说明                                                                                                        |
| ------------ | -- | --------------------------------------------------------------------------------------------------------- |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json` ，表示返回 JSON 格式的文本信息。                                                        |
| 其他           |    | 其它可能返回的头部信息，请参考 [公共响应头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header) 。 |

### 响应内容 [#响应内容]

如果请求成功，不返回任何内容。\
如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "error":   "<errMsg    string>",
}
```

| 字段名称  | 必填 | 说明                |
| ----- | -- | ----------------- |
| error | 是  | 与 HTTP 状态码对应的消息文本 |

### 响应状态码 [#响应状态码]

| HTTP状态码 | 含义                                                                               |
| ------- | -------------------------------------------------------------------------------- |
| 200     | 抓取成功                                                                             |
| 400     | 请求报文格式错误                                                                         |
| 401     | 管理凭证无效                                                                           |
| 404     | 抓取资源不存在                                                                          |
| 478     | 源站返回404外，所有非200的response都返回478。                                                  |
| 599     | 服务端操作失败                                                                          |
| 其他错误码   | 请查阅 [错误响应](/products/kodo/development-guidelines/upload-types/3-simple-response) |

如遇 599 错误，请将完整错误信息（包括所有 HTTP 响应头部） [提交工单](https://support.qiniu.com/tickets/category) 给我们。

## 示例 [#示例]

### 请求示例 [#请求示例]

```
POST /prefetch/bmV3ZG9jczpmaW5kLm1hbi50eHQ= HTTP/1.1
User-Agent: curl/7.30.0
Host: iovip.qiniuio.com
Accept: */*
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...(过长已省略)
```

*注：要在 `Authorization` 头部的 `&lt;AccessToken&gt;` 前添加 `Qiniu` 和半角空格。*

### 响应示例 [#响应示例]

```
HTTP/1.1 200 OK
Server: nginx/1.0.8
Date: Mon, 02 Jan 2006 15:04:05 GMT
Content-Type: application/json
Connection: keep-alive
Content-Length: 0
X-Log: RS.in;RS.mo;qtbl.mv:3;MQ;MC/404;RS.mcd:1;RS:5
X-Reqid: wxIAAD3btw-v3TwT
```

*注：本接口在执行同步操作时，如果抓取的资源过大或者源站响应过慢，可能会导致超时。*


# 资源元信息查询 (/products/kodo/rs/7-stat)



最近更新时间: 2026-01-05 14:22:59

## 描述 [#描述]

本接口仅用于获取资源的 `Metadata` 信息，不返回资源内容。

## 请求 [#请求]

### 请求语法 [#请求语法]

```
GET /stat/<EncodedEntryURI> HTTP/1.1
Host:          rs.qiniuapi.com
Content-Type:  application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu <AccessToken>
```

### 请求参数 [#请求参数]

| 参数名称            | 必填 | 说明                                                    |
| --------------- | -- | ----------------------------------------------------- |
| EncodedEntryURI | 是  | 具体请参考 [EncodedEntryURI](/products/kodo/0-data-format) |

### 请求头 [#请求头]

| 头部名称            | 必填 | 说明                                                                                                                                                                 |
| --------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Authorization` | 是  | 该参数应严格按照 [管理凭证](/products/kodo/development-guidelines/security/access-token) 格式进行填充，否则会返回401错误码  一个合法的 Authorization 值应类似于： `Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他              |    | 该请求操作的实现使用了所有操作的公共请求头。详情请查阅 [公共请求头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header)                                                |

### 请求内容 [#请求内容]

该请求操作的请求体为空。

## 响应 [#响应]

### 响应头 [#响应头]

| 头部名称         | 必填 | 说明                                                                                                                    |
| ------------ | -- | --------------------------------------------------------------------------------------------------------------------- |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json` ，表示返回 JSON 格式的文本信息。                                                                    |
| 其他           |    | 该请求操作的实现使用了所有操作的公共响应头。详情请查阅 [公共响应头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header) 。 |

### 响应内容 [#响应内容]

| 字段名称                           | 必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------ | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fsize                          | 是  | 文件大小，int64 类型，单位为字节（Byte）。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| hash                           | 是  | 文件 `HASH` 值，string 类型。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| mimeType                       | 是  | 文件 `MIME` 类型，string 类型。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| type                           | 是  | 文件存储类型，uint32 类型， `0` 表示标准存储， `1` 表示 [低频存储](/products/kodo/kodo-category#IA) ， `2` 表示 [归档存储](/products/kodo/kodo-category#archive) ， `3` 表示 [深度归档存储](/products/kodo/kodo-category#deep_archive) ， `4` 表示 [归档直读存储](/products/kodo/kodo-category#archive_ir) 、 `5` 表示 [智能分层存储](/products/kodo/kodo-category/0-storage-class-intelligent-tiering) 。                                                                                                                                                                       |
| putTime                        | 是  | 文件上传时间，文件上传（含覆盖写）的时间。int64 类型， [Unix时间戳](/products/kodo/3-u) 格式，单位为 100 纳秒。  例如：值为 `13603956734587420` 的时间，对应的实际时间为 `2013-02-09 15:41:13` 。                                                                                                                                                                                                                                                                                                                                                                            |
| lastModify                     | 是  | 文件修改时间，文件上传（含覆盖写）或修改元数据（含文件类型）、存储类型的时间。int64 类型， [Unix时间戳](/products/kodo/3-u) 格式，单位为 100 纳秒。  例如：值为 `13603956734587420` 的时间，对应的实际时间为 `2013-02-09 15:41:13` 。                                                                                                                                                                                                                                                                                                                                                          |
| restoreStatus                  | 否  | 归档/深度归档存储文件的解冻状态，uint32 类型， `2` 表示解冻完成， `1` 表示解冻中；归档/深度归档文件冻结时，不返回该字段。                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| x-qn-meta                      | 否  | 自定义元数据，含 `meta_key` 参数 及对应 `metaValue` 值；仅当自定义元数据后返回该字段。                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| status                         | 否  | 文件状态，uint32 类型。 `1` 表示禁用；只有禁用状态的文件才会返回该字段。                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| md5                            | 否  | 文件 `md5` 值，string 类型，32 位 16 进制组成的字符串，只有通过直传文件 API 上传的文件，服务端确保有该字段返回，如请求时服务端没有返回 md5 字段，可以通过请求 qhash/md5 方法来获取，比如 [http://test.com/test.mp4?qhash/md5](http://test.com/test.mp4?qhash/md5)                                                                                                                                                                                                                                                                                                                             |
| expiration                     | 否  | 文件过期删除日期，int64 类型，Unix 时间戳格式，具体文件过期日期计算参考 [生命周期管理](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management) 。文件在设置过期时间后才会返回该字段（通过生命周期规则设置文件过期时间，仅对该功能发布后满足规则条件新上传文件返回该字段；历史文件想要返回该字段需要在功能发布后可通过 [修改文件过期删除时间 API](/products/kodo/rs/9-update-file-lifecycle) 或者 [修改文件生命周期 API](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management) 指定过期时间；对于已经设置过过期时间的历史文件，到期都会正常过期删除，只是服务端没有该字段返回)   例如：值为 `1568736000` 的时间，表示文件会在 `2019/9/18` 当天内删除。 |
| transitionToIA                 | 否  | 文件生命周期中转为低频存储的日期，int64 类型，Unix 时间戳格式 ，具体日期计算参考 [生命周期管理](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management) 。文件在设置转低频后才会返回该字段（通过生命周期规则设置文件转低频，仅对该功能发布后满足规则条件新上传文件返回该字段；历史文件想要返回该字段需要在功能发布后可通过 [修改文件生命周期 API](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management) 指定转低频时间；对于已经设置过转低频时间的历史文件，到期都会正常执行，只是服务端没有该字段返回)   例如：值为 `1568736000` 的时间，表示文件会在 `2019/9/18` 当天转为低频存储类型。                                                        |
| transitionToIntelligentTiering | 否  | 文件生命周期中转为智能分层存储的日期，int64 类型，Unix 时间戳格式 ，具体日期计算参考 [生命周期管理](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management) 。文件在设置转智能分层后才会返回该字段   例如：值为 `1568736000` 的时间，表示文件会在 `2021/9/18` 当天转为智能分层存储类型。                                                                                                                                                                                                                                                                                 |
| transitionToArchiveIR          | 否  | 文件生命周期中转为归档直读存储的日期，int64 类型，Unix 时间戳格式 ，具体日期计算参考 [生命周期管理](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management) 。文件在设置转归档后才会返回该字段   例如：值为 `1568736000` 的时间，表示文件会在 `2019/9/18` 当天转为归档直读存储类型。                                                                                                                                                                                                                                                                                   |
| transitionToARCHIVE            | 否  | 文件生命周期中转为归档存储的日期，int64 类型，Unix 时间戳格式 ，具体日期计算参考 [生命周期管理](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management) 。文件在设置转归档后才会返回该字段（通过生命周期规则设置文件转归档，仅对该功能发布后满足规则条件新上传文件返回该字段；历史文件想要返回该字段需要在功能发布后可通过 [修改文件生命周期 API](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management) 指定转归档时间；对于已经设置过转归档时间的历史文件，到期都会正常执行，只是服务端没有该字段返回)   例如：值为 `1568736000` 的时间，表示文件会在 `2019/9/18` 当天转为归档存储类型。                                                        |
| transitionToDeepArchive        | 否  | 文件生命周期中转为深度归档存储的日期，int64 类型，Unix 时间戳格式 ，具体日期计算参考 [生命周期管理](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management) 。文件在设置转深度归档后才会返回该字段   例如：值为 `1568736000` 的时间，表示文件会在 `2019/9/18` 当天转为深度归档存储类型。                                                                                                                                                                                                                                                                                 |
| cacheControl                   | 否  | 指定文件下载时的缓存行为，仅当对象元数据包含此项时才会返回该头部。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| contentLanguage                | 否  | 描述文件所用的语言，仅当对象元数据包含此项时才会返回该头部。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| contentEncoding                | 否  | 声明文件的编码方式，仅当对象元数据包含此项时才会返回该头部。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| contentDisposition             | 否  | 指定文件的展示形式，仅当对象元数据包含此项时才会返回该头部。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| expires                        | 否  | RFC2616 中定义的缓存失效时间，仅当对象元数据包含此项时才会返回该头部。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

### 响应状态码 [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅 [错误响应](/products/kodo/development-guidelines/upload-types/3-simple-response) 。

## 示例 [#示例]

### 请求示例 [#请求示例]

```
GET /stat/ZGVtbzoyMDEzLTAyLTA5LTA3LTM5LTIwLmpwZw== HTTP/1.1
User-Agent: curl/7.30.0
Host: rs.qiniuapi.com
Accept: */*
Content-Type: application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r72Vsn...(过长已省略)
```

*注：要在 `Authorization` 头部的 `&lt;AccessToken&gt;` 前添加 `Qiniu` 和半角空格。*

### 响应示例 [#响应示例]

```
HTTP/1.1 200 OK
Server: nginx/1.0.8
Date: Mon, 02 Jan 2006 15:04:05 GMT
Content-Type: application/json
Connection: keep-alive
Cache-Control: no-store
Content-Length: 121
X-Log: qtbl.get;RS
X-Reqid: swEAAMipp-5bIjMT

{
    "fsize":        5122935,
    "hash":         "ljfockr0lOil_bZfyaI2ZY78HWoH",
    "mimeType":     "application/octet-stream",
    "putTime":      13603956734587420,
    "md5":          "e41714a18899cf59c200a9bddfa78b95"
}
```


# 直传文件 (/products/kodo/rs/8-upload)



最近更新时间: 2025-12-16 16:02:39

## 描述 [#描述]

本接口用于在一次 HTTP 会话中上传单一的一个文件。

## 请求 [#请求]

### 请求语法 [#请求语法]

请求报文的内容以 `multipart/form-data` 格式组织：

```
POST / HTTP/1.1
Host:           <UpHost>
Content-Type:   multipart/form-data; boundary=<Boundary>
Content-Length: <MultipartContentLength>

--<Boundary>
Content-Disposition:       form-data; name="key"

<key>
--<Boundary>
Content-Disposition:       form-data; name="x:<customName>"

<customValue>
--<Boundary>
Content-Disposition:       form-data; name="token"

<token>
--<Boundary>
Content-Disposition:       form-data; name="crc32"

<crc32>
--<Boundary>
Content-Disposition: form-data; name="x-qn-meta-<metaKey>"

<metaValue>
--<Boundary>
Content-Disposition: form-data; name="cacheControl"

<cacheControl>
--<Boundary>
Content-Disposition: form-data; name="contentLanguage"

<contentLanguage>
--<Boundary>
Content-Disposition: form-data; name="contentEncoding"

<contentEncoding>
--<Boundary>
Content-Disposition: form-data; name="contentDisposition"

<contentDisposition>
--<Boundary>
Content-Disposition: form-data; name="expires"

<expires>
--<Boundary>
Content-Disposition:       form-data; name="accept"

<accept>
--<Boundary>
Content-Disposition:       form-data; name="file"; filename="<filename>"
Content-Type:              <mimeType>
Content-Transfer-Encoding: binary

<fileContent>
--<Boundary>--
```

### 请求头 [#请求头]

| 头部名称 | 必填 | 说明                                                                         |
| ---- | -- | -------------------------------------------------------------------------- |
| Host | 是  | 上传域名。七牛对象存储支持的区域和对应区域上传域名列表见 [存储区域列表](/products/kodo/2-region-endpoint-fq) |

### 请求内容 [#请求内容]

| 参数名称               | 必填 | 说明                                                                                                                                                                                                                                                                                                            |
| ------------------ | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key                | 否  | 资源名，必须是UTF-8编码。如果 [上传凭证](/products/kodo/development-guidelines/security/2-upload-token) 中 scope 指定为 \<bucket>:\<key>， 则该字段也必须指定，并且与上传凭证中的 key 一致，否则会报 `403` 错误。如果表单没有指定 key，可以使用上传策略 [saveKey](/products/kodo/development-guidelines/security/1-put-policy#save-key) 字段所指定魔法变量生成 Key，如果没有模板，则使用 Hash 值作为 Key。 |
| customName         | 否  | [自定义变量](/products/kodo/development-guidelines/upload-types/0-vars#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%98%E9%87%8F) 的名字，不限个数。                                                                                                                                                                                    |
| customValue        | 否  | [自定义变量](/products/kodo/development-guidelines/upload-types/0-vars#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%98%E9%87%8F) 的值。                                                                                                                                                                                          |
| token              | 是  | [上传凭证](/products/kodo/development-guidelines/security/2-upload-token) ，位于 token 消息中。                                                                                                                                                                                                                          |
| crc32              | 否  | 上传内容的 CRC32 校验码。如果指定此值，则七牛服务器会使用此值进行内容检验。                                                                                                                                                                                                                                                                     |
| x-qn-meta-         | 否  | 自定义元数据，可同时自定义多组元数据，总和大小不能超过 1024 字节。                                                                                                                                                                                                                                                                          |
| cacheControl       | 否  | 指定文件下载时的缓存行为。详见 [Cache-Control](https://www.rfc-editor.org/rfc/rfc9111#section-5.2)                                                                                                                                                                                                                           |
| contentLanguage    | 否  | 描述文件所用的语言                                                                                                                                                                                                                                                                                                     |
| contentEncoding    | 否  | 声明文件的编码方式。必须按照文件的实际编码类型填写，否则可能造成客户端解析失败或下载失败。若文件未编码，请置空此项。详见 [Content-Encoding](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-encoding)                                                                                                                                                           |
| contentDisposition | 否  | 指定文件的展示形式。详见 [Content-Disposition](https://www.rfc-editor.org/rfc/rfc6266#section-4)                                                                                                                                                                                                                          |
| expires            | 否  | RFC2616 中定义的缓存失效时间。详见 [Expires](https://www.rfc-editor.org/rfc/rfc7234#section-5.3)                                                                                                                                                                                                                           |
| accept             | 否  | 当 HTTP 请求指定 accept 头部时，七牛会返回 Content-Type 头部值。该值用于兼容低版本 IE 浏览器行为。低版本 IE 浏览器在表单上传时，返回 application/json 表示下载，返回 text/plain 才会显示返回内容。                                                                                                                                                                            |
| filename           | 是  | 原文件名。对于没有文件名的情况，建议填入随机生成的纯文本字符串。本参数的值将作为魔法变量 [$(fname)](/products/kodo/development-guidelines/upload-types/0-vars#magicvar-fname) 的值使用。                                                                                                                                                                       |
| fileContent        | 是  | 上传文件的完整内容。文件大小不超过 1GB。                                                                                                                                                                                                                                                                                        |

## 响应 [#响应]

### 响应语法 [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
 {
 hash:"xx"
 key:"xx"
}
```

### 响应头 [#响应头]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅 [公共响应头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header) 。

### 响应内容 [#响应内容]

| 名称   | 说明                                                                                                            |
| ---- | ------------------------------------------------------------------------------------------------------------- |
| hash | 目标资源的 [hash值](/products/kodo/development-guidelines/upload-types/0-vars#qiniu-etag) ，可用于 ETag 头部。      类型：字符串 |
| key  | 目标资源的最终名字，可由七牛云存储自动命名。      类型：字符串                                                                            |

### 响应状态码 [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅 [错误响应](/products/kodo/development-guidelines/upload-types/3-simple-response) 。

## 在线示例 [#在线示例]

* [JS表单上传（异步）](https://kodo-utils.qiniu.com/upload-token?ref=developer.qiniu.com\&s_path=%2Fkodo%2F1208%2Fupload-token)


# 修改文件生命周期 (/products/kodo/rs/8062-modify-object-life-cycle)



最近更新时间: 2024-08-12 15:48:14

# **描述** [#描述]

本接口用于修改已上传文件 Object 的 [生命周期](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management)。后续可以通过 [资源元信息查询](/products/kodo/rs/7-stat) 看到修改生命周期相关时间。

<br />

# **请求** [#请求]

### **请求语法** [#请求语法]

```
POST /lifecycle/<EncodedEntryURI>/toIAAfterDays/<ToIAAfterDays>/toIntelligentTieringAfterDays/<ToIntelligentTieringAfterDays>/toArchiveAfterDays/<ToArchiveAfterDays>/toDeepArchiveAfterDays/<ToDeepArchiveAfterDays>/deleteAfterDays/<DeleteAfterDays> HTTP/1.1
Host:           rs.qiniuapi.com
Content-Type:   application/x-www-form-urlencoded
X-Qiniu-Date:   20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

<br />

## 请求参数 [#请求参数]

| 参数名称                          | 是否必填 | 说明                                                                                     |
| ----------------------------- | ---- | -------------------------------------------------------------------------------------- |
| EncodedEntryURI               | 是    | 指定文件信息，详情参考 [EncodedEntryURI](/products/kodo/0-data-format)                            |
| ToIAAfterDays                 | 否    | 指定文件上传后在设置的 ToIAAfterDays 转换到 低频存储类型，设置为 `-1` 表示取消已设置的转低频存储的生命周期规则                     |
| ToIntelligentTieringAfterDays | 否    | 指定文件上传后在设置的 ToIntelligentTieringAfterDays 转换到 智能分层存储类型，设置为 `-1` 表示取消已设置的转智能分层存储的生命周期规则 |
| ToArchiveIRAfterDays          | 否    | 指定文件上传后在设置的 ToArchiveIRAfterDays 转换到 归档直读存储类型， 设置为 `-1` 表示取消已设置的转归档直读存储的生命周期规则         |
| ToArchiveAfterDays            | 否    | 指定文件上传后在设置的 ToArchiveAfterDays 转换到 归档存储类型， 设置为 `-1` 表示取消已设置的转归档存储的生命周期规则               |
| ToDeepArchiveAfterDays        | 否    | 指定文件上传后在设置的 ToDeepArchiveAfterDays 转换到 深度归档存储类型， 设置为 `-1` 表示取消已设置的转深度归档存储的生命周期规则       |
| DeleteAfterDays               | 否    | 指定文件上传后在设置的 DeleteAfterDays 过期删除，删除后不可恢复，设置为 `-1` 表示取消已设置的过期删除的生命周期规则                  |

<br />

### **请求头** [#请求头]

| 头部名称          | 必填 | 说明                                                                                                                                                                    |
| :------------ | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | 是  | 该参数应严格按照[管理凭证](/products/kodo/development-guidelines/security/access-token)格式进行填充，否则会返回 401 错误码<br />一个合法的 Authorization 值应类似于：`Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他            |    | 请查阅[公共请求头](/products/kodo/3924-common-request-headers)                                                                                                                |

<br />

<a id="chgm-response" />

### **请求内容** [#请求内容]

该请求操作的请求体为空。

<br />

# **响应** [#响应]

### **响应语法** [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
```

<br />

### **响应头** [#响应头]

| 头部名称         | 必填 | 说明                                                                  |
| :----------- | :- | :------------------------------------------------------------------ |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json`，表示返回 JSON 格式的文本信息。                   |
| 其他           |    | 其它可能返回的头部信息，请参考[公共响应头](/products/kodo/3924-common-request-headers)。 |

<br />

### **响应内容** [#响应内容]

如果请求成功，不返回任何内容。
如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "error":   "<errMsg    string>",
}
```

| 字段名称  | 必填 | 说明                |
| :---- | :- | :---------------- |
| error | 是  | 与 HTTP 状态码对应的消息文本 |

<br />

<a id="copy-response-copyus" />

### **响应状态码** [#响应状态码]

| HTTP状态码 | 含义                                             |
| :------ | :--------------------------------------------- |
| 200     | 更新成功                                           |
| 400     | 请求报文格式错误                                       |
| 401     | 管理凭证无效                                         |
| 599     | 服务端操作失败                                        |
| 612     | 待设置生命周期的资源不存在                                  |
| 其他错误码   | 请查阅[错误响应](/products/kodo/3928-error-responses) |

如遇 599 错误，请将完整错误信息（包括所有 HTTP 响应头部）[提交工单](https://support.qiniu.com/tickets/category) 给我们。

<br />

# **示例** [#示例]

### **请求示例** [#请求示例]

```
POST /lifecycle/bmV3ZG9jczpmaW5kX21hbi50eHQ=/ToArchiveAfterDays/-1 HTTP/1.1
User-Agent: curl/7.30.0
Host: rs.qiniuapi.com
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...(过长已省略)
```

*注：要在 `Authorization` 头部的 `<AccessToken>` 前添加 `Qiniu` 和半角空格。*

<br />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Server: nginx/1.0.8
Date: Mon, 02 Jan 2006 15:04:05 GMT
Content-Type: application/json
Connection: keep-alive
Content-Length: 0
X-Reqid: wxIAAD3btw-v3TwT
```


# 修改文件存储类型 (/products/kodo/rs/9-modify-the-file-storage-type)



最近更新时间: 2025-03-28 10:39:03

# **描述** [#描述]

本接口用于修改文件的存储类型信息，可以实现标准存储、低频存储、智能分层存储、归档直读存储、归档存储和深度归档存储之间的互相转换。
低频存储、归档直读存储、归档存储、深度归档存储有最短存储时间要求，修改为其他存储类型时可能会产生提前删除的计量计费。详情参见 [计量项与计费项](/products/kodo/1-metering-and-billing) 说明

<br />

# **请求** [#请求]

### **请求语法** [#请求语法]

```
POST /chtype/<EncodedEntryURI>/type/<type> HTTP/1.1
Host:           rs.qiniuapi.com
Content-Type:   application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

使用说明：

* 归档/深度归档存储文件，只有解冻状态时可以修改存储类型。

<br />

### **请求参数** [#请求参数]

| 参数名称            | 必填 | 说明                                                               |
| --------------- | -- | ---------------------------------------------------------------- |
| EncodedEntryURI | 是  | 指定文件信息，详情请参考[EncodedEntryURI](/products/kodo/0-data-format)      |
| type            | 是  | 值为数字，0 表示标准存储，1 表示低频存储，2 表示归档存储，3 表示深度归档存储，4 表示归档直读存储，5 表示智能分层存储 |

<br />

### **请求头** [#请求头]

| 头部名称          | 必填 | 说明                                                                                                                                                                    |
| :------------ | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | 是  | 该参数应严格按照[管理凭证](/products/kodo/development-guidelines/security/access-token)格式进行填充，否则会返回 401 错误码<br />一个合法的 Authorization 值应类似于：`Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他            |    | 请查阅[公共请求头](/products/kodo/3924-common-request-headers)                                                                                                                |

<br />

### **请求内容** [#请求内容]

该请求操作的请求体为空。

<br />

# **响应** [#响应]

### **响应语法** [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
```

<br />

### **响应头** [#响应头]

| 头部名称         | 必填 | 说明                                                                  |
| :----------- | :- | :------------------------------------------------------------------ |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json`，表示返回 JSON 格式的文本信息。                   |
| 其他           |    | 其它可能返回的头部信息，请参考[公共响应头](/products/kodo/3924-common-request-headers)。 |

<br />

### **响应内容** [#响应内容]

如果请求成功，不返回任何内容。
如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "error":   "<errMsg    string>",
}
```

| 字段名称  | 必填 | 说明                |
| :---- | :- | :---------------- |
| error | 是  | 与 HTTP 状态码对应的消息文本 |

<br />

<a id="chtype-response-status" />

### **响应状态码** [#响应状态码]

| HTTP状态码                                                                                   | 含义                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| :---------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 200                                                                                       | 更改成功                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 400                                                                                       | 请求报文格式错误<br />当 `&lt;EncodedEntryURI&gt;` 解析失败，返回 `400 Bad Request {"error":"invalid argument"}`<br />当 `&lt;EncodedEntryURI&gt;` 不符合UTF-8编码，返回 `400 Bad Request {"error":"key must be utf8 encoding"}`<br />当文件类型已经是普通存储仍然转换成普通存储会返回 `400 Bad Request {"error":"already in normal stat"}`<br />当文件类型已经是低频存储仍然转换成低频存储会返回 `400 Bad Request {"error":"already in line stat"}`<br />当文件类型已经是归档直读存储仍然转换成归档制度存储会返回 `400 Bad Request {"error":"already in archive_ir stat"}`<br />当文件类型已经是归档存储仍然转换成归档存储会返回 `400 Bad Request {"error":"already in archive stat"}`<br />当文件类型已经是深度归档存储仍然转换成深度归档存储会返回 `400 Bad Request {"error":"already in deep archive stat"}` |
| 401                                                                                       | 管理凭证无效                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 403                                                                                       | 禁止操作<br />当归档存储文件未解冻完成时调用接口会返回 `403 ArchiveUnrestored {"error":"archive unrestored"}`<br />当深度归档存储文件未解冻完成时调用接口会返回 `403 DeepArchiveUnrestored {"error":"deep archive unrestored"}`                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 612                                                                                       | 目标文件不存在                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 其他错误码                                                                                     | 请查阅[错误响应](/products/kodo/3928-error-responses)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 如遇 599 错误，请将完整错误信息（包括所有 HTTP 响应头部）[提交工单](https://support.qiniu.com/tickets/category) 给我们。 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

<br />

<a id="chtype-samples" />

# **示例** [#示例]

### **请求示例** [#请求示例]

```
POST /chtype/aXRpc2F0ZXN0OmdvZ29waGVyLmpwZw==/type/1 HTTP/1.1
User-Agent: curl/7.30.0
Host: rs.qiniuapi.com
Accept: */*
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu bt500PzCG9tV0bccCOdnrmCHPXCPLieGSDEprB7M:4wG...(过长已省略)
```

*注：要在 `Authorization` 头部的 `<AccessToken>` 前添加 `Qiniu` 和半角空格。*

<br />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Server: nginx/1.4.4
Date: Mon, 02 Jan 2006 15:04:05 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
X-Reqid: vDEAAG2lN7zSqpQT
```


# 修改文件过期删除时间 (/products/kodo/rs/9-update-file-lifecycle)



最近更新时间: 2023-03-02 18:59:52

## 描述 [#描述]

本接口用于修改指定资源的过期删除时间。\
修改指定资源生命周期其他时间，比如转低频存储时间和转归档存储时间，请参考 [修改文件生命周期](/products/kodo/development-guidelines/management-of-storage-space/7-dev-life-cycle-management) 。后续可以通过 [资源元信息查询](/products/kodo/rs/7-stat) 查看修改生命周期相关时间。

## 请求 [#请求]

### 请求语法 [#请求语法]

```
POST /deleteAfterDays/<EncodedEntryURI>/<deleteAfterDays> HTTP/1.1
Host:           rs.qiniuapi.com
Content-Type:   application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization:  Qiniu <AccessToken>
```

使用说明：

* 文件在设置的 `&lt;deleteAfterDays&gt;` 天之后被删除， **删除后不可恢复**

### 请求参数 [#请求参数]

| 参数名称            | 必填 | 说明                                                           |
| --------------- | -- | ------------------------------------------------------------ |
| EncodedEntryURI | 是  | 指定文件信息，详情请参考 [EncodedEntryURI](/products/kodo/0-data-format) |
| deleteAfterDays | 是  | 值为数字，设置为 0 表示取消过期删除设置                                        |

### 请求头 [#请求头]

| 头部名称          | 必填 | 说明                                                                                                                                                                   |
| ------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | 是  | 该参数应严格按照 [管理凭证](/products/kodo/development-guidelines/security/access-token) 格式进行填充，否则会返回 401 错误码  一个合法的 Authorization 值应类似于： `Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...` |
| 其他            |    | 请查阅 [公共请求头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header)                                                                          |

### 请求内容 [#请求内容]

该请求操作的请求体为空。

## 响应 [#响应]

### 响应语法 [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
```

### 响应头 [#响应头]

| 头部名称         | 必填 | 说明                                                                                                        |
| ------------ | -- | --------------------------------------------------------------------------------------------------------- |
| Content-Type | 是  | 正常情况下该值将被设为 `application/json` ，表示返回 JSON 格式的文本信息。                                                        |
| 其他           |    | 其它可能返回的头部信息，请参考 [公共响应头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header) 。 |

### 响应内容 [#响应内容]

如果请求成功，不返回任何内容。\
如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

```
{
    "error":   "<errMsg    string>",
}
```

| 字段名称  | 必填 | 说明                |
| ----- | -- | ----------------- |
| error | 是  | 与 HTTP 状态码对应的消息文本 |

### 响应状态码 [#响应状态码]

| HTTP状态码 | 含义                                                                               |
| ------- | -------------------------------------------------------------------------------- |
| 200     | 更新成功                                                                             |
| 400     | 请求报文格式错误                                                                         |
| 401     | 管理凭证无效                                                                           |
| 599     | 服务端操作失败                                                                          |
| 612     | 待设置生命周期的资源不存在                                                                    |
| 其他错误码   | 请查阅 [错误响应](/products/kodo/development-guidelines/upload-types/3-simple-response) |

如遇 599 错误，请将完整错误信息（包括所有 HTTP 响应头部） [提交工单](https://support.qiniu.com/tickets/category) 给我们。

## 示例 [#示例]

### 请求示例 [#请求示例]

```
POST /deleteAfterDays/bmV3ZG9jczpmaW5kX21hbi50eHQ=/1 HTTP/1.1
User-Agent: curl/7.30.0
Host: rs.qiniuapi.com
X-Qiniu-Date: 20060102T150405Z
Accept: */*
Authorization: Qiniu u8WqmQu1jH21kxpIQmo2LqntzugM1VoHE9_pozCU:2LJIG...(过长已省略)
```

*注：要在 `Authorization` 头部的 `&lt;AccessToken&gt;` 前添加 `Qiniu` 和半角空格。*

### 响应示例 [#响应示例]

```
HTTP/1.1 200 OK
Server: nginx/1.0.8
Date: Mon, 02 Jan 2006 15:04:05 GMT
Content-Type: application/json
Connection: keep-alive
Content-Length: 0
X-Reqid: wxIAAD3btw-v3TwT
```


# Object 接口 (/products/kodo/rs)



最近更新时间: 2021-12-06 12:19:58

对象管理相关的接口：

| 接口                                                                                                  | 说明                                                      |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| [upload](/products/kodo/rs/8-upload)                                                                | 用于在一次 HTTP 会话中上传单一的一个对象                                 |
| [mkblk](/products/kodo/rs/shard-to-upload/1-mkblk)                                                  | 为后续分片上传创建一个新的块，同时上传第一片数据                                |
| [bput](/products/kodo/rs/shard-to-upload/0-bput)                                                    | 上传指定块的一片数据，具体数据量可根据现场环境调整，同一块的每片数据必须串行上传                |
| [mkfile](/products/kodo/rs/shard-to-upload/2-mkfile)                                                | 将上传好的所有数据块按指定顺序合并成一个对象资源                                |
| [initiateMultipartUpload](/products/kodo/rs/multipartupload-interface/0-initialize-multipartupload) | 通知服务端开启分块上传任务,得到全局唯一任务UploadId                          |
| [uploadPart](/products/kodo/rs/multipartupload-interface/1-upload-part)                             | 分块上传数据，需指定的任务UploadId                                   |
| [completeMultipartUpload](/products/kodo/rs/multipartupload-interface/3-complete-multipart-upload)  | 完成整个对象的分块上传，需指定的任务UploadId                              |
| [abortMultipartUpload](/products/kodo/rs/multipartupload-interface/2-abort-multipart-upload)        | 中止分块上传任务，并且删除已经上传的块，需指定的任务UploadId                      |
| [listParts](/products/kodo/rs/multipartupload-interface/4-listparts)                                | 列举指定 UploadId 所属的所有已经上传成功Part                           |
| [list](/products/kodo/rs/4-list)                                                                    | 用于列举指定空间里的所有对象条目                                        |
| [stat](/products/kodo/rs/7-stat)                                                                    | 仅获取对象的 Metadata 信息，不返回对象内容                              |
| [chgm](/products/kodo/rs/1-chgm)                                                                    | 修改对象的 MIME 类型信息                                         |
| [move](/products/kodo/rs/5-move)                                                                    | 将源空间的指定对象移动到目标空间，或在同一空间内对对象重命名                          |
| [copy](/products/kodo/rs/2-copy)                                                                    | 将指定对象复制为新命名对象                                           |
| [delete](/products/kodo/rs/3-delete)                                                                | 删除指定对象                                                  |
| [batch](/products/kodo/rs/0-batch)                                                                  | 指在单一请求中执行多次获取元信息、移动、复制、删除操作，极大提高对象管理效率                  |
| [chstatus](/products/kodo/rs/11-modify-the-file-status)                                             | 修改对象的存储状态，即切换启用、禁用状态                                    |
| [chtype](/products/kodo/rs/9-modify-the-file-storage-type)                                          | 修改对象的存储类型信息，即低频存储、标准存储和归档存储的互相转换                        |
| [restoreAr](/products/kodo/rs/12-restore-archive)                                                   | 解冻归档存储类型的对象                                             |
| [deleteAfterDays](/products/kodo/rs/9-update-file-lifecycle)                                        | 设置一个对象多少天后过期删除                                          |
| [lifecycle](/products/kodo/rs/8062-modify-object-life-cycle)                                        | 修改已上传对象的生命周期，即修改对象转低频时间、转归档时间、过期删除时间                    |
| [prefetch](/products/kodo/rs/6-prefetch)                                                            | 对于设置了镜像存储的空间，从镜像源站抓取指定名称的对象并存储到该空间中                     |
| [sisyphus/fetch](/products/kodo/rs/10-asynch-fetch)                                                 | 从指定 URL 抓取对象，并将该对象存储到指定空间中。每次只抓取一个对象，抓取时可以指定保存空间名和最终对象名 |

<br />


# 创建 Bucket (/products/kodo/the-bucket-interface/0-mkbucketv3)



最近更新时间: 2025-11-05 10:54:35

<a id="mkbucketv3-description" />

# **描述** [#描述]

本接口用于创建一个新的 Bucket。此接口不支持匿名请求。您可以在请求参数中指定存储区域，例如，您在华东，选择华东存储区域可以减少延迟、降低成本。

<br />

<a id="mkbucketv3-requests" />

# **请求** [#请求]

<a id="mkbucketv3-requests-syntax" />

### **请求语法** [#请求语法]

```
POST /mkbucketv3/<BucketName>/region/<Region> HTTP/1.1
Host: uc.qiniuapi.com
Content-Type: application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu <AccessToken>
```

使用说明：

* 如果请求的 Bucket 已经存在/重名，返回错误码 614，错误信息：目标资源已存在。

* 如果创建的 Bucket 不符合命名规范，返回错误码 400，错误信息：invalid arguments。

* 如果发起创建 Bucket 请求的时候，没有传入认证信息，返回错误码 401，错误信息：bad token。

* 如果创建 Bucket 的时候超过最大创建数（默认 20 个），返回错误码 630，错误信息：too many buckets。

* 目前 Bucket 有两种访问权限：公开和私有。创建的 Bucket，默认为公开权限。

* Bucket 名称和其存储所在区域在创建后无法修改。

<br />

<a id="mkbucketv3-request-parameters" />

### **请求参数** [#请求参数]

| 参数名称       | 必填 | 说明                                                                                              |
| ---------- | -- | ----------------------------------------------------------------------------------------------- |
| BucketName | 是  | 空间名称，要求**在对象存储系统范围内唯一**，由3～63个字符组成，支持小写字母、短划线`-`和数字，且必须以小写字母或数字开头和结尾。                           |
| Region     | 否  | 存储区域 ID，默认 z0。<span id="Null"> 存储区域 ID 列表见 [存储区域列表](/products/kodo/2-region-endpoint-fq)</span> |

<br />

<a id="mkbucketv3-request-headers" />

### **请求头** [#请求头]

该请求操作的实现使用了所有操作的公共请求头。有关详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

<br />

<a id="mkbucketv3-request-elements" />

### **请求内容** [#请求内容]

该请求操作的请求体为空。

<br />

<a id="mkbucketv3-responses" />

# **响应** [#响应]

<a id="mkbucketv3-request-headers" />

### **响应头** [#响应头]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

<br />

<a id="mkbucketv3-response-elements" />

### **响应内容** [#响应内容]

该请求操作的响应体为空。

<br />

<a id="mkbucketv3-special-errors" />

### **响应状态码** [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误响应](/products/kodo/3928-error-responses)。

<br />

<a id="mkbucketv3-examples" />

# **示例** [#示例]

<a id="mkbucketv3-request-examples" />

### **请求示例** [#请求示例]

```
POST /mkbucketv3/mybucketforvideo HTTP/1.1
Host: uc.qiniuapi.com
User-Agent: Go-http-client/1.1
Content-Length: 0
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:nP7NSSyGo4x3W_nJ8T9X1gJrgpk=
```

*注：要在 `Authorization` 头部的 `<AccessToken>` 前添加 `Qiniu` 和半角空格。*

<br />

<a id="mkbucketv3-response-examples" />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Content-Length: 2
Connection: keep-alive
Content-Type: application/json
Date: Mon, 02 Jan 2006 15:04:05 GMT
Server: nginx
X-Reqid: SFkAAAC8BDebTtsU

{}
```


# 删除 Bucket (/products/kodo/the-bucket-interface/1-drop-bucket)



最近更新时间: 2023-03-01 17:47:02

## 描述 [#描述]

本接口用于删除指定的 Bucket。

## 请求 [#请求]

### 请求语法 [#请求语法]

```
POST /drop/<BucketName> HTTP/1.1
Host: uc.qiniuapi.com
Content-Type: application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu <AccessToken>
```

使用说明：

* 删除存储空间后，其中保存的文件也会被删除，无法恢复。
* 删除存储空间后，空间名称可以被重新使用。

### 请求参数 [#请求参数]

| 参数名称       | 必填 | 说明         |
| ---------- | -- | ---------- |
| BucketName | 是  | 需要删除的目标空间名 |

### 请求头 [#请求头]

该请求操作的实现使用了所有操作的公共请求头。有关详细信息，请查阅 [公共请求头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header) 。

### 请求内容 [#请求内容]

该请求操作的请求体为空。

## 响应 [#响应]

### 响应头 [#响应头]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅 [公共响应头](/products/kodo/development-guidelines/aws-s3-compatible/1-s3-compatible-header) 。

### 响应内容 [#响应内容]

该请求操作的响应体为空。

### 响应状态码 [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅 [错误响应](/products/kodo/development-guidelines/upload-types/3-simple-response) 。

## 示例 [#示例]

### 请求示例 [#请求示例]

```
POST /drop/test05 HTTP/1.1
Host: uc.qiniuapi.com
User-Agent: Go-http-client/1.1
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:nj2E4apIRDq67g_PMJ932w_2qiA=
```

*注：要在 `Authorization` 头部的 `&lt;AccessToken&gt;` 前添加 `Qiniu` 和半角空格。*

### 响应示例 [#响应示例]

```
HTTP/1.1 200 OK
Content-Length: 2
Connection: keep-alive
Content-Type: application/json
Date: Mon, 02 Jan 2006 15:04:05 GMT
Server: nginx
X-Reqid: r3oAAD-vqeUyT9sU

{}
```


# 获取 Bucket 空间域名 (/products/kodo/the-bucket-interface/2-get-the-bucket-space-domain)



最近更新时间: 2026-01-04 15:11:36

<a id="buckets-description" />

# **描述** [#描述]

本接口用于获取 Bucket 的域名列表。

<br />

<a id="buckets-requests" />

# **请求** [#请求]

<a id="buckets-requests-syntax" />

### **请求语法** [#请求语法]

```
GET /v2/domains?tbl=<bucketName> HTTP/1.1
Host: uc.qiniuapi.com
Content-Type: application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu <AccessToken>
```

<br />

<a id="buckets-request-parameters" />

### **请求参数** [#请求参数]

| 参数名称 | 必填 | 说明             |
| ---- | -- | -------------- |
| tbl  | 是  | 要获取域名列表的目标空间名称 |

<br />

<a id="buckets-request-headers" />

### **请求头** [#请求头]

该请求操作的实现使用了所有操作的公共请求头。有关详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

<br />

<a id="buckets-request-elements" />

### **请求内容** [#请求内容]

该请求操作的请求体为空。

<br />

<a id="buckets-responses" />

# **响应** [#响应]

### **响应语法** [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
{
DomainName
}
```

<br />

### **响应头** [#响应头]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

<br />

<a id="buckets-response-elements" />

### **响应内容** [#响应内容]

| 名称         | 说明                      |
| ---------- | ----------------------- |
| DomainName | 空间域名<br /><br /> 类型：字符串 |

<br />

<a id="buckets-special-errors" />

### **响应状态码** [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误响应](/products/kodo/3928-error-responses)。

<br />

<a id="buckets-examples" />

# **示例** [#示例]

<a id="buckets-request-examples" />

### **请求示例** [#请求示例]

```
GET /v2/domains?tbl=test01 HTTP/1.1
Host: uc.qiniuapi.com
User-Agent: Go-http-client/1.1
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:jfblnkj6JsrlxgbE3l4SfhSyiL4=
Accept-Encoding: gzip
```

*注：要在 `Authorization` 头部的 `<AccessToken>` 前添加 `Qiniu` 和半角空格。*

<br />

<a id="buckets-response-examples" />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Date: Mon, 02 Jan 2006 15:04:05 GMT
Server: nginx
Vary: Accept-Encoding
X-Reqid: BksAALTAQtVZhdsU

[
  "oupgm4mi4.bkt.clouddn.com",
  "sarah.qiniudemo.com"
]
```


# 设置空间标签 (/products/kodo/the-bucket-interface/3-put-bucket-tagging)



最近更新时间: 2025-11-05 10:54:35

<a id="putbucketTagging-description" />

# **描述** [#描述]

本接口用于设置空间标签，包括新增和修改。

<br />

<a id="putbucketTagging-requests" />

# **请求** [#请求]

<a id="putbucketTagging-requests-syntax" />

### **请求语法** [#请求语法]

```
PUT /bucketTagging?bucket=<BucketName> HTTP/1.1
Host: uc.qiniuapi.com
Content-Type: application/json
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu <AccessToken>

{
    "Tags":[
            {"Key":xx, "Value": xx},
            {"Key":xx, "Value": xx},
            ...
        ]
}
```

使用说明：

* 标签（tag）是 Key-Value的结构，同一个Bucket下，Key必须是唯一的, 且一个Key只能有1个Value，Key设置重复时服务端会返回400: tag contain duplicate key。

* 每个Bucket最多可以设置10对标签，超出限制时服务端会返回400: tag num exceed limit。

* API是覆盖语义，调用时会替换整个Bucket的标签，比如：原来Bucket有10对标签, 想更新其中1对，request.body应该包含9对old tag + 1对 new tag。

<br />

<a id="putbucketTagging-request-parameters" />

### **请求参数** [#请求参数]

| 参数名称       | 必填 | 说明                                                                                 |
| ---------- | -- | ---------------------------------------------------------------------------------- |
| BucketName | 是  | 空间名称                                                                               |
| Key        | 是  | 标签名称，最大64Byte，不能为空且大小写敏感，不能以kodo为前缀(预留), 不支持中文字符，可使用的字符有：字母，数字，空格，+ - = . \_ : / @ |
| Value      | 是  | 标签值，最大128Byte，不能为空且大小写敏感，不支持中文字符，可使用的字符有：字母，数字，空格，+ - = . \_ : / @                 |

<br />

<a id="putbucketTagging-request-headers" />

### **请求头** [#请求头]

该请求操作的实现使用了所有操作的公共请求头。有关详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

<br />

<a id="putbucketTagging-request-elements" />

### **请求内容** [#请求内容]

该请求操作的请求体为空。

<br />

<a id="putbucketTagging-responses" />

# **响应** [#响应]

<a id="putbucketTagging-request-headers" />

### **响应头** [#响应头]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

<br />

<a id="putbucketTagging-response-elements" />

### **响应内容** [#响应内容]

该请求操作的响应体为空。

<br />

<a id="putbucketTagging-special-errors" />

### **响应状态码** [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误响应](/products/kodo/3928-error-responses)。

<br />

<a id="putbucketTagging-examples" />

# **示例** [#示例]

<a id="putbucketTagging-request-examples" />

### **请求示例** [#请求示例]

```
PUT /bucketTagging?bucket=temp-bucket-jnacytgvzwpgiotaprp1z0 HTTP/1.1
Host: uc.qiniuapi.com
User-Agent: Go-http-client/1.1
Content-Length: 0
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:yfdfCaZNBlgi2HACEXRSgycc8IY=
Content-Type: application/json

{
	"Tags": [
		{
			"Key": "KODO-BUKCET-TAGS-key-qyxvhJ0b3l",
			"Value": "KODO-BUKCET-TAGS-value-tUwjRvCVzz"
		}
	]
}
```

<br />

<a id="putbucketTagging-response-examples" />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Content-Length: 2
Connection: keep-alive
Content-Type: application/json
Date: Mon, 02 Jan 2006 15:04:05 GMT
X-Reqid: rWkAAFTxT13GrdYV

{}
```


# 设置 Bucket 访问权限 (/products/kodo/the-bucket-interface/3946-set-bucket-private)



最近更新时间: 2025-11-05 10:54:35

<a id="private-description" />

# **描述** [#描述]

本接口用于设置 Bucket 访问权限。目前 Bucket 有两种访问权限：公开和私有。创建 Bucket 时默认为公开空间。

<br />

<a id="private-requests" />

# **请求** [#请求]

<a id="private-requests-syntax" />

### **请求语法** [#请求语法]

```
POST /private?bucket=<BucketName>&private=<Private> HTTP/1.1
Host: uc.qiniuapi.com
Content-Type: application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu <AccessToken>
```

<br />

<a id="private-request-parameters" />

### **请求参数** [#请求参数]

| 参数名称    | 必填 | 说明                            |
| ------- | -- | ----------------------------- |
| bucket  | 是  | 空间名称                          |
| private | 是  | <br />- `0` 公开 <br />- `1` 私有 |

<br />

<a id="private-request-headers" />

### **请求头** [#请求头]

该请求操作的实现使用了所有操作的公共请求头。有关详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

<br />

### **请求内容** [#请求内容]

该请求操作的请求体为空。

<br />

<a id="private-responses" />

# **响应** [#响应]

<a id="private-request-headers" />

### **响应头** [#响应头]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

<br />

<a id="private-response-elements" />

### **响应内容** [#响应内容]

该请求操作的响应体为空。

<br />

<a id="private-special-errors" />

### **响应状态码** [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误响应](/products/kodo/3928-error-responses)。

<br />

<a id="private-examples" />

# **示例** [#示例]

<a id="private-request-examples" />

### **请求示例** [#请求示例]

```
POST /private?bucket=test06&private=1 HTTP/1.1
Host: uc.qiniuapi.com
User-Agent: Go-http-client/1.1
Content-Length: 23
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu j853F3bLkWl59I5BOkWm6q1Z1mZClpr9Z9CLfDE0:YHLW5tnhbumBI56iQ0AzJdZONSY=
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip
```

<br />

<a id="private-response-examples" />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Content-Length: 2
Connection: keep-alive
Content-Type: application/json
Date: Mon, 02 Jan 2006 15:04:05 GMT
Server: nginx
X-Reqid: VBoAAJjbI4_ZmdsU

{}
```


# 删除空间标签 (/products/kodo/the-bucket-interface/4-delete-bucket-tagging)



最近更新时间: 2025-11-05 10:54:35

<a id="deletebucketTagging-description" />

# **描述** [#描述]

本接口用于一键删除指定空间的所有标签。

<br />

<a id="deletebucketTagging-requests" />

# **请求** [#请求]

<a id="deletebucketTagging-requests-syntax" />

### **请求语法** [#请求语法]

```
DELETE /bucketTagging?bucket=<BucketName> HTTP/1.1
Host: uc.qiniuapi.com
Content-Type: application/json
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu <AccessToken>
```

<br />

<a id="deletebucketTagging-request-parameters" />

### **请求参数** [#请求参数]

| 参数名称       | 必填 | 说明   |
| ---------- | -- | ---- |
| BucketName | 是  | 空间名称 |

<br />

<a id="deletebucketTagging-request-headers" />

### **请求头** [#请求头]

该请求操作的实现使用了所有操作的公共请求头。有关详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

<br />

<a id="deletebucketTagging-request-elements" />

### **请求内容** [#请求内容]

该请求操作的请求体为空。

<br />

<a id="deletebucketTagging-responses" />

# **响应** [#响应]

<a id="deletebucketTagging-request-headers" />

### **响应头** [#响应头]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

<br />

<a id="deletebucketTagging-response-elements" />

### **响应内容** [#响应内容]

该请求操作的响应体为空。

<br />

<a id="deletebucketTagging-special-errors" />

### **响应状态码** [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误响应](/products/kodo/3928-error-responses)。

<br />

<a id="deletebucketTagging-examples" />

# **示例** [#示例]

<a id="deletebucketTagging-request-examples" />

### **请求示例** [#请求示例]

```
DELETE /bucketTagging?bucket=temp-bucket-wdszkatkt3hdk3cid9dnz0 HTTP/1.1
Host: uc.qiniuapi.com
User-Agent: Go-http-client/1.1
Content-Length: 0
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:kHhCAVNFp4hti6x7YMMi1_9Fs7k=
Content-Type: application/json
```

<br />

<a id="deletebucketTagging-response-examples" />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Content-Length: 2
Connection: keep-alive
Content-Type: application/json
Date: Mon, 02 Jan 2006 15:04:05 GMT
X-Reqid: rWkAAJJlhDXGrdYV

{}
```


# 查询空间标签 (/products/kodo/the-bucket-interface/6315-get-bucket-tagging)



最近更新时间: 2025-11-05 10:54:35

<a id="getbucketTagging-description" />

# **描述** [#描述]

本接口用于查询指定空间已设置的标签信息。

<br />

<a id="getbucketTagging-requests" />

# **请求** [#请求]

<a id="getbucketTagging-requests-syntax" />

### **请求语法** [#请求语法]

```
GET /bucketTagging?bucket=<BucketName> HTTP/1.1
Host: uc.qiniuapi.com
Content-Type: application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu <AccessToken>
```

<br />

<a id="getbucketTagging-request-parameters" />

### **请求参数** [#请求参数]

| 参数名称       | 必填 | 说明   |
| ---------- | -- | ---- |
| BucketName | 是  | 空间名称 |

<br />

<a id="getbucketTagging-request-headers" />

### **请求头** [#请求头]

该请求操作的实现使用了所有操作的公共请求头。有关详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

<br />

<a id="getbucketTagging-request-elements" />

### **请求内容** [#请求内容]

该请求操作的请求体为空。

<br />

<a id="getbucketTagging-responses" />

# **响应** [#响应]

### **响应语法** [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
 {
 "Tags":[{"Key":xx,"Value":xx}]
}
```

<br />

<a id="getbucketTagging-request-headers" />

### **响应头** [#响应头]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

<br />

<a id="getbucketTagging-response-elements" />

### **响应内容** [#响应内容]

| 名称    | 说明   |
| ----- | ---- |
| Key   | 标签名称 |
| Value | 标签值  |

<br />

<a id="getbucketTagging-special-errors" />

### **响应状态码** [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误响应](/products/kodo/3928-error-responses)。

<br />

<a id="getbucketTagging-examples" />

# **示例** [#示例]

<a id="getbucketTagging-request-examples" />

### **请求示例** [#请求示例]

```
GET /bucketTagging?bucket=temp-bucket-jnacytgvzwpgiotaprp1z0 HTTP/1.1
Host: uc.qiniuapi.com
User-Agent: Go-http-client/1.1
Content-Length: 0
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:z_ksteUK6jI_0MLAaHNEPFqrpqY=
Content-Type: application/json
```

<br />

<a id="getbucketTagging-response-examples" />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Content-Length: 2
Connection: keep-alive
Content-Type: application/json
Date: Mon, 02 Jan 2006 15:04:05 GMT
X-Reqid: rWkAAGaeqzDGrdYV

 {
	"Tags": [
		{
			"Key": "123",
			"Value": "0000"
		},
		{
			"Key": "aaaaa",
			"Value": "bbbbb"
		}
	]
}
```


# Bucket 接口 (/products/kodo/the-bucket-interface)



最近更新时间: 2025-02-25 11:45:38

空间管理相关的接口：

| 接口                                                                                 | 说明              |
| ---------------------------------------------------------------------------------- | --------------- |
| [mkbucketv3](/products/kodo/the-bucket-interface/0-mkbucketv3)                     | 创建新的存储空间        |
| [drop](/products/kodo/the-bucket-interface/1-drop-bucket)                          | 删除指定存储空间        |
| [domains](/products/kodo/the-bucket-interface/2-get-the-bucket-space-domain)       | 获取一个空间绑定的所有域名列表 |
| [private](/products/kodo/the-bucket-interface/3946-set-bucket-private)             | 设置空间访问权限        |
| [putBucketTagging](/products/kodo/the-bucket-interface/3-put-bucket-tagging)       | 设置空间标签          |
| [getBucketTagging](/products/kodo/the-bucket-interface/6315-get-bucket-tagging)    | 查询空间标签          |
| [deleteBucketTagging](/products/kodo/the-bucket-interface/4-delete-bucket-tagging) | 删除空间标签          |


# 获取 Bucket 列表 (/products/kodo/the-service-interface/3926-get-service)



最近更新时间: 2024-05-21 14:10:26

<a id="buckets-description" />

# **描述** [#描述]

本接口作 GET 请求用来获取请求者拥有的所有存储空间列表。该接口需要您使用带 Authorization 签名认证的请求，如果使用匿名请求无法获取存储空间列表，且只能获取签名中 AccessKey 所属账户的存储空间列表。

<br />

<a id="buckets-requests" />

# **请求** [#请求]

<a id="buckets-requests-syntax" />

### **请求语法** [#请求语法]

```
GET /buckets?tagCondition=<Encodedtags> HTTP/1.1
Host: uc.qiniuapi.com
Content-Type: application/x-www-form-urlencoded
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu <AccessToken>
```

<br />

<a id="buckets-request-parameters" />

### **请求参数** [#请求参数]

| 参数名称        | 必填 | 说明                                                                                                                                                                                                                                                                                                   |
| ----------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Encodedtags | 否  | 过滤空间的标签或标签值条件，指定多个标签或标签值时同时满足条件的空间才会返回。参数值必须做[URL 安全的 Base64 编码](/products/kodo/development-guidelines/0-appendix#urlsafe-base64)。<br />按标签名过滤空间时，参数值设置为Encoded(key=key1;key=key2)；按标签值过滤空间时，参数值设置为Encoded(key=key1\&value=value1;key=key2\&value=value2)\<br>别人授权的空间，标签属性不传递，因此依据标签列举空间时只会返回自己创建的空间 |

<br />

<a id="buckets-request-headers" />

### **请求头** [#请求头]

该请求操作的实现使用了所有操作的公共请求头。有关详细信息，请查阅[公共请求头](/products/kodo/3924-common-request-headers)。

<br />

<a id="buckets-request-elements" />

### **请求内容** [#请求内容]

该请求操作的请求体为空。

<br />

<a id="buckets-responses" />

# **响应** [#响应]

### **响应语法** [#响应语法]

```
HTTP/1.1 200 OK
Content-Type: application/json
[
BucketName
]
```

<br />

<a id="buckets-response-headers" />

### **响应头** [#响应头]

该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅[公共响应头](/products/kodo/3924-common-request-headers)。

<br />

<a id="buckets-response-elements" />

### **响应内容** [#响应内容]

| 名称         | 说明                      |
| ---------- | ----------------------- |
| BucketName | 空间名称<br /><br /> 类型：字符串 |

<br />

<a id="buckets-special-errors" />

### **响应状态码** [#响应状态码]

该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅[错误响应](/products/kodo/3928-error-responses)。

<br />

<a id="buckets-examples" />

# **示例** [#示例]

<a id="buckets-request-examples" />

### **请求示例** [#请求示例]

```
GET /buckets?tagCondition=S09ETy1CVUtDRVQtVEFHUy1rZXktWDdPNjZiNkxLdz1LT0RPLUJVS0NFVC1UQUdTLXZhbHVlLWdFOGhIV2VXUGo= HTTP/1.1
Host: uc.qiniuapi.com
User-Agent: Go-http-client/1.1
X-Qiniu-Date: 20060102T150405Z
Authorization: Qiniu HwFOxpYCQU6oXoZXFOTh1mq5ZZig6Yyocgk3BTZZ:8tgafMszuwgd99Ix4eQ2HeVT9B0=
```

*注：要在 `Authorization` 头部的 `<AccessToken>` 前添加 `Qiniu` 和半角空格。*

<br />

<a id="buckets-response-examples" />

### **响应示例** [#响应示例]

```
HTTP/1.1 200 OK
Content-Length: 75
Connection: keep-alive
Content-Type: application/json
Date: Mon, 02 Jan 2006 15:04:05 GMT
X-Reqid: rWkAACgHbskB5dYV

[
  "temp-bucket-xufk1x3r1wa9ayoy7knuz0",
  "temp-bucket-pighpwdt7lu88ljltffmz0"
]
```


# 上传速度检测 (/products/kodo/diagnostic-tools/0-upload-webtest)



最近更新时间: 2026-04-30 16:30:21

# 上传速度检测 [#上传速度检测]

<br />

在遇到上传慢或上传不了问题时，需要用户通过[提交工单](https://support.qiniu.com/question)提供有效地信息，发给我们来帮助排查。为了方便用户操作，七牛云提供了简单的 web 端检测工具。

<br />

# 使用方法 [#使用方法]

<br />

打开 [测速页面](https://kodo-utils.qiniu.com/upload-test) ，选择您指定的区域点击**开始测试**查看该区域的测速结果。

* 测试方式：使用指定测速区域七牛云对象存储 Kodo 标准域名向该区域所在空间中，上传大小为 100MB 的文件来进行网络测速。
* 查看当前七牛云对象存储 Kodo 所支持的[存储区域](/products/kodo/2-region-endpoint-fq)。

![image.png](/docs-assets/products/kodo/%287-tools%29/diagnostic-tools/0-upload-webtest/FmlJh9OpCKQZ2fe8qHvW_7hUfYCw-5f2f265f0199.webp)

<br />

# 测试结果 [#测试结果]

![image.png](/docs-assets/products/kodo/%287-tools%29/diagnostic-tools/0-upload-webtest/FmO5viBseKeAecz4RLmyfeFdIbPp-51d4a22ce673.webp)


# 上传测试页面 (/products/kodo/diagnostic-tools/1-upload-webtest2)



最近更新时间: 2026-04-30 16:49:50

# 上传测试页面 [#上传测试页面]

<br />

在遇到上传慢或上传不了问题时，需要用户通过[提交工单](https://support.qiniu.com/question)提供有效地信息，发给我们来帮助排查。为了方便用户操作，七牛云提供了简单的 web 端检测工具。

<br />

# 使用方法 [#使用方法]

<br />

打开 [检测页面](/products/kodo/diagnostic-tools/1-upload-webtest2) ，选择您指定的区域点击**开始测试**查看该区域的测试结果。

* 测试方式：使用指定测试区域七牛云对象存储 Kodo 标准上传域名向该区域所在空间中，上传大小需大于为 10MB 的文件来进行测试1。
* 查看当前七牛云对象存储 Kodo 所支持的[存储区域](/products/kodo/2-region-endpoint-fq)。

![image.png](/docs-assets/products/kodo/%287-tools%29/diagnostic-tools/1-upload-webtest2/FmUTtzExU1fqD0hbJAPK2_PIKlRe-f85f6a6f61d6.webp)

<br />

# 测试结果 [#测试结果]

![image.png](/docs-assets/products/kodo/%287-tools%29/diagnostic-tools/1-upload-webtest2/Fk9YPT8KsJKLYjch1RWfaEuyWIGH-59bfba53b89a.webp)


# Android SDK (/products/kodo/android)



最近更新时间: 2025-06-16 17:59:42

Android SDK 只包含了最终用户使用场景中的必要功能。相比服务端 SDK 而言，客户端 SDK 不会包含对云存储服务的管理和配置功能。

* [Android SDK 下载地址](https://github.com/qiniu/android-sdk/releases)
* [Android SDK 源码地址](https://github.com/qiniu/android-sdk)
* [Android SDK 历史文档](/products/kodo/android/android-sdk-6)

| Qiniu SDK 版本 | 最低 Android版本 | 依赖库版本                                               | Gradle 版本 |
| ------------ | ------------ | --------------------------------------------------- | --------- |
| 8.9.x        | Android 4.0+ | okhttp 4+ （如果要支持 Android 4.0+，需调整 okhttp 至 v3.12.+） | 8.2       |
| 8.8.x        | Android 4.0+ | okhttp 4+ （如果要支持 Android 4.0+，需调整 okhttp 至 v3.12.+） | 8.2       |
| 8.7.x        | Android 4.0+ | okhttp 4+ （如果要支持 Android 4.0+，需调整 okhttp 至 v3.12.+） | 7.6.2     |
| 8.6.x        | Android 4.0+ | okhttp 4+ （如果要支持 Android 4.0+，需调整 okhttp 至 v3.12.+） | 7.6.2     |
| 8.5.x        | Android 4.0+ | okhttp 4+ （如果要支持 Android 4.0+，需调整 okhttp 至 v3.12.+） | 6.3       |
| 8.4.x        | Android 4.0+ | okhttp 4+ （如果要支持 Android 4.0+，需调整 okhttp 至 v3.12.+） | 6.3       |
| 8.3.1+       | Android 4.0+ | okhttp 4+ （如果要支持 Android 4.0+，需调整 okhttp 至 v3.12.+） | 6.3       |
| 8.3.0        | Android 5.0+ | okhttp 4+                                           | 6.3       |
| 8.2.x        | Android 5.0+ | okhttp 4+                                           | 6.3       |
| 8.1.x        | Android 5.0+ | okhttp 4+                                           | 6.3       |
| 8.0.x        | Android 5.0+ | okhttp 4+                                           | 6.3       |
| 7.6.x        | Android 5.0+ | okhttp 4+                                           | 6.3       |
| 7.5.x        | Android 5.0+ | okhttp 4+                                           | 6.3       |
| 7.4.6        | Android 4.0+ | okhttp 3.12.6                                       | 6.3       |
| 7.3.x        | Android 2.3+ | okhttp 3.11.0                                       | 6.3       |
| 7.2.x        | Android 2.3+ | okhttp 3+                                           | 6.3       |
| 7.1.x        | Android 2.3+ | okhttp 2.6+                                         | 6.3       |
| 7.0.8,7.0.9  | Android 2.2+ | android-async-http 1.4.9                            | 6.3       |
| 7.0.7        | Android 2.2+ | android-async-http 1.4.8                            | 6.3       |

### 注意 [#注意]

* 如果要兼容 Android 4.x ，对应 okhttp 版本请调整至 3.12.+；maven 依赖版本调整方法可参考下方 **1.2 通过 maven**

## 1 安装 [#1-安装]

## 1.1 直接安装 [#11-直接安装]

将 sdk jar文件 复制到项目中去， [jar包下载地址](http://search.maven.org/#search%7Cga%7C1%7Ccom%2Fqiniu%2Fqiniu-android-sdk), 下载对应的 jar 包，以及搜索下载对应的依赖库

[happy-dns下载地址](https://repo1.maven.org/maven2/com/qiniu/happy-dns/)

## 1.2 通过 maven [#12-通过-maven]

Android Studio中添加 dependencies 或者在项目中添加 maven 依赖

```
// 1 直接导入
implementation 'com.qiniu:qiniu-android-sdk:8.9.+'

// 2 如果要修改okhttp依赖的版本，可采用以下方式（强烈建议使用七牛库依赖的okhttp版本）
implementation ('com.qiniu:qiniu-android-sdk:8.9.+'){
    exclude (group: 'com.squareup.okhttp3', module: 'okhttp')
}
implementation 'com.squareup.okhttp3:okhttp:4.2.2'
```

如果是 eclipse, 也可以直接添加依赖来处理。

**相关链接**

* [qiniu-android-sdk](https://github.com/qiniu/android-sdk/)
* [okhttp](http://square.github.io/okhttp/)

如果需要下载历史 jar 包，也可以在 maven 上直接下载，请参考 [这里](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.qiniu%22%20AND%20a%3A%22qiniu-android-sdk%22) 。

## 2 推荐的使用姿势 [#2-推荐的使用姿势]

Android SDK 作为移动端的 SDK，在使用时会被嵌入到移动端的应用中，为了保证用户信息的安全以及业务的灵活性，我们给出以下几点建议：

**注** ：\
文档中的示例基于 SDK 的版本为 v8.9.0

### 2.1 AccessKey 和 SecretKey 下发 [#21-accesskey-和-secretkey-下发]

账户以及 iam 子账户的密钥对 AccessKey 和 SecretKey 不要固化在客户端中，其涉及相关参数通过用户自己的业务服务端来生成并下发（比如上传的 Token）。业务服务端集中管理 AccessKey 和 SecretKey ，避免泄漏；其次 AccessKey 、SecretKey 和客户端应用需解耦，其因泄露更换时不会产生不必要麻烦。

### 2.2 上传域名下发，并可以下发多个域名 [#22-上传域名下发并可以下发多个域名]

SDK 上传过程：

1. 获取七牛 Bucket 的上传域名；
   * 指定域名。通过指定区域 id 或直接给上传域名列表方式指定域名，详情见 [域名配置](/products/kodo/android#3-%E5%9F%9F%E5%90%8D%E9%85%8D%E7%BD%AE) FixedZone；
     * SDK 自动查询域名。SDK 内部自动调用七牛服务端接口，查询 Bucket 的上传域名，详情见 [域名配置](/products/kodo/android#3-%E5%9F%9F%E5%90%8D%E9%85%8D%E7%BD%AE) AutoZone；
2. 使用上传域名进行上传，上传过程会伴随主备重试，既多个域名时，一个域名上传失败，会尝试使用其他域名进行上传。

**建议上传域名下发的方式**

用户服务在下发上传 Token 时同时下发上传域名（可以在 App 需要进行上传时，先请求获取获取上传 Token 及上传域名），可下发多个域名，App 在拿到 Token 和上传域名后，配置上传 Config 以及 UploadManager，进而进行上传操作。

具体代码示例如下：

```
// Upload_Domain1, Upload_Domain2 为服务下发的上传域名
FixedZone fixedZone = new FixedZone(new String[]{"Upload_Domain1", "Upload_Domain2"});
Configuration config = new Configuration.Builder()
     .zone(fixedZone)
     .buildV2();
UploadManager manager = new UploadManager(config);
```

**域名下发的优点：**

1. 跳过域名查询过程，上传更高效。
2. 避免在 App 硬编码上传域名，导致使用不灵活，比如：
   * 在客户更换/增加区域时，由于 App 硬编码了区域，已发布的 App 无法处理此问题。
     * 某些客户生产环境使用的 Bucket 和 测试环境使用的 Bucket 不在同一个区域，在实际上线时错用了测试 Bucket 的区域，导致 Bucket 和区域不匹配，App 相关功能不可用。
     * 自定义域名，由于硬编码，老版本 App 也无法灵活应对。

除了上面的问题，还有很多情景不再列举，上面问题的根本原因是由于 App 硬编码了区域的上传域名导致 App 不能灵活应对上传域名需要修改的场景，所以建议客户通过服务下发上传的方式来配置 SDK 的上传域名, 而不是直接硬编码上传域名。

## 3 域名配置 [#3-域名配置]

域名配置分为 FixZone 和 AutoZone 两种方式。

## 3.1 FixZone [#31-fixzone]

在 FixZone 中，上传域名被固定，且不可更改。有两种配置方式：

### 3.1.1 通过指定上传区域 ID 方式 [#311-通过指定上传区域-id-方式]

区域 ID 和区域域名对应关系参考 [这里](/products/kodo/2-region-endpoint-fq)

```
// 指定上传区域为 华东-浙江
FixedZone zone = FixedZone.createWithRegionId("z0");
```

这种方式硬编码了上传域名的区域，且不可更改，所以不建议在生产环境中使用，仅供测试使用。

### 3.1.2 直接配置上传域名 [#312-直接配置上传域名]

直接配置上传域名的方式可以灵活配置域名，我们不建议上传域名配置为固定域名，而是通过服务下发的方式进行配置。具体上传域名下发请参考 **上传域名下发** 介绍。

```
// Upload_Domain1, Upload_Domain2 为服务下发的上传域名
FixedZone zone = new FixedZone(new String[]{"Upload_Domain1", "Upload_Domain2"});
```

## 3.2 AutoZone [#32-autozone]

如果用户不想关心上传域名相关的逻辑，而且没有任何自定义的需求，完全依赖七牛的上传域名，则可以使用 AutoZone。AutoZone 相对于 FixZone 来说，在第一次上传时查询上传域名，后续会使用缓存的上传域名进行上传。在缓存有效期内不会更换上传域名，当前域名缓存有效期为 24 小时。\
示例代码：

```
// 不指定 uc 域名，使用七牛公有云默认域名
AutoZone zone = new AutoZone();

// 指定 uc 域名，公有云无需指定
AutoZone zone = new AutoZone();
zone.setUcServers(new String[]{"UCHost0", "UCHost1"});
```

不过我们推荐用户使用 **上传域名下发** 的方式来配置上传域名，防止后续业务变更需要。

## 4 上传 [#4-上传]

## 4.1 上传示例 [#41-上传示例]

SDK 内置两种上传方式：表单上传和分片上传，并根据具体情况，内部做了自动切换。表单上传使用一个 HTTP POST 请求完成文件的上传，因此比较适合较小的文件和较好的网络环境。相比而言，分片上传更能适应不稳定的网络环境，也比较适合上传比较大的文件（例如数百 MB 或更大）。

若需深入了解上传方式之间的区别，请参阅上传类型中 [表单上传](/products/kodo/development-guidelines/upload-types/1-form-upload) 、 [分片上传 v1 版](/products/kodo/development-guidelines/upload-types/2-chunked-upload) 和 [分片上传 v2 版](/products/kodo/rs/multipartupload-interface) 接口说明。

UploadManager.put 参数说明：

| 参数                | 类型                  | 说明                                                                              |
| ----------------- | ------------------- | ------------------------------------------------------------------------------- |
| data              | byte\[]/String/File | 数据，可以是 byte 数组、文件路径、文件、数据流和 Uri 资源                                              |
| key               | String              | 保存在服务器上的资源唯一标识，请参阅 [键值对](/products/kodo/3-the-basic-concept#%E8%B5%84%E6%BA%90) |
| token             | String              | 服务器分配的 token                                                                    |
| completionHandler | UpCompletionHandler | 上传回调函数，必填                                                                       |
| options           | UploadOptions       | 如果需要进度通知、中途取消、指定 mimeType，则需要填写相应字段，详见下面的 UploadOptions 参数说明                    |

UploadOptions 参数说明：

| 参数                 | 类型                   | 说明                                      |
| ------------------ | -------------------- | --------------------------------------- |
| params             | Map\<String, String> | 自定义变量，key 必须以 x: 开始                     |
| mimeType           | String               | 指定文件的 mimeType                          |
| progressHandler    | UpProgressHandler    | 上传进度回调                                  |
| cancellationSignal | UpCancellationSignal | 取消上传，当 isCancelled() 返回 true 时，不再执行更多上传 |

```
import com.qiniu.android.common.FixedZone;
import com.qiniu.android.http.ResponseInfo;
import com.qiniu.android.storage.Configuration;
import com.qiniu.android.storage.FileRecorder;
import com.qiniu.android.storage.KeyGenerator;
import com.qiniu.android.storage.Recorder;
import com.qiniu.android.storage.UpCancellationSignal;
import com.qiniu.android.storage.UpCompletionHandler;
import com.qiniu.android.storage.UpProgressHandler;
import com.qiniu.android.storage.UploadManager;
import com.qiniu.android.storage.UploadOptions;
import com.qiniu.android.utils.Utils;

Recorder recorder = null;
try {
    recorder = new FileRecorder(Utils.sdkDirectory() + "/recorder");
} catch (IOException e) {
    e.printStackTrace();
}

// uploadHosts 建议通过服务方式下发，
String[] uploadHosts = new String[]{"Host0", "Host1"};
FixedZone zone = new FixedZone(uploadHosts);
Configuration configuration = new Configuration.Builder()
        .zone(zone)                         // 配置上传区域
        .putThreshold(4 * 1024 * 1024) // 分片上传阈值：4MB，大于 4MB 采用分片上传，小于 4MB 采用表单上传
        .useConcurrentResumeUpload(true)   // 开启分片上传
        .recorder(recorder)  // 文件分片上传时断点续传信息保存，表单上传此配置无效
        .resumeUploadVersion(Configuration.RESUME_UPLOAD_VERSION_V2) // 使用分片 V2
        .buildV2();
UploadManager uploadManager = new UploadManager(configuration);

UploadOptions options = new UploadOptions(null, null, true,
        new UpProgressHandler() {
            @Override
            public void progress(String key, double percent) {
                // 上传进度
            }
        }, new UpCancellationSignal() {
    @Override
    public boolean isCancelled() {
        // 当需要取消时，此处返回 true，SDK 内部会多次检查返回值，当返回值为 true 时会取消上传操作
        return false;
    }
});

String filePath = "";    // 文件路径
String key = "";         // 文件 key
String uploadToken = ""; // 上传的 Token
uploadManager.put(filePath, key, uploadToken, new UpCompletionHandler() {
    @Override
    public void complete(String key, ResponseInfo info, JSONObject response) {
        if (info != null && info.isOK()) {
            // 上传成功
        } else {
            // 上传失败
        }
    }
}, options);
```

## 4.2 上传配置介绍 [#42-上传配置介绍]

### 4.2.1 开启传输加速 [#421-开启传输加速]

默认情况下，SDK 未开启使用加速域名上传的功能，如需开启需按下面方式进行配置：

```
// 1. 在七牛云存储控制台修改 Bucket 配置，域名管理 -> 开启传输加速（SDK 开启使用加速域名上传的功能仅仅是 SDK 支持
//    使用加速域名，所以要想使用传输加速，七牛云服务端需开启此功能）
// 
// 2. SDK 配置 
// 方式一：使用 FixZone 配置
// Upload_Domain1 和 Upload_Domain2 为加速域名，可以参考七牛云存储控制台域名管理页面，建议通过用户服务下发，不要硬编码
Zone zone = new FixedZone(new String[]{"Upload_Domain1", "Upload_Domain2"});
Configuration configuration = new Configuration.Builder()
                .zone(zone)    // 区域必须使用 AutoZone，默认是 AutoZone，所以 zone 也可以不配置
                .buildV2();

// 方式二：使用 AutoZone
Configuration configuration = new Configuration.Builder()
                .accelerateUploading(true) // 开启传输加速，此参数仅对使用 QNAutoZone 时有效（v8.8.0 开始支持）
                .zone(new AutoZone())      // 默认是 AutoZone，所以 zone 也可以不配置
                .buildV2();
```

### 4.2.2 使用 HTTP/3 协议 [#422-使用-http3-协议]

导入 [HTTP/3 client 插件](https://github.com/qiniu/qiniu-android-curl-plugin) ，http3 client 插件依赖于 Android SDK v8.5.0及以上版本

安装导入

```
// 移除 qiniu-android-sdk 依赖 : implementation 'com.qiniu:qiniu-android-sdk:x.x.+' 
implementation 'com.qiniu:qiniu-android-curl-plugin:1.0.0'
```

使用 CurlClient

```
import com.qiniu.client.curl.CurlClient;
import com.qiniu.android.storage.GlobalConfiguration;
import com.qiniu.android.storage.Configuration;
import com.qiniu.android.storage.UploadManager;

// 开启 HTTP/3
GlobalConfiguration.getInstance().enableHttp3 = true;

// @param caPath: SSL 证书本地路径；如果想自定义 CA 可设置此选项，此处为 CA 文件的本地路径。
//                   如果未定义（caPath 配置 null）则使用 SDK 内部提供的 CA 证书，证书来源：https://curl.se/ca/cacert.pem
CurlClient client = new CurlClient(caPath);
Configuration config = new Configuration.Builder()
                .requestClient(client) // 指定 HTTP/3 Client
                .buildV2();
UploadManager manager = new UploadManager(config);
```

### 4.2.3 DNS 预解析 [#423-dns-预解析]

DNS 预解析是对 SDK 上传的一种优化，SDK 会先对上传域名提前做 DNS 解析并缓存（会根据有效期定期刷新缓存），等上传时直接使用缓存的 IP 地址进行上传，可以跳过 DNS 解析阶段，提高上传的效率，在弱网场景效果比较明显。由于 DNS 预解析功能要解决因请求跨运营商而导致请求速度较慢或者不通的问题，所以 DNS 预解析解析结果必须要区分解析结果对应的运营商，因此在 DNS 预解析之后会获取当前设备的 IP 并以此作为区分，所以 DNS 预解析功能会获取当前设备 IP；如果希望关闭 DNS 预解析参考： `其他配置` 章节。

* 从 7.4.0 开始增加了 DNS 预解析和缓存策略，减少 DNS 解析错误。
* 从 8.0.0 开始增加了每 2 分钟（进程非挂起状态）自动刷新缓存策略。同时增加了 DNS 预解析 开关控制，默认开启，可以通过 GlobalConfiguration.getInstance().isDnsOpen = false 关闭 DNS 预解析。
* 从 8.3.2 开始对 DNS 预解析缓存增加缓存有效期，默认 10 分钟，支持手动修改有效期 GlobalConfiguration.getInstance().dnsCacheMaxTTL 时长，单位为 s。

SDK 内置服务系统 DNS 解析和 HTTP DNS 解析（从 8.4.0 开始），如果这两个 DNS 解析不能满足您的需求，那么可以选择自定义 DNS 解析。如果您自定义了 DNS 解析，那么在 DNS 预取时会优先使用您自定义的 DNS 解析，SDK 内部有 DNS 解析缓存相关的逻辑，用户无需考虑 DNS 解析缓存相关的逻辑。一般情况下，我们不建议用户自己自定义 DNS 预解析。

下方为 8.4.0 以上版本使用外部 DNS 组件 HappyDns 的示例代码(实例仅为使用方式演示，请根据您的需求自行处理 DNS 解析细节)，如果找不到 Dns 类，可在工程的 Gradle 配置中依赖 HappyDns

```
implementation 'com.qiniu:happy-dns:2.0.1'
```

具体实例代码如下:

```
import com.qiniu.android.dns.DnsManager;
import com.qiniu.android.dns.Domain;
import com.qiniu.android.dns.IResolver;
import com.qiniu.android.dns.NetworkInfo;
import com.qiniu.android.dns.Record;
import com.qiniu.android.dns.dns.DnsUdpResolver;
import com.qiniu.android.dns.dns.DohResolver;
import com.qiniu.android.http.dns.Dns;
import com.qiniu.android.http.dns.IDnsNetworkAddress;

import java.io.IOException;
import java.net.UnknownHostException;
import java.util.ArrayList;
import java.util.List;

class CustomDns {

    public static Dns buildDefaultDns() {
//         可添加修改 多个 IResolver
//         适当调整不同 IResolver 的加入顺序，比如:223.5.5.5，119.29.29.29，114.114.114.114，8.8.8.8 等
        IResolver[] resolvers = new IResolver[2];
        // 自定义 DNS 服务器地址: UDP
        resolvers[0] = new DnsUdpResolver("8.8.8.8");
        // 自定义 DNS 服务器地址：Doh
        resolvers[1] = new DohResolver("https://dns.alidns.com/dns-query");

        final DnsManager dnsManager = new DnsManager(NetworkInfo.normal, resolvers);
        Dns dns = new Dns() {
            // 若抛出异常 Exception ，sdk 会使用 okhttp 组件默认 dns 解析结果
            @Override
            public List<IDnsNetworkAddress> lookup(String hostname) throws UnknownHostException {
                Domain domain = new Domain(hostname);
                List<IDnsNetworkAddress> addressList = null;
                try {
                    Record[] records = dnsManager.queryRecords(domain);
                    if (records != null && records.length > 0) {
                        addressList = new ArrayList<>();
                        for (Record record : records) {
                            String source = "customized";
                            DemoDnsNetworkAddress address = new DemoDnsNetworkAddress(hostname, record.value, (long) record.ttl, source, record.timeStamp);
                            addressList.add(address);
                        }
                    }
                } catch (IOException ignored) {
                }
                return addressList;
            }
        };
        return dns;
    }

    public static class DemoDnsNetworkAddress implements IDnsNetworkAddress {
        private final String hostValue;
        private final String ipValue;
        private final Long ttlValue;
        private final String sourceValue;
        private final Long timestampValue;

        DemoDnsNetworkAddress(String hostValue,
                              String ipValue,
                              Long ttlValue,
                              String sourceValue,
                              Long timestampValue) {
            this.hostValue = hostValue;
            this.ipValue = ipValue;
            this.ttlValue = ttlValue;
            this.sourceValue = sourceValue;
            this.timestampValue = timestampValue;
        }

        @Override
        public String getHostValue() {
            return hostValue;
        }

        @Override
        public String getIpValue() {
            return ipValue;
        }

        @Override
        public Long getTtlValue() {
            return ttlValue;
        }

        @Override
        public String getSourceValue() {
            return sourceValue;
        }

        @Override
        public Long getTimestampValue() {
            return timestampValue;
        }
    }
}

// 在 UploadManager 初始化之前配置    
GlobalConfiguration.getInstance().dns = CustomDns.buildDefaultDns();
uploadManager = new UploadManager();
```

### 4.2.4 其他配置 [#424-其他配置]

```
// 自定义请求 client，需要自行实现
IRequestClient client = null;

// 定义分片上传时，断点续传信息保存的 Recorder
Recorder recorder = null;
try {
    recorder = new FileRecorder(Utils.sdkDirectory() + "/recorder");
} catch (IOException e) {
    e.printStackTrace();
}

// 断点续传信息保存时使用的 key 的生成器，根据 key 可以获取相应文件的上传信息
// 需要确保每个文件的 key 是唯一的，下面为默认值
// 可以自定义，也可以不配置（keyGenerator 参数可以不传）
KeyGenerator keyGenerator = new KeyGenerator() {
    @Override
    public String gen(String key, File file) {
        return key + "_._" + new StringBuffer(file.getAbsolutePath()).reverse();
    }
    @Override
    public String gen(String key, String sourceId) {
        if (sourceId == null) {
            sourceId = "";
        }
        return key + "_._" + sourceId;
    }
};

// 定义代理
ProxyConfiguration proxy = new ProxyConfiguration("192.168.1.1", 8888);
Configuration configuration = new Configuration.Builder()
        .requestClient(client)  // 自定义请求 client，内部所有请求都会走此 client
        .zone(new AutoZone())              // 配置上传区域，使用 AutoZone
        .recorder(recorder, keyGenerator)  // 文件分片上传时断点续传信息保存，表单上传此配置无效
        .proxy(proxy)
        .useHttps(false)
        .chunkSize(4*1024*1024) // 文件采用分片上传时，分片大小为 4MB
        .putThreshold(4 * 1024 * 1024) // 分片上传阈值：4MB，大于 4MB 采用分片上传，小于 4MB 采用表单上传
        .connectTimeout(10) // 请求连接超时 10s
        .writeTimeout(30) // 请求写超时 30s
        .responseTimeout(10) // 请求响应超时 10s
        .retryMax(1) // 单个域名/IP请求失败后最大重试次数为 1 次
        .retryInterval(500) // 重试时间间隔
        .allowBackupHost(true) // 是否使用备用域名进行重试
        .urlConverter(new UrlConverter() {
            @Override
            public String convert(String url) {
                // 公有云不可配置
                return url;
            }
        })
        .useConcurrentResumeUpload(true)  // 开启并发分片上传
        .concurrentTaskCount(3)           // 使用并发分片上传时，一个文件并发上传的分片个数
        .resumeUploadVersion(Configuration.RESUME_UPLOAD_VERSION_V2) // 使用分片 V2
        .buildV2();

// 用于服务器上传回调通知的自定义参数，参数的key必须以x: 开头  eg: x:foo
Map<String, String> params = new HashMap<>();
// 用于设置meta数据，参数的key必须以x-qn-meta- 开头  eg: x-qn-meta-key
Map<String, String> metaDataParam = new HashMap<>();
// 指定文件 mime type
String mimeType = "";
UploadOptions options = new UploadOptions(params, null, mimeType, true,
        new UpProgressHandler() {
            @Override
            public void progress(String key, double percent) {
                // 上传进度
            }
        }, new UpCancellationSignal() {
    @Override
    public boolean isCancelled() {
        // 当需要取消时，此处返回 true，SDK 内部会多次检查返回值，当返回值为 true 时会取消上传操作
        return false;
    }
}, null);

// 关闭 DNS 预解析
GlobalConfiguration.getInstance().isDnsOpen = false;
// 关闭网络状态检测，当因网络异常而失败时，会检测网络状态，进而根据情况调整重试逻辑
GlobalConfiguration.getInstance().connectCheckEnable = false;
```

## 5 下载文件 [#5-下载文件]

该 SDK 并未提供下载文件相关的功能接口，因为文件下载是一个标准的 HTTP GET 过程。开发者只需理解资源 URI 的组成格式即可非常方便的构建资源 URI，并在必要的时候加上 [下载凭证](/products/kodo/development-guidelines/security/0-download-token) ，即可使用 HTTP GET 请求获取相应资源。

从安全性和代码可维护性的角度考虑，我们建议下载 URL 的拼接过程也在业务服务器进行，让客户端从业务服务器请求。

## API 参考 [#api-参考]

* [存储 API 参考](/products/kodo/kodo-console-guide/0-an-overview-of-the-console)
* [官方数据处理 API 参考](/faq/dora)

## 常见问题 [#常见问题]

**1. 混淆处理**\
对 七牛 的 SDK 不需要做特殊混淆处理，如果有混淆，请将 七牛 相关的包都排除。

* 在 Android Studio 中，混淆配置在 proguard-rules.pro 里面加上下面几行混淆代码就行：

```
-keep class com.qiniu.**{*;}
-keep class com.qiniu.**{public <init>();}
-ignorewarnings
```

**注意：**

* ignorewarnings 这个也是必须加的，如果不加这个，编译的时候可能可以通过，但是 release 的时候还是会出现错误。
* 在 eclipse 中，混淆配置在 proguard-project.txt 里面加上下面几行混淆代码就行：

```
-keep class com.qiniu.**{*;}
-keep class com.qiniu.**{public <init>();}
-ignorewarnings
```

**2. 为什么进度会在 95% 停很久？**

因为上传进度是用 sdk 写入 socket 的字节数／总字节数作为进度，但写入 socket 不等于服务器收到并且处理完成，中间还有一段时间，如果只是用字节数就会出现更怪异的情况，在 100% 停留很久，所以综合考虑就使用了 95% 这个值。

如果您发现上传卡在 95% 很长的时间，请检查是否使用了上传回调业务服务器的功能，请确保业务服务器接受到上传回调后可以返回正确的状态码和回复内容。

**3. 如何才能得到下载的 url ？**

上传没有域名概念，只有 bucket ，一个 bucket 可以绑定多个域名。下载的 url 可以用 bucket 里的域名加 key 拼接而成，私有 url 还要加上 token。

**4. 如何跳过 https 证书验证？**

在部分测试环境发生 Trust anchor for certification path not found 异常，可以设置跳过 https 证书验证：在 Configuration 配置 useHttps( false ) 开启。

## 相关资源 [#相关资源]

如果您有任何关于我们文档或产品的建议和想法，欢迎您通过以下方式与我们互动讨论：

* [技术论坛](http://segmentfault.com/qiniu) - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
* [提交工单](http://support.qiniu.com/) - 如果您的问题不适合在论坛讨论或希望及时解决，您也可以提交一个工单，我们的技术支持人员会第一时间回复您
* [博客](http://blog.qiniu.com/) - 这里会持续更新发布市场活动和技术分享文章
* [微博](http://weibo.com/qiniutek)
* [常见问题](http://support.qiniu.com/)

## 贡献代码 [#贡献代码]

1. Fork
2. 创建您的特性分支 git checkout -b my-new-feature
3. 提交您的改动 git commit -am ‘Added some feature’
4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature
5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

## 许可证 [#许可证]

Copyright © 2021 qiniu.com

基于 MIT 协议发布:

* [www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)


# C# SDK v6 文档 (/products/kodo/csharp/0-csharp-sdk-v6)



最近更新时间: 2017-08-01 12:19:21

![SDK-version](/docs-assets/products/kodo/%286-sdk-downloads%29/csharp/0-csharp-sdk-v6/0cde9e6d5a60a277f7798a6b6369b128-010b16ba6ac9.webp)>

此 C# SDK 适用于.net framework>2.0版本，基于 七牛云存储官方API 构建。使用此 SDK 构建您的网络应用程序，能让您以非常便捷地方式将数据安全地存储到七牛云存储上。无论您的网络应用是一个网站程序，还是包括从云端（服务端程序）到终端（手持设备应用）的架构的服务或应用，通过七牛云存储及其 SDK，都能让您应用程序的终端用户高速上传和下载，同时也让您的服务端更加轻盈。

* [安装](/products/kodo/csharp/0-csharp-sdk-v6#%E5%AE%89%E8%A3%85)
* [配置密钥](/products/kodo/csharp/0-csharp-sdk-v6#%E9%85%8D%E7%BD%AE%E5%AF%86%E9%92%A5)
* [资源管理](/products/kodo/csharp/0-csharp-sdk-v6#%E8%B5%84%E6%BA%90%E7%AE%A1%E7%90%86)
  * [获取单个文件属性信息](/products/kodo/csharp/0-csharp-sdk-v6#%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA%E6%96%87%E4%BB%B6%E5%B1%9E%E6%80%A7%E4%BF%A1%E6%81%AF)
    * [复制单个文件](/products/kodo/csharp/0-csharp-sdk-v6#%E5%A4%8D%E5%88%B6%E5%8D%95%E4%B8%AA%E6%96%87%E4%BB%B6)
    * [移动单个文件](/products/kodo/csharp/0-csharp-sdk-v6#%E7%A7%BB%E5%8A%A8%E5%8D%95%E4%B8%AA%E6%96%87%E4%BB%B6)
    * [删除单个文件](/products/kodo/csharp/0-csharp-sdk-v6#%E5%88%A0%E9%99%A4%E5%8D%95%E4%B8%AA%E6%96%87%E4%BB%B6)
    * [批量操作](/products/kodo/csharp/0-csharp-sdk-v6#%E6%89%B9%E9%87%8F%E6%93%8D%E4%BD%9C)
    * [批量获取文件属性信息](/products/kodo/csharp/0-csharp-sdk-v6#batch-stat)
      * [批量复制文件](/products/kodo/csharp/0-csharp-sdk-v6#batch-copy)
      * [批量移动文件](/products/kodo/csharp/0-csharp-sdk-v6#batch-move)
      * [批量删除文件](/products/kodo/csharp/0-csharp-sdk-v6#batch-delete)
* [获取空间文件列表](/products/kodo/csharp/0-csharp-sdk-v6#rsf-api)
* [文件上传](/products/kodo/csharp/0-csharp-sdk-v6#%E6%96%87%E4%BB%B6%E4%B8%8A%E4%BC%A0)
  * [上传策略](/products/kodo/csharp/0-csharp-sdk-v6#%E4%B8%8A%E4%BC%A0%E7%AD%96%E7%95%A5)
    * [普通上传](/products/kodo/csharp/0-csharp-sdk-v6#%E6%99%AE%E9%80%9A%E4%B8%8A%E4%BC%A0)
    * [断点续上传](/products/kodo/csharp/0-csharp-sdk-v6#%E6%96%AD%E7%82%B9%E7%BB%AD%E4%B8%8A%E4%BC%A0)
* [文件下载](/products/kodo/csharp/0-csharp-sdk-v6#%E6%96%87%E4%BB%B6%E4%B8%8B%E8%BD%BD)
  * [公有资源下载](/products/kodo/csharp/0-csharp-sdk-v6#%E5%85%AC%E6%9C%89%E8%B5%84%E6%BA%90%E4%B8%8B%E8%BD%BD)
    * [私有资源下载](/products/kodo/csharp/0-csharp-sdk-v6#%E7%A7%81%E6%9C%89%E8%B5%84%E6%BA%90%E4%B8%8B%E8%BD%BD)
* [数据处理](/products/kodo/csharp/0-csharp-sdk-v6#%E6%95%B0%E6%8D%AE%E5%A4%84%E7%90%86)
  * [图像处理](/products/kodo/csharp/0-csharp-sdk-v6#%E5%9B%BE%E5%83%8F%E5%A4%84%E7%90%86)
    * [查看图像属性](/products/kodo/csharp/0-csharp-sdk-v6#fop-image-info)
      * [查看图片EXIF信息](/products/kodo/csharp/0-csharp-sdk-v6#fop-exif)
      * [生成图片预览](/products/kodo/csharp/0-csharp-sdk-v6#fop-image-view)
      * [图片高级处理(缩略、裁剪、旋转、转化)](/products/kodo/csharp/0-csharp-sdk-v6#fop-image-mogr)

<span id="fop-image-watermark" />

* [图片水印](/products/kodo/csharp/0-csharp-sdk-v6#fop-image-watermark)
* [API参考手册](/products/kodo/csharp/0-csharp-sdk-v6#api%E5%8F%82%E8%80%83%E6%89%8B%E5%86%8C)
* [贡献代码](/products/kodo/csharp/0-csharp-sdk-v6#%E8%B4%A1%E7%8C%AE%E4%BB%A3%E7%A0%81)
* [许可证](/products/kodo/csharp/0-csharp-sdk-v6#%E8%AE%B8%E5%8F%AF%E8%AF%81)

## 安装 [#安装]

## NuGet安装方式： [#nuget安装方式]

如果您的Visual Studio没有安装NuGet，请先 [安装](http://docs.nuget.org/docs/start-here/installing-nuget) 它,然后在项目中添加引用，使用NuGet管理程序包，在其中搜索qiniu并选择v6.x.x（版本代号，例如6.2.1.2）版本，或者在包管理器控制台输入：

```
install-package qiniu -version=6.x.x
```

## 源码下载: [#源码下载]

```
git clone https://github.com/qiniu/csharp-sdk/tree/v6
```

## DLL引用方式: [#dll引用方式]

下载DLL文件，右键\<项目>-\<引用>文件夹，在弹出的菜单中点击"添加引用"选项后弹出"添加引用"对话框，选择”浏览"Qiniu.DLL文件,点击确定

## 项目引用方式： [#项目引用方式]

下载项目文件，右键解决方案，在弹出的菜单中点击"添加"->"现有项目"，然后在弹出的对话框中选择 Qiniu.csproj"文件，点击确定。接下来与DLL引用方式类似，在"添加引用”对话框选择"项目"选项卡后选中Qiniu项目即可。

## 依赖项: [#依赖项]

此版本SDK引用了第三方的开源库 [Json.NET](https://github.com/JamesNK/Newtonsoft.Json),因此，您需要在项目中引用它(如果使用NuGet管理dll，刚不需要手工加载Json.NET)

<span id="qiniu-keys-set" />

## 配置密钥 [#配置密钥]

服务端使用。

要接入七牛云存储，您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得：

1. [开通七牛开发者帐号](https://portal.qiniu.com/signup)
2. 登录 [七牛开发者自助平台](https://portal.qiniu.com/setting/key) ，查看 Access Key 和 Secret Key 。

在获取到 Access Key 和 Secret Key 之后，您可以在您的程序中调用如下两行代码进行初始化对接, 要确保 `ACCESS_KEY` 和 `SECRET_KEY` 在调用所有七牛API服务之前均已赋值：

```csharp
using Qiniu.Conf;
qiniu.conf.ACCESS_KEY = "<YOUR_APP_ACCESS_KEY>"
qiniu.conf.SECRET_KEY = "<YOUR_APP_SECRET_KEY>"
```

或者，编译配置文件app.conf或者web.conf等文件，添加以下配置项：

```xml
<appSettings>
    <add key="USER_AGENT" value="" />
    <add key="ACCESS_KEY" value="" />
    <add key="SECRET_KEY" value="" />
    <add key="RS_HOST" value="" />
    <add key="UP_HOST" value="" />
    <add key="RSF_HOST" value="" />
    <add key="PREFETCH_HOST" value="" />
  </appSettings>
```

添加完成后，在程序启动的时候调用 `Qiniu.Conf.Config.Init()` 进行初始化。

## 资源管理 [#资源管理]

服务端使用。

基本的数据结构定义：

```csharp
// 摘要:
//    对bucket、key进行封装
public class EntryPath
{
    public EntryPath(string bucket, string key);

    public string Base64EncodedURI { get; }
    //
    // 摘要:
    //     七牛云存储空间名
    public string Bucket { get; }
    //
    // 摘要:
    //     文件key
    public string Key { get; }
    //
    // 摘要:
    //     bucket+ ":"+ key
    public string URI { get; }
}
// 摘要:
//     二元操作路径
public class EntryPathPair
{
    // 摘要:
    //     二元操作路径构造函数
    // 参数:
    //   bucket:
    //     源空间名称，目标空间名称
    //   keySrc:
    //     源文件key
    //   keyDest:
    //     目标文件key
    public EntryPathPair(string bucket, string keySrc, string keyDest);
    //
    // 摘要:
    //     二元操作路径构造函数
    // 参数:
    //   bucketSrc:
    //     源空间名称
    //   keySrc:
    //     源文件key
    //   bucketDest:
    //     目标空间名称
    //   keyDest:
    //     目标文件key
    public EntryPathPair(string bucketSrc, string keySrc, string bucketDest, string keyDest);

    // 摘要:
    //     bucketDest+":"+keyDest
    public string URIDest { get; }
    //
    // 摘要:
    //     bucketSrc+":"+keySrc
    public string URISrc { get; }
}
```

## 获取单个文件属性信息 [#获取单个文件属性信息]

```csharp
using Qiniu.RS

/// <summary>
/// 查看单个文件属性信息
/// </summary>
/// <param name="bucket">七牛云存储空间名</param>
/// <param name="key">文件key</param>
public static void Stat(string bucket, string key)
{
    RSClient client = new RSClient();
    Entry entry = client.Stat(new EntryPath(bucket, key));
    if (entry.OK)
    {
        Console.WriteLine("Hash: " + entry.Hash);
        Console.WriteLine("Fsize: " + entry.Fsize);
        Console.WriteLine("PutTime: " + entry.PutTime);
        Console.WriteLine("MimeType: " + entry.MimeType);
        Console.WriteLine("Customer: " + entry.Customer);
    }
    else
    {
        Console.WriteLine("Failed to Stat");
    }
}
```

## 复制单个文件 [#复制单个文件]

```csharp
/// <summary>
/// 复制单个文件
/// </summary>
/// <param name="bucketSrc">需要复制的文件所在的空间名</param>
/// <param name="keySrc">需要复制的文件key</param>
/// <param name="bucketDest">目标文件所在的空间名</param>
/// <param name="keyDest">标文件key</param>
public static void Copy(string bucketSrc, string keySrc, string bucketDest, string keyDest)
{
    RSClient client = new RSClient();
    CallRet ret = client.Copy(new EntryPathPair(bucketSrc, keySrc, bucketDest, keyDest));
    if (ret.OK)
    {
        Console.WriteLine("Copy OK");
    }
    else
    {
        Console.WriteLine("Failed to Copy");
    }
}
```

## 移动单个文件 [#移动单个文件]

```csharp
/// <summary>
/// 移动单个文件
/// </summary>
/// <param name="bucketSrc">需要移动的文件所在的空间名</param>
/// <param name="keySrc">需要移动的文件</param>
/// <param name="bucketDest">目标文件所在的空间名</param>
/// <param name="keyDest">目标文件key</param>
public static void Move(string bucketSrc, string keySrc, string bucketDest, string keyDest)
{
    Console.WriteLine("\n===> Move {0}:{1} To {2}:{3}", 
    bucketSrc, keySrc, bucketDest, keyDest);
    RSClient client = new RSClient();
    new EntryPathPair(bucketSrc, keySrc, bucketDest, keyDest);
    CallRet ret = client.Move(new EntryPathPair(bucketSrc, keySrc, bucketDest, keyDest));
    if (ret.OK)
    {
        Console.WriteLine("Move OK");
    }
    else
    {
        Console.WriteLine("Failed to Move");
    }
}
```

## 删除单个文件 [#删除单个文件]

```csharp
/// <summary>
/// 删除单个文件
/// </summary>
/// <param name="bucket">文件所在的空间名</param>
/// <param name="key">文件key</param>
public static void Delete(string bucket, string key)
{
    Console.WriteLine("\n===> Delete {0}:{1}", bucket, key);
    RSClient client = new RSClient();
    CallRet ret = client.Delete(new EntryPath(bucket, key));
    if (ret.OK)
    {
        Console.WriteLine("Delete OK");
    }
    else
    {
    Console.WriteLine("Failed to delete");
    }
}
```

<span id="rs-batch" />

## 批量操作 [#批量操作]

当您需要一次性进行多个操作时, 可以使用批量操作.

<span id="batch-stat" />

批量获取文件属性信息:

```csharp
public static void BatchStat(string bucket, string[] keys)
{
    RSClient client = new RSClient();
    List<EntryPath> EntryPaths= new List<EntryPath>();
    foreach(string key in keys)
    {
        Console.WriteLine("\n===> Stat {0}:{1}", bucket, key);
        EntryPaths.Add(new EntryPath(bucket,key));
    }
    client.BatchStat(EntryPaths.ToArray()); 
}
```

<span id="batch-copy" />

批量复制文件:

```csharp
public static void BatchCopy(string bucket, string[] keys)
{
    List<EntryPathPair> pairs = new List<EntryPathPair>();
    foreach (string key in keys)
    {
        EntryPathPair entry = new EntryPathPair(bucket, key, Guid.NewGuid().ToString());
        pairs.Add(entry);
    }
    RSClient client = new RSClient();
    client.BatchCopy(pairs.ToArray());
}
```

<span id="batch-move" />

批量移动文件:

```csharp
public static void BatchMove(string bucket, string[] keys)
{
    List<EntryPathPair> pairs = new List<EntryPathPair>();
    foreach (string key in keys)
    {
        EntryPathPair entry = new EntryPathPair(bucket, key, Guid.NewGuid().ToString());
        pairs.Add(entry);
    }
    RSClient client = new RSClient();
    client.BatchMove(pairs.ToArray());
}
```

<span id="batch-delete" />

批量删除文件

```csharp
public static void BatchDelete(string bucket, string[] keys)
{
    RSClient client = new RSClient();
    List<EntryPath> EntryPaths = new List<EntryPath>();
    foreach (string key in keys)
    {
        Console.WriteLine("\n===> Stat {0}:{1}", bucket, key);
        EntryPaths.Add(new EntryPath(bucket, key));
    }
    client.BatchDelete(EntryPaths.ToArray());
}
```

<span id="rsf-api" />

## 获取文件列表 [#获取文件列表]

服务端使用。

资源列表接口允许用户列出空间下的所有文件信息。使用资源列表接口如果引入Qiniu.RSF命名空间。

```csharp
using Qiniu.RSF;
    RSFClient client = new RSFClient();
    client.listPrifix("<bucketName>", "<prefix>", "<marker>", 500);
```

或者,

```csharp
public static void List (string bucket)
{
    RSF.RSFClient rsf = new Qiniu.RSF.RSFClient(bucket);
    rsf.Prefix = "test";
    rsf.Limit = 100;
    List<DumpItem> items;
    while ((items=rsf.Next())!=null)
    {
        //todo
    }
}
```

<span id="upload-file" />

<span id="form-upload-file" />

## 文件上传 [#文件上传]

服务端或客户端使用。

## 上传策略 [#上传策略]

PutPolicy类用于定制上传策略，关于上传策略完整的说明，请参考 [上传策略（PutPolicy）](/products/kodo/development-guidelines/security/1-put-policy) 。

uptoken 实际上是用 AccessKey/SecretKey对上传策略进行数字签名的字符串,用于上传接口。

```csharp
string bucketName = "test";
PutPolicy put = new PutPolicy(bucketName);
string uptoken = put.Token();
```

文件上传有两种方式，一种是以普通方式直传文件，简称普通上传，另一种方式是断点续上传，断点续上传在网络条件很一般的情况下也能有出色的上传速度，而且对大文件的传输非常友好。

## 普通上传 [#普通上传]

普通上传的接口在 `qiniu.io` 里，如下：

上传本地文件

```csharp
/// <summary>
/// 上传文件测试
/// </summary>
/// <param name="bucket"></param>
/// <param name="key"></param>
/// <param name="fname"></param>
public static void PutFile(string bucket, string key, string fname)
{
    var policy = new PutPolicy(bucket, 3600);
    string upToken = policy.Token();
    PutExtra extra = new PutExtra ();
    IOClient client = new IOClient();
    client.PutFile(upToken, key, fname, extra);
}
```

**注意： key必须采用utf8编码，如使用非utf8编码访问七牛云存储将反馈错误**

<span id="upload-resumable" />

<span id="resume-upload-file" />

## 断点续上传 [#断点续上传]

上传本地文件,示例如下:

```csharp
public static void ResumablePutFile(string bucket, string key, string fname)
{
    Console.WriteLine("\n===> ResumablePutFile {0}:{1} fname:{2}", bucket, key, fname);
    PutPolicy policy = new PutPolicy(bucket, 3600);
    string upToken = policy.Token();
    Settings setting = new Settings();
    ResumablePutExtra extra = new ResumablePutExtra();
    ResumablePut client = new ResumablePut(setting, extra);
    client.PutFile(upToken, fname, Guid.NewGuid().ToString());
}
```

ResumablePut采用分快上传，各快之间采用并行上传,可以通过注册ResumablePutExtra以下两个事件监听当前上传进度以及成功情况：

```csharp
public event EventHandler<PutNotifyEvent> Notify;
public event EventHandler<PutNotifyErrorEvent> NotifyErr;
```

## 文件下载 [#文件下载]

七牛云存储上的资源下载分为 公有资源下载 和 私有资源下载 。

私有（private）是 Bucket（空间）的一个属性，一个私有 Bucket 中的资源为私有资源，私有资源不可匿名下载。

新创建的空间（Bucket）缺省为私有，也可以将某个 Bucket 设为公有，公有 Bucket 中的资源为公有资源，公有资源可以匿名下载。

## 公有资源下载 [#公有资源下载]

如果在给bucket绑定了域名的话，可以通过以下地址访问。

```
[GET] http://<domain>/<key>
```

其中 是bucket所对应的域名。七牛云存储为每一个bucket提供一个默认域名。默认域名可以到 [七牛云存储开发者平台](https://portal.qiniu.com/) 中，空间设置的域名设置一节查询。用户也可以将自有的域名绑定到bucket上，用户可以通过自有域名访问七牛云存储。

**注意： key必须采用utf8编码，如使用非utf8编码访问七牛云存储将返回错误**

## 私有资源下载 [#私有资源下载]

私有资源必须通过临时下载授权凭证(downloadToken)下载，如下：

```
[GET] http://<domain>/<key>?e=<deadline>&token=<downloadToken>
```

注意，尖括号不是必需，代表替换项.

私有下载链接可以使用 SDK 提供的如下方法生成：

```csharp
using Qiniu.RS;
public static void MakeGetToken(string domain, string key)
{
    string baseUrl = GetPolicy.MakeBaseUrl(domain, key);
    string private_url = GetPolicy.MakeRequest(baseUrl);
}
```

## 数据处理 [#数据处理]

服务端或客户端使用。

七牛支持在云端对图像, 视频, 音频等富媒体进行个性化处理。使用数据处理接口需要引入Qiniu.FileOp命名空间。

```csharp
using Qiniu.FileOp;
```

## 图像处理 [#图像处理]

<span id="fop-image-info" />

查看图像属性

```csharp
string domain = "domain";
    string key = key;
    Console.WriteLine("\n===> FileOp.ImageInfo");
    //生成base_url
    string url = Qiniu.RS.GetPolicy.MakeBaseUrl(domian, key);
    //生成fop_url
    string imageInfoURL = ImageInfo.MakeRequest(url);
    //对其签名，生成private_url。如果是公有bucket此步可以省略
    imageInfoURL = GetPolicy.MakeRequest(imageInfoURL);
    ImageInfoRet infoRet = ImageInfo.Call(imageInfoURL);
    if (infoRet.OK)
    {
        Console.WriteLine("Format: " + infoRet.Format);
        Console.WriteLine("Width: " + infoRet.Width);
        Console.WriteLine("Heigth: " + infoRet.Height);
        Console.WriteLine("ColorModel: " + infoRet.ColorModel);
    }
    else
    {
        Console.WriteLine("Failed to ImageInfo");
    }
```

<span id="fop-exif" />

查看图片EXIF信息

```csharp
string exifURL = Exif.MakeRequest(url);
    ExifRet exifRet = Exif.Call(exifURL);
    if (exifRet.OK)
    {
        Console.WriteLine("ApertureValue.val: " + exifRet["ApertureValue"].val);
        Console.WriteLine("ApertureValue.type: " + exifRet["ApertureValue"].type.ToString());
        Console.WriteLine("ExifInfo: " + exifRet.ToString());
    }
    else
    {
        Console.WriteLine("Failed to ImageExif");
    }
```

<span id="fop-image-view" />

生成图片预览

```csharp
ImageView imageView = new ImageView { Mode = 0, Width = 200, Height = 200, Quality = 90, Format = "gif" };
    string viewUrl = imageView.MakeRequest(url);
    viewUrl = GetPolicy.MakeRequest(viewUrl);
    Console.WriteLine("ImageViewURL:" + viewUrl);
```

<span id="fop-image-mogr" />

图片高级处理(缩略、裁剪、旋转、转化)

```csharp
ImageMogrify imageMogr = new ImageMogrify
    {
        Thumbnail = "!50x50r",
        Gravity = "center",
        Rotate = 90,
        Crop = "!50x50",
        Quality = 80,
        AutoOrient = true
    };
    string mogrUrl = imageMogr.MakeRequest(url);
    mogrUrl = GetPolicy.MakeRequest(mogrUrl);
    Console.WriteLine("ImageMogrifyURL:" + mogrUrl);
```

图片水印

```csharp
//文字水印
    WaterMarker marker = new TextWaterMarker("hello,qiniu cloud!","","red");
    string MarkerUrl = marker.MakeRequest(url);
    //图片水印
    marker = new ImageWaterMarker("http://www.b1.qiniudn.com/images/logo-2.png");
    MarkerUrl = marker.MakeRequest(url);
```

## API参考手册 [#api参考手册]

* [数据处理API参考手册](/faq/dora)
* [融合CDN加速API参考手册](/products/cdn/0-fusion-api-overview)

## 贡献代码 [#贡献代码]

1. Fork
2. 创建您的特性分支 (`git checkout -b my-new-feature`)
3. 提交您的改动 (`git commit -am 'Added some feature'`)
4. 将您的修改记录提交到远程 `git` 仓库 (`git push origin my-new-feature`)
5. 然后到 github 网站的该 `git` 远程仓库的 `my-new-feature` 分支下发起 Pull Request

## 许可证 [#许可证]

Copyright (c) 2017 [qiniu.com](https://www.qiniu.com/)

基于 MIT 协议发布:

* [www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)


# C# SDK v7.0 文档 (/products/kodo/csharp/1-csharp-sdk-v7p0)



最近更新时间: 2019-11-08 14:36:05

![SDK-version](/docs-assets/products/kodo/%286-sdk-downloads%29/csharp/1-csharp-sdk-v7p0/5ce1c20f38af3838d1f47f8961230d60-e51b3c9542c9.webp)>

此 C# SDK 适用于.NET Framework 2.0及以上版本，基于七牛云API参考手册构建。使用此 SDK 构建您的网络应用程序，能让您以非常便捷地方式将数据安全地存储到七牛云存储上。无论您的网络应用是一个网站程序，还是包括从云端（服务端程序）到终端（手持设备应用）的架构的服务或应用，通过七牛云存储及其 SDK，都能让您应用程序的终端用户高速上传和下载，同时也让您的服务端更加轻盈。

## 安装 [#安装]

## 源码下载 [#源码下载]

```
https://github.com/qiniu/csharp-sdk
```

## 添加引用 [#添加引用]

获取编译好的qiniu.dll后，在项目中添加Qiniu.dll引用

## NuGet安装 [#nuget安装]

直接从NuGet安装，搜索 `qiniu` 并选择7.3.x（如7.3.0）版本安装，或者在包管理器控制台键入以下命令：

```
install-package qiniu -version=7.3.0
```

## 附加依赖项 [#附加依赖项]

C# SDK引用了第三方的开源项库 [Json.NET](http://www.newtonsoft.com/json) 因此，您需要在项目中引用它，或者使用NuGet安装

```
Install-Package Newtonsoft.Json
```

## 秘钥配置 [#秘钥配置]

要接入七牛云存储，您需要拥有一对有效的 Access Key (以下简称AK) 和 Secret Key (以下简称SK) 用来进行签名认证。步骤如下：

1. 登录七牛开发者平台，查看 [AK 和 SK](https://portal.qiniu.com/user/key) ，如果没有账号，可以开通一个 [七牛开发者帐号](https://portal.qiniu.com/signup)
2. 在适当位置(比如程序中的settings模块)配置 AK & SK
3. 接下来就可以调用七牛API服务，如文件上传、数据处理等

## SDK设置 [#sdk设置]

因为不同的空间(bucket)可能位于不同的机房(区域/Zone)，因此文件管理等操作需要正确配置Zone(位于Qiniu.Common命名空间)，默认配置为"华东机房"，用户可以有以下两种方法配置Zone:

直接配置（ 如果确定机房所在Zone，可以使用此方法）:

```csharp
// XXX是其中之一: CN_East CN_South CN_North US_North
Qiniu.Common.Config.ZONE = Qiniu.Common.Zone.ZONE_XXX();
// 或者使用ZoneID (CN_East CN_South CN_North US_North)
Qiniu.Common.Config.ConfigZone(zoneId);
```

使用AutoZone自动配置（推荐使用这个方法）:

```csharp
// AK = ACCESS_KEY    
Qiniu.Common.Config.ConfigZoneAuto(AK,BUCKET);
```

以下示例代码中没有特别指明有关Zone的设置，请特别注意。

## 上传文件 [#上传文件]

## 上传流程 [#上传流程]

为了尽可能地改善终端用户的上传体验，七牛云存储首创了客户端直传功能。更多信息请参阅 [业务流程](/products/kodo/0-programming-model) 。

## 普通上传 [#普通上传]

推荐使用UploadManager，以下代码示意了如何使用UploadManager来上传一个本地文件（请注意Zone设置，下同）：

```csharp
using System;
using Qiniu.Util;
using Qiniu.Storage;
using System.IO;

namespace ConsoleDemo
{
    class SimpleUploadDemo
    {
        public static void Main(string[] args)
        {
            string AK = "ACCESS_KEY";
            string SK = "SECRET_KEY";
            // 目标空间名
            string bucket = "TARGET_BUCKET";
            // 目标文件名
            string saveKey = "SAVE_KEY";
            // 本地文件
            string localFile = "LOCAL_FILE";

            // 上传策略
            PutPolicy putPolicy = new PutPolicy();
            // 设置要上传的目标空间
            putPolicy.Scope = bucket;
            // 上传策略的过期时间(单位:秒)
            putPolicy.SetExpires(3600);
            // 文件上传完毕后，在多少天后自动被删除
            putPolicy.DeleteAfterDays = 1;

            // 请注意这里的Zone设置(如果不设置，就默认为华东机房)
            // var zoneId = Qiniu.Common.AutoZone.Query(AK,BUCKET);
            // Qiniu.Common.Config.ConfigZone(zoneId);

            Mac mac = new Mac(AK,SK); // Use AK & SK here
            // 生成上传凭证
            string uploadToken = Auth.createUploadToken(putPolicy, mac);

            UploadOptions uploadOptions = null;

            // 上传完毕事件处理
            UpCompletionHandler uploadCompleted = new UpCompletionHandler(OnUploadCompleted);

            // 方式1：使用UploadManager
            //默认设置 Qiniu.Common.Config.PUT_THRESHOLD = 512*1024;
            //可以适当修改,UploadManager会根据这个阈值自动选择是否使用分片(Resumable)上传    
            UploadManager um = new UploadManager();
            um.uploadFile(localFile, saveKey, token, uploadOptions, uploadCompleted);

            // 方式2：使用FormManager
            //FormUploader fm = new FormUploader();
            //fm.uploadFile(localFile, saveKey, token, uploadOptions, uploadCompleted);

            Console.ReadKey();
        }

        private static void OnUploadCompleted(string key, ResponseInfo respInfo, string respJson)
        {
            // respInfo.StatusCode
            // respJson是返回的json消息，示例: { "key":"FILE","hash":"HASH","fsize":FILE_SIZE }
        }
    }
}
```

## 断点续上传 [#断点续上传]

实际上也是分片上传，使用ResumeUploader，参考如下示例：

```csharp
using System;
using Qiniu.Util;
using Qiniu.Storage;
using System.IO;

namespace ConsoleDemo
{
    class ResumableUploadDemo
    {
        public static void Main(string[] args)
        {
            string AK = "ACCESS_KEY";
            string SK = "SECRET_KEY";
            string bucket = "TARGET_BUCKET";
            string saveKey = "SAVE_KEY";
            string localFile = "LOCAL_FILE";
            // 上传进度记录保存的目录
            string recordPath = "RECORD_PATH";
            // 上传进度保存为文件
            string recordFile = "RECORD_FILE";

            // 设置上传时的分片大小(单位为字节,已默认设置为2MB,不得大于4MB,一般保留默认即可)
            // Qiniu.Common.CHUNK_SIZE = N_CHUNK_SIZE;

            UploadOptions uploadOptions = new UploadOptions(
                null, // ExtraParams
                null, // MimeType
                false,  // CheckCrc32
                new UpProgressHandler(OnUploadProgressChanged), // 上传进度
                null // CancelSignal
                );

            UpCompletionHandler uploadCompleted = new UpCompletionHandler(OnUploadCompleted); // 上传完毕

            // 上传时会将当前进度记录写到文件，下次可以“断点续传”
            ResumeRecorder rr = new ResumeRecorder(recordPath);
            // 开始上传
            ResumeUploader ru = new ResumeUploader(
                rr,               // 续传记录
                recordFile,       // 续传记录文件
                localFile,        // 待上传的本地文件
                saveKey,          // 要保存的文件名
                token,            // 上传凭证
                uploadOptions,    // 上传选项(其中包含进度处理)，可为null
                uploadCompleted   // 上传完毕事件处理
                ); 

            ru.uploadFile();
            Console.ReadKey();
        }

        private static void OnUploadProgressChanged(string key,double percent)
        {
            // percent = [0(开始)~1.0(完成)]
        }

        private static void OnUploadCompleted(string key,ResponseInfo respInfo,string respJson)
        {
            // respInfo.StatusCode
            // respJson是返回的json消息，示例: { "key":"FILE","hash":"HASH","fsize":FILE_SIZE }
        }
    }
}
```

**说明**

可以使用UploadManager配合一个阈值(Qiniu.Common.PUT\_THRESHOLD)让程序(SDK)自动选择使用简单上传(传适合于小文件)或者分片上传(传适合于大文件或者需要断点续上传)。分片上传/断点续上传使用ResumbaleUploader。

使用此SDK上传文件需要注意：

*上传域名*

请设置 `UploadFromCDN` 参数(true/false)：

```csharp
// 不使用CDN
Qiniu.Common.Config.UploadFromCDN = false;
```

*关于UpCompletionHandler参数*

1.上传方法(如uploadFile)中包含UploadOptions,UpCompletionHandler等参数，可以保持默认(设置null即可)，也可以自行设置

2.UpCompletionHandler是 **在上传完成后或者遇到错误(比如网络错误等)触发** ，其中会包含一些返回信息，可以在此进行处理

*关于分片上传*

1.分片上传时，片大小(Qiniu.Common.CHUNK\_SIZE)可以在上传之前预先设置

2.**CHUNK\_SIZE必须为4MB或者4MB/n** ，默认已设置为2MB(可自行设置为512KB,1MB等)

3.如果分片(chunk)较小，上传一个chunk的耗时更短，但整个文件需要被切分成更多的chunk

4.如果chunk设置得太大，上传单个chunk可能会出现连接超时的问题

5.使用ResumbaleUploader时， **上传不同的文件，请务必使用不同的recordPath/recordFile** ，因为断点记录和上传文件是对应的

## 文件下载 [#文件下载]

## 公开空间文件下载 [#公开空间文件下载]

直接访问外链即可下载。

## 私有空间文件下载 [#私有空间文件下载]

私有空间中的文件下载时，需要先 **生成已授权的下载链接** ：

生成授权下载链接 `ACC_URL = RAW_URL+Expire+Token`

比如原始链接 `RAW_URL = http://example.com/file/1.jpg`

加上过期时间戳(Expire)后 `http://example.com/file/1.jpg?e=1476783956`

然后Auth生成Token拼接上去 `http://example.com/file/1.jpg?e=1476783956&token=&lt;TOKEN&gt;`

如果原始链接中已包含·?·字符（如 `http://xxx/1.jpg?query_what` ），后面就不应该再次出现该字符，因此时间戳后缀应该是类似 `&e=1476783956` 这样的形式，最后的链接可能会是这样子 `http://xxx/1.jpg?query_what&e=1476783956&token=&lt;TOKEN&gt;`

示例代码

```csharp
using Qiniu.Util;
// AK = "ACCESS_KEY"
// SK = "SECRET_KEY"
// 加上过期参数，使用 ?e=<UnixTimestamp>
// 如果rawUrl中已包含?，则改用&e=<UnixTimestamp>
// rawURL = "RAW_URL" + "?e=1482207600"; 
Mac mac = new Mac(AK,SK);
string token = Auth.createDownloadToken(rawUrl, mac);
string signedURL = rawURL + "&token=" + token;
```

## 空间资源管理 [#空间资源管理]

## 简单处理 [#简单处理]

支持stat、copy、move、delete,listFiles等，具体使用方法可参阅 [BucketFileManagemt.cs](https://github.com/qiniu/csharp-sdk/blob/master/src/QiniuTests/Storage/BucketManagerTests.cs) 代码。

## 获取空间文件列表 [#获取空间文件列表]

在BucketManager类中提供了listFiles方法 `listFiles(bucket, prefix, marker, limit, delimiter)`.

该方法返回值中，有以下3个字段需要关注：

| 字段             | 含义                               |
| -------------- | -------------------------------- |
| Marker         | 请参阅下述的 `marker` 参数               |
| Items          | 返回的结果，其中包括文件名、hash、大小等信息         |
| CommonPrefixes | 请参阅下述的 `delimiter` 和 `prefix` 参数 |

函数参数说明如下：

| 参数        | 含义                                                                                                                                                                                                                                            |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bucket    | 目标空间名称                                                                                                                                                                                                                                        |
| prefix    | 返回指定文件名前缀的文件列表(prefix可设为null)                                                                                                                                                                                                                 |
| marker    | 考虑到设置limit后返回的文件列表可能不全(需要重复执行listFiles操作) 执行listFiles操作时使用marker标记来追加新的结果。 **特别注意** 首次执行listFiles操作时marker为null                                                                                                                               |
| limit     | 每次返回结果所包含的文件总数限制(limit\<=1000， *建议值100*)                                                                                                                                                                                                      |
| delimiter | 分隔符，比如-或者/等等，可以模拟作为目录结构(参考下述示例)。假设指定空间中有2个文件 fakepath/1.txt fakepath/2.txt 现设置delimiter=/ 得到结果items =\[]，commonPrefixes = \[fakepath/] 调整prefix=fakepath/ delimiter=null 得到所需结果items=\[1.txt,2.txt] 于是可以在本地先创建一个目录fakepath,然后在该目录下写入items中的文件 |

以下是一个简单的示例：

```csharp
// AK = "ACCESS_KEY"
// SK = "SECRET_KEY"
Mac mac = new Mac(AK, SK);
BucketManager bm = new BucketManager(mac);

string bucket = "BUCKET"; // 目标空间
string marker = ""; // 首次请求时marker必须为空
string prefix = null; // 按文件名前缀保留搜索结果
string delimiter = null; // 目录分割字符(比如"/")
int limit = 100; // 最大值1000

// 返回结果存储在items中
List<FileDesc> items = new List<FileDesc>();

// 由于limit限制，可能需要执行多次操作
// 返回值中Marker字段若非空，则表示文件数超过了limit
do
{
    var result = bm.listFiles(bucket, prefix, marker, limit, delimiter);
    marker = result.Marker;
    if (result.Items != null)
    {
        items.AddRange(result.Items);
    }
} while (!string.IsNullOrEmpty(marker));

// 在这里处理文件列表items
```

完整示例及其它更多代码可以参考SDK-v7.0的 [examples目录](https://github.com/qiniu/csharp-sdk/tree/v7.0/examples)

## 批量处理 [#批量处理]

batch批处理如下示例：

```csharp
// AK = ACCESS_KEY
// SK = SECRET_KEY
Mac mac = new Mac(AK, SK);
// 批量操作类似于
// op=<op1>&op=<op2>&op=<op3>...
string batchOps = "BATCH_OPS";
BucketManager bm = new BucketManager(mac);
HttpResult result = bm.batch(batchOps);
// 或者
//string[] batch_ops={"<op1>","<op2>","<op3>",...};
//bm.batch(batch_ops);
//返回结果在这里result.Response
```

可参考 [examples/BucketManagement](https://github.com/qiniu/csharp-sdk/blob/master/src/QiniuTests/Storage/BucketManagerTests.cs) 中的batch示例。

## 持久化操作 [#持久化操作]

如 `fops = vframe/jpg/offset/1/w/480/h/360/rotate/90` 表示视频截图。

详细内容请参阅 [持久化数据处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop) 文档。

## API参考手册 [#api参考手册]

* [数据处理API参考手册](/faq/dora)

## 相关资源 [#相关资源]

如果您有任何关于我们文档或产品的建议和想法，欢迎到我们的技术论坛参与讨论。

* [技术论坛](http://segmentfault.com/qiniu) - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
* [提交工单](http://support.qiniu.com/hc/request/guest/) - 如果您的问题不适合在论坛讨论或得不到回答，您也可以提交一个工单，技术支持人员会尽快回复您
* [博客](http://blog.qiniu.com/) - 这里会持续发布市场活动和技术分享文章
* [微博](http://weibo.com/qiniutek)
* [常见问题](https://support.qiniu.com/)

## 贡献代码 [#贡献代码]

1. Fork
2. 创建您的特性分支 git checkout -b my-new-feature
3. 提交您的改动 git commit -am 'Added some feature'
4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature
5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

## 许可证 [#许可证]

Copyright (c) 2017 [qiniu.com](https://www.qiniu.com/)

基于 MIT 协议发布:

[www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)


# C# SDK v7.2.15 文档 (/products/kodo/csharp/2-c-sdk-v7-2-15)



最近更新时间: 2019-11-08 14:36:27

![NuGet release](/docs-assets/products/kodo/%286-sdk-downloads%29/csharp/2-c-sdk-v7-2-15/5efe0f87c5c5e55cc03fd46b3d63dee4-d9b936ed17e5.webp)

此 C# SDK 适用于.NET Framework 2.0+ , .NET Core 以及UWP(Windows 10 通用应用)，基于七牛云API参考手册构建。使用此 SDK 构建您的网络应用程序，能让您以非常便捷地方式将数据安全地存储到七牛云存储上。无论您的网络应用是一个网站程序，还是包括从云端（服务端程序）到终端（手持设备应用）的架构的服务或应用，通过七牛云存储及其 SDK，都能让您应用程序的终端用户高速上传和下载，同时也让您的服务端更加轻盈。

# 安装 [#安装]

* <a href="#qiniu-sdk-dll">
    直接添加DLL引用
  </a>
* <a href="#qiniu-sdk-nuget">
    包管理器(NuGet)方式安装
  </a>
* <a href="#qiniu-sdk-src">
    从源码编译
  </a>

<a id="qiniu-sdk-dll" />

**直接添加DLL引用**

您可以在[这里](https://github.com/qiniu/csharp-sdk/releases)找到所有的Release，选择您需要的版本下载，解压后将\*.dll文件添加至项目引用。需要注意的是，此SDK依赖[Json.NET](http://www.newtonsoft.com/json)，可以添加对应版本Newtonsoft.Json.dll引用或者使用NuGet来安装它：

```
Install-Package Newtonsoft.Json
```

<a id="qiniu-sdk-nuget" />

**包管理器(NuGet)方式安装**

或者从NuGet来安装，以Visual Studio 2013/2015为例(如果您的Visual Studio没有安装NuGet，请先[安装](http://docs.nuget.org/docs/start-here/installing-nuget))。打开NuGet程序包管理器搜索Qiniu.Shared或者在控制台中键入以下命令：

```
Install-Package Qiniu.Shared
```

<a id="qiniu-sdk-src" />

**从源码编译**

当然，您也可以直接从源码编译

```
git clone https://github.com/qiniu/csharp-sdk
```

# 鉴权 [#鉴权]

* <a href="#qiniu-keys-get">
    获取密钥
  </a>
* <a href="#qiniu-keys-set">
    配置密钥
  </a>
* <a href="#qiniu-keys-auth">
    生成凭证
  </a>

七牛C# SDK的上传、文件管理等功能需要合法的授权。授权凭证的签算需要七牛账号下的一对有效的密钥：`Access Key`和`Secret Key`。

<a id="qiniu-keys-get" />

**获取密钥**

要接入七牛云存储，您需要拥有一对有效的 Access Key (以下简称AK) 和 Secret Key (以下简称SK) 用来进行签名认证。您可以登录七牛开发者平台，查看 [AK 和 SK](https://portal.qiniu.com/user/key)。如果没有账号，可以在[七牛开发者平台](https://portal.qiniu.com/signup)开通一个七牛开发者帐号。

<a id="qiniu-keys-set" />

**配置密钥**

使用各种七牛API服务(如upload等)之前请确保AK & SK均已赋值：

```csharp
// AK = "<YOUR_ACCESS_KEY>"
// SK = "<YOUR_SECRET_KEY>"
```

<a id="qiniu-keys-auth" />

**生成凭证**

使用AK & SK构建Mac对象，然后使用Mac对象生成鉴权类`Auth`，然后就可以生成上传凭证、管理凭证等（以下`CreateXXToken`中的XXToken是是`UploadToken`,`DownloadToken`,`ManageToken`之一）：

```csharp
using Qiniu.Util;
Mac mac = new Mac(AK, SK);
Auth auth = new Auth(mac);
auth.CreateXXToken(...);
```

或者使用Auth的静态方法：

```csharp
using Qiniu.Util;
Mac mac = new Mac(AK, SK);
Auth.CreateXXToken(mac,...);
```

# SDK设置 [#sdk设置]

## Zone设置 [#zone设置]

此步骤是必要的。

不同的空间(bucket)可能位于不同的机房(区域/Zone)，因此文件管理/文件上传等操作需要正确配置Zone(位于`Qiniu.Common`命名空间)，默认配置为”华东机房”，用户可以有以下两种方法配置Zone:

1.直接配置（ 如果确定机房所在Zone，可以使用此方法）

```csharp
// ZoneID zoneId = ZoneID.CN_East;
// [CN_East:华东] [CN_South:华南] [CN_North:华北] [US_North:北美]
// USE_HTTPS = (true|false) 是否使用HTTPS
Qiniu.Common.Config.SetZone(zoneId,USE_HTTPS);
```

2.使用AutoZone自动配置（推荐使用这个方法）

```csharp
// AK = ACCESS_KEY
// USE_HTTPS = (true|false) 是否使用HTTPS
// 使用前请确保AK和BUCKET正确，否则此函数会抛出异常(比如code612/631等错误)
Qiniu.Common.Config.AutoZone(AK,BUCKET,USE_HTTPS);
```

## JSON解析器设置 [#json解析器设置]

这个步骤是可选的。

此SDK选用[Newtonsoft.Json](http://www.newtonsoft.com/json)（也称作Json.NET）作为默认的JSON解析器，您也可以自行设置（分别设置`Qiniu.JSON.JsonHelper`的两个属性：`JsonSerializer`和`JsonDeserializer`），可以参考如下示例。

首先定义您的JSON序列化(Serialize)、反序列化(Deserialize)方法（此例使用默认的Newtonsoft.Json来实现）：

```csharp
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;
using Qiniu.JSON;

namespace CSharpSDKExamples
{
    public class AnotherJsonSerializer : IJsonSerializer
    {
        // 实现此接口的JSON序列化方法
        public string Serialize<T>(T obj) where T : new()
        {
            var settings = new JsonSerializerSettings();
            settings.ContractResolver = new CamelCasePropertyNamesContractResolver();
            settings.NullValueHandling = NullValueHandling.Ignore;
            return JsonConvert.SerializeObject(obj, settings);
        }
    }

    public class AnotherJsonDeserializer : IJsonDeserializer
    {
        // 实现此接口的JSON反序列化方法
        public bool Deserialize<T>(string str, out T obj) where T : new()
        {
            obj = default(T);

            bool ok = true;

            try
            {
                obj = JsonConvert.DeserializeObject<T>(str);
            }
            catch (System.Exception)
            {
                ok = false;
            }

            return ok;
        }
    }
}
```

然后在使用此SDK的其他功能(函数)之前设置JSON解析器，只需设置一次即可：

```csharp
// 使用自定义的JSON序列化、反序列化方法
Qiniu.JSON.JsonHelper.JsonSerializer = new AnotherJsonSerializer();
Qiniu.JSON.JsonHelper.JsonDeserializer = new AnotherJsonDeserializer();
```

如果您希望摆脱Json.NET依赖（比如您只想使用其他更轻量、更高效的JSON解析器或者自行实现），可在[此项目的github release](https://github.com/qiniu/csharp-sdk/releases)中找到ext-json版本，或者安装NuGet上的`Qiniu.Shared.ExtJson`版本，又或者参照此SDK源码的说明对`Qiniu.JSON`模块稍作修改然后编译。

<a id="qiniu-upload-module" />

# 上传文件 [#上传文件]

* <a href="#qiniu-upload-flow">
    上传流程
  </a>
* <a href="#qiniu-upload-putpolicy">
    上传策略
  </a>
* <a href="#qiniu-upload-token">
    上传凭证
  </a>
* <a href="#qiniu-upload-methods">
    上传方式选择
  </a>
* <a href="#qiniu-upload-simple">
    简单上传
  </a>
* <a href="#qiniu-upload-bytes">
    字节数据上传
  </a>
* <a href="#qiniu-upload-stream">
    数据流上传
  </a>
* <a href="#qiniu-upload-overwrite">
    覆盖上传
  </a>
* <a href="#qiniu-upload-resumable">
    断点续上传
  </a>
* <a href="#qiniu-upload-persist">
    上传&预转持久化
  </a>

<a id="qiniu-upload-flow" />

## 上传流程 [#上传流程]

为了尽可能地改善终端用户的上传体验，七牛云存储首创了客户端直传功能。更多信息请参阅[业务流程](/products/kodo/0-programming-model)。

<a id="qiniu-upload-putpolicy" />

## 上传策略 [#上传策略]

上传策略包含了上传文件的各种配置。在PuPolicy(上传策略)中可以进行丰富的参数设置，比如：文件类型限制、大小限制、回调设置等等，可以参考[上传策略](/products/kodo/development-guidelines/security/1-put-policy)，具体使用方法可参考下面的上传示例。

<a id="qiniu-upload-token" />

## 上传凭证 [#上传凭证]

关于上传凭证的详细介绍，请参见[上传凭证](/products/kodo/csharp/2-c-sdk-v7-2-15)。可以使用`Auth.CreateUploadToken`来生成上传凭证，请参考上述的“鉴权”部分或者后面的“上传文件”示例代码。

<a id="qiniu-upload-methods" />

## 上传方式选择 [#上传方式选择]

此SDK提供了两种上传模式：[表单上传](/products/kodo/development-guidelines/upload-types/1-form-upload)和[分片上传](/products/kodo/development-guidelines/upload-types/2-chunked-upload)。

**表单上传**：一般适用于文件体积较小的情形，请使用`FormUploader`

**分片上传**：适用于大文件或者需要支持断点续上传的情形，请使用`ResumableUploader`

**自动选择**：自动选择以上两种方式之一（但需要预先知道待上传文件或者数据(流)的大小），请使用`UploadManager`

需要注意的是，如果您需要上传“一种特殊的数据流（此流不支持查找）”时（例如NetworkStream，请参阅后面的“上传数据流”示例），请使用FormUploader或者ResumableUploader的UploadStream方法，因为这两个方法不需要预先知道流的长度。

<a id="qiniu-upload-simple" />

## 简单上传 [#简单上传]

使用FormUploader,ResumableUploader或者UploadManager，以下代码示意了如何使用UploadManager来上传一个本地文件

```csharp
using System;
using Qiniu.Common;
using Qiniu.IO;
using Qiniu.IO.Model;
using Qiniu.Http;

namespace CSharpSDKExamples
{
    public class UploadDemo
    {
        /// <summary>
        /// 简单上传-上传小文件
        /// </summary>
        public void UploadFile()
        {
            // 生成(上传)凭证时需要使用此Mac
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            string bucket = "test";
            string saveKey = "1.png";
            string localFile = "D:\\QFL\\1.png";

            // 上传策略，参见
            // [/products/kodo/development-guidelines/security/1-put-policy](/products/kodo/development-guidelines/security/1-put-policy)
            PutPolicy putPolicy = new PutPolicy();

            // 如果需要设置为"覆盖"上传(如果云端已有同名文件则覆盖)，请使用 SCOPE = "BUCKET:KEY"
            // putPolicy.Scope = bucket + ":" + saveKey;
            putPolicy.Scope = bucket;

            // 上传策略有效期(对应于生成的凭证的有效期)
            putPolicy.SetExpires(3600);

            // 上传到云端多少天后自动删除该文件，如果不设置（即保持默认默认）则不删除
            putPolicy.DeleteAfterDays = 1;

            // 生成上传凭证，参见
            // [/products/kodo/development-guidelines/security/2-upload-token](/products/kodo/development-guidelines/security/2-upload-token)

            string jstr = putPolicy.ToJsonString();
            string token = Auth.CreateUploadToken(mac, jstr);

            UploadManager um = new UploadManager();

            HttpResult result = um.UploadFile(localFile, saveKey, token);

            Console.WriteLine(result);
        }
    }
}
```

<a id="qiniu-upload-bytes" />

## 字节数据上传 [#字节数据上传]

使用FormUploader,ResumableUploader或者UploadManager，以下代码示意了如何使用FormUploader来上传字节数据

```csharp
using System;
using Qiniu.Common;
using Qiniu.IO;
using Qiniu.IO.Model;
using Qiniu.Http;

namespace CSharpSDKExamples
{
    public class UploadDemo
    {
        /// <summary>
        /// 简单上传-上传字节数据
        /// </summary>
        public void UploadData()
        {
            // 生成(上传)凭证时需要使用此Mac
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            string bucket = "test";
            string saveKey = "myfile";
            byte[] data = System.IO.File.ReadAllBytes("D:/QFL/1.mp3");
            //byte[] data = System.Text.Encoding.UTF8.GetBytes("Hello World!");

            // 上传策略，参见
            // [/products/kodo/development-guidelines/security/1-put-policy](/products/kodo/development-guidelines/security/1-put-policy)
            PutPolicy putPolicy = new PutPolicy();

            // 如果需要设置为"覆盖"上传(如果云端已有同名文件则覆盖)，请使用 SCOPE = "BUCKET:KEY"
            // putPolicy.Scope = bucket + ":" + saveKey;
            putPolicy.Scope = bucket;

            // 上传策略有效期(对应于生成的凭证的有效期)
            putPolicy.SetExpires(3600);

            // 上传到云端多少天后自动删除该文件，如果不设置（即保持默认默认）则不删除
            putPolicy.DeleteAfterDays = 1;

            // 生成上传凭证，参见
            // [/products/kodo/development-guidelines/security/2-upload-token](/products/kodo/development-guidelines/security/2-upload-token)

            string jstr = putPolicy.ToJsonString();
            string token = Auth.CreateUploadToken(mac, jstr);

            FormUploader fu = new FormUploader();

            HttpResult result = fu.UploadData(data, saveKey, token);

            Console.WriteLine(result);
        }
    }
}
```

<a id="qiniu-upload-stream" />

## 数据流上传 [#数据流上传]

使用FormUploader,ResumableUploader或者UploadManager，如果预先不知道上传的流的长度，请使用FormUploader或者ResumableUploader，以下代码示意了如何使用FormUploader来上传一个网络流（“此流不支持查找操作”）：

```csharp
using System;
using Qiniu.Common;
using Qiniu.IO;
using Qiniu.IO.Model;
using Qiniu.Http;

namespace CSharpSDKExamples
{
    public class UploadDemo
    {
        /// <summary>
        /// 上传（来自网络回复的）数据流
        /// </summary>
        public void UploadStream()
        {
            // 生成(上传)凭证时需要使用此Mac
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            string bucket = "test";
            string saveKey = "1.jpg";

            // 上传策略，参见
            // [/products/kodo/development-guidelines/security/1-put-policy](/products/kodo/development-guidelines/security/1-put-policy)
            PutPolicy putPolicy = new PutPolicy();

            // 如果需要设置为"覆盖"上传(如果云端已有同名文件则覆盖)，请使用 SCOPE = "BUCKET:KEY"
            // putPolicy.Scope = bucket + ":" + saveKey;
            putPolicy.Scope = bucket;

            // 上传策略有效期(对应于生成的凭证的有效期)
            putPolicy.SetExpires(3600);

            // 上传到云端多少天后自动删除该文件，如果不设置（即保持默认默认）则不删除
            putPolicy.DeleteAfterDays = 1;

            // 生成上传凭证，参见
            // [/products/kodo/development-guidelines/security/2-upload-token](/products/kodo/development-guidelines/security/2-upload-token)

            string jstr = putPolicy.ToJsonString();
            string token = Auth.CreateUploadToken(mac, jstr);

            try
            {
                string url = "http://img.ivsky.com/img/tupian/pre/201610/09/beifang_shanlin_xuejing-001.jpg";
                var wReq = System.Net.WebRequest.Create(url) as System.Net.HttpWebRequest;
                var resp = wReq.GetResponse() as System.Net.HttpWebResponse;
                using (var stream = resp.GetResponseStream())
                {
                    // 请不要使用UploadManager的UploadStream方法，因为此流不支持查找(无法获取Stream.Length)
                    // 请使用FormUploader或者ResumableUploader的UploadStream方法
                    FormUploader fu = new FormUploader();
                    var result = fu.UploadStream(stream, "xuejing-001.jpg", token);
                    Console.WriteLine(result);
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex);
            }
        }
    }
}
```

<a id="qiniu-upload-overwrite" />

## 覆盖上传 [#覆盖上传]

在上传策略中设置`SCOPE = "BUCKET:KEY"`:

```csharp
PutPolicy putPolicy = new PutPolicy();
putPolicy.Scope = bucket + ":" + saveKey;
```

其余部分代码类似。

<a id="qiniu-upload-resumable" />

## 断点续上传 [#断点续上传]

对于大尺寸文件的上传，可能需要进行分片上传或者需要从中断后的位置继续上传，这时请使用ResumeUploader。

```csharp
using System;
using Qiniu.Common;
using Qiniu.IO;
using Qiniu.IO.Model;
using Qiniu.Http;

namespace CSharpSDKExamples
{
    public class UploadDemo
    {
        /// <summary>
        /// 上传大文件，可以从上次的断点位置继续上传
        /// </summary>
        public void UploadBigFile()
        {
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            string bucket = "test";
            string saveKey = "1.mp4";
            string localFile = "D:\\QFL\\1.mp4";

            // 断点记录文件，可以不用设置，让SDK自动生成，如果出现续上传的情况，SDK会尝试从该文件载入断点记录
            // 对于不同的上传任务，请使用不同的recordFile
            string recordFile = "D:\\QFL\\resume.12345";

            PutPolicy putPolicy = new PutPolicy();
            putPolicy.Scope = bucket;
            putPolicy.SetExpires(3600);

            string token = Auth.CreateUploadToken(mac, putPolicy.ToJsonString());

            // 包含两个参数，并且都有默认值
            // 参数1(bool): uploadFromCDN是否从CDN加速上传，默认否
            // 参数2(enum): chunkUnit上传分片大小，可选值128KB,256KB,512KB,1024KB,2048KB,4096KB
            ResumableUploader ru = new ResumableUploader(false, ChunkUnit.U1024K);

            // ResumableUploader.UploadFile有多种形式，您可以根据需要来选择
            //
            // 最简模式，使用默认recordFile和默认uploadProgressHandler
            // UploadFile(localFile,saveKey,token)
            //
            // 基本模式，使用默认uploadProgressHandler
            // UploadFile(localFile,saveKey,token,recordFile)
            //
            // 一般模式，使用自定义进度处理(可以监视上传进度)
            // UploadFile(localFile,saveKey,token,recordFile,uploadProgressHandler)
            //
            // 高级模式，包含上传控制(可控制暂停/继续 或者强制终止)
            // UploadFile(localFile,saveKey,token,recordFile,uploadProgressHandler,uploadController)
            //

            // 支持自定义参数
            //var extra = new System.Collections.Generic.Dictionary<string, string>();
            //extra.Add("FileType", "UploadFromLocal");
            //extra.Add("YourKey", "YourValue");
            //uploadFile(...,extra,...)

            //最大尝试次数(有效值1~20)，在上传过程中(如mkblk或者bput操作)如果发生错误，它将自动重试，如果没有错误则无需重试
            int maxTry = 10;

            // 使用默认进度处理，使用自定义上传控制
            UploadProgressHandler upph = new UploadProgressHandler(ResumableUploader.DefaultUploadProgressHandler);
            UploadController upctl = new UploadController(uploadControl);
            HttpResult result = ru.UploadFile(localFile, saveKey, token, recordFile, maxTry, upph, upctl);

            Console.WriteLine(result);
        }

        // 内部变量，仅作演示
        private static bool paused = false;

        /// <summary>
        /// 上传控制
        /// </summary>
        /// <returns></returns>
        private static UPTS uploadControl()
        {
            // 这个函数只是作为一个演示，实际当中请根据需要来设置
            // 这个演示的实际效果是“走走停停”，也就是停一下又继续，如此重复直至上传结束
            paused = !paused;

            if (paused)
            {
                return UPTS.Suspended;
            }
            else
            {
                return UPTS.Activated;
            }
        }
    }
}
```

<a id="qiniu-upload-persist" />

## 上传&预转持续化 [#上传预转持续化]

如果需要在在资源上传后自动触发[持久化处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop)，在PutPolicy（[上传策略](/products/kodo/development-guidelines/security/1-put-policy)）中设置persistentOps这一项即可。

```csharp
PutPolicy putPolicy = new PutPolicy();
// ... (这里省略了putPolicy的一些设置)
putPolicy.PersistentOps = "PERSISTENT_OPS";
```

其中`PERSISTENT_OPS`可以参考[persistentOps详解](/products/kodo/development-guidelines/security/1-put-policy#put-policy-persistent-ops-explanation)

<a id="qiniu-download-module" />

# 下载文件 [#下载文件]

* <a href="#qiniu-download-public">
    下载可公开访问的文件
  </a>
* <a href="#qiniu-download-private">
    下载私有空间中的文件
  </a>

<a id="qiniu-download-public" />

## 下载可公开访问的文件 [#下载可公开访问的文件]

可下载网络上或者公开空间中的小文件（如文本、图片等）。

```csharp
using System;
using Qiniu.Common;
using Qiniu.IO;
using Qiniu.IO.Model;
using Qiniu.Http;

namespace CSharpSDKExamples
{
    public class DownloadDemo
    {
        /// <summary>
        /// 下载可公开访问的文件
        /// </summary>
        public void DownloadFile()
        {
            // 文件URL
            string rawUrl = "http://img.ivsky.com/img/tupian/pre/201610/09/beifang_shanlin_xuejing-001.jpg";
            // 要保存的文件名，如果已存在则默认覆盖
            string saveFile = "D:\\QFL\\saved-snow.jpg";

            // 可公开访问的url，直接下载
            HttpResult result = DownloadManager.Download(rawUrl, saveFile);

            Console.WriteLine(result);
        }
    }
}
```

<a id="qiniu-download-private" />

## 下载私有空间中的文件 [#下载私有空间中的文件]

私有空间中的文件访问链接需要经过授权，**生成授权下载链接**的过程如下：

```csharp
ACC_URL = RAW_URL+Expire+Token
```

比如原始链接` http://example.com/file/1.jpg`

加上过期时间戳 `http://example.com/file/1.jpg?e=1476783956`

（如果原始链接中已包含?打头的query字符串，则时间戳字符串改为`&e=...`）

然后Auth生成token拼接上去 `http://example.com/file/1.jpg?e=1476783956&token=Token`

可参考下面的方法下载私有空间中的小文件：

```csharp
using System;
using Qiniu.Common;
using Qiniu.Util;
using Qiniu.IO;
using Qiniu.IO.Model;
using Qiniu.Http;

namespace CSharpSDKExamples
{
    public class DownloadDemo
    {
        /// <summary>
        /// 下载私有空间中的文件
        /// </summary>
        public void DownloadPrivateFile()
        {
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            string rawUrl = "http://your-bucket.bkt.clouddn.com/1.jpg";
            string saveFile = "D:\\QFL\\saved-1.jpg";

            // 设置下载链接有效期3600秒
            int expireInSeconds = 3600;
            string accUrl = DownloadManager.CreateSignedUrl(mac, rawUrl, expireInSeconds);

            // 接下来可以使用accUrl来下载文件
            HttpResult result = DownloadManager.Download(accUrl, saveFile);

            Console.WriteLine(result);
        }
    }
}
```

<a id="qiniu-bucket-module" />

# 空间文件管理 [#空间文件管理]

* <a href="#qiniu-bucket-functions">
    支持的功能列表
  </a>
* <a href="#qiniu-bucket-simple">
    简单处理
  </a>
* <a href="#qiniu-bucket-batch">
    批量处理
  </a>
* <a href="#qiniu-bucket-listfiles">
    获取空间文件列表
  </a>
* <a href="#qiniu-bucket-update">
    更新文件生命周期
  </a>

<a id="qiniu-bucket-functions" />

## 支持的功能 [#支持的功能]

下表列举了空间管理的一些基本功能（部分不常见的功能未在此列举）：

| 功能          | 函数                                               | 说明                  |
| ----------- | ------------------------------------------------ | ------------------- |
| 获取文件信息      | Stat(bucket,key)                                 | 文件名、大小、Hash等信息      |
| 修改文件类型      | Chgm(bucket,key,mimeType)                        | 修改后的类型为`mimeType`   |
| 移动或重命名文件    | Move(srcBucket,srcKey,dstBucket,dstKey,\[force]) | 可选参数force           |
| 复制文件        | Copy(srcBucket,srcKey,dstBucket,dstKey,\[force]) | 可选参数force           |
| 删除文件        | Delete(bucket,key)                               |                     |
| 设置或更新文件生存时间 | UpdateLifecycle(bucket,key,days)                 | 设置days=0表示取消        |
| 获取空间文件列表    | ListFiles(bucket)                                | 另请参阅后面的“获取文件列表”示例   |
| 抓取网络资源到空间   | Fetch(resURL,bucket,key)                         |                     |
| 更新镜像空间中的文件  | Prefetch(resURL,bucket,key)                      | 空间`bucket`设置了“镜像存储” |
| 资源管理批量操作    | Batch(opstr)                                     | 另请参阅后面的“批量处理”示例     |
| 批量获取文件信息    | BatchStat(bucket,keys)                           | 参数keys是string数组     |
| 批量删除文件      | BatchDelete(bucket,keys)                         | 参数keys是string数组     |

<a id="qiniu-bucket-simple" />

## 简单处理 [#简单处理]

支持stat、copy、move、delete等，其中move/copy支持force参数(强制覆盖选项，即如果目标文件已存在，可以设置强制覆盖参数force来覆盖那个文件的内容)。

以下代码示意了如何获取空间中文件的信息(stat)：

```csharp
using System;
using Qiniu.Common;
using Qiniu.RS;
using Qiniu.RS.Model;
using Qiniu.Http;

namespace CSharpSDKExamples
{
    public BucketDemo
    {
        /// <summary>
        /// 获取文件基本信息
        /// </summary>
        public void Stat()
    {
        // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
        // 实际应用中，请自行设置您的AccessKey和SecretKey
        Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

        string bucket = "test";
        string key = "1.avi";

        BucketManager bm = new BucketManager(mac);

        StatResult result = bm.Stat(bucket, key);

        Console.WriteLine(result);
    }
}
}
```

其他操作类似。

<a id="qiniu-bucket-batch" />

## 批量处理 [#批量处理]

batch批处理请求的主体内容具有op=OP1\&op=OP2\&op=...这样的格式，其中op=OPS作为一个单位，用&符号相连，OPS是以上stat,copy,move,delete等操作字符串。

```csharp
using System;
using Qiniu.Common;
using Qiniu.RS;
using Qiniu.RS.Model;
using Qiniu.Http;

namespace CSharpSDKExamples
{
    public class BucketDemo
    {
        /// <summary>
        /// 批量操作
        /// </summary>
        public void Batch()
        {
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            // 批量操作类似于
            // op=<op1>&op=<op2>&op=<op3>...
            string batchOps = "op=OP1&op=OP2";
            BucketManager bm = new BucketManager(mac);
            var result = bm.Batch(batchOps);
            // 或者
            //string[] batch_ops={"<op1>","<op2>","<op3>",...};
            //bm.Batch(batch_ops);

            Console.WriteLine(result);
        }
    }
}
```

<a id="qiniu-bucket-listfiles" />

## 获取空间文件列表 [#获取空间文件列表]

在BucketManager类中提供了ListFiles方法`ListFiles(bucket, prefix, marker, limit, delimiter)`.

该方法返回值中，有以下3个字段需要关注：

| 字段             | 含义                       |
| -------------- | ------------------------ |
| Marker         | 请参阅下述的marker参数           |
| Items          | 返回的结果，其中包括文件名、hash、大小等信息 |
| CommonPrefixes | 请参阅下述的delimiter和prefix参数 |

函数参数说明如下：

| 参数        | 含义                                                                                                                                                                                                                                            |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bucket    | 目标空间名称                                                                                                                                                                                                                                        |
| prefix    | 返回指定文件名前缀的文件列表(prefix可设为null)                                                                                                                                                                                                                 |
| marker    | 考虑到设置limit后返回的文件列表可能不全(需要重复执行listFiles操作) 执行listFiles操作时使用marker标记来追加新的结果。**特别注意**首次执行listFiles操作时marker为null                                                                                                                                 |
| limit     | 每次返回结果所包含的文件总数限制(limit最大值1000，*建议值100*)                                                                                                                                                                                                       |
| delimiter | 分隔符，比如-或者/等等，可以模拟作为目录结构(参考下述示例)。假设指定空间中有2个文件 fakepath/1.txt fakepath/2.txt 现设置delimiter=/ 得到结果items =\[]，commonPrefixes = \[fakepath/] 调整prefix=fakepath/ delimiter=null 得到所需结果items=\[1.txt,2.txt] 于是可以在本地先创建一个目录fakepath,然后在该目录下写入items中的文件 |

以下是一个获取文件列表的示例：

```csharp
using System;
using Qiniu.Common;
using Qiniu.RS;
using Qiniu.RS.Model;
using Qiniu.Http;

namespace CSharpSDKExamples
{
    public class BucketDemo
    {
        /// <summary>
        /// 获取空间文件列表
        /// </summary>
        public void ListFiles()
        {
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            string bucket = "test";
            string marker = ""; // 首次请求时marker必须为空
            string prefix = null; // 按文件名前缀保留搜索结果
            string delimiter = null; // 目录分割字符(比如"/")
            int limit = 100; // 单次列举数量限制(最大值为1000)

            BucketManager bm = new BucketManager(mac);
            //List<FileDesc> items = new List<FileDesc>();
            //List<string> commonPrefixes = new List<string>();

            do
            {
                ListResult result = bm.ListFiles(bucket, prefix, marker, limit, delimiter);

                Console.WriteLine(result);

                marker = result.Result.Marker;

                //if (result.Result.Items != null)
                //{
                //    items.AddRange(result.Result.Items);
                //}

                //if (result.Result.CommonPrefixes != null)
                //{
                //    commonPrefixes.AddRange(result.Result.CommonPrefixes);
                //}

            } while (!string.IsNullOrEmpty(marker));

            //foreach (string cp in commonPrefixes)
            //{
            //    Console.WriteLine(cp);
            //}

            //foreach(var item in items)
            //{
            //    Console.WriteLine(item.Key);
            //}
        }
    }
}
```

<a id="qiniu-bucket-update" />

## 更新文件生命周期 [#更新文件生命周期]

```csharp
using System;
using Qiniu.Common;
using Qiniu.RS;
using Qiniu.RS.Model;
using Qiniu.Http;

namespace CSharpSDKExamples
{
    public BucketDemo
    {
        /// <summary>
        /// 设置或更新文件生命周期
        /// </summary>
        public void UpdateLifecycle()
    {
        // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
        // 实际应用中，请自行设置您的AccessKey和SecretKey
        Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

        string bucket = "test";
        string key = "1.jpg";

        BucketManager bm = new BucketManager(mac);

        // 新的deleteAfterDays，设置为0表示取消lifecycle
        int deleteAfterDays = 1;
        BucketManager bm = new BucketManager(mac);
        var result = bm.UpdateLifecycle(bucket, key, deleteAfterDays);

        Console.WriteLine(result);
    }
}
}
```

<a id="qiniu-processing" />

# 持久化操作 [#持久化操作]

如果需要对已保存在空间中的资源进行云处理并将结果持久化，可以使用[持久化数据处理](/products/dora/processing-mechanism/persist/0-persistent-data-processing-pfop),
如果需要使用独立资源的处理队列，建议先创建一个队列(可将队列名赋给下述示例中的pipeline变量)，队列的创建可以参考[音视频转码界面化操作队列](/faq/dora/other-dora/3853-how-to-create-audio-and-video-processing-private-queues)

```csharp
using System;
using Qiniu.Common;
using Qiniu.RSF;
using Qiniu.RSF.Model;
using Qiniu.Util;

namespace CSharpSDKExamples
{
    public class ProcessingDemo
    {
        /// <summary>
        /// 持久化并保存处理结果
        /// </summary>
        public void PfopAndSave()
        {
            string bucket = "test";
            string key = "1.avi";
            // 队列名称，如果没有，请设置为null
            // 另请参阅https://qiniu.kf5.com/hc/kb/article/112978/
            string pipeline = "MEDIAPROC_PIPELINE";
            // 接收处理结果通知的URL，另请参阅
            // [/products/dora/file-processing/4-mkzip#pfop-notification](/products/dora/file-processing/4-mkzip#pfop-notification)
            string notifyUrl = "NOTIFY_URL";
            bool force = false;

            // 要保存的目标空间
            string dstBucket = "dest-bucket";
            string dstKey = "2.mp4";
            string saveAsUri = StringHelper.urlSafeBase64Encode(dstBucket + ":" + dstKey);
            // 需要执行的数据处理,例如视频转码
            string fopM = "FILE_OPS"; //示例: "avthumb/mp4";
            // 使用管道'|'命令，将处理结果saveas另存
            string fops = fopM + "|saveas/" + saveAsUri;

            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            OperationManager ox = new OperationManager(mac);
            PfopResult result = ox.Pfop(bucket, key, fops, pipeline, notifyUrl, force);

            // 稍后可以根据PersistentId查询处理进度/结果
            //string persistentId = result.PersistentId;
            //HttpResult pr = ox.Prefop(persistentId);
            //Console.WriteLine(pr);

            Console.WriteLine(result);
        }
    }
}
```

其中`FILE_OPS`就是要进行的操作，如：`vframe/jpg/offset/1/w/480/h/360/rotate/90`表示视频截图。

<a id="qiniu-cdn-module" />

# CDN加速 [#cdn加速]

融合CDN加速的功能有：[缓存刷新](/products/kodo/csharp/2-c-sdk-v7-2-15)（包括文件刷新和目录刷新）、[文件预取](/products/kodo/csharp/2-c-sdk-v7-2-15)、获取[流量带宽](/products/kodo/csharp/2-c-sdk-v7-2-15)、获取[日志下载](/products/kodo/csharp/2-c-sdk-v7-2-15)链接、生成[时间戳防盗链](/faq/cdn/domain-name-configuration-problem/1670-timestamp-hotlinking-prevention)，下面分别是对应的示例。

* <a href="#qiniu-cnd-refresh-url">
    文件刷新
  </a>
* <a href="#qiniu-cnd-refresh-dir">
    目录刷新
  </a>
* <a href="#qiniu-cdn-prefetch">
    文件预取操作
  </a>
* <a href="#qiniu-cdn-flux">
    获取域名流量
  </a>
* <a href="#qiniu-cdn-bandwidth">
    获取域名带宽
  </a>
* <a href="#qiniu-cdn-loglist">
    获取日志下载链接
  </a>
* <a href="#qiniu-cdn-hotlink">
    构建时间戳防盗链访问链接
  </a>

<a id="qiniu-cdn-refresh-url" />

## 文件刷新 [#文件刷新]

```csharp
using System;
using Qiniu.Util;
using Qiniu.CDN;
using Qiniu.CDN.Model;

namespace CSharpSDKExamples
{
    public class FusionDemo
    {
        /// <summary>
        /// 缓存刷新
        /// </summary>
        public void CdnRefresh()
        {
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            CdnManager cdnMgr = new CdnManager(mac);

            string[] urls = new string[] { "http://yourdomain.bkt.clouddn.com/somefile.php" };

            var result = cdnManager.RefreshUrls(urls);

            // 或者使用下面的方法
            //RefreshRequest request = new RefreshRequest();
            //request.AddUrls(urls);
            //var result = cdnMgr.RefreshUrlsAndDirs(request);

            Console.WriteLine(result);
        }
    }
}
```

<a id="qiniu-cdn-refresh-dir" />

## 目录刷新 [#目录刷新]

```csharp
using System;
using Qiniu.Util;
using Qiniu.CDN;
using Qiniu.CDN.Model;

namespace CSharpSDKExamples
{
    public class FusionDemo
    {
        /// <summary>
        /// 缓存刷新
        /// </summary>
        public void CdnRefresh()
        {
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            CdnManager cdnMgr = new CdnManager(mac);

            string[] dirs = new string[] { "http://yourdomain.bkt.clouddn.com/" };

            var result = cdnMgr.RefreshDirs(dirs);

            // 或者使用下面的方法
            //RefreshRequest request = new RefreshRequest();
            //request.AddDirs(dirs);
            //var result = cdnMgr.RefreshUrlsAndDirs(request);

            Console.WriteLine(result);
        }
    }
}
```

<a id="qiniu-cdn-prefetch" />

## 文件预取操作 [#文件预取操作]

```csharp
using System;
using Qiniu.Util;
using Qiniu.CDN;
using Qiniu.CDN.Model;

namespace CSharpSDKExamples
{
    public class FusionDemo
    {
        /// <summary>
        /// 文件预取
        /// </summary>
        public void CdnPrefetch()
        {
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            CdnManager cdnMgr = new CdnManager(mac);

            string[] urls = new string[] { "http://yourdomain.clouddn.com/somefile.php" };

            var result = cdnMgr.PrefetchUrls(urls);

            // 或者使用下面的方法
            //PrefetchRequest request = new PrefetchRequest(urls);
            //var result = cdnMgr.PrefetchUrls(request);

            Console.WriteLine(result);
        }
    }
}
```

<a id="qiniu-cdn-flux" />

## 获取域名流量 [#获取域名流量]

```csharp
using System;
using Qiniu.Util;
using Qiniu.CDN;
using Qiniu.CDN.Model;

namespace CSharpSDKExamples
{
    public class FusionDemo
    {
        /// <summary>
        /// 查询流量
        /// </summary>
        public void GetFluxData()
        {
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            CdnManager cdnMgr = new CdnManager(mac);

            FluxRequest request = new FluxRequest();
            request.StartDate = "2016-09-01";
            request.EndDate = "2016-09-02";
            request.Granularity = "day";
            request.Domains = "DOMAIN1;DOMAIN2";
            var result = cdnMgr.GetFluxData(request);

            Console.WriteLine(result);
        }
    }
}
```

<a id="qiniu-cdn-bandwidth" />

## 获取域名带宽 [#获取域名带宽]

```csharp
using System;
using Qiniu.Util;
using Qiniu.CDN;
using Qiniu.CDN.Model;

namespace CSharpSDKExamples
{
    public class FusionDemo
    {
        /// <summary>
        /// 查询带宽
        /// </summary>
        public void GetBandwidthData()
        {
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            CdnManager cdnMgr = new CdnManager(mac);

            BandwidthRequest request = new BandwidthRequest();
            request.StartDate = "2016-09-01";
            request.EndDate = "2016-09-20";
            request.Granularity = "day";
            request.Domains = "yourdomain.bkt.clouddn.com;yourdomain2;yourdomain3";
            var result = cdnMgr.GetBandwidthData(request);

            Console.WriteLine(result);
        }
    }
}
```

<a id="qiniu-cdn-loglist" />

## 获取日志列表 [#获取日志列表]

可以获取一个或多个域名在某一天的日志列表（下载链接），参考如下示例：

```csharp
using System;
using Qiniu.Util;
using Qiniu.CDN;
using Qiniu.CDN.Model;

namespace CSharpSDKExamples
{
    public class FusionDemo
    {
        /// <summary>
        /// 查询日志
        /// </summary>
        public void GetCdnLogList()
        {
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            CdnManager cdnMgr = new CdnManager(mac);

            LogListRequest request = new LogListRequest();
            request.Day = "2016-09-01"; // date:which-day
            request.Domains = "DOMAIN1;DOMAIN2"; // domains
            var result = cdnMgr.GetCdnLogList(request);

            Console.WriteLine(result);
        }
    }
}
```

<a id="qiniu-cdn-hotlink" />

## 构建时间戳防盗链访问链接 [#构建时间戳防盗链访问链接]

```csharp
using System;
using Qiniu.Util;
using Qiniu.CDN;
using Qiniu.CDN.Model;

namespace CSharpSDKExamples
{
    public class FusionDemo
    {
        /// <summary>
        /// 生成时间戳防盗链接
        /// </summary>
        public void HotLink()
        {
            // 这个示例单独使用了一个Settings类，其中包含AccessKey和SecretKey
            // 实际应用中，请自行设置您的AccessKey和SecretKey
            Mac mac = new Mac(Settings.AccessKey, Settings.SecretKey);

            CdnManager cdnMgr = new CdnManager(mac);

            TimestampAntiLeechUrlRequest request = new TimestampAntiLeechUrlRequest();
            request.Host = "http://your-host";
            request.Path = "/path/";
            request.File = "file-name";
            request.Query = "?version=1.1";
            request.SetLinkExpire(600); // 设置有效期，单位:秒

            string prefLink = cdnMgr.CreateTimestampAntiLeechUrl(request);

            Console.WriteLine(prefLink);
        }
    }
}
```

# 使用案例 [#使用案例]

在QSunSync和qiniulab这两个工具中，都用到了此SDK，研究它们的源代码也能帮助您更好地了解此SDK：

[QSunSync](https://github.com/qiniu/QSunSync)，图形界面同步工具（Windows）

[QiniuLab](https://github.com/qiniu/qiniulab)，图像界面实验工具，不用编写繁复的代码就可以测试七牛云的多项服务（Windows）

# API参考手册 [#api参考手册]

* [对象存储API参考手册](/faq/kodo)

* [数据处理API参考手册](/faq/dora)

* [融合CDN加速API参考手册](/products/kodo/csharp/2-c-sdk-v7-2-15)

# 常见问题 [#常见问题]

更多使用方法。可以参考[QiniuTests](https://github.com/qiniu/csharp-sdk/blob/master/src/QiniuTests/Storage/BucketManagerTests.cs)下的示例。

问题排查。在SDK的大多函数中(如果有)响应消息，可以反馈给我们进行问题排查。

# 相关资源 [#相关资源]

如果您有任何关于我们文档或产品的建议和想法，欢迎到我们的技术论坛参与讨论。

* [技术论坛](http://segmentfault.com/qiniu) - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务

* [提交工单](http://support.qiniu.com/hc/request/guest/) - 如果您的问题不适合在论坛讨论或得不到回答，您也可以提交一个工单，技术支持人员会尽快回复您

* [博客](http://blog.qiniu.com/) - 这里会持续发布市场活动和技术分享文章

* [微博](http://weibo.com/qiniutek)

* [常见问题](https://support.qiniu.com/)

# 贡献代码 [#贡献代码]

1. Fork

2. 创建您的特性分支 git checkout -b my-new-feature

3. 提交您的改动 git commit -am 'Added some feature'

4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature

5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

# 许可证 [#许可证]

Copyright (c) 2017 [qiniu.com](https://www.qiniu.com/)

基于 MIT 协议发布:

[www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)


# C# SDK (/products/kodo/csharp)



最近更新时间: 2026-08-18 15:17:28

### **C# SDK 使用指南** [#c-sdk-使用指南]

[NuGet release](https://www.nuget.org/packages/Qiniu)

此 C# SDK 基于 .Net Standard 2.0，适用于 .NET Core 2.0 和 .NET Framework v4.6.1，详情 [查看官网](https://docs.microsoft.com/en-us/dotnet/standard/net-standard)。 基于<span id="Productname">七牛云</span> API 参考手册构建。使用此 SDK 构建您的网络应用程序，能让您以非常便捷地方式将数据安全地存储到<span id="Productname">七牛云</span>上。无论您的网络应用是一个网站程序，还是包括从云端（服务端程序）到终端（手持设备应用）的架构的服务或应用，通过<span id="Productname">七牛云存储</span>及其 SDK，都能让您应用程序的终端用户高速上传和下载，同时也让您的服务端更加轻盈。

C# SDK 属于服务端 SDK 之一，主要有如下功能：

1. 提供生成客户端上传所需的上传凭证的功能
2. 提供文件从服务端直接上<span id="Productname">七牛</span>的功能
3. 提供对<span id="Productname">七牛</span>空间中文件进行管理的功能
4. 提供对<span id="Productname">七牛</span>空间中文件进行处理的功能
5. <span id="del_in_kodoe_docs_line">
     提供七牛 CDN 相关的刷新，预取，日志功能
   </span>

<a id="opensource" />

# **开源** [#开源]

* [c# SDK 项目地址](https://github.com/qiniu/csharp-sdk)
* [c# SDK 发布地址](https://github.com/qiniu/csharp-sdk/releases)
* [c# SDK 历史文档](/products/kodo/csharp/2-c-sdk-v7-2-15)

# **安装** [#安装]

* <a href="#qiniu-sdk-nuget">
    包管理器(NuGet)方式安装
  </a>
* <a href="#qiniu-sdk-src">
    从源码编译
  </a>

<a id="qiniu-sdk-nuget" />

**包管理器(NuGet)方式安装**

从 NuGet 来安装，以 Visual Studio 2013/2015 为例(如果您的 Visual Studio 没有安装 NuGet，请先[安装](http://docs.nuget.org/docs/start-here/installing-nuget))。打开 NuGet 程序包管理器搜索 Qiniu 或者在控制台中键入以下命令：

```
Install-Package Qiniu
```

<a id="qiniu-sdk-src" />

**从源码编译**

当然，您也可以直接从源码编译

```
git clone https://github.com/qiniu/csharp-sdk
```

# **鉴权** [#鉴权]

c# SDK 的所有的功能，都需要合法的授权。授权凭证的签算需要<span id="Productname">七牛</span>账号下的一对有效的`Access Key`和`Secret Key`，这对密钥可以通过如下步骤获得：

1. <span id="Null">点击[注册 🔗](https://portal.qiniu.com/signup)</span>开通<span id="Productname">七牛</span>开发者帐号
2. 如果已有账号，直接登录<span id="Productname">七牛</span>开发者后台，<span id="Null">点击[这里 🔗](https://portal.qiniu.com/user/key)</span>查看 Access Key 和 Secret Key

<a id="io-put" />

# **文件上传** [#文件上传]

* <a href="#upload-flow">
    上传流程
  </a>
* <a href="#upload-token">
    客户端上传凭证
  </a>
  * <a href="#simple-uptoken">
      简单上传凭证
    </a>
  * <a href="#overwrite-uptoken">
      覆盖上传凭证
    </a>
  * <a href="#returnbody-uptoken">
      自定义上传回复凭证
    </a>
  * <a href="#callback-uptoken">
      带回调业务服务器的凭证
    </a>
  * <span id="del_in_kodoe_docs_line">
      <a href="#pfop-uptoken">带数据处理的凭证</a>
    </span>
  * <a href="#param-uptoken">
      带自定义参数的凭证
    </a>
  * <a href="#general-uptoken">
      综合上传凭证
    </a>
* <a href="#server-upload">
    服务器直传
  </a>
  * <a href="#upload-config">
      构建配置类
    </a>
  * <a href="#upload-config">
      指定上传域名
    </a>
  * <a href="#form-upload-file">
      文件上传（表单方式）
    </a>
  * <a href="#form-upload-bytes">
      字节数组上传（表单方式）
    </a>
  * <a href="#form-upload-stream">
      数据流上传（表单方式）
    </a>
  * <a href="#resume-upload-file">
      文件分片上传（断点续传）
    </a>
  * <a href="#upload-result-parse">
      解析自定义回复内容
    </a>
  * <a href="#upload-callback-verify">
      业务服务器验证存储服务回调
    </a>
  * <a href="#upload-transfer-acceleration">
      上传加速
    </a>

<a id="upload-flow" />

## **上传流程** [#上传流程]

文件上传分为客户端上传（主要是指网页端和移动端等面向终端用户的场景）和服务端上传两种场景，具体可以参考文档[业务流程](/products/kodo/0-programming-model)。

服务端 SDK 在上传方面主要提供两种功能，一种是生成客户端上传所需要的上传凭证，另外一种是直接上传文件到云端。

<a id="upload-token" />

## **客户端上传凭证** [#客户端上传凭证]

客户端（移动端或者 Web 端）上传文件的时候，需要从客户自己的业务服务器获取上传凭证，而这些上传凭证是通过服务端的 SDK 来生成的，然后通过客户自己的业务 API 分发给客户端使用。根据上传的业务需求不同，c# SDK 支持丰富的上传凭证生成方式。

创建各种上传凭证之前，我们需要定义好其中鉴权对象`mac`：

```
Mac mac = new Mac(AccessKey, SecretKey);
```

<a id="simple-uptoken" />

### **简单上传的凭证** [#简单上传的凭证]

最简单的上传凭证只需要`AccessKey`，`SecretKey`和`Bucket`就可以。

```
PutPolicy putPolicy = new PutPolicy();
putPolicy.Scope = Bucket;
string token = Auth.CreateUploadToken(mac, putPolicy.ToJsonString());
```

默认情况下，在不指定上传凭证的有效时间情况下，默认有效期为 1 个小时。也可以自行指定上传凭证的有效期，例如：

```
//自定义凭证有效期（示例2小时，expires单位为秒，为上传凭证的有效时间）
PutPolicy putPolicy = new PutPolicy();
putPolicy.Scope = Bucket;
putPolicy.SetExpires(7200);
string token = Auth.CreateUploadToken(mac, putPolicy.ToJsonString());
```

<a id="overwrite-uptoken" />

### **覆盖上传的凭证** [#覆盖上传的凭证]

覆盖上传除了需要`简单上传`所需要的信息之外，还需要想进行覆盖的文件名称，这个文件名称同时可是客户端上传代码中指定的文件名，两者必须一致。

```
PutPolicy putPolicy = new PutPolicy();
putPolicy.Scope = Bucket + ":" + Key;
putPolicy.SetExpires(7200);
string token = Auth.CreateUploadToken(mac, putPolicy.ToJsonString());
```

<a id="returnbody-uptoken" />

### **自定义上传回复的凭证** [#自定义上传回复的凭证]

默认情况下，文件上传到存储之后，在没有设置`returnBody`或者`回调`相关的参数情况下，存储返回给上传端的回复格式为`hash`和`key`，例如：

```
{"hash":"Ftgm-CkWePC9fzMBTRNmPMhGBcSV","key":"qiniu.jpg"}
```

有时候我们希望能自定义这个返回的 JSON 格式的内容，可以通过设置`returnBody`参数来实现，在`returnBody`中，我们可以使用<span id="Productname">七牛</span>支持的[魔法变量](/products/kodo/development-guidelines/upload-types/0-vars#magicvar)和[自定义变量](/products/kodo/development-guidelines/upload-types/0-vars#xvar)。

```
PutPolicy putPolicy = new PutPolicy();
putPolicy.Scope = Bucket + ":" + Key;
putPolicy.ReturnBody = "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"fsiz\":$(fsize),\"bucket\":\"$(bucket)\",\"name\":\"$(x:name)\"}";
string token = Auth.CreateUploadToken(mac, putPolicy.ToJsonString());
```

则文件上传到存储之后，收到的回复内容如下：

```
{"key":"qiniu.jpg","hash":"Ftgm-CkWePC9fzMBTRNmPMhGBcSV","bucket":"if-bc","fsize":39335,"name":"qiniu"}
```

<a id="callback-uptoken" />

### **带回调业务服务器的凭证** [#带回调业务服务器的凭证]

上面生成的`自定义上传回复`的上传凭证适用于上传端（无论是客户端还是服务端）和存储服务器之间进行直接交互的情况下。在客户端上传的场景之下，有时候客户端需要在文件上传到存储之后，从业务服务器获取相关的信息，这个时候就要用到存储的上传回调及相关回调参数的设置。

```
putPolicy = new PutPolicy();
putPolicy.Scope = Bucket;
putPolicy.CallbackUrl = "http://api.example.com/qiniu/upload/callback";
putPolicy.CallbackBody = "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"fsiz\":$(fsize),\"bucket\":\"$(bucket)\",\"name\":\"$(x:name)\"}";
putPolicy.CallbackBodyType = "application/json";
upToken = Auth.CreateUploadToken(mac, putPolicy.ToJsonString());
Console.WriteLine(upToken);
```

在使用了上传回调的情况下，客户端收到的回复就是业务服务器响应<span id="Productname">七牛</span>的 JSON 格式内容。
通常情况下，我们建议使用`application/json`格式来设置`callbackBody`，保持数据格式的统一性。实际情况下，`callbackBody`也支持`application/x-www-form-urlencoded`格式来组织内容，这个主要看业务服务器在接收到`callbackBody`的内容时如果解析。例如：

```
putPolicy = new PutPolicy();
putPolicy.Scope = Bucket;
putPolicy.CallbackUrl = "http://api.example.com/qiniu/upload/callback";
putPolicy.CallbackBody = "key=$(key)&hash=$(etag)&bucket=$(bucket)&fsize=$(fsize)&name=$(x:name)";
upToken = Auth.CreateUploadToken(mac, putPolicy.ToJsonString());
Console.WriteLine(upToken);
```

<span id="del_in_kodoe_docs_block_start" />

<a id="pfop-uptoken" />

### **带数据处理的凭证** [#带数据处理的凭证]

七牛支持在文件上传到七牛之后，立即对其进行多种指令的数据处理，这个只需要在生成的上传凭证中指定相关的处理参数即可。

```
putPolicy = new PutPolicy();
string saveMp4Entry = Base64.UrlSafeBase64Encode(Bucket + ":avthumb_test_target.mp4");
string saveJpgEntry = Base64.UrlSafeBase64Encode(Bucket + ":vframe_test_target.jpg");
string avthumbMp4Fop = "avthumb/mp4|saveas/" + saveMp4Entry;
string vframeJpgFop = "vframe/jpg/offset/1|saveas/" + saveJpgEntry;
string fops = string.Join(";", new string[] { avthumbMp4Fop, vframeJpgFop });
putPolicy.Scope = Bucket;
putPolicy.PersistentOps = fops;
putPolicy.PersistentPipeline = "video-pipe";
putPolicy.PersistentNotifyUrl = "http://api.example.com/qiniu/pfop/notify";
putPolicy.PersistentType = 0; // 任务类型：0: 普通任务 1: 闲时任务（一旦指定闲时任务，就不能指定 persistentPipeline）
putPolicy.
upToken = Auth.CreateUploadToken(mac, putPolicy.ToJsonString());
Console.WriteLine(upToken);
```

* 队列 pipeline 请参阅[创建私有队列](https://portal.qiniu.com/dora/media-gate/pipeline)；转码操作具体参数请参阅[音视频转码](/products/dora/1-features_introduction)；saveas 请参阅[处理结果另存](/products/dora/1-features_introduction)。
* 闲时任务的功能介绍、使用场景、定价，详见 [闲时任务策略说明](/products/dora/1-features_introduction)。

也可以支持使用工作流模版替代数据处理指令。工作流模板是预先编排好的一系列媒体处理流程（如转码、截图、视频拼接等各类处理），登录 [对象存储控制台](https://portal.qiniu.com/kodo/bucket) 进行创建，详情参考[工作流模板操作指南](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template)，`PersistentWorkflowTemplateId` 对应工作流模板列表的`名称`字段

```
putPolicy = new PutPolicy();
putPolicy.Scope = Bucket;
putPolicy.PersistentWorkflowTemplateId = "tempname";
putPolicy.PersistentPipeline = "video-pipe";
putPolicy.PersistentNotifyUrl = "http://api.example.com/qiniu/pfop/notify";
putPolicy.PersistentType = 0; // 任务类型：0: 普通任务 1: 闲时任务（一旦指定闲时任务，就不能指定 persistentPipeline）
putPolicy.
upToken = Auth.CreateUploadToken(mac, putPolicy.ToJsonString());
Console.WriteLine(upToken);
```

* 需要注意的是，`PersistentWorkflowTemplateId` 和 `PersistentOps` 两个参数只能二选一。

<span id="del_in_kodoe_docs_block_end" />

<a id="param-uptoken" />

### **带自定义参数的凭证** [#带自定义参数的凭证]

存储支持客户端上传文件的时候定义一些自定义参数，这些参数可以在`returnBody`和`callbackBody`里面和<span id="Productname">七牛</span>内置支持的魔法变量（即系统变量）通过相同的方式来引用。这些自定义的参数名称必须以`x:`开头。例如客户端上传的时候指定了自定义的参数`x:name`和`x:age`分别是`string`和`int`类型。那么可以通过下面的方式引用：

```
putPolicy.ReturnBody = "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"fsiz\":$(fsize),\"bucket\":\"$(bucket)\",\"name\":\"$(x:name)\"}";
```

或者

```
putPolicy.CallbackBody = "{\"key\":\"$(key)\",\"hash\":\"$(etag)\",\"fsiz\":$(fsize),\"bucket\":\"$(bucket)\",\"name\":\"$(x:name)\"}";
```

<a id="general-uptoken" />

### **综合上传凭证** [#综合上传凭证]

上面的生成上传凭证的方法，都是通过设置[上传策略 🔗](/products/kodo/development-guidelines/security/1-put-policy)相关的参数来支持的，这些参数可以通过不同的组合方式来满足不同的业务需求，可以灵活地组织你所需要的上传凭证。

<a id="server-upload" />

## **服务端直传** [#服务端直传]

服务端直传是指客户利用<span id="Productname">七牛</span>服务端 SDK 从服务端直接上传文件到存锤，交互的双方一般都在机房里面，所以服务端可以自己生成上传凭证，然后利用 SDK 中的上传逻辑进行上传，最后从<span id="Productname">七牛云</span>获取上传的结果，这个过程中由于双方都是业务服务器，所以很少利用到上传回调的功能，而是直接自定义`returnBody`来获取自定义的回复内容。

<a id="upload-config" />

### **构建配置类** [#构建配置类]

存储支持空间创建在不同的机房，在使用<span id="Productname">七牛</span>的 C# SDK 中的`FormUploader`和`ResumeUploader`上传文件之前，必须要构建一个上传用的`config`对象，在该对象中，可以指定空间对应的`zone`以及其他的一些影响上传的参数。

```
Config config = new Config();
// 空间对应的机房
config.Zone = Zone.ZONE_CN_East;
// 是否使用https域名
config.UseHttps = true;
// 上传是否使用cdn加速
config.UseCdnDomains = true;
```

<span id="del_in_kodoe_docs_block_start" />

其中关于`Zone`对象和机房的关系如下：

| 机 房 | Zone 对象             |
| --- | ------------------- |
| 华 东 | `ZONE_CN_East`      |
| 华 北 | `ZONE_CN_North`     |
| 华 南 | `ZONE_CN_South`     |
| 北 美 | `ZONE_US_North`     |
| 东南亚 | `ZONE_AS_Singapore` |

### **指定上传域名** [#指定上传域名]

在上传代码初始化前，通过自定义Zone实现，示例如下：

```csharp
var customZone = new Zone
{
    // 设置上传域名 (SrcUpHosts)
    // 你可以替换成你的具体域名，例如：new string[] { "http://up.your-domain.com" }
    SrcUpHosts = new string[]
    {
        "http://up.qiniup.com",
        "https://up.qiniup.com"
    }
};

// 2. 创建配置对象并指定使用自定义 Zone
var config = new Config
{
    // ZoneID 可以指定区域，或者留空由 SDK 自动选择
    Zone = customZone,

    // 其他配置...
    UseHttps = false // 根据你的域名协议设置
};

// 3. 初始化上传管理器
var uploadManager = new UploadManager(config);

```

<span id="del_in_kodoe_docs_block_end" />

<a id="form-upload-file" />

### **文件上传（表单方式）** [#文件上传表单方式]

最简单的就是上传本地文件，直接指定文件的完整路径即可上传。

```
Mac mac = new Mac(AccessKey, SecretKey);
// 上传文件名
string key = "key";
// 本地文件路径
string filePath = "D:\\tools\\putty.exe";
// 存储空间名
string Bucket = "7qiniu";

// 设置上传策略
PutPolicy putPolicy = new PutPolicy();
// 设置要上传的目标空间
putPolicy.Scope = Bucket;
// 上传策略的过期时间(单位:秒)
putPolicy.SetExpires(3600);
// 文件上传完毕后，在多少天后自动被删除
putPolicy.DeleteAfterDays = 1;
// 生成上传token
string token = Auth.CreateUploadToken(mac, putPolicy.ToJsonString());

Config config = new Config();
// 设置上传区域
config.Zone = Zone.ZONE_CN_East;
// 设置 http 或者 https 上传
config.UseHttps = true;
config.UseCdnDomains = true;
config.ChunkSize = ChunkUnit.U512K;
// 表单上传
FormUploader target = new FormUploader(config);
HttpResult result = target.UploadFile(filePath, key, token, null);
Console.WriteLine("form upload result: " + result.ToString());
```

<a id="resume-upload-file" />

### **文件分片上传（断点续传）** [#文件分片上传断点续传]

断点续传是在分片上传的基础上实现。SDK 内置两种上传方式：表单上传和分片上传。表单上传使用一个 HTTP POST 请求完成文件的上传，因此比较适合较小的文件。相比而言，分片上传比较适合上传比较大的文件（例如数百 MB 或更大）。
若需深入了解上传方式之间的区别，请参阅上传类型中 [表单上传](/products/kodo/development-guidelines/upload-types/1-form-upload) 、[分片上传 v1 版](/products/kodo/development-guidelines/upload-types/2-chunked-upload) 和 [分片上传 v2 版](/products/kodo/rs/multipartupload-interface) 接口说明。
可以选择分片上传版本，推荐 extra.Version = "v2"，表示 分片上传 v2 版，默认分片上传 v1 版。

```
Mac mac = new Mac(AccessKey, SecretKey);
// 上传文件名
string key = "putty.exe";
// 本地文件路径
string filePath = "D:\\tools\\putty.exe";
// 空间名
string Bucket = "7qiniu";
// 设置上传策略
PutPolicy putPolicy = new PutPolicy();
putPolicy.Scope = Bucket + ":" + key;
putPolicy.SetExpires(3600);
string token = Auth.CreateUploadToken(mac, putPolicy.ToJsonString());
Config config = new Config();
// 设置上传区域
config.Zone = Zone.ZONE_CN_East;
// 设置 http 或者 https 上传
config.UseHttps = true;
config.UseCdnDomains = true;
config.ChunkSize = ChunkUnit.U512K;
ResumableUploader target = new ResumableUploader(config);
PutExtra extra = new PutExtra();
//设置断点续传进度记录文件
extra.ResumeRecordFile = ResumeHelper.GetDefaultRecordKey(filePath, key);
Console.WriteLine("record file:" + extra.ResumeRecordFile);
extra.ResumeRecordFile = "test.progress";
//指定分片上传版本，默认分片上传 v1
extra.Version = "v2";
// 分片上传 v2 指定 part 大小，默认大小为4MB 分片大小范围为1 MB - 1 GB
extra.PartSize = 4 * 1024 * 1024;
// 指定分片并发大小，默认为1
extra.BlockUploadThreads = 4;
HttpResult result = target.UploadFile(filePath, key, token, extra);
Console.WriteLine("resume upload: " + result.ToString());
```

<a id="upload-result-parse" />

## **解析自定义回复内容** [#解析自定义回复内容]

有些情况下，<span id="Productname">七牛</span>返回给上传端的内容不是默认的`hash`和`key`形式，这种情况下，可能出现在自定义`returnBody`或者自定义了`callbackBody`的情况下，前者一般是服务端直传的场景，而后者则是接受上传回调的场景，这两种场景之下，都涉及到需要将自定义的回复进行内容解析，一般建议在交互过程中，都采用`JSON`的方式，这样处理起来方法比较一致，而且`JSON`的方法最通用，基本上了解回复结构就可以处理，这里不再赘述。

<a id="upload-callback-verify" />

## **业务服务器验证存储服务回调** [#业务服务器验证存储服务回调]

在上传策略里面设置了上传回调相关参数的时候，存储在文件上传到服务器之后，会主动地向`callbackUrl`发送 POST 请求的回调，回调的内容为`callbackBody`模版所定义的内容，如果这个模版里面引用了[魔法变量](/products/kodo/development-guidelines/upload-types/0-vars#magicvar)或者[自定义变量](/products/kodo/development-guidelines/upload-types/0-vars#xvar)，那么这些变量会被自动填充对应的值，然后在发送给业务服务器。

业务服务器在收到来自<span id="Productname">七牛</span>的回调请求的时候，可以根据请求头部的`Authorization`字段来进行验证，查看该请求是否是来自<span id="Productname">七牛</span>的未经篡改的请求,具体可以参考[回调鉴权](/faq/kodo/upload-download-problem/1409-seven-cattle-callback-and-callback-authentication)。

**注意**：业务端服务器回调鉴权的 Content-Type 类型应该与上传策略中指定的 callbackBodyType 相同，默认为 application/x-www-form-urlencoded，当 Content-Type 为 application/x-www-form-urlencoded 时，签名内容必须包括请求内容。当 Content-Type 为 application/json 时，签名内容不包括请求内容。

<a id="upload-transfer-acceleration" />

## **上传加速** [#上传加速]

```
Zone zone = new Zone
{
    SrcUpHosts = new string[1] { "<BucketId>.kodo-accelerate.<RegionId>.qiniucs.com" }, // 这里填写空间级别传输加速域名
};

Config config = new Config
{
    Zone = zone,
    UseHttps = true,
};
// 表单上传
FormUploader formUploader = new FormUploader(config);
HttpResult result = formUploader.UploadFile(filePath, key, token, null);
Console.WriteLine("form upload result: " + result.ToString());

// 分片上传
ResumableUploader resumableUploader = new ResumableUploader(config);
HttpResult result = resumableUploader.UploadFile(filePath, key, token, null);
Console.WriteLine("resumable upload result: " + result.ToString());
```

<a id="io-get" />

# **下载文件** [#下载文件]

* <a href="#public-get">
    公开空间
  </a>
* <a href="#private-get">
    私有空间
  </a>

文件下载分为公开空间的文件下载和私有空间的文件下载。

<a id="public-get" />

## **公开空间** [#公开空间]

对于公开空间，其访问的链接主要是将空间绑定的域名（可以是存储空间的默认域名或者是绑定的自定义域名）拼接上空间里面的文件名即可访问，标准情况下需要在拼接链接之前，将文件名进行`urlencode`以兼容不同的字符。

```
string domain = "http://if-pbl.qiniudn.com";
string key = "hello/world/七牛/test.png";
string publicUrl = DownloadManager.CreatePublishUrl(domain, key);
Console.WriteLine(publicUrl);
```

<a id="private-get" />

## **私有空间** [#私有空间]

对于私有空间，首先需要按照公开空间的文件访问方式构建对应的公开空间访问链接，然后再对这个链接进行私有授权签名。

```
Mac mac = new Mac(AccessKey, SecretKey);
string domain = "http://if-pri.qiniudn.com";
string key = "hello/world/七牛/test.png";
string privateUrl = DownloadManager.CreatePrivateUrl(mac, domain, key, 3600);
Console.WriteLine(privateUrl);
```

<a id="rs" />

# **资源管理** [#资源管理]

资源管理包括的主要功能有：

* <a href="#rs-stat">
    获取文件信息
  </a>
* <a href="#rs-chgm">
    修改文件 MimeType
  </a>
* <a href="#rs-chtype">
    修改文件存储类型
  </a>
* <a href="#rs-move">
    移动或重命名文件
  </a>
* <a href="#rs-copy">
    复制文件副本
  </a>
* <a href="#rs-delete">
    删除空间中的文件
  </a>
* <a href="#rs-delete-after-days">
    设置或更新文件生存时间
  </a>
* <a href="#rs-list">
    获取指定前缀文件列表
  </a>
* <a href="#rs-fetch">
    抓取网络资源到空间
  </a>
* <a href="#rs-prefetch">
    更新镜像存储空间中文件内容
  </a>
* <a href="#rs-batch">
    资源管理批量操作
  </a>
  * <a href="#rs-batch-stat">
      批量获取文件信息
    </a>
  * <a href="#rs-batch-chgm">
      批量修改文件类型
    </a>
  * <a href="#rs-batch-delete">
      批量删除文件
    </a>
  * <a href="#rs-batch-copy">
      批量复制文件
    </a>
  * <a href="#rs-batch-move">
      批量移动或重命名文件
    </a>
  * <a href="#rs-batch-deleteAfterDays">
      批量更新文件的有效期
    </a>
  * <a href="#rs-batch-type">
      批量更新文件存储类型
    </a>

资源管理相关的操作首先要构建`BucketManager`对象：

```
// 设置存储区域
Config config = new Config();
config.Zone = Zone.ZONE_CN_East;

Mac mac = new Mac(AccessKey, SecretKey);
BucketManager bucketManager = new BucketManager(mac, config);
```

<a id="rs-stat" />

## **获取文件信息** [#获取文件信息]

```
// 存储空间名
string Bucket = "7qiniu";
// 	待查询文件名
string key = "02.mp4";

StatResult statRet = bucketManager.Stat(Bucket, key);
if (statRet.Code != (int)HttpCode.OK)
{
    Console.WriteLine("stat error: " + statRet.ToString());
}

Console.WriteLine(statRet.Result.Hash);
Console.WriteLine(statRet.Result.MimeType);
Console.WriteLine(statRet.Result.Fsize);
Console.WriteLine(statRet.Result.MimeType);
Console.WriteLine(statRet.Result.FileType);
```

<a id="rs-chgm" />

## **修改文件 MimeType** [#修改文件-mimetype]

```
string Bucket = "7qiniu";
string key = "7qiniu.mp4";

HttpResult ret = bucketManager.ChangeMime(Bucket, key, "application / mpegurl");
if (ret.Code != (int)HttpCode.OK)
{
    Console.WriteLine("change mime error: " + ret.ToString());
    Console.ReadKey();
}
Console.WriteLine(ret.ToString());
```

<a id="rs-chtype" />

## **修改文件存储类型** [#修改文件存储类型]

```
// 存储空间
string Bucket = "7qiniu";
// 文件名
string key = "7qiniu.mp4";
// newType 为 0 表示普通存储，newType 为 1 表示低频存储，newType 为 2 表示归档存储，newType 为 3 表示深度归档存储，newType 为 4 表示归档直读存储
int newType = 1;
HttpResult ret = bucketManager.ChangeType(Bucket, key, newType);
if (ret.Code != (int)HttpCode.OK && !ret.Text.Contains("already in line stat"))
{
    Console.WriteLine("change type error: " + ret.ToString());
}
Console.WriteLine(ret.ToString());
```

<a id="rs-move" />

## **移动或重命名文件** [#移动或重命名文件]

移动操作本身支持移动文件到相同，不同空间中，在移动的同时也可以支持文件重命名。唯一的限制条件是，移动的源空间和目标空间必须在同一个机房。

| 源空间     | 目标空间    | 源文件名 | 目标文件名 | 描述                       |
| ------- | ------- | ---- | ----- | ------------------------ |
| BucketA | BucketA | KeyA | KeyB  | 相当于同空间文件重命名              |
| BucketA | BucketB | KeyA | KeyA  | 移动文件到 BucketB，文件名一致      |
| BucketA | BucketB | KeyA | KeyB  | 移动文件到 BucketB，文件名变成 KeyB |

`move`操作支持强制覆盖选项，即如果目标文件已存在，可以设置强制覆盖选项`force`来覆盖那个文件的内容。

```
// 原始空间
string Bucket = "7qiniu";
// 原始文件名
string Key = "0_01.png";
// 目标空间
string newBucket = "07qiniu";
// 目标文件名
string newKey = "move0_01.png";
// 是否设置强制覆盖
Boolean force = true;
HttpResult copyRet = bucketManager.move(Bucket, Key, newBucket, newKey, force);
if (copyRet.Code != (int)HttpCode.OK)
{
    Console.WriteLine("move error: " + moveRet.ToString());
}
Console.WriteLine(moveRet.ToString());
```

<a id="rs-copy" />

## **复制文件副本** [#复制文件副本]

文件的复制和文件移动其实操作一样，主要的区别是移动后源文件不存在了，而复制的结果是源文件还存在，只是多了一个新的文件副本。

```
// 原始空间
string Bucket = "7qiniu";
// 原始文件名
string Key = "0_01.png";
// 目标空间
string newBucket = "07qiniu";
// 目标文件名
string newKey = "copy0_01.png";
// 是否设置强制覆盖
Boolean force = true;
HttpResult copyRet = bucketManager.copy(Bucket, Key, newBucket, newKey, force);
if (copyRet.Code != (int)HttpCode.OK)
{
    Console.WriteLine("copy error: " + copyRet.ToString());
}
Console.WriteLine(copyRet.ToString());
```

<a id="rs-delete" />

## **删除空间中的文件** [#删除空间中的文件]

```
// 空间名
string Bucket = "7qiniu";
// 文件名
string Key = "10138_7e706ac5317f2993176725cbdf50d0e10f079c05.ppt";

HttpResult deleteRet = bucketManager.Delete(Bucket, Key);
Console.WriteLine("delete error: " + deleteRet.ToString());

if (deleteRet.Code != (int)HttpCode.OK)
{
    Console.WriteLine("delete error: " + deleteRet.ToString());
}
```

<a id="rs-delete-after-days" />

## **设置或更新文件的生存时间** [#设置或更新文件的生存时间]

可以给已经存在于空间中的文件设置文件生存时间，或者更新已设置了生存时间但尚未被删除的文件的新的生存时间。

```
// 存储空间名
string Bucket = "7qiniu";
// 文件名
string key = "0_01.png";

HttpResult expireRet = bucketManager.DeleteAfterDays(Bucket, key, 7);

if (expireRet.Code != (int)HttpCode.OK)
{
    Console.WriteLine("deleteAfterDays error: " + expireRet.ToString());
}
Console.WriteLine(expireRet.ToString());
```

<a id="rs-list" />

## **获取指定前缀的文件列表** [#获取指定前缀的文件列表]

```
// 空间名
string Bucket = "7qiniu";
// 指定前缀，只有资源名匹配该前缀的资源会被列出
string prefix = "qiniu";
// 指定目录分隔符，列出所有公共前缀（模拟列出目录效果）
string delimiter = "";
// 本次列举的条目数，范围为1-1000
int limit = 100;
// 上一次列举返回的位置标记，作为本次列举的起点信息
string marker = "";


ListResult listRet = bucketManager.ListFiles(Bucket, prefix, marker, limit, delimiter);
if (listRet.Code != (int)HttpCode.OK)
{
    Console.WriteLine("list files error: " + listRet.ToString());
}
Console.WriteLine(listRet.ToString());
```

<a id="rs-fetch" />

## **抓取网络资源到空间** [#抓取网络资源到空间]

```
// 公网可访问的文件链接
string resUrl = "http://devtools.qiniu.com/qiniu.png";
// 存储空间名
string Bucket = "7qiniu";
// 文件名
string Key = "qiniu.jpg";
FetchResult ret = bucketManager.Fetch(resUrl, Bucket, Key);

if (ret.Code != (int)HttpCode.OK)
{
    Console.WriteLine("fetch error: " + ret.ToString());
}
Console.WriteLine(ret.ToString());
```

<a id="rs-prefetch" />

## **更新镜像空间中存储的文件内容** [#更新镜像空间中存储的文件内容]

```
// 设置存储空间
string Bucket = "7qiniu";
// 文件名
string key = "333";
HttpResult ret = bucketManager.Prefetch(Bucket, "qiniu.png");
if (ret.Code != (int)HttpCode.OK && !ret.Text.Contains("bucket source not set"))
{
    Console.WriteLine("prefetch error: " + ret.ToString());
}
Console.WriteLine(ret.ToString());
```

<a id="rs-batch" />

## **资源管理批量操作** [#资源管理批量操作]

<a id="rs-batch-stat" />

### **批量获取文件信息** [#批量获取文件信息]

```
// 每个operations的数量不可以超过1000个，如果总数量超过1000，需要分批发送
string[] keys = {
    "00007.mp4",
    "0072102104.png"
};
// 空间名
string Bucket = "7qiniu";
List<string> ops = new List<string>();
foreach (string key in keys)
{
    string op = bucketManager.StatOp(Bucket, key);
    ops.Add(op);
}
BatchResult ret = bucketManager.Batch(ops);
if (ret.Code / 100 != 2)
{
    Console.WriteLine("batch error: " + ret.ToString());

}
foreach (BatchInfo info in ret.Result)
{
    if (info.Code == (int)HttpCode.OK)
    {
        Console.WriteLine("{0}, {1}, {2}, {3}, {4}", info.Data.MimeType,
            info.Data.PutTime, info.Data.Hash, info.Data.Fsize, info.Data.FileType);

    }
    else
    {
        Console.WriteLine(info.Data.Error);

    }

}
```

<a id="rs-batch-chgm" />

### **批量修改文件类型** [#批量修改文件类型]

```
//每个operations的数量不可以超过1000个，如果总数量超过1000，需要分批发送
// 空间名
string Bucket = "7qiniu";
// 文件名
string[] keys = {
    "354",
    "3.json"
};

List<string> ops = new List<string>();
foreach (string key in keys)
{
    string op = bucketManager.ChangeTypeOp(Bucket, key, 1);
    ops.Add(op);
}

BatchResult ret = bucketManager.Batch(ops);
if (ret.Code / 100 != 2)
{
    Console.WriteLine("batch error: " + ret.ToString());
}
foreach (BatchInfo info in ret.Result)
{
    if (info.Code == (int)HttpCode.OK)
    {
        Console.WriteLine("chtype success");
    }
    else
    {
        Console.WriteLine(info.Data.Error);
    }
}
```

<a id="rs-batch-delete" />

### **批量删除文件** [#批量删除文件]

```
//每个operations的数量不可以超过1000个，如果总数量超过1000，需要分批发送
// 设置空间
string Bucket = "7qiniu";
string[] keys = {
    "00_wo_ts_a.mp4",
    "0327-02.png",
    "0715589972949ea3a.mp4"
};

List<string> ops = new List<string>();
foreach (string key in keys)
{
    string op = bucketManager.DeleteOp(Bucket, key);
    ops.Add(op);
}

BatchResult ret = bucketManager.Batch(ops);
if (ret.Code / 100 != 2)
{
    Console.WriteLine("batch error: " + ret.ToString());
}
foreach (BatchInfo info in ret.Result)
{
    if (info.Code == (int)HttpCode.OK)
    {
        Console.WriteLine("delete success");
    }
    else
    {
        Console.WriteLine(info.Data.Error);
    }
}
```

<a id="rs-batch-copy" />

### **批量复制文件** [#批量复制文件]

```
//每个operations的数量不可以超过1000个，如果总数量超过1000，需要分批发送

// 原空间
string srcBucket = "7qiniu";
// 目标空间
string dstBucket = "07qiniu";

string[] keys = {
    "007210021.png",
    "0072102104.png",
    "0327-02.png"
};

List<string> ops = new List<string>();
foreach (string key in keys)
{
    string op = bucketManager.CopyOp(srcBucket, key, dstBucket, key, true);
    ops.Add(op);
}

BatchResult ret = bucketManager.Batch(ops);
if (ret.Code / 100 != 2)
{
    Console.WriteLine("batch error: " + ret.ToString());
}
foreach (BatchInfo info in ret.Result)
{
    if (info.Code == (int)HttpCode.OK)
    {
        Console.WriteLine("copy success");
    }
    else
    {
        Console.WriteLine(info.Data.Error);
    }
}
```

<a id="rs-batch-move" />

### **批量移动或重命名文件** [#批量移动或重命名文件]

```
//每个operations的数量不可以超过1000个，如果总数量超过1000，需要分批发送
// 原空间
string srcBucket = "7qiniu";
// 目标空间
string dstBucket = "01test";
string[] keys = {
    "007210021.png",
    "0072102104.png"
};

List<string> ops = new List<string>();
foreach (string key in keys)
{
    string op = bucketManager.MoveOp(srcBucket, key, dstBucket, key + "-batch-move", true);
    ops.Add(op);
}

BatchResult ret = bucketManager.Batch(ops);
if (ret.Code / 100 != 2)
{
    Console.WriteLine("batch error: " + ret.ToString());
}
foreach (BatchInfo info in ret.Result)
{
    if (info.Code == (int)HttpCode.OK)
    {
        Console.WriteLine("move success");
    }
    else
    {
        Console.WriteLine(info.Data.Error);
    }
}
```

<a id="rs-batch-deleteAfterDays" />

### **批量更新文件的有效期** [#批量更新文件的有效期]

```
//每个operations的数量不可以超过1000个，如果总数量超过1000，需要分批发送
string[] keys = {
    "4389.png",
    "4.gif"
};
// 空间名
string Bucket = "7qiniu";
List<string> ops = new List<string>();
foreach (string key in keys)
{
    string op = bucketManager.DeleteAfterDaysOp(Bucket, key, 7);
    ops.Add(op);
}

BatchResult ret = bucketManager.Batch(ops);
if (ret.Code / 100 != 2)
{
    Console.WriteLine("batch error: " + ret.ToString());
}
foreach (BatchInfo info in ret.Result)
{
    if (info.Code == (int)HttpCode.OK)
    {
        Console.WriteLine("deleteAfterDays success");
    }
    else
    {
        Console.WriteLine(info.Data.Error + "2");
    }
}
```

<a id="rs-batch-type" />

### **批量更新文件存储类型** [#批量更新文件存储类型]

```
//每个operations的数量不可以超过1000个，如果总数量超过1000，需要分批发送
//type=0为普通存储，type=1为低频存储
string[] keys = {
        "qiniu-0.png",
        "qiniu-1.png",
        "qiniu-2.png"
    };

    List<string> ops = new List<string>();
    int type = 0;
    foreach (string key in keys)
    {
        string op = bucketManager.ChangeTypeOp(Bucket, key, type);
        ops.Add(op);
    }

    BatchResult ret = bucketManager.Batch(ops);
    if (ret.Code / 100 != 2)
    {
        Console.WriteLine("batch error: " + ret.ToString());
    }
    foreach (BatchInfo info in ret.Result)
    {
        if (info.Code == (int)HttpCode.OK)
        {
            Console.WriteLine("chtype success");
        }
        else
        {
            Console.WriteLine(info.Data.Error);
        }
    }
}
```

<span id="del_in_kodoe_docs_block_start" />

<a id="pfop" />

# **持久化数据处理** [#持久化数据处理]

<a id="pfop-request" />

## **发送数据处理请求（数据处理指令）** [#发送数据处理请求数据处理指令]

对于已经保存到七牛空间的文件，可以通过发送持久化的数据处理指令来进行处理，这些指令支持七牛官方提供的指令，也包括客户自己开发的自定义数据处理的指令。数据处理的结果还可以通过七牛主动通知的方式告知业务服务器。

闲时任务的功能介绍、使用场景、定价，详见 [闲时任务策略说明](/products/dora/1-features_introduction)。

```
Mac mac = new Mac(AccessKey, SecretKey);
Config config = new Config();
OperationManager manager = new OperationManager(mac, config);

//处理指令集合
string saveMp4Entry = Base64.UrlSafeBase64Encode(Bucket + ":avthumb_test_target.mp4");
string saveJpgEntry = Base64.UrlSafeBase64Encode(Bucket + ":avthumb_test_target.jpg");

string avthumbMp4Fop = "avthumb/mp4|saveas/" + saveMp4Entry;
string vframeJpgFop = "vframe/jpg/offset/1|saveas/" + saveJpgEntry;

string fops = string.Join(";", new string[] { avthumbMp4Fop, vframeJpgFop });

// 私有隊列名
string pipeline = "da";
string notifyUrl = "http://api.example.com/qiniu/pfop/notify";

// 存储空间名
string Bucket = "7qiniu";
// 文件名
string key = "00007.mp4";
// 当服务端发现 fops 指定的数据处理结果已经存在，那就认为已经处理成功，避免重复处理浪费资源。加上本字段并设为 1，则可强制执行数据处理并覆盖原结果。
bool force = true;
// 任务类型：0: 普通任务 1: 闲时任务（一旦指定闲时任务，就不能指定 pipeline）
int persistentType = 0;
PfopResult pfopRet = manager.Pfop(Bucket, key, fops, pipeline, notifyUrl, force, persistentType);
if (pfopRet.Code != (int)HttpCode.OK)
{
    Console.WriteLine("pfop error: " + pfopRet.ToString());
}
//持久化数据处理返回的是任务的persistentId，可以根据这个id查询处理状态
Console.WriteLine(pfopRet.PersistentId);
```

## **发送数据处理请求（工作流模版）** [#发送数据处理请求工作流模版]

也可以支持使用工作流模版替代数据处理指令。工作流模板是预先编排好的一系列媒体处理流程（如转码、截图、视频拼接等各类处理），登录 [对象存储控制台](https://portal.qiniu.com/kodo/bucket) 进行创建，详情参考[工作流模板操作指南](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template)，`workflowTemplateId` 对应工作流模板列表的`名称`字段

```
Mac mac = new Mac(AccessKey, SecretKey);
Config config = new Config();
OperationManager manager = new OperationManager(mac, config);

// 私有隊列名
string pipeline = "da";
string notifyUrl = "http://api.example.com/qiniu/pfop/notify";

// 存储空间名
string Bucket = "7qiniu";
// 文件名
string key = "00007.mp4";
// 工作流模版
string workflowTemplateId = "tempname";
// 当服务端发现 workflowTemplateId 指定的数据处理结果已经存在，那就认为已经处理成功，避免重复处理浪费资源。加上本字段并设为 1，则可强制执行数据处理并覆盖原结果。
bool force = true;
// 任务类型：0: 普通任务 1: 闲时任务（一旦指定闲时任务，就不能指定 pipeline）
int persistentType = 0;
PfopResult pfopRet = manager.Pfop(Bucket, key, null, pipeline, notifyUrl, force, persistentType, workflowTemplateId);
if (pfopRet.Code != (int)HttpCode.OK)
{
    Console.WriteLine("pfop error: " + pfopRet.ToString());
}
//持久化数据处理返回的是任务的persistentId，可以根据这个id查询处理状态
Console.WriteLine(pfopRet.PersistentId);
```

<a id="pfop-status" />

## **查询数据处理请求状态** [#查询数据处理请求状态]

由于数据处理是异步处理，可以根据发送处理请求时返回的 `persistentId` 去查询任务的处理进度，如果在设置了`persistentNotifyUrl` 的情况下，直接业务服务器等待处理结果通知即可，如果需要主动查询，可以采用如下代码中的：

```
//持久化数据处理返回的是任务的persistentId
string persistentId = "z0.59abf1eb45a2650c9954087d";
Mac mac = new Mac(AccessKey, SecretKey);
Config config = new Config();
OperationManager manager = new OperationManager(mac, config);
PrefopResult ret = manager.Prefop(persistentId);
if (ret.Code != (int)HttpCode.OK)
{
    Console.WriteLine("prefop error: " + ret.ToString());
}
Console.WriteLine(ret.ToString());
```

<a id="fusion-cdn" />

# **CDN 相关功能** [#cdn-相关功能]

* <a href="#fusion-refresh-urls">
    文件刷新
  </a>
* <a href="#fusion-refresh-dirs">
    目录刷新
  </a>
* <a href="#fusion-prefetch">
    文件预取操作
  </a>
* <a href="#fusion-flux">
    获取域名流量
  </a>
* <a href="#fusion-bandwidth">
    获取域名带宽
  </a>
* <a href="#fusion-logs">
    获取日志下载链接
  </a>
* <a href="#fusion-antileech">
    构建时间戳防盗链访问链接
  </a>

在使用 CDN 相关功能之前，需要构建`CdnManager`对象：

```
Mac mac = new Mac(AccessKey, SecretKey);
CdnManager manager = new CdnManager(mac);
```

<a id="fusion-refresh-urls" />

## **文件刷新** [#文件刷新]

```
//URL 列表
string Domain = "sq.qiniuts.com";
string[] urls = {
    string.Format("http://{0}/images/1.png",Domain),
    string.Format("http://{0}/images/2.png",Domain)
};

RefreshResult ret = manager.RefreshUrls(urls);
if (ret.Code != (int)HttpCode.OK)
{
    Console.WriteLine(ret.ToString());
}
Console.WriteLine(ret.Result.Code);
Console.WriteLine(ret.Result.Error);
Console.WriteLine(ret.Result.UrlQuotaDay);
Console.WriteLine(ret.Result.UrlSurplusDay);
Console.WriteLine(ret.Result.RequestId);
if (ret.Result.InvalidUrls != null)
{
    foreach (string url in ret.Result.InvalidUrls)
    {
        Console.WriteLine(url);
    }
}
```

<a id="fusion-refresh-dirs" />

## **目录刷新** [#目录刷新]

```
string Domain = "sq.qiniuts.com";
//DIR 列表
string[] dirs = {
    string.Format("http://{0}/images1/",Domain),
    string.Format("http://{0}/images2/",Domain)
};

//刷新目录，刷新目录需要联系七牛技术支持开通权限
//单次请求链接不可以超过10个，如果超过，请分批发送请求
RefreshResult ret = manager.RefreshDirs(dirs);
if (ret.Code != (int)HttpCode.OK)
{
    Console.WriteLine(ret.ToString());
}
Console.WriteLine(ret.Result.Code);
Console.WriteLine(ret.Result.Error);
Console.WriteLine(ret.Result.DirQuotaDay);
Console.WriteLine(ret.Result.DirSurplusDay);
Console.WriteLine(ret.Result.RequestId);
if (ret.Result.InvalidDirs != null)
{
    foreach (string dir in ret.Result.InvalidDirs)
    {
        Console.WriteLine(dir);
    }
}
```

<a id="fusion-prefetch" />

## **文件预取** [#文件预取]

```
//URL 列表
string Domain = "sq.qiniuts.com";
string[] urls = {
    string.Format("http://{0}/images/1.png",Domain),
    string.Format("http://{0}/images/2.png",Domain)
};

PrefetchResult ret = manager.PrefetchUrls(urls);
if (ret.Code != (int)HttpCode.OK)
{
    Console.WriteLine(ret.ToString());
}
Console.WriteLine(ret.Result.Code);
Console.WriteLine(ret.Result.Error);
Console.WriteLine(ret.Result.QuotaDay);
Console.WriteLine(ret.Result.SurplusDay);
Console.WriteLine(ret.Result.RequestId);
if (ret.Result.InvalidUrls != null)
{
    foreach (string url in ret.Result.InvalidUrls)
    {
        Console.WriteLine(url);
    }
}
```

<a id="fusion-flux" />

## **获取域名流量** [#获取域名流量]

```
// 域名
string Domain = "sq.qiniuts.com";
string[] domains = new string[] { Domain };
// 指定日期
string start = "2017-08-01";
string end = "2017-08-10";
// 流量数据粒度
string granu = "day";
//获取域名流量
FluxResult ret = manager.GetFluxData(domains, start, end, granu);
if (ret.Code != (int)HttpCode.OK)
{
    Console.WriteLine(ret.ToString());
}

foreach (string domain in domains)
{
    Console.WriteLine("flux data of domain: " + domain);
    foreach (string t in ret.Result.Time)
    {
        Console.Write(t + "\t");
    }
    Console.WriteLine();
    if (ret.Result.Data.ContainsKey(domain))
    {
        if (ret.Result.Data[domain].China != null)
        {
            Console.WriteLine("China:");
            foreach (UInt64 v in ret.Result.Data[domain].China)
            {
                Console.Write(v + "\t");
            }
            Console.WriteLine();
        }


        if (ret.Result.Data[domain].Oversea != null)
        {
            Console.WriteLine("Oversea:");
            foreach (int v in ret.Result.Data[domain].Oversea)
            {
                Console.Write(v + "\t");
            }
            Console.WriteLine();
        }
    }
}
```

<a id="fusion-bandwidth" />

## **获取域名带宽** [#获取域名带宽]

```
// 域名
string Domain = "sq.qiniuts.com";
string[] domains = new string[] { Domain };
// 设置时间范围
string start = "2017-08-01";
string end = "2017-08-10";
// 带宽数据粒度
string granu = "day";

//获取域名带宽
BandwidthResult ret = manager.GetBandwidthData(domains, start, end, granu);
if (ret.Code != (int)HttpCode.OK)
{
    Console.WriteLine(ret.ToString());
}

foreach (string domain in domains)
{
    Console.WriteLine("bandwidth data of domain: " + domain);
    foreach (string t in ret.Result.Time)
    {
        Console.Write(t + "\t");
    }
    Console.WriteLine();
    if (ret.Result.Data.ContainsKey(domain))
    {
        if (ret.Result.Data[domain].China != null)
        {
            Console.WriteLine("China:");
            foreach (int v in ret.Result.Data[domain].China)
            {
                Console.Write(v + "\t");
            }
            Console.WriteLine();
        }


        if (ret.Result.Data[domain].Oversea != null)
        {
            Console.WriteLine("Oversea:");
            foreach (UInt64 v in ret.Result.Data[domain].Oversea)
            {
                Console.Write(v + "\t");
            }
            Console.WriteLine();
        }
    }
}
```

<a id="fusion-logs" />

## **获取日志下载链接** [#获取日志下载链接]

```
// 设置域名
string Domain = "sq.qiniuts.com";
// 设置时间
string day = "2017-08-10";
string[] domains = new string[] { Domain };
LogListResult ret = manager.GetCdnLogList(domains, day);
if (ret.Code != (int)HttpCode.OK)
{
    Console.WriteLine(ret.ToString());
}

foreach (string domain in ret.Result.Data.Keys)
{
    Console.WriteLine("log list for domain: " + domain);
    foreach (LogData data in ret.Result.Data[domain])
    {
        Console.WriteLine(data.Name + "\t" + data.Size + "\t" + data.Mtime + "\t" + data.Url);
    }
}
```

<a id="fusion-antileech" />

## **构建时间戳防盗链访问链接** [#构建时间戳防盗链访问链接]

具体算法可以参考：[时间戳防盗链](/faq/cdn/domain-name-configuration-problem/1670-timestamp-hotlinking-prevention)

```
string host = "http://qnls.example.com";
string fileName = "hello/6000694.ls";
string query = "v=34";
int expireInSeconds = 3600;
//加密密钥
string encryptKey = "xxx";
string finalUrl = CdnManager.CreateTimestampAntiLeechUrl(host, fileName, query, encryptKey, expireInSeconds);
Console.WriteLine(finalUrl);
```

<a id="api-references" />

# **API 参考** [#api-参考]

* [存储 API 参考](/products/kodo/3939-overview-of-the-api)
* [融合 CDN API 参考](/products/cdn/0-fusion-api-overview)
* 官方数据处理 API 参考

<a id="faq" />

# **常见问题** [#常见问题]

* API 的使用，可以参考我们为大家精心准备的[使用实例](https://github.com/qiniu/csharp-sdk/tree/master/src/QiniuTests)。

<a id="related-resources" />

# **相关资源** [#相关资源]

如果您有任何关于我们文档或产品的建议和想法，欢迎您通过以下方式与我们互动讨论：

* [技术论坛](http://segmentfault.com/qiniu) - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
* [提交工单](https://support.qiniu.com/tickets/new) - 如果您的问题不适合在论坛讨论或希望及时解决，您也可以提交一个工单，我们的技术支持人员会第一时间回复您
* [博客](http://blog.qiniu.com) - 这里会持续更新发布市场活动和技术分享文章
* [微博](http://weibo.com/qiniutek)
* [常见问题](https://support.qiniu.com/question)

<span id="del_in_kodoe_docs_block_end" />

<a id="contribute-code" />

# **贡献代码** [#贡献代码]

1. Fork

2. 创建您的特性分支 git checkout -b my-new-feature

3. 提交您的改动 git commit -am 'Added some feature'

4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature

5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

<a id="license" />

# **许可证** [#许可证]

Copyright (c) 2014 qiniu.com

基于 MIT 协议发布:

* [www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)


# Go SDK历史版本 (/products/kodo/go/0-go-v6)



最近更新时间: 2019-12-16 17:22:39

七牛云存储的 GO 语言版本 SDK（本文以下称 GO-SDK）是对七牛云存储API协议的一层封装，以提供一套对于 GO 开发者而言简单易用的原生 GO 函数。GO 开发者在对接 GO-SDK 时无需理解七牛云存储 API 协议的细节，原则上也不需要对 HTTP 协议和原理做非常深入的了解，但如果拥有基础的 HTTP 知识，对于出错场景的处理可以更加高效。

GO-SDK 以开源方式提供。开发者可以随时从本文档提供的下载地址查看和下载 SDK 的源代码。

由于 GO 语言的通用性，GO-SDK 被设计为同时适合服务器端和客户端使用。服务端是指开发者自己的业务服务器，客户端是指开发者的客户终端。服务端因为有七牛颁发的 AccessKey/SecretKey，可以做很多客户端做不了的事情，比如删除文件、移动/复制文件等操作。一般而言，客服端操作文件需要获得服务端的授权。客户端上传文件需要获得服务端颁发的 [上传凭证](/products/kodo/development-guidelines/security/2-upload-token) ，客户端下载文件（包括下载处理过的文件，比如下载图片的缩略图）需要获得服务端颁发的 [下载凭证](/products/kodo/development-guidelines/security/0-download-token) 。但开发者也可以将 bucket 设置为公开，此时文件有永久有效的访问地址，不需要业务服务器的授权，这对网站的静态文件（如图片、js、css、html）托管非常方便。

从 v5.0.0 版本开始，我们对 SDK 的内容进行了精简。所有管理操作，比如：创建/删除 bucket、为 bucket 绑定域名（publish）、设置数据处理的样式分隔符、新增数据处理样式等都去除了，统一建议到 [开发者平台](https://portal.qiniu.com/) 来完成。另外，此前服务端还有自己独有的上传 API，现在也推荐统一成基于客户端上传的工作方式。

从内容上来说，GO-SDK 主要包含如下几方面的内容：

* 公共库: api/conf
* 客户端上传文件：api/io
* 客户端断点续上传：api/resumable/io
* 数据处理：api/fop
* 服务端操作：api/auth/digest (授权)，api/rs(资源管理，uptoken/dntoken颁发)，api/rsf(批量获取文件列表)

## 安装 [#安装]

在命令行下执行

```
go get -u github.com/qiniu/api.v7
```

**初始化**

要接入七牛云存储，您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得：

1. [开通七牛开发者帐号](https://portal.qiniu.com/signup)
2. 登录七牛开发者自助平台，查看 [Access Key 和 Secret Key](https://portal.qiniu.com/user/key) 。

在获取到 Access Key 和 Secret Key 之后，您可以在您的程序中调用如下两行代码进行初始化对接， 要确保 `ACCESS_KEY` 和 `SECRET_KEY` 在服务端调用 api/auth/digest，api/rs，api/rsf之前均已赋值：

```
import ."github.com/qiniu/api.v6/conf"

ACCESS_KEY = "<YOUR_APP_ACCESS_KEY>"
SECRET_KEY = "<YOUR_APP_SECRET_KEY>"
```

## 上传文件 [#上传文件]

为了尽可能地改善终端用户的上传体验，七牛云存储首创了客户端直传功能。一般云存储的上传流程是：

```
客户端（终端用户） => 业务服务器 => 云存储服务
```

这样多了一次上传的流程，和本地存储相比，会相对慢一些。但七牛引入了客户端直传，将整个上传过程调整为：

```
客户端（终端用户） => 七牛 => 业务服务器
```

客户端（终端用户）直接上传到七牛的服务器，通过DNS智能解析，七牛会选择到离终端用户最近的ISP服务商节点，速度会比本地存储快很多。文件上传成功以后，七牛的服务器使用回调功能，只需要将非常少的数据（比如Key）传给应用服务器，应用服务器进行保存即可。

**注意** ：如果您只是想要上传已存在您电脑本地或者是服务器上的文件到七牛云存储，可以直接使用七牛提供的 [qshell](/products/kodo/0-qshell) 上传工具。\
文件上传有两种方式，一种是以普通方式直传文件，简称普通上传，另一种方式是断点续上传，断点续上传在网络条件很一般的情况下也能有出色的上传速度，而且对大文件的传输非常友好。

## 上传流程 [#上传流程]

在七牛云存储中，整个上传流程大体分为这样几步：

1. 业务服务器颁发 [上传凭证](/products/kodo/development-guidelines/security/2-upload-token) 给客户端（终端用户）
2. 客户端凭借上传凭证上传文件到七牛
3. 在七牛获得完整数据后，发起一个 HTTP 请求回调到业务服务器
4. 业务服务器保存相关信息，并返回一些信息给七牛
5. 七牛原封不动地将这些信息转发给客户端（终端用户）

需要注意的是，回调到业务服务器的过程是可选的，它取决于业务服务器颁发的 [上传凭证](/products/kodo/development-guidelines/security/2-upload-token) 。如果没有回调，七牛会返回一些标准的信息（比如文件的 hash）给客户端。如果上传发生在业务服务器，以上流程可以自然简化为：

1. 业务服务器生成 uptoken（不设置回调，自己回调到自己这里没有意义）
2. 凭借 [上传凭证](/products/kodo/development-guidelines/security/2-upload-token) 上传文件到七牛
3. 善后工作，比如保存相关的一些信息

## 生成上传授权uptoken [#生成上传授权uptoken]

uptoken是一个字符串，业务服务器根据(`rs.PutPolicy`)的结构体的各个参数来生成 [上传凭证](/products/kodo/development-guidelines/security/2-upload-token) 的代码如下（调用如下代码前，请确保Access Key 和 Secret Key已经被正确初始化）:

```
func uptoken(bucketName string) string {
    putPolicy := rs.PutPolicy {
        Scope:         bucketName,
        //CallbackUrl: callbackUrl,   
        //CallbackBody:callbackBody,    
        //ReturnUrl:   returnUrl,  
        //ReturnBody:  returnBody,    
        //AsyncOps:    asyncOps,    
        //EndUser:     endUser,    
        //Expires:     expires,   
    }
    return  putPolicy.Token(nil)
}
```

参阅 `rs.PutPolicy`

## 上传代码 [#上传代码]

上传文件到七牛（通常是客户端完成，但也可以发生在业务服务器）。\
由于七牛的服务器支持自动生成key，所以本SDK提供的上传函数有两种展现方式，一种是有key的，一种是无key，让服务端自动生成key。\
普通上传的文件和二进制，最后一个参数都是PutExtra类型，是用来细化上传功能用的，PutExtra的成员及其意义如下：

```
type PutExtra struct {
    Params   map[string]string    //可选，用户自定义参数，必须以 "x:" 开头
                                  //若不以x:开头，则忽略
    MimeType string               //可选，当为 "" 时候，服务端自动判断 
    Crc32    uint32
    CheckCrc uint32
            // CheckCrc == 0: 表示不进行 crc32 校验
            // CheckCrc == 1: 对于 Put 等同于 CheckCrc = 2；对于 PutFile 会自动计算 crc32 值
            // CheckCrc == 2: 表示进行 crc32 校验，且 crc32 值就是上面的 Crc32 变量
}
```

直接上传内存中的数据，代码如下:

```
var err error
var ret io.PutRet
var extra = &io.PutExtra {
    //Params:    params,
    //MimeType:  mieType,
    //Crc32:     crc32,
    //CheckCrc:  CheckCrc,
}

// ret       变量用于存取返回的信息，详情见 io.PutRet
// uptoken   为业务服务器端生成的上传口令
// key       为文件存储的标识
// r         为io.Reader类型，用于从其读取数据
// extra     为上传文件的额外信息,可为空， 详情见 io.PutExtra, 可选
err = io.Put(nil, &ret, uptoken, key, r, extra)

if err != nil {
//上传产生错误
    log.Print("io.Put failed:", err)
    return
}

//上传成功，处理返回值
log.Print(ret.Hash, ret.Key)
```

参阅: `io.Put`, `io.PutExtra`

直接上传内存中的数据，且不提供key参数，此时key由七牛服务器自动生成，代码如下:

```
var err error
var ret io.PutRet
var extra = &io.PutExtra {
    //Params:    params,
    //MimeType:  mieType,
    //Crc32:     crc32,
    //CheckCrc:  CheckCrc,
}

// ret       变量用于存取返回的信息，详情见 io.PutRet
// uptoken   为业务服务器端生成的上传口令
// r         为io.Reader类型，用于从其读取数据
// extra     为上传文件的额外信息,可为空， 详情见 io.PutExtra, 可选
err = io.PutWithoutKey(nil, &ret, uptoken, r, extra)

if err != nil {
//上传产生错误
    log.Print("io.Put failed:", err)
    return
}

//上传成功，处理返回值
log.Print(ret.Hash, ret.Key)
```

参阅: `io.Put`, `io.PutExtra`

上传本地文件，代码如下:

```
var err error
var ret io.PutRet
var extra = &io.PutExtra {
    //Params:    params,
    //MimeType:  mieType,
    //Crc32:     crc32,
    //CheckCrc:  CheckCrc,
}

// ret       变量用于存取返回的信息，详情见 io.PutRet
// uptoken   为业务服务器生成的上传口令
// key       为文件存储的标识
// localFile 为本地文件名
// extra     为上传文件的额外信息，详情见 io.PutExtra，可选
err = io.PutFile(nil, &ret, uptoken, key, localFile, extra)

if err != nil {
//上传产生错误
    log.Print("io.PutFile failed:", err)
    return
}

//上传成功，处理返回值
log.Print(ret.Hash, ret.Key)
```

参阅: `io.PutFile`, `io.PutExtra`, `io.PutRet`

上传本地文件，且不提供 key 参数，此时 key 由七牛服务器自动生成代码:

```
var err error
var ret io.PutRet
var extra = &io.PutExtra {
    //Params:    params,
    //MimeType:  mieType,
    //Crc32:     crc32,
    //CheckCrc:  CheckCrc,
}

// ret       变量用于存取返回的信息，详情见 io.PutRet
// uptoken   为业务服务器生成的上传口令
// localFile 为本地文件名
// extra     为上传文件的额外信息，详情见 io.PutExtra，可选
err = io.PutFileWithoutKey(nil, &ret, uptoken, localFile, extra)

if err != nil {
//上传产生错误
    log.Print("io.PutFile failed:", err)
    return
}

//上传成功，处理返回值
log.Print(ret.Hash, ret.Key)
```

参阅: `io.PutFile`, `io.PutExtra`, `io.PutRet`

## 断点续上传、分块并行上传 [#断点续上传分块并行上传]

除了基本的上传外，七牛还支持你将文件切成若干块（除最后一块外，每个块固定为4M大小），每个块可独立上传，互不干扰；每个分块块内则能够做到断点上续传。

断点续上传函数，最后一个选项是 resumable.io.PutExtra结构体，来细化上传用的，其成员及其含义如下：

```
type PutExtra struct {
    CallbackParams  string  // 当 uptoken 指定了 CallbackUrl，则 CallbackParams 必须非空
    Bucket          string
    CustomMeta      string  // 可选。用户自定义 Meta，不能超过 256 字节
    MimeType        string  // 可选。在 uptoken 没有指定 DetectMime 时，用户客户端可自己指定 MimeType
    ChunkSize    int    // 可选。每次上传的Chunk大小
    TryTimes    int    // 可选。尝试次数
    Progresses    []BlkputRet // 可选。上传进度
    Notify        func(blkIdx int, blkSize int, ret *BlkputRet) // 可选。进度提示（注意多个block是并行传输的）
    NotifyErr    func(blkIdx int, blkSize int, err error)
}
```

我们先看支持的断点续上传、分块并行上传的基本样例：

上传二进制流

```
var err error
var ret io.PutRet
var extra = &rio.PutExtra {
    //CallbackParams: callbackParams,
    //Bucket:         bucket,
    //CustomMeta:     customMeta,
    //MimeType:       mieType,
    //ChunkSize:      chunkSize,
    //TryTimes:       tryTimes,    
    //Progresses:     progresses,
    //Notify:         notify,        
    //NotifyErr:      NotifyErr,
}

// ret       变量用于存取返回的信息，详情见 resumable.io.PutRet
// uptoken   为业务服务器生成的上传口令
// key       为文件存储的标识
// r         为io.ReaderAt,用于读取数据
// fsize     数据总字节数
// extra     为上传文件的额外信息, 详情见 resumable.io.PutExtra
err = rio.Put(nil, ret, uptoken, key, r, fsize, extra)

if err != nil {
//上传产生错误
    log.Print("resumable.io.Put failed:", err)
    return
}

//上传成功，处理返回值
log.Print(ret.Hash)
```

参阅: `resumable.io.Put`, `resumable.io.PutExtra`, `rs.PutPolicy`

上传本地文件

```
var err error
var ret rio.PutRet
var extra = &rio.PutExtra {
    //CallbackParams: callbackParams,
    //Bucket:         bucket,
    //CustomMeta:     customMeta,
    //MimeType:       mieType,
    //ChunkSize:      chunkSize,
    //TryTimes:       tryTimes,    
    //Progresses:     progresses,
    //Notify:         notify,        
    //NotifyErr:      NotifyErr,
}

// ret       变量用于存取返回的信息，详情见 resumable.io.PutRet
// uptoken   为业务服务器生成的上传口令
// key       为文件存储的标识
// localFile 为本地文件名
// extra     为上传文件的额外信息,可为空， 详情见 resumable.io.PutExtra
err = rio.PutFile(nil, ret, uptoken, key, localFile, extra)

if err != nil {
//上传产生错误
    log.Print("resumable.io.Put failed:", err)
    return
}

//上传成功，处理返回值
log.Print(ret.Hash)
```

参阅: `resumable.io.PutFile`, `resumable.io.PutExtra`, `rs.PutPolicy`

相比普通上传，断点上续传代码没有变复杂。基本上就只是将 `io.PutExtra` 改为 `resumable.io.PutExtra` ， `io.PutFile` 改为 `resumable.io.PutFile` 。

但实际上 `resumable.io.PutExtra` 多了不少配置项，其中最重要的是两个回调函数： `Notify` 与 `NotifyErr` ，它们用来通知使用者有更多的数据被传输成功，或者有些数据传输失败。在 `Notify` 回调函数中，比较常见的做法是将传输的状态进行持久化，以便于在软件退出后下次再进来还可以继续进行断点续上传。但不传入 `Notify` 回调函数并不表示不能断点续上传，只要程序没有退出，上传失败自动进行续传和重试操作。

## 上传策略 [#上传策略]

[上传凭证](/products/kodo/development-guidelines/security/2-upload-token) 实际上是用 AccessKey/SecretKey 进行数字签名的上传策略(`rs.PutPolicy`)，它控制着整个上传流程的行为。让我们快速过一遍你都能够决策啥：

* `Expires` 指定上传凭证有效期（默认1小时）。一个上传凭证可以被用于多次上传（只要它还没有过期）。
* `Scope` 限定客户端的权限。如果 `scope` 是 bucket，则客户端只能新增文件到指定的 bucket，不能修改文件。如果 `scope` 为 bucket:key，则客户端可以修改指定的文件。
* `CallbackUrl` 设定业务服务器的回调地址，这样业务服务器才能感知到上传行为的发生。可选。
* `AsyncOps` 可指定上传完成后，需要自动执行哪些数据处理。这是因为有些数据处理操作（比如音视频转码）比较慢，如果不进行预转可能第一次访问的时候效果不理想，预转可以很大程度改善这一点。
* `ReturnBody` 可调整返回给客户端的数据包（默认情况下七牛返回文件内容的 `hash` ，也就是下载该文件时的 `etag` ）。这只在没有 `CallbackUrl` 时有效。
* `Escape` 为真（非0）时，表示客户端传入的 `CallbackParams` 中含有转义符。通过这个特性，可以很方便地把上传文件的某些元信息如 `fsize` （文件大小）、 `ImageInfo.width/height` （图片宽度/高度）、 `exif` （图片EXIF信息）等传给业务服务器。
* `DetectMime` 为真（非0）时，表示服务端忽略客户端传入的 `MimeType` ，自己自行检测。

关于上传策略更完整的说明，请参考 [上传凭证](/products/kodo/development-guidelines/security/2-upload-token) 。

## 下载文件 [#下载文件]

七牛云存储上的资源下载分为 公有资源下载 和 私有资源下载 。

私有（private）是 Bucket（空间）的一个属性，一个私有 Bucket 中的资源为私有资源，私有资源不可匿名下载。

新创建的空间（Bucket）缺省为私有，也可以将某个 Bucket 设为公有，公有 Bucket 中的资源为公有资源，公有资源可以匿名下载。

## 公有资源下载 [#公有资源下载]

如果在给bucket绑定了域名的话，可以通过以下地址访问：

```
[GET] http://<domain>/<key>
```

其中 可以到 [七牛开发者平台](https://portal.qiniu.com/) 绑定。步骤： **首先** 选择需要绑定的空间， **其次** 在空间设置标签下，点击域名绑定项，即可申请绑定自定义域名。域名可以使用自己的一级域名或是由七牛提供的二级域名(`&lt;bucket&gt;.qiniudn.com`)。 &#x2A;*注意：** 尖括号不是必需，代表替换项。

## 私有资源下载 [#私有资源下载]

如果某个 bucket 是私有的，那么这个 bucket 中的所有文件只能通过一个的临时有效的 downloadUrl 访问：

```
[GET] http://<domain>/<key>?token=<dnToken>
```

**注意：** 尖括号不是必需，代表替换项。\
其中 dntoken 是由业务服务器签发的一个临时\[下载凭证]\[downloadTokenHref]，deadline 是 dntoken 的有效期。dntoken不需要生成，GO-SDK 提供了生成完整 downloadUrl 的方法（包含了 dntoken），示例代码如下：

```
func downloadUrl(domain, key string) string {
    baseUrl := rs.MakeBaseUrl(domain, key)
    policy := rs.GetPolicy{}
    return  policy.MakeRequest(baseUrl, nil)
}
```

生成 downloadUrl 后，服务端下发 downloadUrl 给客户端。客户端收到 downloadUrl 后，和公有资源类似，直接用任意的 HTTP 客户端就可以下载该资源了。唯一需要注意的是，在 downloadUrl 失效却还没有完成下载时，需要重新向服务器申请授权。

无论公有资源还是私有资源，下载过程中客户端并不需要七牛 GO-SDK 参与其中。

参阅: `rs.GetPolicy`, `rs.GetPolicy.MakeRequest`, `rs.MakeBaseUrl`

## HTTPS支持 [#https支持]

几乎所有七牛云存储 API 都同时支持 HTTP 和 HTTPS，但 HTTPS 下载有些需要注意的点。如果你的资源希望支持 HTTPS 下载，有如下限制：

1. 不能用 xxx.qiniudn.com 这样的二级域名，只能用 dn-xxx.qbox.me 域名。样例： [https://dn-abc.qbox.me/1.txt](https://dn-abc.qbox.me/1.txt)
2. 使用自定义域名是付费的。我们并不建议使用自定义域名，但如确有需要，请联系我们的销售人员。

## 断点续下载 [#断点续下载]

无论是公有资源还是私有资源，获得的下载 url 支持标准的 HTTP 断点续传协议。考虑到多数语言都有相应的断点续下载支持的成熟方法，七牛 GO-SDK 并不提供断点续下载相关代码。

## 资源管理 [#资源管理]

资源管理包括对存储在七牛云存储上的文件进行查看、复制、移动和删除处理。\
该节调用的函数第一个参数都为 `logger` ，用于记录log，如果无需求，可以设置为nil。具体接口可以查阅 `github.com/qiniu/rpc`

## 获取文件信息 [#获取文件信息]

函数 `rs.Client.Stat` 可获取文件信息。

```
var ret  rs.Entry
ret, err = rsCli.Stat(nil, bucket, key)
if err != nil {
//产生错误
    log.Println("rs.Stat failed:", err)
    return
}
//处理返回值
log.Println(ret)
```

若有错误发生，则返回的err包含错误信息。若没错误返回的 `ret` 变量包含文件信息。\
`ret` 是为 `rs.Entry` 类型的结构体，其成员如下：

```
type Entry struct {
    Hash     string \`json:"hash"\`
    Fsize    int64  \`json:"fsize"\`
    PutTime  int64  \`json:"putTime"\`
    MimeType string \`json:"mimeType"\`
    Customer string \`json:"customer"\`
}
```

参阅: `rs.Entry`, `rs.Client.Stat`

## 删除文件 [#删除文件]

函数 `rs.Client.Delete` 可删除指定的文件。

```
err = rsCli.Delete(nil, bucket, key)
if err != nil {
//产生错误
    log.Println("rs.Copy failed:", err)
    return
}
```

若无错误发生则返回的err为nil，否则err包含错误信息。\
参阅: `rs.Client.Delete`

## 复制文件 [#复制文件]

函数 `rs.Client.Copy` 可用来复制文件。

```
err = rsCli.Copy(nil, bucketSrc, keySrc, bucketDest, keyDest)
if err != nil {
//产生错误
    log.Println("rs.Copy failed:", err)
    return
}
```

参阅: `rs.Client.Move` `rs.Client.Copy`

## 移动文件 [#移动文件]

函数 `rs.Client.Move` 可用来移动文件。

```
err = rsCli.Move(nil, bucketSrc, keySrc, bucketDest, keyDest)
if err != nil {
//产生错误
    log.Println("rs.Copy failed:", err)
    return
}
```

参阅: `rs.Client.Move`

## 批量获取文件信息 [#批量获取文件信息]

函数 `rs.Client.BatchStat` 可批量获取文件信息。

```
entryPathes := []rs.EntryPath {
    rs.EntryPath {
        Bucket: bucket1,
        Key: key1,
    },
    rs.EntryPath {
        Bucket: bucket2,
        Key: key2,
    },
}
var batchStatRets []rs.BatchStatItemRet
batchStatRets, err = rsCli.BatchStat(nil, entryPathes) // []rs.BatchStatItemRet, error
if err != nil {
//产生错误
    log.Println("rs.BatchStat failed:", err)
    return
}
//处理返回值
for _, item := range batchStatRets {
    log.Println(item)
}
```

其中 `entryPathes` 为 `rs.EntryPath` 结构体的数组切片。结构体 `rs.EntryPath` 中填写每个文件对应的bucket和key：

```
type EntryPath struct {
    Bucket string
    Key string
}
```

`rs.BatchStat` 会将文件信息(及成功/失败信息)，返回给由结构体 `rs.BatchStatItemRet` 组成的数组切片 `batchStatRets` 变量中。

```
type BatchStatItemRet struct {
    Data  Entry       \`json:"data"\`
    Error string      \`json:"error"\`
    Code  int         \`json:"code"\`
}
```

参阅: `rs.EntryPath`, `rs.BatchStatItemRet`, `rs.Client.BatchStat`

## 批量删除文件 [#批量删除文件]

函数 `rs.Client.BatchDelete` 可进行批量删除文件。

```
entryPathes := []rs.EntryPath {
    rs.EntryPath {
        Bucket: bucket1,
        Key: key1,
    },
    rs.EntryPath {
        Bucket: bucket2,
        Key: key2,
    },
}
var batchDeleteRets []rs.BatchItemRet
batchDeleteRets, err = rsCli.BatchDelete(nil, entryPathes)
if err != nil {
//产生错误
    log.Println("rs.BatchMove failed:", err)
    return
}
for _, item := range batchDeleteRets {
//遍历每个操作的返回结果
    log.Println(item.Code, item.Error)
}
```

和批量查看一样， `entryPathes` 为 `rs.EntryPath` 结构体的数组切片。 `rs.BatchDelete` 会将删除操作的成功/失败信息返回给由结构体 `rs.BatchItemRet` 组成的数组切片 `batchDeleteRets` 变量中。其中 `rs.BatchItemRet` 结构体信息如下：

```
type BatchItemRet struct {
    Error string      \`json:"error"\`
    Code  int         \`json:"code"\`
}
```

参阅: `rs.EntryPath`, `rs.Client.BatchDelete`, `rs.BatchItemRet`

## 批量复制文件 [#批量复制文件]

函数 `rs.Client.BatchCopy` 可进行批量复制文件。

```
// 每个复制操作都含有源文件和目标文件
entryPairs := []rs.EntryPathPair {
    rs.EntryPathPair {
        Src: rs.EntryPath {
            Bucket: bucket1,
            Key: key1,
        },
        Dest: rs.EntryPath {
            Bucket: bucket2,
            Key: key2,
        },
    }, rs.EntryPathPair {
        Src: rs.EntryPath {
            Bucket: bucket3,
            Key: key3,
        },
        Dest: rs.EntryPath {
            Bucket: bucket4,
            Key: key4,
        },
    },
}
var batchCopyRets []rs.BatchItemRet
batchCopyRets, err = rsCli.BatchCopy(nil, entryPairs)
if err != nil {
//产生错误
    log.Println("rs.BatchCopy failed:", err)
    return
}
for _, item := range batchCopyRets {
//遍历每个操作的返回结果
    log.Println(item.Code, item.Error)
}
```

批量复制需要指明每个操作的源路径和目标路径， `entryPairs` 是一个 `rs.EntryPathPair` 结构体的数组切片。结构体 `rs.EntryPathPair` 结构如下：

```
type EntryPathPair struct {
    Src EntryPath
    Dest EntryPath
}
```

同样， `rs.BatchCopy` 会将复制操作的成功/失败信息返回给由结构体 `rs.BatchItemRet` 组成的数组切片 `batchCopyRets` 变量中

参阅: `rs.BatchItemRet`, `rs.EntryPathPair`, `rs.Client.BatchCopy`

## 批量移动文件 [#批量移动文件]

批量移动和批量很类似，唯一的区别就是调用 `rs.Client.BatchMove`

```
// 每个复制操作都含有源文件和目标文件
entryPairs := []rs.EntryPathPair {
    rs.EntryPathPair {
        Src: rs.EntryPath {
            Bucket: bucket1,
            Key: key1,
        },
        Dest: rs.EntryPath {
            Bucket: bucket2,
            Key: key2,
        },
    }, rs.EntryPathPair {
        Src: rs.EntryPath {
            Bucket: bucket3,
            Key: key3,
        },
        Dest: rs.EntryPath {
            Bucket: bucket4,
            Key: key4,
        },
    },
}
var batchMoveRets []rs.BatchItemRet
batchCopyRets, err = rsCli.BatchMove(nil, entryPairs)
if err != nil {
//产生错误
    log.Println("rs.BatchMove failed:", err)
    return
}
for _, item := range batchMoveRets {
//遍历每个操作的返回结果
    log.Println(item.Code, item.Error)
}
```

参阅: `rs.EntryPathPair`, `rs.Client.BatchMove`

## 高级批量操作 [#高级批量操作]

批量操作不仅仅支持同时进行多个相同类型的操作，同时也支持不同的操作。

```
ops := []string {
    rs.URIStat(bucket, key1),
    rs.URICopy(bucket, key1, bucket, key2), // 复制key1到key2
    rs.URIDelete(bucket, key1), // 删除key1
    rs.URIMove(bucket, key2, bucket, key1), //将key2移动到key1
}

rets := new([]rs.BatchItemRet)
err = rsCli.Batch(nil, rets, ops)
if err != nil {
//产生错误
    log.Println("rs.Batch failed:", err)
    return
}
for _, ret := range *rets {
    log.Println(ret.Code, ret.Error)
}
```

参阅: `rs.URIStat`, `rs.URICopy`, `rs.URIMove`, `rs.URIDelete`, `rs.Client.Batch`

## 数据处理 [#数据处理]

七牛支持在云端对图像，视频，音频等富媒体进行个性化处理。

## 查看图像属性 [#查看图像属性]

GO-SDK支持生成查看图片信息的URL，示意如下：

```
func makeImageInfoUrl(imageUrl string) string {
    ii := fop.ImageInfo{}
    return ii.MakeRequest(imageUrl)
}
```

还可以已另一种方式，在程序中处理返回的图片信息：

```
infoRet, err = ii.Call(nil, imageUrl)
if err != nil {
//产生错误
    log.Println("fop getImageInfo failed:", err)
    return
}
log.Println(infoRet.Height, infoRet.Width, infoRet.ColorModel,
    infoRet.Format)
```

参阅: `fop.ImageInfoRet`, `fop.ImageInfo`

## 查看图片EXIF信息 [#查看图片exif信息]

同样，本SDK也支持直接生成查看exif的URL：

```
func makeExifUrl(imageUrl string) string {
    e := fop.Exif{}
    return e.MakeRequest(imageUrl)
}
```

也可以在程序中处理exif的信息：

```
exifRet, err = ie.Call(nil, imageUrl)
if err != nil {
//产生错误
    log.Println("fop getExif failed:", err)
    return
}

//处理返回结果
for _, item := range exifRet {
    log.Println(item.Type, item.Val)
}
```

参阅: `fop.Exif`, `fop.ExifRet`, `fop.ExifValType`

## 生成图片预览 [#生成图片预览]

可以根据给定的文件URL和缩略图规格来生成缩略图的URL，代码：

```
func makeViewUrl(imageUrl string) string {
    var view = fop.ImageView {
        //Mode int      // 缩略模式
        //Width int     // Width = 0 表示不限定宽度
        //Height int    // Height = 0 表示不限定高度
        //Quality int   // 质量, 1-100
        //Format string // 输出格式，如jpg, gif, png, tif等等
    }
    return view.MakeRequest(imageUrl)
}
```

参阅: `fop.ImageView`

## 高级资源管理(rsf) [#高级资源管理rsf]

## 批量获取文件列表 [#批量获取文件列表]

根据指定的前缀，获取对应前缀的文件列表，正常使用情景如下：

```
func listAll(l rpc.Logger, rs *rsf.Client, bucketName string, prefix string) {

    var entries []rsf.ListItem
    var marker = ""
    var err error
    var limit = 1000

    for err == nil {
        entries, marker, err = rs.ListPrefix(l, bucketName,
            prefix, marker, limit)
        for _, item := range entries {
            //处理 item
            log.Print("item:", item)
        }
    }
    if err != io.EOF {
        //非预期的错误
        log.Print("listAll failed:", err)
    }
}
```

参阅: `rsf.ListPreFix`

## API参考手册 [#api参考手册]

* [对象存储API参考手册](/products/kodo/kodo-console-guide/0-an-overview-of-the-console)
* [数据处理API参考手册](/faq/dora)

## 相关资源 [#相关资源]

如果您有任何关于我们文档或产品的建议和想法，欢迎到我们的技术论坛参与讨论。

* [技术论坛](http://segmentfault.com/qiniu) - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
* [提交工单](https://support.qiniu.com/tickets/new) - 如果您的问题不适合在论坛讨论或希望及时解决，您也可以提交一个工单，我们的技术支持人员会第一时间回复您
* [博客](http://blog.qiniu.com/) - 这里会持续更新发布市场活动和技术分享文章
* [微博](http://weibo.com/qiniutek)
* [常见问题](https://support.qiniu.com/question)

## 贡献代码 [#贡献代码]

1. Fork
2. 创建您的特性分支 git checkout -b my-new-feature
3. 提交您的改动 git commit -am 'Added some feature'
4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature
5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

## 许可证 [#许可证]

Copyright (c) 2014 qiniu.com

基于 MIT 协议发布:

* [www.opensource.org/licenses/MIT](http://www.opensource.org/licenses/MIT)


# Go SDK (/products/kodo/go)



最近更新时间: 2025-04-02 11:13:24

## 简介 [#简介]

此 SDK 适用于 Go 1.10.0 及以上版本。使用此 SDK 构建您的网络应用程序，能让您以非常便捷的方式将数据安全地存储到七牛云上。无论您的网络应用是一个网站程序，还是包括从云端（服务端程序）到终端（手持设备应用）的架构服务和应用，通过七牛云及其 SDK，都能让您应用程序的终端用户高速上传和下载，同时也让您的服务端更加轻盈。

Go SDK 属于七牛服务端 SDK 之一，主要有如下功能：

1. 提供生成客户端上传所需的上传凭证的功能
2. 提供文件从服务端直接上传七牛的功能
3. 提供对七牛空间中文件进行管理的功能
4. 提供对七牛空间中文件进行处理的功能
5. 提供七牛 CDN 相关的刷新，预取，日志功能
6. 提供七牛视频监控 QVS 的功能

## 开源 [#开源]

* [Go SDK 项目地址](https://github.com/qiniu/go-sdk)
* [Go SDK 发布地址](https://github.com/qiniu/go-sdk/releases)
* [Go SDK 历史文档](/products/kodo/go/0-go-v6)

## 安装 [#安装]

推荐使用 go mod， `github.com/qiniu/go-sdk/v7` ，如 `require github.com/qiniu/go-sdk/v7 v7.25.3` ；

## 鉴权 [#鉴权]

Go SDK 的所有的功能，都需要合法的授权。授权凭证的签算需要七牛账号下的一对有效的 `Access Key` 和 `Secret Key` ，这对密钥可以通过如下步骤获得：

1. 点击 [注册 🔗](https://portal.qiniu.com/signup) 开通七牛开发者帐号
2. 如果已有账号，直接登录七牛开发者后台，点击 [这里 🔗](https://portal.qiniu.com/user/key) 查看 Access Key 和 Secret Key

<span id="upload-file" />

<span id="form-upload-file" />

## 文件上传 [#文件上传]

* [上传流程](/products/kodo/go#%E4%B8%8A%E4%BC%A0%E6%B5%81%E7%A8%8B)
* [客户端上传凭证](/products/kodo/go#%E5%AE%A2%E6%88%B7%E7%AB%AF%E4%B8%8A%E4%BC%A0%E5%87%AD%E8%AF%81)
  * [简单上传凭证](/products/kodo/go#simple-uptoken)
    * [覆盖上传凭证](/products/kodo/go#overwrite-uptoken)
    * [自定义上传回复凭证](/products/kodo/go#returnbody-uptoken)
    * [带回调业务服务器的凭证](/products/kodo/go#%E5%B8%A6%E5%9B%9E%E8%B0%83%E4%B8%9A%E5%8A%A1%E6%9C%8D%E5%8A%A1%E5%99%A8%E7%9A%84%E5%87%AD%E8%AF%81)
    * [带数据处理的凭证](/products/kodo/go#%E5%B8%A6%E6%95%B0%E6%8D%AE%E5%A4%84%E7%90%86%E7%9A%84%E5%87%AD%E8%AF%81)
    * [带自定义参数的凭证](/products/kodo/go#%E5%B8%A6%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%82%E6%95%B0%E7%9A%84%E5%87%AD%E8%AF%81)
    * [综合上传凭证](/products/kodo/go#%E7%BB%BC%E5%90%88%E4%B8%8A%E4%BC%A0%E5%87%AD%E8%AF%81)
* [服务器直传](/products/kodo/go#server-upload)
  * [构建配置类](/products/kodo/go#%E6%9E%84%E5%BB%BA%E9%85%8D%E7%BD%AE%E7%B1%BB)
    * [文件上传](/products/kodo/go#upload-file)
    * [数据流上传](/products/kodo/go#%E6%95%B0%E6%8D%AE%E6%B5%81%E4%B8%8A%E4%BC%A0)
    * [目录上传](/products/kodo/go#%E7%9B%AE%E5%BD%95%E4%B8%8A%E4%BC%A0)
    * [文件分片上传（断点续传）](/products/kodo/go#resume-upload-file)
    * [解析自定义回复内容](/products/kodo/go#%E8%A7%A3%E6%9E%90%E8%87%AA%E5%AE%9A%E4%B9%89%E5%9B%9E%E5%A4%8D%E5%86%85%E5%AE%B9)
    * [业务服务器验证存储服务回调](/products/kodo/go#%E4%B8%9A%E5%8A%A1%E6%9C%8D%E5%8A%A1%E5%99%A8%E9%AA%8C%E8%AF%81%E5%AD%98%E5%82%A8%E6%9C%8D%E5%8A%A1%E5%9B%9E%E8%B0%83)
    * [加速域名](/products/kodo/go#%E5%8A%A0%E9%80%9F%E5%9F%9F%E5%90%8D)

## 上传流程 [#上传流程]

文件上传分为客户端上传（主要是指网页端和移动端等面向终端用户的场景）和服务端上传两种场景，具体可以参考文档 [业务流程](/products/kodo/0-programming-model) 。

服务端 SDK 在上传方面主要提供两种功能，一种是生成客户端上传所需要的上传凭证，另外一种是直接上传文件到云端。

## 客户端上传凭证 [#客户端上传凭证]

客户端（移动端或者 Web 端）上传文件的时候，需要从客户自己的业务服务器获取上传凭证，而这些上传凭证是通过服务端的 SDK 来生成的，然后通过客户自己的业务 API 分发给客户端使用。根据上传的业务需求不同，七牛云 Go SDK 支持丰富的上传凭证生成方式。

<span id="simple-uptoken" />

## 简单上传的凭证 [#简单上传的凭证]

最简单的上传凭证只需要 `AccessKey` ， `SecretKey` 和 `Bucket` 就可以。

```
import (
    "context"
    "time"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/uptoken"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

bucket := "your bucket name"
putPolicy, err := uptoken.NewPutPolicy(bucket, time.Now().Add(1 * time.Hour))
if err != nil {
    return err
}
upToken, err := uptoken.NewSigner(putPolicy, mac).GetUpToken(context.Background())
if err != nil {
    return err
}
```

<span id="overwrite-uptoken" />

## 覆盖上传的凭证 [#覆盖上传的凭证]

覆盖上传除了需要 `简单上传` 所需要的信息之外，还需要想进行覆盖的文件名称，这个文件名称同时可是客户端上传代码中指定的文件名，两者必须一致。

```
import (
    "context"
    "time"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/uptoken"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

bucket := "your bucket name"
// 需要覆盖的文件名
keyToOverwrite := "qiniu.mp4"
putPolicy, err := uptoken.NewPutPolicyWithKey(bucket, keyToOverwrite, time.Now().Add(1 * time.Hour))
if err != nil {
    return err
}
upToken, err := uptoken.NewSigner(putPolicy, mac).GetUpToken(context.Background())
if err != nil {
    return err
}
```

<span id="returnbody-uptoken" />

## 自定义上传回复的凭证 [#自定义上传回复的凭证]

默认情况下，文件上传到七牛之后，在没有设置 `returnBody` 或者 `回调` 相关的参数情况下，七牛返回给上传端的回复格式为 `hash` 和 `key` ，例如：

```
{ "hash": "Ftgm-CkWePC9fzMBTRNmPMhGBcSV", "key": "qiniu.jpg" }
```

有时候我们希望能自定义这个返回的 JSON 格式的内容，可以通过设置 `returnBody` 参数来实现，在 `returnBody` 中，我们可以使用七牛支持的 [魔法变量](/products/kodo/development-guidelines/upload-types/0-vars#%E9%AD%94%E6%B3%95%E5%8F%98%E9%87%8F) 和 [自定义变量](/products/kodo/development-guidelines/upload-types/0-vars#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%98%E9%87%8F) 。

```
import (
    "context"
    "time"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/uptoken"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

bucket := "your bucket name"
putPolicy, err := uptoken.NewPutPolicy(bucket, time.Now().Add(1 * time.Hour))
if err != nil {
    return err
}
putPolicy.SetReturnBody(\`{"key":"$(key)","hash":"$(etag)","fsize":$(fsize),"bucket":"$(bucket)","name":"$(x:name)"}\`)
upToken, err := uptoken.NewSigner(putPolicy, mac).GetUpToken(context.Background())
if err != nil {
    return err
}
```

则文件上传到七牛之后，收到的回复内容格式如下：

```
{
  "key": "github-x.png",
  "hash": "FqKXVdTvIx_mPjOYdjDyUSy_H1jr",
  "fsize": 6091,
  "bucket": "if-pbl",
  "name": "github logo"
}
```

对于上面的自定义返回值，我们需要自定义结构体来解析这个回复，例如下面提供了一个解析结果的方法：

```
import (
    "context"
    "time"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/uptoken"
    "github.com/qiniu/go-sdk/v7/storagev2/uploader"
)

// 自定义返回值结构体
type MyPutRet struct {
    Key    string
    Hash   string
    Fsize  int
    Bucket string
    Name   string
}

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

localFile := "your local file path"
bucket := "your bucket name"
key := "your file save key"

putPolicy, err := uptoken.NewPutPolicy(bucket, time.Now().Add(1 * time.Hour))
if err != nil {
    return err
}
putPolicy.SetReturnBody(\`{"key":"$(key)","hash":"$(etag)","fsize":$(fsize),"bucket":"$(bucket)","name":"$(x:name)"}\`)

ret := MyPutRet{}
uploadManager := uploader.NewUploadManager(&uploader.UploadManagerOptions{})
err = uploadManager.UploadFile(context.Background(), localFile, &uploader.ObjectOptions{
    UpToken: uptoken.NewSigner(putPolicy, mac),
    ObjectName: &key,
    CustomVars: map[string]string{
        "name": "github logo",
    },
}, &ret)
if err != nil {
    return err
}
fmt.Println(ret.Bucket, ret.Key, ret.Fsize, ret.Hash, ret.Name)
```

## 带回调业务服务器的凭证 [#带回调业务服务器的凭证]

上面生成的 `自定义上传回复` 的上传凭证适用于上传端（无论是客户端还是服务端）和七牛服务器之间进行直接交互的情况下。在客户端上传的场景之下，有时候客户端需要在文件上传到七牛之后，从业务服务器获取相关的信息，这个时候就要用到七牛的上传回调及相关回调参数的设置。

```
import (
    "context"
    "time"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/uptoken"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

bucket := "your bucket name"
putPolicy, err := uptoken.NewPutPolicy(bucket, time.Now().Add(1 * time.Hour))
if err != nil {
    return err
}
putPolicy.SetCallbackUrl("http://api.example.com/qiniu/upload/callback").SetCallbackBody(\`{"key":"$(key)","hash":"$(etag)","fsize":$(fsize),"bucket":"$(bucket)","name":"$(x:name)"}\`).SetCallbackBodyType("application/json")
upToken, err := uptoken.NewSigner(putPolicy, mac).GetUpToken(context.Background())
if err != nil {
    return err
}
```

在使用了上传回调的情况下，客户端收到的回复就是业务服务器响应七牛的 JSON 格式内容，业务服务器收到回调之后必须响应 JSON 格式的回复給七牛，这个回复会被七牛传递给客户端。\
例如上面的 `CallbackBody` 的设置会在文件上传到七牛之后，触发七牛回调如下内容給业务服务器：

```
{
  "key": "github-x.png",
  "hash": "FqKXVdTvIx_mPjOYdjDyUSy_H1jr",
  "fsize": 6091,
  "bucket": "if-pbl",
  "name": "github logo"
}
```

通常情况下，我们建议使用 `application/json` 格式来设置 `callbackBody` ，保持数据格式的统一性。实际情况下， `callbackBody` 也支持 `application/x-www-form-urlencoded` 格式来组织内容，这个主要看业务服务器在接收到 `callbackBody` 的内容时如何解析。例如：

```
import (
    "context"
    "time"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/uptoken"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

bucket := "your bucket name"
putPolicy, err := uptoken.NewPutPolicy(bucket, time.Now().Add(1 * time.Hour))
if err != nil {
    return err
}
putPolicy.SetCallbackUrl("http://api.example.com/qiniu/upload/callback").SetCallbackBody(\`key=$(key)&hash=$(etag)&bucket=$(bucket)&fsize=$(fsize)&name=$(x:name)\`)
upToken, err := uptoken.NewSigner(putPolicy, mac).GetUpToken(context.Background())
if err != nil {
    return err
}
```

## 带数据处理的凭证 [#带数据处理的凭证]

七牛支持在文件上传到七牛之后，立即对其进行多种指令的数据处理，这个只需要在生成的上传凭证中指定相关的处理参数即可。

```
import (
    "context"
    "time"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/uptoken"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

bucket := "your bucket name"
putPolicy, err := uptoken.NewPutPolicy(bucket, time.Now().Add(1 * time.Hour))
if err != nil {
    return err
}

saveMp4Entry := base64.URLEncoding.EncodeToString([]byte(bucket + ":avthumb_test_target.mp4"))
saveJpgEntry := base64.URLEncoding.EncodeToString([]byte(bucket + ":vframe_test_target.jpg"))
//数据处理指令，支持多个指令
avthumbMp4Fop := "avthumb/mp4|saveas/" + saveMp4Entry
vframeJpgFop := "vframe/jpg/offset/1|saveas/" + saveJpgEntry

//连接多个操作指令
persistentOps := strings.Join([]string{avthumbMp4Fop, vframeJpgFop}, ";")
pipeline := "test"
persistentType := int64(0)
putPolicy.SetPersistentOps(persistentOps).SetPersistentNotifyUrl("http://api.example.com/qiniu/pfop/notify").SetPersistentPipeline(pipeline).SetPersistentType(persistentType)
upToken, err := uptoken.NewSigner(putPolicy, mac).GetUpToken(context.Background())
if err != nil {
    return err
}
```

* 队列 pipeline 请参阅 [创建私有队列](https://portal.qiniu.com/dora/media-gate/pipeline) ；转码操作具体参数请参阅 [音视频转码](/products/dora/audio-and-video-processing-api/3-audio-and-video-transcoding-avthumb) ；saveas 请参阅 [处理结果另存](/products/dora/processing-mechanism/0-processing-results-save-saveas) 。
* 闲时任务的功能介绍、使用场景、定价，详见 [闲时任务策略说明](/products/dora/processing-mechanism/persist/2-idle-time-task-strategy) 。

也可以支持使用工作流模版替代数据处理指令。工作流模板是预先编排好的一系列媒体处理流程（如转码、截图、视频拼接等各类处理），登录 [对象存储控制台](https://portal.qiniu.com/kodo/bucket) 进行创建，详情参考 [工作流模板操作指南](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template) ， `persistentWorkflowTemplateID` 对应工作流模板列表的 `名称` 字段

```
import (
    "context"
    "time"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/uptoken"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

bucket := "your bucket name"
putPolicy, err := uptoken.NewPutPolicy(bucket, time.Now().Add(1 * time.Hour))
if err != nil {
    return err
}

workflowTemplateID := "tempname"
pipeline := "test"
persistentType := int64(0)
putPolicy.SetPersistentWorkflowTemplateID(workflowTemplateID).SetPersistentNotifyUrl("http://api.example.com/qiniu/pfop/notify").SetPersistentPipeline(pipeline).SetPersistentType(persistentType)
upToken, err := uptoken.NewSigner(putPolicy, mac).GetUpToken(context.Background())
if err != nil {
    return err
}
```

## 带自定义参数的凭证 [#带自定义参数的凭证]

存储支持客户端上传文件的时候定义一些自定义参数，这些参数可以在 `returnBody` 和 `callbackBody` 里面和七牛内置支持的魔法变量（即系统变量）通过相同的方式来引用。这些自定义的参数名称必须以 `x:`开头。例如客户端上传的时候指定了自定义的参数 `x:name` 和 `x:age` 分别是 `string` 和 `int` 类型。那么可以通过下面的方式引用：

```
putPolicy.SetReturnBody(\`{"key":"$(key)","hash":"$(etag)","fsize":$(fsize),"bucket":"$(bucket)","name":"$(x:name)","age":$(x:age)}\`)
```

或者

```
putPolicy.SetCallbackBody(\`{"key":"$(key)","hash":"$(etag)","fsize":$(fsize),"bucket":"$(bucket)","name":"$(x:name)","age":$(x:age)}\`)
```

## 综合上传凭证 [#综合上传凭证]

上面的生成上传凭证的方法，都是通过设置 [上传策略 🔗](/products/kodo/development-guidelines/security/1-put-policy) 相关的参数来支持的，这些参数可以通过不同的组合方式来满足不同的业务需求，可以灵活地组织你所需要的上传凭证。

<span id="server-upload" />

## 服务端直传 [#服务端直传]

服务端直传是指客户利用七牛服务端 SDK 从服务端直接上传文件到七牛云，交互的双方一般都在机房里面，所以服务端可以自己生成上传凭证，然后利用 SDK 中的上传逻辑进行上传，最后从七牛云获取上传的结果，这个过程中由于双方都是业务服务器，所以很少利用到上传回调的功能，而是直接自定义 `returnBody` 来获取自定义的回复内容。

## 构建配置类 [#构建配置类]

存储支持空间创建在不同的机房，在使用七牛的 Go SDK 中 `UploadManager` 上传文件之前，可以构建一个上传用的 `UploadManagerOptions` 对象，在该对象中，可以指定空间对应的 `Regions` (如不指定 `Regions` 则会使用自动判断区域)以及其他的一些影响上传的参数。

```
import (
    "github.com/qiniu/go-sdk/v7/storagev2/http_client"
    "github.com/qiniu/go-sdk/v7/storagev2/region"
    "github.com/qiniu/go-sdk/v7/storagev2/uploader"
)

options := uploader.UploadManagerOptions{
    Options: http_client.Options{
        Regions: region.GetRegionByID("z0", true),
    },
}
uploadManager := uploader.NewUploadManager(&options)
```

其中关于 `Region ID` 和机房的关系如下：

| 机房       | Region ID        |
| -------- | ---------------- |
| 华东       | `z0`             |
| 华东浙江 2 区 | `cn-east-2`      |
| 华北       | `z1`             |
| 华南       | `z2`             |
| 北美       | `na0`            |
| 新加坡      | `as0`            |
| 亚太-河内    | `ap-southeast-2` |
| 亚太-胡志明   | `ap-southeast-3` |

## 文件上传 [#文件上传-1]

最简单的就是上传本地文件，直接指定文件的完整路径即可上传。

```
import (
    "context"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/http_client"
    "github.com/qiniu/go-sdk/v7/storagev2/uploader"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

localFile := "/Users/jemy/Documents/github.png"
bucket := "if-pbl"
key := "github-x.png"

uploadManager := uploader.NewUploadManager(&uploader.UploadManagerOptions{
    Options: http_client.Options{
        Credentials: mac,
    },
})
err := uploadManager.UploadFile(context.Background(), localFile, &uploader.ObjectOptions{
    BucketName: bucket,
    ObjectName: &key,
    CustomVars: map[string]string{
        "name": "github logo",
    },
}, nil)
if err != nil {
    return err
}
```

<span id="form-upload-stream" />

## 数据流上传 [#数据流上传]

可以支持将 `io.Reader` 读取到的数据上传到空间中。

```
import (
    "bytes"
    "context"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/http_client"
    "github.com/qiniu/go-sdk/v7/storagev2/uploader"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

bucket := "if-pbl"
key := "github-x.png"

uploadManager := uploader.NewUploadManager(&uploader.UploadManagerOptions{
    Options: http_client.Options{
        Credentials: mac,
    },
})
err := uploadManager.UploadReader(context.Background(), reader, &uploader.ObjectOptions{
    BucketName: bucket,
    ObjectName: &key,
    CustomVars: map[string]string{
        "name": "github logo",
    },
    FileName: "",
}, nil)
if err != nil {
    return err
}
```

## 目录上传 [#目录上传]

可以支持直接将目录上传到空间中。

```
import (
    "context"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/http_client"
    "github.com/qiniu/go-sdk/v7/storagev2/uploader"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

localDir := "/Users/jemy/Documents/"
bucket := "if-pbl"
keyPrefix := "Documents/"

uploadManager := uploader.NewUploadManager(&uploader.UploadManagerOptions{
    Options: http_client.Options{
        Credentials: mac,
    },
})
err := uploadManager.UploadDirectory(context.Background(), localDir, &uploader.DirectoryOptions{
    BucketName: bucket,
    UpdateObjectName: func(key string) string {
        return keyPrefix + key
    },
    ObjectConcurrency:     16,   // 对象上传并发度
})
if err != nil {
    return err
}
```

## 文件分片上传 [#文件分片上传]

对于大的文件，Go SDK 自动使用分片上传的方式来上传文件， [分片上传 v2](/products/kodo/rs/multipartupload-interface) 通过将一个文件切割为块，然后通过上传块的方式来进行文件的上传。Go SDK 中默认块大小为 4MB，支持根据条件设置块大小（要求除最后一块外，其他块大于等于 1MB，小于等于 1G），块与块之间可以并发上传，以提高上传效率。分片上传不等于断点续传，但是分片上传可以支持断点续传。

```
import (
    "context"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/http_client"
    "github.com/qiniu/go-sdk/v7/storagev2/uploader"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

localFile := "/Users/jemy/Documents/github.mp4"
bucket := "if-pbl"
key := "github-x.mp4"

uploadManager := uploader.NewUploadManager(&uploader.UploadManagerOptions{
    Options: http_client.Options{
        Credentials: mac,
    },
    PartSize: 16 * 1024 * 1024, // 分片大小调整为 16MB，默认为 4MB
    Concurrency: 4, // 分片上传并发度调整为 4，默认为 1
})
err := uploadManager.UploadFile(context.Background(), localFile, &uploader.ObjectOptions{
    BucketName: bucket,
    ObjectName: &key,
    CustomVars: map[string]string{
        "name": "github logo",
    },
}, nil)
if err != nil {
    return err
}
```

<span id="upload-resumable" />

<span id="resume-upload-file" />

## 文件断点续传 [#文件断点续传]

断点续传实现逻辑是将每个块上传完毕的进度信息保存到本地的文件中持久化，如果本次上传被中断，下次可以从这个进度文件中读取每个块上传的状态，然后继续上传完毕没有完成的块，最后完成文件的拼接。需要注意，只有在块上传完毕之后，才向本地的进度文件写入进度内容。另外，每个上传任务初始化之后有效期最长是 7 天，过期会触发 701 的错误，可以检查进度信息中的时间参数来确认是否过期。

断点续传是基于分片上传来实现的，基本原理就是用一个文本文件记录下上传的进度，如果上传中断，下次再从这个文件读取进度，继续上传未完成的分块。用户只需要传入 `ResumableRecorder` 参数即可实现断点续传，其他逻辑内部封装，实例如下：

```
import (
    "context"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/http_client"
    "github.com/qiniu/go-sdk/v7/storagev2/uploader"
    resumablerecorder "github.com/qiniu/go-sdk/v7/storagev2/uploader/resumable_recorder"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

localFile := "/Users/jemy/Documents/github.png"
bucket := "if-pbl"
key := "github-x.png"

uploadManager := uploader.NewUploadManager(&uploader.UploadManagerOptions{
    Options: http_client.Options{
        Credentials: mac,
    },
    ResumableRecorder: resumablerecorder.NewJsonFileSystemResumableRecorder("/data"),
})
err := uploadManager.UploadFile(context.Background(), localFile, &uploader.ObjectOptions{
    BucketName: bucket,
    ObjectName: &key,
    CustomVars: map[string]string{
        "name": "github logo",
    },
}, nil)
if err != nil {
    return err
}
```

## 解析自定义回复内容 [#解析自定义回复内容]

有些情况下，七牛返回给上传端的内容不是默认的 `hash` 和 `key` 形式，这种情况下，可能出现在自定义 `returnBody` 或者自定义了 `callbackBody` 的情况下，前者一般是服务端直传的场景，而后者则是接受上传回调的场景，这两种场景之下，都涉及到需要将自定义的回复进行内容解析，一般建议在交互过程中，都采用 `JSON` 的方式，这样处理起来方法比较一致，而且 `JSON` 的方法最通用。如果需要用到自定义回复，可以类似上面讲解 `returnBody` 的时候给的例子，自定义一个结构体用于回复的解析，例如：

```
// 自定义返回值结构体
type MyPutRet struct {
    Key    string
    Hash   string
    Fsize  int
    Bucket string
    Name   string
}
```

## 业务服务器验证存储服务回调 [#业务服务器验证存储服务回调]

在上传策略里面设置了上传回调相关参数的时候，七牛在文件上传到服务器之后，会主动地向 `callbackUrl` 发送 POST 请求的回调，回调的内容为 `callbackBody` 模版所定义的内容，如果这个模版里面引用了 [魔法变量](/products/kodo/development-guidelines/upload-types/0-vars#%E9%AD%94%E6%B3%95%E5%8F%98%E9%87%8F) 或者 [自定义变量](/products/kodo/development-guidelines/upload-types/0-vars#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%98%E9%87%8F) ，那么这些变量会被自动填充对应的值，然后在发送给业务服务器。

业务服务器在收到来自七牛的回调请求的时候，可以根据请求头部的 `Authorization` 字段来进行验证，查看该请求是否是来自七牛的未经篡改的请求。

Go SDK 提供了一个方法 `credentials.VerifyCallback` 用于验证回调的请求：

```
// VerifyCallback 验证上传回调请求是否来自存储服务
func VerifyCallback(mac *credentials.Credentials, req *http.Request) (bool, error) {
    return mac.VerifyCallback(req)
}
```

## 加速域名 [#加速域名]

### 加速上传 [#加速上传]

```
import (
    "context"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/http_client"
    "github.com/qiniu/go-sdk/v7/storagev2/uploader"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

localFile := "/Users/jemy/Documents/github.png"
bucket := "if-pbl"
key := "github-x.png"

uploadManager := uploader.NewUploadManager(&uploader.UploadManagerOptions{
    Options: http_client.Options{
        Credentials: mac,
        AccelerateUploading: true,
    },
})
err := uploadManager.UploadFile(context.Background(), localFile, &uploader.ObjectOptions{
    BucketName: bucket,
    ObjectName: &key,
    CustomVars: map[string]string{
        "name": "github logo",
    },
}, nil)
if err != nil {
    return err
}
```

## 下载文件 [#下载文件]

* [通过指定的自定义域名从公开空间下载](/products/kodo/go#%E9%80%9A%E8%BF%87%E6%8C%87%E5%AE%9A%E7%9A%84%E8%87%AA%E5%AE%9A%E4%B9%89%E5%9F%9F%E5%90%8D%E4%BB%8E%E5%85%AC%E5%BC%80%E7%A9%BA%E9%97%B4%E4%B8%8B%E8%BD%BD)
* [通过指定的自定义域名从私有空间下载](/products/kodo/go#%E9%80%9A%E8%BF%87%E6%8C%87%E5%AE%9A%E7%9A%84%E8%87%AA%E5%AE%9A%E4%B9%89%E5%9F%9F%E5%90%8D%E4%BB%8E%E7%A7%81%E6%9C%89%E7%A9%BA%E9%97%B4%E4%B8%8B%E8%BD%BD)
* [通过源站下载](/products/kodo/go#%E9%80%9A%E8%BF%87%E6%BA%90%E7%AB%99%E4%B8%8B%E8%BD%BD)
* [下载到文件](/products/kodo/go#%E4%B8%8B%E8%BD%BD%E5%88%B0%E6%96%87%E4%BB%B6)
* [下载到数据流](/products/kodo/go#%E4%B8%8B%E8%BD%BD%E5%88%B0%E6%95%B0%E6%8D%AE%E6%B5%81)
* [目录下载](/products/kodo/go#%E7%9B%AE%E5%BD%95%E4%B8%8B%E8%BD%BD)

对于下载的情况，首先考虑下载 URL 如何生成。这里介绍三种下载 URL 的生成方式：

## 通过指定的自定义域名从公开空间下载 [#通过指定的自定义域名从公开空间下载]

因为是公开空间，所以无需设置鉴权参数。

```
import (
    "context"
    "github.com/qiniu/go-sdk/v7/storagev2/downloader"
)

domain := "download.domain.com"
urlsProvider := downloader.NewStaticDomainBasedURLsProvider([]string{domain})
```

这里的 `urlsProvider` 之后可以用于下载文件。

## 通过指定的自定义域名从私有空间下载 [#通过指定的自定义域名从私有空间下载]

私有空间必须用鉴权参数签名后才能下载。

```
import (
    "context"
    "time"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/downloader"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

domain := "download.domain.com"
urlsProvider := downloader.SignURLsProvider(downloader.NewStaticDomainBasedURLsProvider([]string{domain}), downloader.NewCredentialsSigner(mac), &downloader.SignOptions{
    TTL: 1 * time.Hour, // 有效期
})
```

## 通过源站下载 [#通过源站下载]

如果没有自定义域名可用，就可以选择源站下载，源站下载必须签名且有效期最长五分钟。

```
import (
    "context"
    "time"
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/downloader"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)

urlsProvider := downloader.SignURLsProvider(downloader.NewDefaultSrcURLsProvider(mac.AccessKey, nil), downloader.NewCredentialsSigner(mac), nil)
```

## 下载到文件 [#下载到文件]

```
localFile := "/Users/jemy/Documents/github.png"
bucket := "if-pbl"
key := "github-x.png"

downloadManager := downloader.NewDownloadManager(&downloader.DownloadManagerOptions{})
downloaded, err := downloadManager.DownloadToFile(context.Background(), key, localPath, &downloader.ObjectOptions{
    GenerateOptions:            downloader.GenerateOptions{BucketName: bucket},
    DownloadURLsProvider:       urlsProvider,
})
if err != nil {
    return err
}
```

## 下载到数据流 [#下载到数据流]

```
bucket := "if-pbl"
key := "github-x.png"

downloadManager := downloader.NewDownloadManager(&downloader.DownloadManagerOptions{})
n, err := downloadManager.DownloadToWriter(context.Background(), key, writer, &downloader.ObjectOptions{
    GenerateOptions:      downloader.GenerateOptions{BucketName: bucket},
    DownloadURLsProvider: urlsProvider,
})
if err != nil {
    return err
}
```

## 目录下载 [#目录下载]

```
localDir := "/Users/jemy/Documents/"
bucket := "if-pbl"
keyPrefix := "Documents/"

downloadManager := downloader.NewDownloadManager(&downloader.DownloadManagerOptions{
    Options: http_client.Options{Credentials: mac},
})
err := downloadManager.DownloadDirectory(context.Background(), localDir, &downloader.DirectoryOptions{
    BucketName:           bucket,
    ObjectPrefix:         keyPrefix,
    ObjectConcurrency:    16, // 对象下载并发度
    DownloadURLsProvider: urlsProvider,
})
if err != nil {
    return err
}
```

## 资源管理 [#资源管理]

资源管理包括的主要功能有：

* [获取文件信息](/products/kodo/go#%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E4%BF%A1%E6%81%AF)
* [修改文件 MimeType](/products/kodo/go#%E4%BF%AE%E6%94%B9%E6%96%87%E4%BB%B6-mimetype)
* [修改文件存储类型](/products/kodo/go#%E4%BF%AE%E6%94%B9%E6%96%87%E4%BB%B6%E5%AD%98%E5%82%A8%E7%B1%BB%E5%9E%8B)
* [修改文件 MetaData](/products/kodo/go#%E4%BF%AE%E6%94%B9%E6%96%87%E4%BB%B6-metadata)
* [移动或重命名文件](/products/kodo/go#%E7%A7%BB%E5%8A%A8%E6%88%96%E9%87%8D%E5%91%BD%E5%90%8D%E6%96%87%E4%BB%B6)
* [复制文件副本](/products/kodo/go#%E5%A4%8D%E5%88%B6%E6%96%87%E4%BB%B6%E5%89%AF%E6%9C%AC)
* [删除空间中的文件](/products/kodo/go#%E5%88%A0%E9%99%A4%E7%A9%BA%E9%97%B4%E4%B8%AD%E7%9A%84%E6%96%87%E4%BB%B6)
* [设置或更新文件生存时间](/products/kodo/go#rs-delete-after-days)
* [获取指定前缀文件列表](/products/kodo/go#rs-list)
* [资源管理批量操作](/products/kodo/go#%E8%B5%84%E6%BA%90%E7%AE%A1%E7%90%86%E6%89%B9%E9%87%8F%E6%93%8D%E4%BD%9C)
  * [批量获取文件信息](/products/kodo/go#%E6%89%B9%E9%87%8F%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E4%BF%A1%E6%81%AF)
    * [批量修改文件类型](/products/kodo/go#%E6%89%B9%E9%87%8F%E4%BF%AE%E6%94%B9%E6%96%87%E4%BB%B6%E7%B1%BB%E5%9E%8B)
    * [批量删除文件](/products/kodo/go#%E6%89%B9%E9%87%8F%E5%88%A0%E9%99%A4%E6%96%87%E4%BB%B6)
    * [批量复制文件](/products/kodo/go#%E6%89%B9%E9%87%8F%E5%A4%8D%E5%88%B6%E6%96%87%E4%BB%B6)
    * [批量移动或重命名文件](/products/kodo/go#%E6%89%B9%E9%87%8F%E7%A7%BB%E5%8A%A8%E6%88%96%E9%87%8D%E5%91%BD%E5%90%8D%E6%96%87%E4%BB%B6)
    * [批量更新文件的有效期](/products/kodo/go#%E6%89%B9%E9%87%8F%E6%9B%B4%E6%96%B0%E6%96%87%E4%BB%B6%E7%9A%84%E6%9C%89%E6%95%88%E6%9C%9F)
    * [批量更新文件存储类型](/products/kodo/go#%E6%89%B9%E9%87%8F%E6%9B%B4%E6%96%B0%E6%96%87%E4%BB%B6%E5%AD%98%E5%82%A8%E7%B1%BB%E5%9E%8B)

资源管理相关的操作首先要构建 `Bucket` 对象：

```
import (
    "github.com/qiniu/go-sdk/v7/storagev2/credentials"
    "github.com/qiniu/go-sdk/v7/storagev2/http_client"
    "github.com/qiniu/go-sdk/v7/storagev2/objects"
)

accessKey := "your access key"
secretKey := "your secret key"
mac := credentials.NewCredentials(accessKey, secretKey)
objectsManager := objects.NewObjectsManager(&objects.ObjectsManagerOptions{
    Options: http_client.Options{Credentials: creds},
})
bucketName := "if-pbl"
bucket := objectsManager.Bucket(bucketName)
```

<span id="rs-batch-stat" />

## 获取文件信息 [#获取文件信息]

```
key := "github.png"

objectInfo, err := bucket.Object(key).Stat().Call(context.Background())
if err != nil {
    return err
}
```

<span id="rs-chgm" />

## 修改文件 MimeType [#修改文件-mimetype]

```
key := "github.png"
newMime := "image/x-png"

err := bucket.Object(key).SetMetadata(newMime).Call(context.Background())
if err != nil {
    return err
}
```

## 修改文件存储类型 [#修改文件存储类型]

```
key := "github.png"
storageClass := objects.IAStorageClass

err := bucket.Object(key).SetStorageClass(storageClass).Call(context.Background())
if err != nil {
    return err
}
```

## 修改文件 MetaData [#修改文件-metadata]

```
key := "github.png"
err := bucket.Object(key).SetMetadata("").
    Metadata(map[string]string{"x-qn-meta-c": "x-qn-meta-cc-value"}). // 如果 x-qn-meta-c 存在，则将值修改为 x-qn-meta-cc-value，如果不存在则增加 x-qn-meta-c 键值对
    Call(context.Background())
if err != nil {
    return err
}
```

<span id="rs-move" />

## 移动或重命名文件 [#移动或重命名文件]

移动操作本身支持移动文件到相同，不同空间中，在移动的同时也可以支持文件重命名。唯一的限制条件是，移动的源空间和目标空间必须在同一个机房。

| 源空间     | 目标空间    | 源文件名 | 目标文件名 | 描述                       |
| ------- | ------- | ---- | ----- | ------------------------ |
| BucketA | BucketA | KeyA | KeyB  | 相当于同空间文件重命名              |
| BucketA | BucketB | KeyA | KeyA  | 移动文件到 BucketB，文件名一致      |
| BucketA | BucketB | KeyA | KeyB  | 移动文件到 BucketB，文件名变成 KeyB |

`move` 操作支持强制覆盖选项，即如果目标文件已存在，可以设置强制覆盖选项 `force` 来覆盖那个文件的内容。

```
key := "github.png"
//目标空间可以和源空间相同，但是不能为跨机房的空间
destBucket := srcBucket
//目标文件名可以和源文件名相同，也可以不同
destKey := "github-new.png"
err := bucket.Object(key).MoveTo(destBucket, destKey).Call(context.Background())
if err != nil {
    return err
}
```

<span id="rs-copy" />

## 复制文件副本 [#复制文件副本]

文件的复制和文件移动其实操作一样，主要的区别是移动后源文件不存在了，而复制的结果是源文件还存在，只是多了一个新的文件副本。

```
key := "github.png"
//目标空间可以和源空间相同，但是不能为跨机房的空间
destBucket := srcBucket
//目标文件名可以和源文件名相同，也可以不同
destKey := "github-new.png"
err := bucket.Object(key).CopyTo(destBucket, destKey).Call(context.Background())
if err != nil {
    return err
}
```

<span id="rs-delete" />

## 删除空间中的文件 [#删除空间中的文件]

```
key := "github.png"
err := bucket.Object(key).Delete().Call(context.Background())
if err != nil {
    return err
}
```

<span id="rs-delete-after-days" />

## 设置或更新文件的生存时间 [#设置或更新文件的生存时间]

可以给已经存在于空间中的文件设置文件生存时间，或者更新已设置了生存时间但尚未被删除的文件的新的生存时间。

```
key := "github.png"
days := 7
err := bucket.Object(key).SetLifeCycle().DeleteAfterDays(days).Call(context.Background())
if err != nil {
    return err
}
```

<span id="rs-list" />

## 获取指定前缀的文件列表 [#获取指定前缀的文件列表]

获取指定文件前缀的列表用来从空间列举文件。

```
keyPrefix := "qshell/"

iter := bucket.List(context.Background(), &objects.ListObjectsOptions{Prefix: keyPrefix})
defer iter.Close()

var objectInfo objects.ObjectDetails
for iter.Next(&objectInfo) {
    fmt.Printf("%s\n", objectInfo.Name)
}
if err := iter.Error(); err != nil {
    return err
}
```

<span id="rs-batch" />

## 资源管理批量操作 [#资源管理批量操作]

## 批量获取文件信息 [#批量获取文件信息]

```
onResponse := func(od *objects.ObjectDetails) {
    fmt.Printf("%s: %d\n", od.Name, od.Size)
}
onError := func(err error) {
    fmt.Printf("%s\n", err)
}
err := objectsManager.Batch(context.Background(), []objects.Operation{
    bucket.Object("github1.png").Stat().OnResponse(onResponse).OnError(onError),
    bucket.Object("github2.png").Stat().OnResponse(onResponse).OnError(onError),
    bucket.Object("github3.png").Stat().OnResponse(onResponse).OnError(onError),
    bucket.Object("github4.png").Stat().OnResponse(onResponse).OnError(onError),
    bucket.Object("github5.png").Stat().OnResponse(onResponse).OnError(onError),
}, nil)
if err != nil {
    return err
}
```

## 批量修改文件类型 [#批量修改文件类型]

```
onError := func(err error) {
    fmt.Printf("%s\n", err)
}
err := objectsManager.Batch(context.Background(), []objects.Operation{
    bucket.Object("github1.png").SetMetadata("image/x-png").OnError(onError),
    bucket.Object("github2.png").SetMetadata("image/x-png").OnError(onError),
    bucket.Object("github3.png").SetMetadata("image/x-png").OnError(onError),
    bucket.Object("github4.png").SetMetadata("image/x-png").OnError(onError),
    bucket.Object("github5.png").SetMetadata("image/x-png").OnError(onError),
}, nil)
if err != nil {
    return err
}
```

## 批量删除文件 [#批量删除文件]

```
onError := func(err error) {
    fmt.Printf("%s\n", err)
}
err := objectsManager.Batch(context.Background(), []objects.Operation{
    bucket.Object("github1.png").Delete().OnError(onError),
    bucket.Object("github2.png").Delete().OnError(onError),
    bucket.Object("github3.png").Delete().OnError(onError),
    bucket.Object("github4.png").Delete().OnError(onError),
    bucket.Object("github5.png").Delete().OnError(onError),
}, nil)
if err != nil {
    return err
}
```

## 批量复制文件 [#批量复制文件]

```
destBucket := "if-pbl-2"
onError := func(err error) {
    fmt.Printf("%s\n", err)
}
err := objectsManager.Batch(context.Background(), []objects.Operation{
    bucket.Object("github1.png").CopyTo(destBucket, "github1.png").OnError(onError),
    bucket.Object("github2.png").CopyTo(destBucket, "github1.png").OnError(onError),
    bucket.Object("github3.png").CopyTo(destBucket, "github1.png").OnError(onError),
    bucket.Object("github4.png").CopyTo(destBucket, "github1.png").OnError(onError),
    bucket.Object("github5.png").CopyTo(destBucket, "github1.png").OnError(onError),
}, nil)
if err != nil {
    return err
}
```

<span id="rs-batch-move" />

## 批量移动或重命名文件 [#批量移动或重命名文件]

```
destBucket := "if-pbl-2"
onError := func(err error) {
    fmt.Printf("%s\n", err)
}
err := objectsManager.Batch(context.Background(), []objects.Operation{
    bucket.Object("github1.png").MoveTo(destBucket, "github1.png").OnError(onError),
    bucket.Object("github2.png").MoveTo(destBucket, "github1.png").OnError(onError),
    bucket.Object("github3.png").MoveTo(destBucket, "github1.png").OnError(onError),
    bucket.Object("github4.png").MoveTo(destBucket, "github1.png").OnError(onError),
    bucket.Object("github5.png").MoveTo(destBucket, "github1.png").OnError(onError),
}, nil)
if err != nil {
    return err
}
```

## 批量更新文件的有效期 [#批量更新文件的有效期]

```
onError := func(err error) {
    fmt.Printf("%s\n", err)
}
err := objectsManager.Batch(context.Background(), []objects.Operation{
    bucket.Object("github1.png").SetLifeCycle().DeleteAfterDays(7).OnError(onError),
    bucket.Object("github2.png").SetLifeCycle().DeleteAfterDays(8).OnError(onError),
    bucket.Object("github3.png").SetLifeCycle().DeleteAfterDays(9).OnError(onError),
    bucket.Object("github4.png").SetLifeCycle().DeleteAfterDays(10).OnError(onError),
    bucket.Object("github5.png").SetLifeCycle().DeleteAfterDays(11).OnError(onError),
}, nil)
if err != nil {
    return err
}
```

## 批量更新文件存储类型 [#批量更新文件存储类型]

```
storageClass := objects.IAStorageClass
onError := func(err error) {
    fmt.Printf("%s\n", err)
}
err := objectsManager.Batch(context.Background(), []objects.Operation{
    bucket.Object("github1.png").SetStorageClass(storageClass).OnError(onError),
    bucket.Object("github2.png").SetStorageClass(storageClass).OnError(onError),
    bucket.Object("github3.png").SetStorageClass(storageClass).OnError(onError),
    bucket.Object("github4.png").SetStorageClass(storageClass).OnError(onError),
    bucket.Object("github5.png").SetStorageClass(storageClass).OnError(onError),
}, nil)
if err != nil {
    return err
}
```

## 持久化数据处理 [#持久化数据处理]

## 发送数据处理请求（数据处理指令） [#发送数据处理请求数据处理指令]

对于已经保存到七牛空间的文件，可以通过发送持久化的数据处理指令来进行处理，这些指令支持七牛官方提供的指令，也包括客户自己开发的自定义数据处理的指令。数据处理的结果还可以通过七牛主动通知的方式告知业务服务器。

使用数据处理，首先需要构建一个 `OperationManager` 对象：

```
mac := auth.New(accessKey, secretKey)
cfg := storage.Config{
    UseHTTPS: true,
}

// 指定空间所在的区域，如果不指定将自动探测
// 如果没有特殊需求，默认不需要指定
//cfg.Region=&storage.ZoneHuabei
operationManager := storage.NewOperationManager(mac, &cfg)
```

进行视频的处理示例：

* 闲时任务的功能介绍、使用场景、定价，详见 [闲时任务策略说明](/products/dora/processing-mechanism/persist/2-idle-time-task-strategy) 。

```
bucket := "if-pbl"
key := "qiniu.mp4"
mac := auth.New(accessKey, secretKey)

saveBucket := bucket

// 处理指令集合
fopAvthumb := fmt.Sprintf("avthumb/mp4/s/480x320/vb/500k|saveas/%s",
    storage.EncodedEntry(saveBucket, "pfop_test_qiniu.mp4"))
fopVframe := fmt.Sprintf("vframe/jpg/offset/10|saveas/%s",
    storage.EncodedEntry(saveBucket, "pfop_test_qiniu.jpg"))
fopVsample := fmt.Sprintf("vsample/jpg/interval/20/pattern/%s",
    base64.URLEncoding.EncodeToString([]byte("pfop_test_$(count).jpg")))

fopBatch := []string{fopAvthumb, fopVframe, fopVsample}
fops := strings.Join(fopBatch, ";")

// 强制重新执行数据处理任务
force := int64(1)
// 数据处理指令全部完成之后，通知该地址
notifyURL := "http://api.example.com/pfop/callback"
// 数据处理的私有队列，必须指定以保障处理速度
pipeline := "jemy"
// 任务类型：0: 普通任务 1: 闲时任务（一旦指定闲时任务，就不能指定 pipeline）
persistentType := int64(0)
request := storage.PfopRequest{
    BucketName:         bucket,
    ObjectName:         key,
    Fops:               fops,
    NotifyUrl:          notifyURL,
    Force:              force,
    Type:               persistentType,
    Pipeline:           pipeline,
}
persistentId, err := operationManager.PfopV2(context.Background(), &request)
if err != nil {
    fmt.Println(err)
    return
}

fmt.Println(persistentId)
```

## 发送数据处理请求（工作流模版） [#发送数据处理请求工作流模版]

也可以支持使用工作流模版替代数据处理指令。工作流模板是预先编排好的一系列媒体处理流程（如转码、截图、视频拼接等各类处理），登录 [对象存储控制台](https://portal.qiniu.com/kodo/bucket) 进行创建，详情参考 [工作流模板操作指南](/products/kodo/kodo-console-guide/bucket-management/the-data-processing/tasks-workflows/0-workflow-template) ， `WorkflowTemplateID` 对应工作流模板列表的 `名称` 字段

```
bucket := "if-pbl"
key := "qiniu.mp4"
mac := auth.New(accessKey, secretKey)

// 工作流模版
workflowTemplateID := "tempname"
// 强制重新执行数据处理任务
force := int64(1)
// 数据处理指令全部完成之后，通知该地址
notifyURL := "http://api.example.com/pfop/callback"
// 数据处理的私有队列，必须指定以保障处理速度
pipeline := "jemy"
// 任务类型：0: 普通任务 1: 闲时任务（一旦指定闲时任务，就不能指定 pipeline）
persistentType := int64(0)
request := storage.PfopRequest{
    BucketName:         bucket,
    ObjectName:         key,
    WorkflowTemplateID: workflowTemplateID,
    NotifyUrl:          notifyURL,
    Force:              force,
    Type:               persistentType,
    Pipeline:           pipeline,
}
persistentId, err := operationManager.PfopV2(context.Background(), &request)
if err != nil {
    fmt.Println(err)
    return
}

fmt.Println(persistentId)
```

## 查询数据处理请求状态 [#查询数据处理请求状态]

由于数据处理是异步处理，可以根据发送处理请求时返回的 `persistentId` 去查询任务的处理进度，如果在上传策略里面设置了 `persistentNotifyUrl` 或者发送处理请求时指定 `notifyURL` 的情况下，直接业务服务器等待处理结果通知即可，如果需要主动查询，可以采用如下代码中的：

```
persistentId := "z0.597f28b445a2650c994bb208"
ret, err := operationManager.Prefop(persistentId)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(ret.String())
```

## CDN 相关功能 [#cdn-相关功能]

* [文件刷新](/products/kodo/go#%E6%96%87%E4%BB%B6%E5%88%B7%E6%96%B0)
* [目录刷新](/products/kodo/go#%E7%9B%AE%E5%BD%95%E5%88%B7%E6%96%B0)
* [文件预取操作](/products/kodo/go#fusion-prefetch)
* [获取域名流量](/products/kodo/go#%E8%8E%B7%E5%8F%96%E5%9F%9F%E5%90%8D%E6%B5%81%E9%87%8F)
* [获取域名带宽](/products/kodo/go#%E8%8E%B7%E5%8F%96%E5%9F%9F%E5%90%8D%E5%B8%A6%E5%AE%BD)
* [获取日志下载链接](/products/kodo/go#%E8%8E%B7%E5%8F%96%E6%97%A5%E5%BF%97%E4%B8%8B%E8%BD%BD%E9%93%BE%E6%8E%A5)
* [构建时间戳防盗链访问链接](/products/kodo/go#%E6%9E%84%E5%BB%BA%E6%97%B6%E9%97%B4%E6%88%B3%E9%98%B2%E7%9B%97%E9%93%BE%E8%AE%BF%E9%97%AE%E9%93%BE%E6%8E%A5)

在使用 CDN 相关功能之前，需要构建 `CdnManager` 对象：

```
mac := auth.New(accessKey, secretKey)
cdnManager := cdn.NewCdnManager(mac)
```

<span id="fusion-refresh-urls" />

## 文件刷新 [#文件刷新]

```
//刷新链接，单次请求链接不可以超过100个，如果超过，请分批发送请求
urlsToRefresh := []string{
    "http://if-pbl.qiniudn.com/qiniu.png",
    "http://if-pbl.qiniudn.com/github.png",
}

ret, err := cdnManager.RefreshUrls(urlsToRefresh)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(ret.Code)
fmt.Println(ret.RequestID)
```

<span id="fusion-refresh-dirs" />

## 目录刷新 [#目录刷新]

```
// 刷新目录，刷新目录需要联系七牛技术支持开通权限
// 单次请求链接不可以超过10个，如果超过，请分批发送请求
dirsToRefresh := []string{
    "http://if-pbl.qiniudn.com/images/",
    "http://if-pbl.qiniudn.com/static/",
}

ret, err := cdnManager.RefreshDirs(dirsToRefresh)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(ret.Code)
fmt.Println(ret.RequestID)
fmt.Println(ret.Error)
```

<span id="fusion-prefetch" />

## 文件预取 [#文件预取]

```
// 预取链接，单次请求链接不可以超过100个，如果超过，请分批发送请求
urlsToPrefetch := []string{
    "http://if-pbl.qiniudn.com/qiniu.png",
    "http://if-pbl.qiniudn.com/github.png",
}

ret, err := cdnManager.PrefetchUrls(urlsToPrefetch)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(ret.Code)
fmt.Println(ret.RequestID)
```

<span id="fusion-cdn_flux" />

## 获取域名流量 [#获取域名流量]

```
domains := []string{
    "if-pbl.qiniudn.com",
    "qdisk.qiniudn.com",
}
startDate := "2017-07-30"
endDate := "2017-07-31"
granularity := "day"

data, err := cdnManager.GetFluxData(startDate, endDate, granularity, domains)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Printf("%v\n", data)
```

<span id="fusion-cdn_bandwidth" />

## 获取域名带宽 [#获取域名带宽