pinterest-api

Pinterest API 技能

全面协助开发 Pinterest API v5，包括 OAuth 身份验证、Pin/Board 管理、分析和 API 集成模式。

何时使用此技能

在以下情况下应触发此技能：

• 实现 Pinterest OAuth 2.0 身份验证流程
• 通过 API 创建、更新或管理 Pin 和 Board
• 将 Pinterest 分析和指标集成到应用程序中
• 构建 Pinterest API 客户端或 SDK
• 处理 Pinterest 用户账户数据
• 调试 Pinterest API 请求或响应
• 在 Web/移动应用中实现 Pinterest 分享功能
• 设置 Pinterest 企业账户集成
• 使用 Pinterest 广告账户 API

核心概念

Pinterest API v5 概览

• 基础 URL：https://api.pinterest.com/v5/
• 身份验证：使用访问令牌的 OAuth 2.0
• 速率限制：基于令牌的速率限制（因端点而异）
• 响应格式：JSON
• 必需的标头：Authorization: Bearer {access_token}

核心资源

• Pins：保存到 Pinterest 的独立内容（图片、视频）
• Boards：按主题或话题整理 Pin 的集合
• Sections：Board 中用于进一步整理的子分区
• 用户账户：Pinterest 用户个人资料和账户信息
• 广告账户：用于广告功能的企业账户

访问级别

• 公开访问：对公开数据的只读访问
• 用户授权：完全访问用户的 Pin、Board 和账户
• 企业访问：额外的分析和广告账户管理权限（需要相应角色）

快速参考

OAuth 2.0 身份验证流程

步骤 1：生成授权 URL

// Redirect user to Pinterest authorization page
const authUrl = `https://www.pinterest.com/oauth/?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&response_type=code&scope=boards:read,pins:read,user_accounts:read`;

window.location.href = authUrl;

步骤 2：用授权码换取访问令牌

# After user authorizes, exchange authorization code for access token
curl -X POST https://api.pinterest.com/v5/oauth/token \
  --header "Authorization: Basic {BASE64_ENCODED_CLIENT_CREDENTIALS}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code={AUTHORIZATION_CODE}" \
  --data-urlencode "redirect_uri={REDIRECT_URI}"

客户端凭据的 Base64 编码：

# Encode client_id:client_secret
echo -n "your_client_id:your_client_secret" | base64

响应：

{
  "access_token": "pina_ABC123...",
  "token_type": "bearer",
  "expires_in": 2592000,
  "refresh_token": "DEF456...",
  "scope": "boards:read,pins:read,user_accounts:read"
}

Pin 管理

创建 Pin

curl -X POST https://api.pinterest.com/v5/pins \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "link": "https://example.com/my-article",
    "title": "My Amazing Pin Title",
    "description": "Detailed description of the pin content",
    "board_id": "123456789",
    "media_source": {
      "source_type": "image_url",
      "url": "https://example.com/image.jpg"
    }
  }'

获取 Pin 详情

curl -X GET https://api.pinterest.com/v5/pins/{PIN_ID} \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

响应：

{
  "id": "987654321",
  "created_at": "2025-01-15T10:30:00",
  "link": "https://example.com/my-article",
  "title": "My Amazing Pin Title",
  "description": "Detailed description of the pin content",
  "board_id": "123456789",
  "media": {
    "media_type": "image",
    "images": {
      "150x150": { "url": "...", "width": 150, "height": 150 },
      "400x300": { "url": "...", "width": 400, "height": 300 },
      "originals": { "url": "...", "width": 1200, "height": 800 }
    }
  }
}

更新 Pin

curl -X PATCH https://api.pinterest.com/v5/pins/{PIN_ID} \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Pin Title",
    "description": "Updated description",
    "link": "https://example.com/updated-link"
  }'

删除 Pin

curl -X DELETE https://api.pinterest.com/v5/pins/{PIN_ID} \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Board 管理

创建 Board

curl -X POST https://api.pinterest.com/v5/boards \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Board",
    "description": "A collection of my favorite ideas",
    "privacy": "PUBLIC"
  }'

隐私选项： PUBLIC、PROTECTED、SECRET

列出用户的 Board

curl -X GET https://api.pinterest.com/v5/boards \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

获取 Board 中的 Pin

curl -X GET https://api.pinterest.com/v5/boards/{BOARD_ID}/pins \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

用户账户

获取当前用户账户

curl -X GET https://api.pinterest.com/v5/user_account \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

响应：

{
  "account_type": "BUSINESS",
  "id": "123456789",
  "username": "myusername",
  "website_url": "https://example.com",
  "profile_image": "https://i.pinimg.com/...",
  "follower_count": 1500,
  "following_count": 320,
  "board_count": 25,
  "pin_count": 450
}

分析

获取 Pin 分析数据

curl -X GET "https://api.pinterest.com/v5/pins/{PIN_ID}/analytics?start_date=2025-01-01&end_date=2025-01-31&metric_types=IMPRESSION,SAVE,PIN_CLICK" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

可用指标：

• IMPRESSION - Pin 的展示次数
• SAVE - Pin 的保存次数
• PIN_CLICK - 点击 Pin 目标位置的次数
• OUTBOUND_CLICK - 点击外部网站的次数
• VIDEO_START - 视频开始播放的次数

响应：

{
  "all": {
    "daily_metrics": [
      {
        "date": "2025-01-01",
        "data_status": "READY",
        "metrics": {
          "IMPRESSION": 1250,
          "SAVE": 45,
          "PIN_CLICK": 89
        }
      }
    ]
  }
}

错误处理

常见错误响应

{
  "code": 3,
  "message": "Requested pin not found"
}

常见错误代码：

• 1 - 请求参数无效
• 2 - 超出速率限制
• 3 - 未找到资源
• 4 - 权限不足
• 8 - 访问令牌无效

Python 错误处理示例

import requests

def create_pin(access_token, board_id, title, image_url):
    url = "https://api.pinterest.com/v5/pins"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    data = {
        "board_id": board_id,
        "title": title,
        "media_source": {
            "source_type": "image_url",
            "url": image_url
        }
    }

    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        error_data = e.response.json()
        print(f"Error {error_data.get('code')}: {error_data.get('message')}")
        return None
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {str(e)}")
        return None

JavaScript/Node.js 集成

// Pinterest API Client Example
class PinterestClient {
  constructor(accessToken) {
    this.accessToken = accessToken;
    this.baseUrl = 'https://api.pinterest.com/v5';
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseUrl}${endpoint}`;
    const headers = {
      'Authorization': `Bearer ${this.accessToken}`,
      'Content-Type': 'application/json',
      ...options.headers
    };

    const response = await fetch(url, {
      ...options,
      headers
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Pinterest API Error: ${error.message}`);
    }

    return response.json();
  }

  async createPin(boardId, title, imageUrl, description = '', link = '') {
    return this.request('/pins', {
      method: 'POST',
      body: JSON.stringify({
        board_id: boardId,
        title: title,
        description: description,
        link: link,
        media_source: {
          source_type: 'image_url',
          url: imageUrl
        }
      })
    });
  }

  async getUserBoards() {
    return this.request('/boards');
  }

  async getPinAnalytics(pinId, startDate, endDate) {
    const params = new URLSearchParams({
      start_date: startDate,
      end_date: endDate,
      metric_types: 'IMPRESSION,SAVE,PIN_CLICK'
    });
    return this.request(`/pins/${pinId}/analytics?${params}`);
  }
}

// Usage
const client = new PinterestClient('your_access_token');
const pin = await client.createPin('board_id', 'Pin Title', 'https://example.com/image.jpg');

参考文件

此技能在 references/ 中包含完整文档：

• api.md - 从官方文档提取的完整 Pinterest API v5 端点参考

需要了解特定端点的详细信息时，请使用 view 查看参考文件。

使用此技能

初学者指南

1. 首先了解 OAuth 2.0 身份验证流程（见上方“快速参考”）
2. 从 Pinterest Developer Portal 获取 API 凭据
3. 在应用程序中实现之前，先使用 curl 命令测试身份验证
4. 将提供的 Python/JavaScript 示例作为起始模板

API 集成指南

1. 实现 OAuth 流程以获取访问令牌
2. 安全存储刷新令牌，以便长期访问
3. 使用 Pin/Board 管理示例执行 CRUD 操作
4. 针对速率限制和 API 错误实现恰当的错误处理

用于分析和业务功能

1. 确保你拥有适当的业务账户访问权限
2. 使用分析端点跟踪 Pin 的表现
3. 汇总不同日期范围内的指标以生成报告
4. 实现缓存，避免不必要的 API 调用

最佳实践

• 令牌安全：切勿在客户端代码或版本控制中暴露访问令牌
• 速率限制：针对速率限制错误实现指数退避
• 分页：对大型结果集使用基于游标的分页
• Webhooks：考虑使用 Webhooks 实现实时更新，而不是轮询
• 权限范围：仅申请应用所需的最少 OAuth 权限范围

常见模式

分页

# Initial request
curl -X GET "https://api.pinterest.com/v5/boards/{BOARD_ID}/pins?page_size=25" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

# Follow-up with bookmark from response
curl -X GET "https://api.pinterest.com/v5/boards/{BOARD_ID}/pins?page_size=25&bookmark={BOOKMARK}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

批量操作

# Create multiple pins efficiently
def bulk_create_pins(access_token, board_id, pin_data_list):
    results = []
    for pin_data in pin_data_list:
        result = create_pin(
            access_token,
            board_id,
            pin_data['title'],
            pin_data['image_url']
        )
        results.append(result)
        time.sleep(0.5)  # Respect rate limits
    return results

资源

官方文档

• Pinterest API v5 文档：https://developers.pinterest.com/docs/api/v5/
• API 快速入门：https://github.com/pinterest/api-quickstart
• OAuth 文档：https://developers.pinterest.com/docs/getting-started/authentication/

OAuth 权限范围

你通常需要以下权限范围：

• boards:read - 读取画板数据
• boards:write - 创建或更新画板
• pins:read - 读取 Pin 数据
• pins:write - 创建或更新 Pin
• user_accounts:read - 读取用户账户数据
• ads:read - 读取广告账户分析数据（业务账户）

速率限制

• Pinterest 对每位用户实施速率限制
• 典型限制：每位用户每小时 1000 次请求
• 响应中的速率限制标头：
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

注意事项

• Pinterest API v5 是当前版本（截至 2025 年）
• 所有端点都需要通过 OAuth 2.0 进行身份验证
• 访问令牌会在 30 天后过期
• 使用刷新令牌获取新的访问令牌
• 业务账户可以使用其他分析功能
• 与图片 Pin 相比，视频 Pin 需要特殊处理
• 某些功能需要经过 Pinterest 的应用审核

故障排除

“访问令牌无效”

• 确认令牌尚未过期（有效期为 30 天）
• 使用刷新令牌获取新的访问令牌
• 检查 Authorization 标头格式：Bearer {token}

“权限不足”

• 确认 OAuth 权限范围包含所需权限
• 业务功能需要经过验证的业务账户
• 某些操作需要拥有相应画板或 Pin 的所有权

“超出速率限制”

• 实现指数退避
• 尽可能缓存响应
• 使用 Webhooks 代替轮询
• 检查 X-RateLimit-Reset 标头，确认重试时间

“媒体上传失败”

• 确认图片 URL 可公开访问
• 检查图片是否符合尺寸要求（最大 10MB）
• 确保图片格式受支持（JPG、PNG、GIF）
• 对于视频，请使用专用的视频端点

更新

此技能根据 Pinterest 的官方 API 文档生成。要获取最新的 API 变更：

1. 访问 https://developers.pinterest.com/docs/api/v5/
2. 查看更新日志，了解 API 更新
3. 查看弃用通知
4. 如果添加了新功能，请更新 OAuth 权限范围