每个 /v1/* 接口都是一次普通的 HTTPS 调用:不需要 SDK,不需要 OAuth 握手,也不需要封装库——三步就能拿到数据。
1. 创建 API key
登录 SkillTweet 后进入 Account 页面创建 key,然后充值:新账号自带一小笔免费额度,余额永久有效,调用失败不会计费。
同一页面还能实时看到余额、token 用量和花费,前几次调用花了多少一目了然。
2. 发送请求
curl 'https://api.skilltweet.com/v1/tweets/search?q=AI&count=5' \
-H 'X-API-KEY: $AGENTTWEET_API_KEY'q 支持 X 搜索语法——from:某账号、lang:zh、min_faves:100、-filter:replies——count 取值 1 到 100。如果你更习惯标准鉴权头,所有接口也接受 Authorization: Bearer $AGENTTWEET_API_KEY。
3. 读懂响应
数据类接口都返回同一种结构:data 放数据,meta 放分页和 token 计费信息。
{
"data": [
{ "id": "…", "text": "…", "author": "…" }
],
"meta": {
"count": 5,
"cursor": "g2AAAA…",
"provider": "twittrapi",
"cached": false,
"tokens_raw": 18422,
"tokens_flat": 5814,
"tokens_saved": 12608,
"tokens_saved_pct": 78.4,
"tokens_billed": 5814,
"cost_usd": 0.00058,
"balance_usd": 0.4994,
"request_id": "…"
}
}真正需要关注的几个字段:
meta.tokens_billed是这次调用实际消耗的 token;调用失败完全不计费。meta.tokens_saved_pct是扁平 JSON 相对上游原始返回省下的 token 比例,不用自己算。meta.balance_usd是扣费后的剩余余额,agent 可以据此在余额耗尽前停下。meta.cursor是分页游标,原样带回cursor参数即可请求下一页。
同样的数字还会出现在 X-Tokens-Used、X-Tokens-Remaining、X-Tokens-Saved-Percent 响应头里,流水线读自己的花费不用多发一次请求。
接下来看什么
- Token 计费与充值档位:一页起步量和 30 天滚动充值如何决定单价。
- 监控与 webhook:新推文直接推送到你的 URL,无需轮询。
- API 文档:每个接口的参数与响应示例。