# 创建卡片实体
基于卡片 JSON 代码，创建卡片实体。用于后续通过卡片实体 ID（card_id）发送卡片、更新卡片等。
## 使用限制
- 本接口仅支持[卡片 JSON 2.0 结构](https://open.larksuite.com/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-structure)。
- 调用该接口时，不支持将卡片设置为独享卡片模式。即不支持将卡片 JSON 数据中的 `update_multi` 属性设置为 `false`。
- 卡片实体的有效期为 14 天。即创建卡片实体超出 14 天后，你将无法调用相关接口操作卡片。
## 请求
基本 |
---|---
HTTP URL | https://open.larksuite.com/open-apis/cardkit/v1/cards
HTTP Method | POST
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.larksuite.com/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 创建与更新卡片(cardkit:card:write)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.larksuite.com/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
type | string | 是 | 卡片数据的类型。取固定值 `card_json`。
**示例值**："card_json"
**数据校验规则**：
- 长度范围：`1` ～ `50` 字符
data | string | 是 | 卡片 JSON 数据的内容。仅支持[卡片 JSON 2.0 结构](https://open.larksuite.com/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-structure)，即你必须声明 schema 为 2.0。以下示例值未转义，使用时请注意将其转为 JSON 序列化后的字符串。
**示例值**："{\"schema\":\"2.0\",\"header\":{\"title\":{\"content\":\"项目进度更新提醒\",\"tag\":\"plain_text\"}},\"config\":{\"streaming_mode\":true,\"summary\":{\"content\":\"\"},\"streaming_config\":{\"print_frequency_ms\":{\"default\":70,\"android\":70,\"ios\":70,\"pc\":70},\"print_step\":{\"default\":1,\"android\":1,\"ios\":1,\"pc\":1},\"print_strategy\":\"fast\"}},\"body\":{\"elements\":[{\"tag\":\"markdown\",\"content\":\"截至今日，项目完成度已达80%\",\"element_id\":\"markdown_1\"}]}}"
**数据校验规则**：
- 长度范围：`1` ～ `3000000` 字符
### 请求体示例
```json
{
"type": "card_json",
"data": "{\"schema\":\"2.0\",\"header\":{\"title\":{\"content\":\"项目进度更新提醒\",\"tag\":\"plain_text\"}},\"config\":{\"streaming_mode\":true,\"summary\":{\"content\":\"\"},\"streaming_config\":{\"print_frequency_ms\":{\"default\":70,\"android\":70,\"ios\":70,\"pc\":70},\"print_step\":{\"default\":1,\"android\":1,\"ios\":1,\"pc\":1},\"print_strategy\":\"fast\"}},\"body\":{\"elements\":[{\"tag\":\"markdown\",\"content\":\"截至今日，项目完成度已达80%\",\"element_id\":\"markdown_1\"}]}}"
}
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
card_id | string | 创建的卡片实体 ID。后续可通过[发送消息](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/create)接口传入卡片实体 ID 发送卡片。
### 响应体示例
```json
{
"code": 0,
"msg": "success",
"data": {
"card_id": "7355372766134157313"
}
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 10002 | Your request contains an invalid request parameter. | 参数错误。请根据接口返回的错误信息并参考文档检查输入参数。
400 | 200860 | Card content exceeds limit. | 卡片体积超限。建议卡片大小控制在 30KB 以内。
400 | 300301 | Duplicate element_id in card component. | 卡片内部组件 ID （即 element_id）重复。请检查并修改。
400 | 300302 | update_multi property is false | 卡片全局属性 update_multi 设置为了 false。在流式更新模式下，卡片全局属性 update_multi 需设置为 true。
400 | 300303 | Only schema 2.0 is supported | 该接口仅支持 JSON 2.0 结构。详情参考[卡片 JSON 2.0 结构](https://open.larksuite.com/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-structure)。
400 | 200220 | Failed to generate card content | 生成卡片内容失败。请检查卡片 JSON 格式是否有误。
400 | 300305 | The number of card components exceeds 200 | 超出卡片组件限制。卡片 JSON 2.0 结构中，一张卡片最多支持 200 个元素（如 tag 为 plain_text 的文本元素）或组件。请将组件和元素的数量之和控制在 200 个以内。
400 | 300307 | The card DSL is empty | 卡片 JSON 数据为空。请检查并修改。