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