API 接口参考
CreatiVault Open API 完整接口参考，含可复制的 curl 示例。
💡
基础路径：https://{host}/openapi/v1/ — 所有请求使用 POST 方法，JSON Body 传参。
认证方式
所有请求需要 X-API-Key 和 X-User-Identity（邮箱地址）请求头。
HTTP Headers
X-API-Key: your_api_key_here X-User-Identity: user@example.com Content-Type: application/json
接口列表
| 接口 | 方法 | 描述 | 所需权限 |
|---|---|---|---|
| /v1/creators/tiktok/search | POST | 搜索 TikTok 达人 | creators:tiktok:search |
| /v1/creators/youtube/search | POST | 搜索 YouTube 达人 | creators:youtube:search |
| /v1/creators/instagram/search | POST | 搜索 Instagram 达人 | creators:instagram:search |
| /v1/creators/lookalike | POST | 查找相似达人 | - |
| /v1/collection/tasks/submit | POST | 提交链接/用户名采集任务 | collection:submit |
| /v1/collection/tasks/keyword-submit | POST | 提交关键词采集任务 | collection:keyword-submit |
| /v1/collection/tasks/status | POST | 查询任务状态 | collection:status |
| /v1/collection/tasks/data | POST | 获取采集数据（分页） | collection:data |
| /v1/collection/tasks/export | POST | 导出任务数据为文件 | collection:export |
| /v1/files/download-url | POST | 获取文件下载链接 | files:download |
| /v1/webhook/verify | POST | 验证 Webhook 连通性 | 公开（无需认证） |
响应结构
所有接口返回统一的 JSON 结构，包含 success、data、error 和 meta 字段。
Response Structure
{
"success": true,
"data": { ... },
"error": null,
"meta": {
"request_id": "req_abc123",
"page": 1,
"size": 50,
"total": 1200,
"quota_remaining": -1,
"service_level": "S2",
"credits_consumed": 60
}
}搜索达人
使用关键词和筛选条件搜索达人。service_level 参数控制返回哪些字段（S1/S2/S3）。
TikTok
curl — POST /v1/creators/tiktok/search
curl -X POST "https://{host}/openapi/v1/creators/tiktok/search" \
-H "X-API-Key: your_api_key_here" \
-H "X-User-Identity: user@example.com" \
-H "Content-Type: application/json" \
-d '{
"keyword": "beauty",
"country_code": "US",
"followers_cnt_gte": 10000,
"page": 1,
"size": 20,
"sort_field": "followers_cnt",
"sort_order": "desc",
"service_level": "S2",
"lang": "en"
}'YouTube
curl — POST /v1/creators/youtube/search
curl -X POST "https://{host}/openapi/v1/creators/youtube/search" \
-H "X-API-Key: your_api_key_here" \
-H "X-User-Identity: user@example.com" \
-H "Content-Type: application/json" \
-d '{
"country_code": "US",
"followers_cnt_gte": 50000,
"page": 1,
"size": 20,
"sort_order": "desc",
"service_level": "S2",
"lang": "en"
}'curl — POST /v1/creators/instagram/search
curl -X POST "https://{host}/openapi/v1/creators/instagram/search" \
-H "X-API-Key: your_api_key_here" \
-H "X-User-Identity: user@example.com" \
-H "Content-Type: application/json" \
-d '{
"country_code": "US",
"followers_cnt_gte": 10000,
"is_product_kol": true,
"page": 1,
"size": 20,
"service_level": "S2"
}'采集任务
链接采集（LINK_BATCH）
curl — POST /v1/collection/tasks/submit (LINK_BATCH)
curl -X POST "https://{host}/openapi/v1/collection/tasks/submit" \
-H "X-API-Key: your_api_key_here" \
-H "X-User-Identity: user@example.com" \
-H "Content-Type: application/json" \
-d '{
"task_type": "LINK_BATCH",
"platform": "tiktok",
"values": [
"https://www.tiktok.com/@creator1",
"https://www.tiktok.com/@creator2"
],
"task_name": "Q1 Creator Collection",
"webhook_url": "https://your-server.com/webhook/collection"
}'用户名采集（FILE_UPLOAD）
curl — POST /v1/collection/tasks/submit (FILE_UPLOAD)
curl -X POST "https://{host}/openapi/v1/collection/tasks/submit" \
-H "X-API-Key: your_api_key_here" \
-H "X-User-Identity: user@example.com" \
-H "Content-Type: application/json" \
-d '{
"task_type": "FILE_UPLOAD",
"platform": "tiktok",
"values": ["creator1", "creator2", "creator3"],
"task_name": "Username Batch Collection"
}'关键词采集
curl — POST /v1/collection/tasks/keyword-submit
curl -X POST "https://{host}/openapi/v1/collection/tasks/keyword-submit" \
-H "X-API-Key: your_api_key_here" \
-H "X-User-Identity: user@example.com" \
-H "Content-Type: application/json" \
-d '{
"platform": "tiktok",
"keywords": ["beauty tips", "skincare routine"],
"task_name": "Keyword Collection",
"webhook_url": "https://your-server.com/webhook/collection"
}'查询任务状态
curl — POST /v1/collection/tasks/status
curl -X POST "https://{host}/openapi/v1/collection/tasks/status" \
-H "X-API-Key: your_api_key_here" \
-H "X-User-Identity: user@example.com" \
-H "Content-Type: application/json" \
-d '{
"task_id": "task_20260315_abc123"
}'获取采集数据
curl — POST /v1/collection/tasks/data
curl -X POST "https://{host}/openapi/v1/collection/tasks/data" \
-H "X-API-Key: your_api_key_here" \
-H "X-User-Identity: user@example.com" \
-H "Content-Type: application/json" \
-d '{
"task_id": "task_20260315_abc123",
"page": 1,
"size": 20
}'导出数据
curl — POST /v1/collection/tasks/export
curl -X POST "https://{host}/openapi/v1/collection/tasks/export" \
-H "X-API-Key: your_api_key_here" \
-H "X-User-Identity: user@example.com" \
-H "Content-Type: application/json" \
-d '{
"task_id": "task_20260315_abc123",
"format": "xlsx"
}'获取下载链接
curl — POST /v1/files/download-url
curl -X POST "https://{host}/openapi/v1/files/download-url" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"file_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}'相似达人推荐（Lookalike）
基于种子达人查找相似达人。支持跨平台搜索，可通过用户名或主页地址输入。
curl — POST /v1/creators/lookalike
curl -X POST "https://{host}/openapi/v1/creators/lookalike" \
-H "X-API-Key: your_api_key_here" \
-H "X-User-Identity: user@example.com" \
-H "Content-Type: application/json" \
-d '{
"username": "creator_demo",
"platform": "tiktok",
"target_region": "US",
"limit": 10,
"follower_min": 10000,
"lang": "en"
}'Webhook 网络验证
在提交采集任务前验证 webhook 地址的网络连通性。此接口为公开接口，无需认证。
curl — POST /v1/webhook/verify
curl -X POST "https://{host}/openapi/v1/webhook/verify" \
-H "Content-Type: application/json" \
-d '{
"challenge": "test_connectivity_12345"
}'Webhook 回调
采集任务完成时，系统会向你的 webhook_url 发送 POST 回调，使用 HMAC-SHA256 签名验证。
Webhook Payload
{
"event": "collection.completed",
"task_id": "task_20260315_abc123",
"task_type": "LINK_BATCH",
"status": "completed",
"total": 2,
"completed": 2,
"failed": 0,
"timestamp": "2026-03-15T10:45:00Z"
}💡
Webhook 最多重试 3 次（间隔 10 秒、30 秒、90 秒）。你的端点必须使用 HTTPS 并在 5 秒内响应。
