> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pinterest API

> 使用 Pinterest API 發布內容的選項

## 發布圖片 Pin 到 Pinterest

Pinterest API 要求貼文中必須包含圖片，其他參數則為選填。
更多資訊請參閱 [Pinterest 媒體指南](/media-guidelines/pinterest) 與 [Pinterest 授權](/dashboard/connect-social-accounts/pinterest)。

```json Pinterest Post theme={"system"}
{
  "post": "The best Pinterest API ever!", // Maximum 500 characters or empty string
  "platforms": ["pinterest"],
  "mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"]
}
```

## Pinterest 選項

你可以透過 `pinterestOptions` 參數為貼文設定額外的選項。

```json Pinterest Post theme={"system"}
{
  "post": "The best Pinterest API ever!", // Maximum 500 characters or empty string
  "platforms": ["pinterest"],
  "mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"],
  "pinterestOptions": {
    "altText": ["This is my best pic", "😃 here is the next one"], // maximum 500 characters
    "boardId": "93383204522",
    "carouselOptions": [
      {
        "title": "Image 1",
        "link": "https://www.cnn.com",
        "description": "Super Image 1"
      },
      {
        "title": "Image 2",
        "link": "https://www.google.com",
        "description": "Super Image 2"
      }
    ],
    "link": "https://www.ayrshare.com", // maximum 2048 characters
    "note": "Private note", // maximum 1000 characters
    "thumbNail": "https://images.ayrshare.com/imgs/GhostBusters.jpg",
    "title": "A Pinterest Board for You" // maximum 100 characters
  }
}
```

Pinterest 選項為可選欄位，用來控制貼文的呈現方式。

<ParamField body="altText" type="array of strings">
  圖片與影片的替代文字（alt text），為無障礙功能，可協助螢幕閱讀器讀取內容。最多 500 個字元。

  更多資訊請參閱 [Pinterest 替代文字](/apis/post/social-networks/pinterest#alternative-text)。
</ParamField>

<ParamField body="boardId" type="string">
  透過指定 /user/details 端點回傳的 ID，將貼文發布到使用者另一個 Pinterest Board。

  若未指定，會發布到預設連結的 board。

  更多資訊請參閱 [Pinterest Board ID](/apis/post/social-networks/pinterest#board-id)。
</ParamField>

<ParamField body="carouselOptions" type="array of objects">
  以 Pinterest 輪播 Pin 的形式最多發布 5 張圖片，並可為每張圖片加上選填的標題、連結與描述。

  每個物件可包含：`title`、`link` 與 `description`。

  更多資訊請參閱 [Pinterest 圖片輪播](/apis/post/social-networks/pinterest#pinterest-image-carousel)。
</ParamField>

<ParamField body="link" type="string">
  使用者點擊該 Pin 圖片時會被導向的目的網址。最多 2048 個字元。

  會為你的 Pin 加上一個可點擊的連結。

  更多資訊請參閱 [Pin 連結](/apis/post/social-networks/pinterest#pin-link)。
</ParamField>

<ParamField body="note" type="string">
  在個別 Pin 上加入私密備註，只有你和 board 的協作者能看到。最多 1000 個字元。

  更多資訊請參閱 [Pin 備註](/apis/post/social-networks/pinterest#pin-note)。
</ParamField>

<ParamField body="thumbNail" type="string">
  為影片 Pin 設定縮圖。必須是 PNG 或 JPG 格式，尺寸與影片相同，並小於 10MB。

  影片 Pin 必填。

  更多資訊請參閱 [影片 Pin（縮圖）](/apis/post/social-networks/pinterest#video-pin-thumbnail)。
</ParamField>

<ParamField body="title" type="string">
  要顯示在「Add your title」區塊的 Pin 標題。最多 100 個字元。

  更多資訊請參閱 [Pin 標題](/apis/post/social-networks/pinterest#pin-title)。
</ParamField>

<sup>\*</sup>`post` 欄位中的連結無法點擊，請使用 `link` 欄位為 Pin 加上可點擊的連結。

更多資訊請參閱 [Pinterest 媒體指南](/media-guidelines/pinterest)。

## 替代文字

為 Pinterest 圖片或影片加上替代文字（alt text）。Pinterest 的 alt text 是一項無障礙功能，可提供額外的使用者資訊，並協助螢幕閱讀器讀取內容。

請在 `pinterestOptions` 物件中使用 `altText`。

```json Pinterest Alt Text theme={"system"}
{
  "pinterestOptions": {
    "altText": ["This is my best pic", "😃 here is the next one"]
  }
}
```

Alt text 上限為 500 個字元。

## Board ID

透過指定從 [/user/details](/apis/user/pinterest-board) 端點取得的 ID，將貼文發布到使用者另一個 Pinterest Board。否則會發布到預設連結的 board。

請在 `pinterestOptions` 物件中使用 `boardId`。

```json Pinterest Board ID theme={"system"}
{
  "pinterestOptions": {
    "boardId": "93383204522"
  }
}
```

## 字元限制

更多資訊請參閱 [Pinterest 字元限制](/help-center/technical-support/character_limits#pinterest-character-limits)。

## Pin 連結

使用者點擊你的 Pin 圖片時會被導向的目的網址。這會為你的 Pin 加上一個可點擊的連結。長度上限為 2048 個字元。

請在 `pinterestOptions` 物件中使用 `link`。

```json Pin Link theme={"system"}
{
  "pinterestOptions": {
    "link": "https://www.ayrshare.com"
  }
}
```

## Pin 備註

你可以在 board 上的個別 Pin 加上私密備註，只有你和 board 的協作者能看到。

請在 `pinterestOptions` 物件中使用 `note`。

```json Pin Note theme={"system"}
{
  "pinterestOptions": {
    "note": "Private note for collaborators"
  }
}
```

## Pinterest 圖片輪播

以 Pinterest 輪播 Pin 的形式發布最多五張圖片。當你加入多個媒體 URL 時，系統會自動建立輪播。你也可以加入選填的 carousel 參數（如下所示）。

```json Pinterest Carousel Post theme={"system"}
{
  "post": "Carousel Time",
  "platforms": ["pinterest"],
  "mediaUrls": [
    "https://img.ayrshare.com/random/photo-1.jpg",
    "https://img.ayrshare.com/random/photo-2.jpg"
  ],
  "pinterestOptions": {
    "carouselOptions": [
      // optional
      {
        "title": "Image 1",
        "link": "https://www.cnn.com",
        "description": "Super Image 1"
      },
      {
        "title": "Image 2",
        "link": "https://www.google.com",
        "description": "Super Image 2"
      }
    ]
  }
}
```

選填的 `carouselOptions` 欄位接受一個物件陣列。每個 carousel 物件會對應到相同順序的媒體 URL，例如第一個 carousel 物件對應第一個 `mediaUrl` 字串。

<ul class="custom-bullets">
  <li>`title`：圖片標題。</li>
  <li>`link`：該圖片指向的外部連結。</li>
  <li>`description`：圖片描述。</li>
</ul>

## Pinterest 提及

雖然你可以在 Pinterest 貼文中加入 @handle，但 Pinterest 不會解析貼文文字中的提及。
@handle 將保持為純文字顯示。

## Pin 標題

要顯示的 Pin 標題。會出現在新 Pin 的「Add your title」區塊。最多 100 個字元。

請在 `pinterestOptions` 物件中使用 `title`。

```json Pin Title theme={"system"}
{
  "pinterestOptions": {
    "title": "A Pinterest Board for You"
  }
}
```

## 影片 Pin（縮圖）

可以透過 [/post 端點](/apis/post/post) 的標準 `mediaUrls` 欄位以 Pin 形式發布影片。此外，**必須**同時提供一個有效的圖片縮圖 URL，且 Content-Type 需為 `image/jpeg` 等有效的媒體類型。
需求請參閱 [規範](/media-guidelines/pinterest)。

```json Video Pin with Thumbnail theme={"system"}
{
  "pinterestOptions": {
    // required
    "thumbNail": "https://images.unsplash.com/photo-1513093496871-0a81425386e5?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=MnwxNjQ1ODN8MHwxfHJhbmRvbXx8fHx8fHx8fDE2Mzg0ODAzNDA&ixlib=rb-1.2.1&q=80&w=400"
  }
}
```

更多關於[使用 API 發布 Pin](https://www.ayrshare.com/blog/pinterest-api-integration-on-ayrshare/) 的資訊。

如果你的影片副檔名不是常見的影片格式（例如 mp4），請使用 `isVideo` 參數。詳情請參閱 [/post 端點](/apis/post/post)。