内容管理 API | 翠鸟开发者文档

端点一览

所有内容管理相关端点均挂载在 /v1/resources 路径下，需在请求头中携带有效的 API Key。

方法	路径	描述
GET	`/v1/resources`	列出当前账号下所有内容资源，支持分页与过滤
GET	`/v1/resources/{id}`	获取单条内容资源详情
POST	`/v1/resources`	创建并上传新内容资源
PUT	`/v1/resources/{id}`	更新指定内容资源的元数据或文件
DELETE	`/v1/resources/{id}`	删除指定内容资源（不可逆）
POST	`/v1/resources/{id}/publish`	将草稿状态内容发布上线
POST	`/v1/resources/{id}/archive`	将内容归档（停止追踪，保留数据）

所有请求需在 Header 中携带 Authorization: Bearer <YOUR_API_KEY>，并设置 Content-Type: application/json。

上传内容示例

通过 POST /v1/resources 创建一条新内容资源。对于文件类内容（PDF、视频），需使用 multipart/form-data 格式上传。

请求示例（JSON元数据）

# 创建一篇文章类内容
curl -X POST https://api.cuiniao.com/v1/resources \
  -H "Authorization: Bearer ck_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "2024年B2B内容营销趋势报告",
    "type": "article",
    "description": "深度解析B2B内容营销最新趋势与实践案例",
    "tags": ["B2B", "内容营销", "趋势报告"],
    "cta_id": "cta_abc123",
    "track_visitors": true
  }'

响应示例

{
  "id": "res_7fK2mPqLxNz",
  "title": "2024年B2B内容营销趋势报告",
  "type": "article",
  "status": "draft",
  "url": "https://c.cuiniao.com/r/7fK2mPqLxNz",
  "created_at": "2024-03-15T08:30:00Z",
  "updated_at": "2024-03-15T08:30:00Z",
  "track_visitors": true,
  "cta_id": "cta_abc123"
}

上传 PDF 文件

# 上传 PDF 文件类内容
curl -X POST https://api.cuiniao.com/v1/resources \
  -H "Authorization: Bearer ck_live_xxxxxxxxxxxx" \
  -F "file=@/path/to/report.pdf" \
  -F "title=产品白皮书2024" \
  -F "type=pdf" \
  -F "track_visitors=true"

内容状态说明

每条内容资源都有一个生命周期状态，决定其对外可见性与追踪行为。

状态值	说明	访客可访问	追踪启用
draft	草稿，内容尚未发布	否（仅预览链接可访问）	否
published	已发布，正常对外展示	是	是
archived	已归档，停止追踪但数据保留	否（原链接返回404）	否

使用 POST /v1/resources/{id}/publish 将草稿发布；使用 POST /v1/resources/{id}/archive 归档已发布内容。

错误码

API 使用标准 HTTP 状态码表示请求结果，错误响应体包含 code 和 message 字段。

HTTP 状态	错误码	描述
400	`invalid_params`	请求参数格式错误或缺少必填字段
401	`unauthorized`	API Key 无效或已过期
403	`forbidden`	当前 Key 无权限操作该资源
404	`not_found`	指定的内容资源不存在
413	`file_too_large`	上传文件超出大小限制（免费版 50MB，付费版 500MB）
429	`rate_limited`	请求频率超限，请稍后重试
500	`server_error`	服务器内部错误，请联系支持团队

# 错误响应示例
{
  "error": {
    "code": "not_found",
    "message": "Resource with id 'res_xxx' does not exist.",
    "request_id": "req_9mKp2xLqRt"
  }
}