Pickful API 接入指南 | 6.19

---

Pickful 社区朋友们：

为了帮助开发者和创作者更好地集成 Pickful 的发布功能，我们发布了完整的 API 接入指南。

---

快速开始（3 步）

第一步：创建 API Token

访问 https://pickful.ai/api_tokens 创建新 token

• 格式：pkfl_live_<random>（仅显示一次，请妥善保管）
• 权限：选择 posts:write
• 有效期：无限期（可随时 revoke）

第二步：发送请求

curl -X POST https://pickful.ai/api/posts \
  -H "Authorization: Bearer pkfl_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "我的文章",
    "content": "文章内容（支持 **Markdown** 格式）",
    "topic_id": "t5a"
  }'

第三步：处理响应

{
  "id": 12345,
  "slug": "abc12",
  "post_type": "article",
  "url": "https://pickful.ai/p-abc12",
  "created_at": "2026-06-17T10:30:00Z"
}

---

API 参考

端点

POST /api/posts

认证

Authorization: Bearer <api_token>

请求参数

参数	类型	说明
content	string	文章内容（Markdown 格式）。仅有 content 时发布为短贴
title	string	文章标题。有标题时自动发布为文章
summary	string	文章摘要（可选）
topic_id	string	话题 ID（如 t5a）
source	string	来源标记，用于追踪
published_at	string	发布时间（ISO8601）。留空立即发布；指定未来时间则定时
image_url	string	图片 URL（与 image_base64 二选一）
image_base64	string	Base64 编码图片
image_filename	string	图片文件名（可选）
image_content_type	string	图片类型：image/png、image/jpeg、image/webp
x	boolean	是否发布到 X（默认 false）
tweets	array	X 推文内容数组（可选）

响应状态码

状态码	说明
201	创建成功
401	未授权（token 无效或缺失）
403	权限不足（缺少 posts:write scope）
422	验证失败（参数错误）

---

常见用途示例

发布短贴

{
  "content": "这是一条短贴 🚀"
}

发布文章

{
  "title": "深度解析：DeFi 如何运作",
  "content": "# 简介\n\nDeFi 代表...",
  "summary": "一份 DeFi 完整指南",
  "topic_id": "t5a"
}

带图片的文章

从 URL：

{
  "title": "产品发布",
  "content": "我们很高兴地宣布...",
  "image_url": "https://example.com/image.jpg"
}

从 Base64：

{
  "title": "快速更新",
  "content": "查看我们的新功能！",
  "image_base64": "iVBORw0KGgoAAAAN...",
  "image_content_type": "image/png"
}

定时发布

{
  "title": "定时发布的文章",
  "content": "这篇文章会在指定时间发布",
  "published_at": "2026-06-18T09:00:00Z"
}

发布到 X

自动生成推文：

{
  "title": "我的最新文章",
  "content": "完整文章内容...",
  "x": true
}

自定义推文（形成线程）：

{
  "title": "3 条推文线程",
  "content": "主文章内容...",
  "x": true,
  "tweets": [
    "第一条推文内容",
    "第二条推文内容",
    "第三条推文内容"
  ]
}

---

图片要求

支持格式

• PNG (image/png)
• JPEG (image/jpeg)
• WebP (image/webp)

大小限制

• 最大 5MB

用法

• 文章：图片作为封面，显示在文章顶部
• 短贴：图片嵌入内容中

---

Markdown 支持

# 一级标题
## 二级标题

**粗体** 和 *斜体*

- 列表项
- 列表项

1. 编号列表
2. 编号列表


[链接](https://example.com)

`代码` 和 ```代码块```

---

错误处理

错误	原因	解决方案
401 Unauthorized	token 无效或缺失	检查 token 格式和有效期
403 Forbidden	缺少 posts:write 权限	重新创建具有正确权限的 token
422 - Content can’t be blank	内容为空	提供 content 或 title
422 - invalid_published_at	时间格式错误	使用 ISO8601 格式；必须是未来时间
invalid_image	图片格式或大小错误	检查格式（PNG/JPEG/WebP）和大小（<5MB）

---

代码示例

Python

import requests
import os

API_TOKEN = os.environ.get("PICKFUL_API_TOKEN")
API_URL = "https://pickful.ai/api/posts"

def publish_article(title, content, topic_id="t5a"):
    headers = {
        "Authorization": f"Bearer {API_TOKEN}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "title": title,
        "content": content,
        "topic_id": topic_id
    }
    
    response = requests.post(API_URL, json=payload, headers=headers)
    
    if response.status_code == 201:
        return response.json()
    else:
        print(f"错误 {response.status_code}: {response.text}")
        return None

# 使用
result = publish_article("我的第一篇文章", "文章内容...")
if result:
    print(f"已发布: {result['url']}")

JavaScript

const fetch = require('node-fetch');

const API_TOKEN = process.env.PICKFUL_API_TOKEN;
const API_URL = 'https://pickful.ai/api/posts';

async function publishArticle(title, content, topicId = 't5a') {
  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        title,
        content,
        topic_id: topicId
      })
    });

    if (response.ok) {
      const data = await response.json();
      return data;
    } else {
      console.error(`错误 ${response.status}`);
      return null;
    }
  } catch (error) {
    console.error('请求失败:', error);
    return null;
  }
}

publishArticle('我的文章', '内容...').then(result => {
  if (result) console.log(`已发布: ${result.url}`);
});

---

安全最佳实践

1. 保管好 token
   • 不要在代码中硬编码 token
   • 使用环境变量：PICKFUL_API_TOKEN
   • 泄露时立即 revoke 并创建新的
2. 验证请求
   • 总是使用 HTTPS
   • 检查响应状态码
3. 错误处理
   • 实现重试逻辑（指数退避）
   • 记录错误日志

---

与 Claude CLI 配合

结合你现有的 Claude 订阅，自动化整个工作流：

# 用 Claude 生成摘要，然后调用 API
claude -p "为以下文章生成 50 字摘要：[你的文章]"

---

我们已为你准备好了一切。立即创建 token，开始集成吧！任何问题都欢迎在社区讨论。

Pickful Team
2026-06-17