服务端 API/云文档/电子表格/浮动图片/创建浮动图片
# 创建浮动图片
根据传入的参数创建一张浮动图片。Float_image_token （[上传图片至表格后得到](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/media/upload_all)）和range（只支持一个单元格） 必填。Float_image_id 可选，不填的话会默认生成，长度为10，由 0-9、a-z、A-Z 组合生成。表格内不重复的图片（浮动图片+单元格图片）总数不超过4000。width 和 height 为图片展示的宽高，可选，不填的话会使用图片的真实宽高。offset_x 和 offset_y 为图片左上角距离所在单元格左上角的偏移，可选，默认为 0。
**注意事项**：浮动图片的设置参考：[浮动图片指南](https://open.larksuite.com/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/sheets-v3/spreadsheet-sheet-float_image/float-image-user-guide)
## 请求
基本 |
---|---
HTTP URL | https://open.larksuite.com/open-apis/sheets/v3/spreadsheets/:spreadsheet_token/sheets/:sheet_id/float_images
HTTP Method | POST
支持的应用类型 | Custom App、Store App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论、编辑和管理电子表格(sheets:spreadsheet)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
或
`user_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"
[了解更多：获取与使用access_token](https://open.larksuite.com/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 路径参数
名称 | 类型 | 描述
---|---|---
spreadsheet_token | string | 表格 token
**示例值**："shtcnmBA*****yGehy8"
sheet_id | string | 子表 id
**示例值**："0b**12"
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
float_image_id | string | 否 | 浮动图片 id
**示例值**："ye06SS14ph"
float_image_token | string | 否 | 【更新时不用传，创建需要】浮动图片 token，需要先上传图片到表格获得此 token 之后再进行浮动图片的相关操作
**示例值**："boxbcbQsaSqIXsxxxxx1HCPJFbh"
range | string | 否 | 浮动图片的左上角单元格定位，只支持一个单元格
**示例值**："0b**12!A1:A1"
width | float | 否 | 浮动图片的宽度，大于等于 20px
**示例值**：100
height | float | 否 | 浮动图片的高度，大于等于 20px
**示例值**：100
offset_x | float | 否 | 浮动图片左上角所在位置相对于所在单元格左上角的横向偏移，大于等于0且小于所在单元格的宽度
**示例值**：0
offset_y | float | 否 | 浮动图片左上角所在位置相对于所在单元格左上角的纵向偏移，大于等于0且小于所在单元格的高度
**示例值**：0
### 请求体示例
```json
{
"float_image_id": "ye06SS14ph",
"float_image_token": "boxbcbQsaSqIXsxxxxx1HCPJFbh",
"range": "0b**12!A1:A1",
"width": 100,
"height": 100,
"offset_x": 0,
"offset_y": 0
}
```
```
curl --location --request POST 'https://open.larksuite.com/open-apis/sheets/v3/spreadsheets/shtbchuIXPxjaYxsZzQxBqxxxxx/sheets/ea131a/float_images' \
--header 'Authorization: Bearer t-f148d9ee6b5c07373a2671e795e9e855a6f171f6' \
--header 'Content-Type: application/json' \
--data-raw '{
"float_image_id": "ye06SS14p9",
"float_image_token": "boxbcbQEhbFAe0XJvGzkD165FGb",
"offset_x": 0,
"offset_y": 0,
"range": "ea131a!C3:C3"
}'
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
float_image | float_image | 浮动图片返回值
float_image_id | string | 浮动图片 id
float_image_token | string | 【更新时不用传，创建需要】浮动图片 token，需要先上传图片到表格获得此 token 之后再进行浮动图片的相关操作
range | string | 浮动图片的左上角单元格定位，只支持一个单元格
width | float | 浮动图片的宽度，大于等于 20px
height | float | 浮动图片的高度，大于等于 20px
offset_x | float | 浮动图片左上角所在位置相对于所在单元格左上角的横向偏移，大于等于0且小于所在单元格的宽度
offset_y | float | 浮动图片左上角所在位置相对于所在单元格左上角的纵向偏移，大于等于0且小于所在单元格的高度
### 响应体示例
```json
{
"code": 0,
"msg": "success",
"data": {
"float_image": {
"float_image_id": "ye06SS14ph",
"float_image_token": "boxbcbQsaSqIXsxxxxx1HCPJFbh",
"range": "0b**12!A1:A1",
"width": 100,
"height": 100,
"offset_x": 0,
"offset_y": 0
}
}
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 1310229 | Wrong URL Param | 检查 url 参数
400 | 1310217 | Too Many Request | 检查请求是否发送过于频繁
400 | 1310235 | Retry Later | 稍后重试
500 | 1315201 | Server Error | 服务内部错误，详询客服
400 | 1310214 | SpreadSheet Not Found | 检查表格 token
400 | 1310213 | Permission Fail | 没有文档相应权限
400 | 1310215 | Sheet Id Not Found | 检查 sheet_id
400 | 1310202 | Wrong Range | 区域范围错误
400 | 1310245 | Wrong Float Image Token | 检查 Float Image Token
400 | 1310244 | Exist Float Image Id | 检查 Float Image Id
400 | 1310243 | Wrong Float Image Id | 检查 Float Image Id
400 | 1310211 | Wrong Sheet Id | 检查 sheet_id
400 | 1310247 | Image Excess | 图片总数超出限制
400 | 1310246 | Wrong Float Image Value | 图片宽高或者偏移错误
400 | 1310218 | Locked Cell | 检查操作的是否为保护范围
400 | 1310226 | Excess Limit | 超出限制，参考响应体中的错误提示
400 | 1310242 | In Mix state | Retey Later
500 | 1315203 | Server Error | 服务内部错误，详询客服
400 | 1310249 | Spreadsheet Deleted | 恢复表格后重试