> ## 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.

# Post API 概述

> 安排帖子、自动话题标签、自动发布日程等

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

<PlansAvailable plans={["premium"]} maxPackRequired={false} />

post 端点允许你将帖子发布到以下社交网络：Bluesky、Facebook、Google Business Profile、Instagram、LinkedIn、Pinterest、Reddit、Snapchat、Telegram、TikTok、X/Twitter 和 YouTube。
有许多选项可以自定义你的帖子，例如安排帖子、添加自动话题标签、自动发布日程等等。
这通常被代理机构使用，用于多个相关方需要在帖子发布前审批。

使用 [/post POST 端点](/apis/post/post) 开始发布帖子。

## 审批工作流

如果你的发布工作流需要在发送帖子之前进行审批，请将 `requiresApproval` 字段设置为 `true`。
这相当于暂停帖子，直到 `approved` 参数被设置为 `true`。

### 审批工作流示例

帖子将处于 "awaiting approval" 状态，直到通过 [/post PATCH 端点](/apis/post/update-post) 将 `approved` 参数设置为 `true`。

<Steps>
  <Step title="使用参数发布">
    使用 [/post 端点](/apis/post/post) 发布你的帖子，将 `requiresApproval` 字段
    设为 `true`。你还可以包含标准参数，例如 `scheduleDate`。
  </Step>

  <Step title="状态为等待审批">
    该帖子将处于 "awaiting approval" 状态，并将暂停到获得审批为止。
  </Step>

  <Step title="批准帖子">
    使用 [/post PATCH 操作](/apis/post/update-post) 更新帖子，将 `approved`
    字段设为 `true`。帖子现在将在预定时间发送。
  </Step>

  <Step title="使用备注">
    可选：在帖子上设置 `notes` 供参考，例如谁需要审批该帖子。
  </Step>
</Steps>

```json Publish the Post with Approval theme={"system"}
{
  "requiresApproval": true,
  "notes": "need approval by John Smith" // optional
}
```

<Warning>
  如果包含 `scheduleDate` 且日期在过去，帖子将在审批后立即
  发布。
</Warning>

### 审批工作流视频

请参见下方视频，了解审批工作流的示例。

<div class="video-container">
  <iframe width="380" height="200" src="https://www.youtube.com/embed/DtmTGgqQ-Mo" title="Social Approval Workflow API" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" />
</div>

## 自动话题标签

向你的帖子添加最相关的话题标签。

`autoHashtag` 是一个对象或布尔值（见下方），包含以下参数：

<ul class="custom-bullets">
  <li>`max`：（可选）要添加的话题标签数量的整数，范围 1-10。默认 2。</li>

  <li>
    `position`：（可选）字符串 "auto" 或 "end"。"auto" 将话题标签添加到帖子内或
    末尾。"end" 仅将话题标签添加到末尾。
  </li>
</ul>

*需要付费套餐。*

```json theme={"system"}
{
  "hashtags": {
    "max": 3, // optional: Integer range 1-10
    "position": "auto" // optional: String "auto" or "end"
  }
}
```

如果你不想发送以上任何选项，可以传递布尔值 `true` 代替对象。

```json theme={"system"}
{
  "autoHashtag": true
}
```

## 自动重发

按固定间隔多次自动重发你的内容，创建保持新鲜且对受众可见的常青内容。
需要付费套餐。

参数：

* `repeat`：（必填）重发内容的次数。必须在 1 到 10 之间。
* `days`：（必填）每次重发之间的天数。必须至少 2 天。
* `startDate`：（可选）何时开始重发日程，采用 ISO-8601 UTC 格式。如未指定，首次帖子将立即发布。你应该使用 `startDate` 参数代替顶层的 `scheduleDate` 参数。

```json Auto Repost theme={"system"}
{
  "repeat": 2, // min 2, max 10
  "days": 5, // min 2
  "startDate": "2021-07-08T12:30:00Z"
}
```

响应将包含所有未来的已安排重发以及每个重发的 `autoRepostId`。

```json Auto Repost Response theme={"system"}
{
  "status": "scheduled",
  "scheduleDate": "2025-06-13T12:30:00.000Z",
  "id": "eIT96IYEodNuzU4oMmwG",
  "refId": "9abf1426d6ce9122ef11c72bd",
  "autoRepostId": "F5wdoaOAAGtDQVciExSxL",
  "post": "The most important things are the hardest to say - Stephen King"
}
```

创建自动重发时，系统会分配一个 `autoRepostId` 来跟踪这一系列帖子。

你可以使用带 `autoRepostId` 的 [History 调用](/apis/history/get-history) 获取某个帖子的所有自动重发。

如果需要删除某个重发，可以使用带帖子 ID 的 [DELETE 调用](/apis/post/delete-post)。

<Tip>
  重要：使用自动重发时，请确保你遵守每个社交网络的发布频率指南，以避免账户被限制。

  注意：`autoRepost` 功能不能与 `scheduleDate` 一起使用。如果同时包含两个参数，`scheduleDate` 将优先，`autoRepost` 将被忽略。请改用 `startDate` 参数。
</Tip>

## 首个评论

在帖子发布后自动添加带媒体的首个评论。对于 TikTok，评论会延迟到视频处理完成后（参见 [首个评论处理时间](#first-comment-processing-time)）。
在自己的社交媒体帖子上发布首个评论有助于启动互动并为后续讨论定下基调。

```json theme={"system"}
{
  "firstComment": {
    "comment": "My first comment", // required
    "mediaUrls": ["https://..."] // Facebook, LinkedIn, and X/Twitter only
  }
}
```

## 首个评论处理时间

对于大多数社交网络，API 响应会延迟，因为我们的系统必须 (1) 等待原始帖子完全发布，然后 (2) 将评论添加到已发布的帖子。这个顺序处理过程会增加大约 20 秒的延迟。

**TikTok 的处理方式不同。** TikTok 异步处理视频，因此在 TikTok 的 `post.publish.publicly_available` webhook 解析真实视频 ID 之前，帖子 `id` 是 `"pending"`（参见 [TikTok 处理](/apis/post/social-networks/tiktok#tiktok-processing)）。因此 `/post` 响应会立即返回 TikTok 首个评论，`status: "pending"`，一旦 TikTok 完成处理并且 [`tikTokPublished` Scheduled Action webhook](/apis/webhooks/actions#scheduled-action) 触发，评论就会自动发布。TikTok 不保证处理时间，因此没有固定的延迟。

**TikTok 重要说明**：为了让首个评论在 TikTok 上正常工作，帖子的 `visibility` 参数必须设为 `public`。非公开视频永远不会收到 `publicly_available` webhook，因此无法发布其首个评论；在这种情况下 Ayrshare 返回评论错误而不是将其保留为待处理状态。

## 幂等帖子

[幂等性](https://en.wikipedia.org/wiki/Idempotence) 是一项可选功能，可以确保请求只被执行一次，即使意外发送了多次。
使用 API 发布内容时，你可以在请求正文中包含可选的 `idempotencyKey` 参数以唯一标识该操作。这可以让你安全地重试发布请求，而没有创建重复帖子的风险。

要使用幂等性，请将 `idempotencyKey` 参数添加到 `/post` POST 请求的 JSON 正文中：

```json Idempotency Key theme={"system"}
{
  "idempotencyKey": "Unique Key"
}
```

`idempotencyKey` 的值应该是每个用户配置文件的唯一字符串。如果对给定用户配置文件使用相同的 `idempotencyKey` 发出请求，无论帖子的状态如何（success、error、pending 或 deleted），都会返回错误，表明发现了重复的键。

<Warning>
  API 必须先接受并处理 POST 请求以存储幂等键并检查
  重复。但是，如果同时发送多个具有相同 `idempotencyKey` 的 POST 请求，
  或者安排在同一发布时间，API 可能不会检测到重复的键。
  这是因为 API 并行处理这些并发或同时安排的请求，
  在它有机会从任何单个请求注册幂等键之前。因此，
  在同时提交或执行已安排帖子的这些场景中，不能保证会
  捕获到重复的幂等键。
</Warning>

使用幂等性有助于防止在重试失败请求或处理网络问题时意外创建重复帖子。但仍建议你在应用程序中实现适当的错误处理和重试机制，以优雅地处理潜在的失败。

## 图片和视频要求

发布图片和视频对每个网络都有不同的要求，但不用担心。我们的系统会在发送前验证你的帖子，如果有任何问题，你会收到错误响应。请参见以下链接了解图片和视频指南的详细信息。

<Card title="图片和视频指南" icon="link" href="/media-guidelines" horizontal />

### 有效 URL

请确保你的媒体 URL 有效并直接访问媒体。
第一步测试是在浏览器中尝试该 URL。
如果图片无法在浏览器中加载或下载，很可能会失败。
例如，打开 DropBox Web 应用的 DropBox URL 将无法工作。

<Tip>
  如果你有 [Google Drive 分享
  URL](https://www.ayrshare.com/how-to-get-direct-download-urls-from-google-drive/) 或 [Dropbox
  分享 URL](https://www.ayrshare.com/blog/how-to-get-direct-download-urls-from-dropbox/)，你只需
  在发布帖子或评论时在 `mediaUrls` 参数中使用该 URL。Ayrshare 将
  自动将分享 URL 转换为下载链接。
</Tip>

我们通过发出 `HEAD` 请求来验证媒体 URL。
请确保托管提供商没有阻止 `HEAD` 请求，否则帖子将失败并返回 403 错误。

例如，这是对媒体 URL 的 `HEAD` 请求：

```javascript Fetch HEAD Request theme={"system"}
const run = async () => {
  const url = "https://img.ayrshare.com/012/gb.jpg";
  return await fetch(url, {
    method: "HEAD"
  })
    .then((res) => {
      if (res.ok) {
        return console.log("Success:", res.status, res.statusText);
      } else {
        return console.error("Error:", res.status, res.statusText, res);
      }
    })
    .catch((error) => {
      return console.error("Error Catch:", error);
    });
};

run();
```

#### 自动化媒体保护

Ayrshare 包含内置的媒体保护，可以在发布过程中检测并解决某些媒体传送问题。当帖子成功但检测到并解决了内容问题时，`postIds[]` 中每个受影响的条目都包含一个可选的 `contentIssues` 对象，以便你识别并修复根本问题：

```json theme={"system"}
{
    "postIds": [
        {
            "status": "success",
            "platform": "instagram",
            "id": "17878176260289172",
            "postUrl": "https://www.instagram.com/p/CP1dI9Hp_WO/",
            "contentIssues": {
                "originMediaHostFailed": true,
                "details": ["Media URL could not be retrieved by the social network. Successfully posted using Ayrshare automated media protection."]
            }
        }
    ]
}
```

如果你在响应中看到 `originMediaHostFailed`，请检查你的媒体托管配置。有关常见原因和解决方案，请参见 [Meta 媒体爬虫被阻止](/help-center/technical-support/meta_media_crawler_blocked)。

#### 空格和特殊字符

我们建议在你的媒体 URL 中避免以下内容：

<ul class="custom-bullets">
  <li>URL 中的空格。</li>
  <li>URL 中的 URL 编码空格。</li>
  <li>URL 中的特殊字符，即使它们经过 URL 编码，例如重音符号 é。</li>
</ul>

例如：

```bash theme={"system"}
https://img.ayrshare.com/012/test .webp
```

此 URL 因为空格 `test .webp` 而失败。我们也不建议使用 URL 编码的空格，例如 `%20`，在 URL 中 - 这在某些社交网络上也可能引起问题。

以及此 Unsplash 图片：

```bash theme={"system"}
https://unsplash.com/photos/a-house-in-the-middle-of-a-field-with-trees-in-the-background-znbmh2-cIj0
```

此 Unsplash 图片失败，因为它不是直接访问图片，而是显示 Web 应用程序。

#### 清理文件名和 URL

你可以使用正则表达式 `/[^a-z0-9\/\.]/gi` 清理文件名。

```javascript theme={"system"}
const sanitizeFileName = (url) => url.replace(/[^a-z0-9\/\.]/gi, "_");
sanitizeFileName("tést .webp"); // t_st_.webp
```

或清理 URL

```javascript theme={"system"}
const sanitizeUrl = (url) => {
  const [protocol, rest] = url.split("://");
  const [domain, ...path] = rest.split("/");
  const sanitizedPath = path.join("/").replace(/[^a-z0-9\/\.]/gi, "_");
  return `${protocol}://${domain}/${sanitizedPath}`;
};

// Output: https://img.ayrshare.com/012/t_st_.webp
sanitizeUrl("https://img.ayrshare.com/012/tést .webp");
```

### 附加信息

<Info>
  <ul class="custom-bullets">
    <li>
      如果你自行托管，请确保 URL 可以外部访问且不需要
      特殊权限。
    </li>

    <li>
      请参见下方关于如何处理未知扩展名的视频（通常是签名 URL，如 AWS S3）。
    </li>

    <li>
      如果你使用签名 URL（如 S3），我们建议将 URL 过期时间至少设为
      7 天。这样我们的团队可以协助解答你在发布帖子时的任何问题。
    </li>

    <li>
      使用我们的 [验证媒体工具](/apis/media/verify-media-url) 测试媒体 URL 是否存在。
    </li>
  </ul>
</Info>

### 下载速度

请确保你的媒体托管具有快速连接，特别是下载速度。你可以在 [pingdom](https://tools.pingdom.com/) 测试你的媒体托管性能。我们建议至少 *B 评级*。

### 视频扩展名

如果你的 URL 不是以已知的视频扩展名（如 `mp4`）结尾，你可以在帖子中使用 `isVideo: true` 字段指定 `mediaUrl` 是视频。Ayrshare 将尝试确定文件类型，例如 `MOV`。但是，我们建议显式地以已知扩展名（如 `mp4`）结束你的视频文件，因为这在社交网络上的成功率更高。

### 仅图片或视频

一些社交网络支持发送不带帖子文本的媒体。如果你不希望包含帖子文本，请发送空字符串：`post: ""`

以下社交网络支持无帖子/空白文本：Facebook、Instagram、LinkedIn、Threads、TikTok 和 X/Twitter。

### 测试图片和视频

考虑使用 [生成随机文本和随机图片或视频](/quickstart#sending-test-posts-with-a-random-quote-image-or-video) 来加速你的测试。不要再为每个测试帖子思考不同的内容了！

## 换行

<Info>
  如果你想在帖子中使用换行（新行），请使用不可见换行符 `\u2063\n`。例如，`This is a new\u2063\nline.`

  我们也建议在 Postman 中尝试，看看新行换行符在你选择的语言中如何翻译。例如，PHP 通常仅使用 `\n`

  一些社交网络目前不支持帖子文本中的换行。
</Info>

## 多平台帖子和媒体

此功能允许你在单个 API 调用中为不同的社交网络自定义帖子内容和媒体。你可以通过对 `post` 和 `mediaUrls` 字段使用对象来为每个平台指定唯一的文本和/或图片。

1. 对 `post` 和/或 `mediaUrls` 字段使用对象结构。
2. 使用平台名称作为键指定特定于平台的内容。
3. 包含 `default` 键，用于未明确指定的平台上使用的内容。

```json theme={"system"}
{
  "post": {
    "instagram": "Great IG pic!",
    "facebook": "Great FB pic!",
    "default": "Great default pic!"
  },
  "platforms": ["instagram", "facebook", "linkedin"],
  "mediaUrls": {
    "instagram": "https://img.ayrshare.com/012/gb.jpg",
    "linkedin": "https://img.ayrshare.com/012/gb.jpg",
    "default": "https://img.ayrshare.com/012/gb.jpg"
  }
}
```

在上面的示例中：

<ul class="custom-bullets">
  <li>Instagram 将使用其特定的文本和图片 URL。</li>
  <li>Facebook 将使用其特定的文本和默认图片 URL。</li>
  <li>LinkedIn 将使用默认文本和其特定的图片 URL。</li>
</ul>

<Info>
  如果你需要向不同平台发布多张图片，请为每个平台
  创建单独的帖子，而不是使用此多平台结构。
</Info>

## Profile Keys

通过提供用户的 Profile Keys 作为正文参数以及响应中的附加数据，代表用户发布。*需要 Business 或 Enterprise 计划。*

<Card title="Profiles" icon="link" href="/apis/profiles/overview" horizontal />

## 富文本帖子

你可以添加富文本，例如 "𝓗𝓮𝓵𝓵𝓸, how about a little 𝗯𝗼𝗹𝗱 𝘁𝗲𝘅𝘁 and 𝘪𝘵𝘢𝘭𝘪𝘤𝘴 𝘵𝘦𝘹𝘵 and an x₂?"。你可以在诸如 Twitter、Facebook、LinkedIn、Telegram 和 Instagram 等网络上使用富文本。
如果发布到 Reddit，请使用 [Reddit 风格的 Markdown 格式](https://www.reddit.com/wiki/markdown#wiki_new_reddit-flavored_markdown)。

HTML 元素用于指定富文本的类型，并被转换为 unicode。例如：

```json theme={"system"}
{
    "post": "<var>Hello</var>, how about a little <b>bold text</b> and <i>italics text</i> and an x<sub>2</sub>?"
    "platforms": ["twitter"]
}
```

### HTML 元素

| HTML                                          | 示例                                |
| --------------------------------------------- | --------------------------------- |
| \<b>Nice One!\</b>                            | **Nice One!**                     |
| \<strong>Hello, world!\</strong>              | **Hello, world!**                 |
| \<em>World\</em>                              | *World*                           |
| normal \<i>italics \<b>bold italics\</b>\</i> | normal *italics **bold italics*** |
| \`\<b>Hello\</b>, world!\`                    | `Hello, world!`                   |
| \`\<b>Hello\</b>, world!\`                    | **`Hello`**`, world!`             |
| \<samp>123\</samp>                            | 𝟷𝟸𝟹                            |
| \<var>Hello\</var>                            | 𝓗𝓮𝓵𝓵𝓸                        |
| x\<sub>2\</sub>                               | x₂                                |
| x\<sup>2\</sup>                               | x²                                |

### CSS 代码

| 代码       | 示例                         | 结果                       |
| -------- | -------------------------- | ------------------------ |
| \u00B0   | It's 25\u00B0C today!      | It's 25°C today!         |
| \u2063\n | This is a new\u2063\nline. | This is a new<br />line. |

## 安排帖子

### 创建已安排帖子

你可以通过指定 `scheduleDate` 参数（采用 Zulu/UTC 时间）来安排未来的帖子。Zulu 时间也称为协调世界时（UTC），是世界时间标准。

例如，使用格式 `YYYY-MM-DDThh:mm:ssZ` 并按 `2026-07-08T12:30:00Z` 发送。
更多示例请参见 [utctime](https://www.utctime.net/)。

```json {5} theme={"system"}
{
  "post": "Hello, world!",
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["facebook", "instagram"],
  "scheduleDate": "2023-07-08T12:30:00Z"
}
```

有关如何将本地时间转换为 Zulu/UTC 时间，请参见 [https://www.utctime.net/](https://www.utctime.net/)。

如果安排的日期时间在过去，帖子将立即发送。

<Info>
  如果已安排的帖子包含 `mediaUrl`，则媒体必须在安排的
  发布时间可用。例如，如果帖子安排在 2026 年 3 月 5 日发布，
  媒体必须在 2026 年 3 月 5 日可用。
</Info>

<Tip>
  已安排帖子与立即帖子的错误处理

  立即帖子与已安排帖子之间在验证错误处理上有重要区别：

  * 立即帖子
    * 立即发布（无 scheduleDate）时，如果一个平台未通过验证检查，其他平台将继续处理。例如，如果帖子超过 Twitter 的字符限制但对 Facebook 和 Instagram 有效，帖子将在 Twitter 上失败，但仍将发布到 Facebook 和 Instagram。

  * 已安排帖子
    * 为未来发布安排帖子时（带 scheduleDate），所有平台必须通过初始验证检查后才会安排帖子。如果任何平台未通过这些预验证检查，整个安排操作将被拒绝，并立即返回错误。
    * 但是，一些平台特定的错误可能直到实际发布时间才被检测到。在这些情况下，已安排的帖子将尝试发布到所有平台，各个平台的失败将在最终结果中报告，而不会影响其他平台。
</Tip>

### 检查已安排帖子的状态

你可以通过几种方式检查已安排帖子的状态：

<ul class="custom-bullets">
  <li>
    设置 [Webhook 已安排操作](/apis/webhooks/actions#scheduled-action) 以自动
    接收已安排帖子的状态。此功能可用于 Business 计划，是
    推荐的方法。
  </li>

  <li>
    使用带帖子 ID 的 [GET 调用](/apis/post/get-post) 获取已安排帖子的状态。
  </li>

  <li>
    在 Ayrshare 仪表板中检查状态。首先切换到帖子作为
    发布下的用户配置文件，然后转到 "Posts" 页面并使用 Ayrshare 帖子 ID 进行搜索。
  </li>
</ul>

### 暂停已安排帖子

你可以暂停尚未发布的已安排帖子。
暂停已安排的帖子会阻止其在被取消暂停之前发布。

使用 [PATCH 调用](/apis/post/update-post) 暂停或取消暂停已安排的帖子。
请注意，如果取消暂停的帖子的 `scheduleDate` 在过去，帖子将立即发布。考虑在取消暂停前更新 `scheduleDate`。

## 缩短链接

帖子中的链接可以使用 Ayrshare [链接缩短器](/apis/links/overview) 缩短。你可以在发送帖子时通过 `shortenLinks` 参数打开自动链接缩短。[需要 Max Pack](/additional/maxpack)。

```json {4} theme={"system"}
{
  "post": "Hello, world with a link https://www.ayrshare.com",
  "platforms": ["linkedin"],
  "shortenLinks": true
}
```

## Unsplash 图片

`unsplash` 正文参数可用以下字段：

<ul class="custom-bullets">
  <li>随机图片：`random` 返回随机 Unsplash 图片。</li>

  <li>
    基于搜索的图片：值为字符串搜索词；例如 `money` 将根据 money 选择一个随机图片
    。
  </li>

  <li>
    图片 ID：值为 ID 数组；例如 \["HubtZZb2fCM"] 图片
    [https://unsplash.com/photos/HubtZZb2fCM](https://unsplash.com/photos/HubtZZb2fCM)
  </li>
</ul>

```json {4,5,6} theme={"system"}
{
  "post": "Hello, world!",
  "platforms": ["instagram"],
  "unsplash": "random",
  "unsplash": "search term", // unsplash: "money"
  "unsplash": ["unsplash image ID"] // unsplash: ["HubtZZb2fCM"]
}
```

<Info>
  如果复制 Unsplash URL 以在 `mediaUrls` 中发布，请务必复制图片地址而
  不仅仅是 URL。有关更多信息，请参见此
  [示例](/help-center/technical-support/get_an_unsplash_image_url)。
</Info>