> ## 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.
# 配置你自己的 X API Key
> 分步指南：将你自己的 X（Twitter）API 凭证连接到 Ayrshare
自 2026 年 3 月 31 日起，X 更改了第三方平台访问其 API 的方式。因此，每个通过 Ayrshare 向 X 发布内容的 Ayrshare 账号都必须注册自己的 X 开发者应用，并在每一次请求中使用其 API Key 和 API Secret。
这是 X 强制推行的、影响所有第三方工具的平台级变更。
**BYO（自带）密钥按平台（账号级别）配置一次，而非按每个客户或子资料配置。** 你在自己的 X 账号下创建**一个 X 开发者应用**，然后同一组 **API Key + API Secret** 会应用到你 Ayrshare 账号下所有关联 X 的**每一个**子资料 / 最终用户。如果你使用的是 Business 或 Enterprise 套餐、拥有数百个子资料，你**不需要**为每个子资料重复此配置。你只需为 X 平台配置一次，然后在每次请求中传入同样的两个 header 即可。
我们对配置流程进行了简化，尽可能降低复杂度，完成整个过程大约不超过 10 分钟。请按下方的分步指南操作，如需帮助，我们的团队随时协助。
## 第 1 步：创建你的 X 开发者账号
前往 [console.x.com](https://console.x.com) 并使用你的 X 账号登录。如需帮助，请参见 [X 的入门指南](https://docs.x.com/x-api/getting-started/getting-access)。
完成开发者引导流程，并接受 Developer Agreement 与相关政策。
你现在已经进入了 X Developer Console。
## 第 2 步：创建一个应用
你**每个 Ayrshare 账号只需创建一个 X 开发者应用**。同一个应用及其 API Key + API Secret 会在你的 Ayrshare 账号下之后关联的每个子资料 / 最终用户之间复用。你不需要为每个客户单独创建新应用。
在 Developer Console 中进入 **Apps**。
在 App 面板中，点击 **Create App**（详情见 [X 的 App 配置文档](https://docs.x.com/fundamentals/developer-apps)）。输入一个应用名称（通常为你的品牌名）。当用户连接他们的 X 账号时，OAuth 授权页面会显示该名称。
在下拉菜单中选择 **Production**（生产）环境。
X 会生成若干凭证。**忽略这些凭证并关闭该窗口。**
## 第 3 步：配置应用权限
在 "Apps" 下找到新建的应用（如果没有显示，请刷新页面），然后点击该应用查看详情。
在 **User authentication settings** 下点击 **Set up**。
在 **App permissions** 下，选择 **Read and write and Direct message**。这是完整功能支持（包括发帖与私信）所必需的。
在 **Type of App** 下，选择 **Web App, Automated App or Bot**。这是像 Ayrshare 这样的服务端集成的正确选项。
在 **App info** 下：
* **Callback URL：** 同时添加下面两个回调地址：
* `https://profile.ayrshare.com/social-accounts`
* `https://app.ayrshare.com/social-accounts`
* **Website URL：** `https://app.ayrshare.com`
**请勿跳过此步骤。** OAuth 关联流程需要这些回调地址。当你的最终用户授权 X 连接时，X 会将他们重定向回其中一个 URL 以完成关联流程。如果缺少这些地址，OAuth 流程将失败并返回 `403 Callback URL not approved` 错误。
点击 **Save**。你可以忽略 OAuth 2.0 弹窗，因为你只会用到 OAuth 1.0 的两个密钥（API Key 和 API Secret）。
**重要：请在关联账号之前设置好权限。** 你在这里选择的权限决定了你的应用能做什么。如果你在通过 OAuth 关联 X 账号之后再修改权限，就需要重新关联，以便新的 Access Token 继承更新后的权限。
请务必妥善保存以下 2 个密钥：
1. **API Key**（又名 Consumer Key，X 应用的标识符）
2. **API Secret**（又名 Consumer Secret）
你**不需要**手动生成 Access Token。当你通过 OAuth 关联 X 账号时，Ayrshare 会自动处理这部分。
## 第 4 步：购买 X API 额度
X 现在采用基于额度（credit）的 API 计费方式，通过开发者控制台购买。
在 Developer Console 左侧栏点击 **Billing → Credits**。
购买额度（最低 \$5，足够支持数百次 API 调用）。每次 API 调用只需一分钱的几分之一，对大多数用户来说成本极低。
你可以启用 **auto-recharge**（自动充值）以避免服务中断，同时通过设置账单周期内可花费的最高金额来管理你的消费上限。
**没有额度时你的 API 调用会失败。** X 的 API 是按使用量付费的。如果你的额度余额为零，所有 API 请求都会返回 `402 CreditsDepleted` 错误，消息为 "Your enrolled account does not have any credits to fulfill this request."。这包括发帖、读取推文和用户查询。在测试你的集成前请先充值。完整的 X 定价说明请参见 [X API 定价方式](#how-x-api-pricing-works)。
## 第 5 步：更新你的 Ayrshare API 调用
在第 3 步中，你已在你自己的 env、config 或密钥管理器中妥善保存了以下 2 项：
1. **API Key**（又名 Consumer Key，X 应用的标识符）
2. **API Secret**（又名 Consumer Secret）
现在，将你的 X 凭证添加到 Ayrshare API 调用的 header 中。
**你的密钥保持私有。** Ayrshare 不会存储你的 API Key 和 API Secret。
### Header 对照表
| Header | 值 |
| ----------------------------- | ------------------------------- |
| `X-Twitter-OAuth1-Api-Key` | API Key（Consumer Key） |
| `X-Twitter-OAuth1-Api-Secret` | API Key Secret（Consumer Secret） |
**如何判断权限是否配置错误：**
* 如果你的应用权限配置错误，API 请求可能返回 `403 Forbidden` 错误，消息为："Your client app is not configured with the appropriate OAuth1 app permissions."
如果你看到此错误，请在 X Developer Console 中将应用权限更新为 **Read and write and Direct message**，然后通过 OAuth 重新关联你的 X 账号，以便新的 Access Token 继承更新后的权限。
### 代码示例
```bash cURL theme={"system"}
curl -X POST https://api.ayrshare.com/api/post \
-H "Authorization: Bearer YOUR_AYRSHARE_API_KEY" \
-H "X-Twitter-OAuth1-Api-Key: your_api_key" \
-H "X-Twitter-OAuth1-Api-Secret: your_api_secret" \
-H "Content-Type: application/json" \
-d '{"post": "Hello from my own X App!", "platforms": ["twitter"]}'
```
```javascript Node.js theme={"system"}
const response = await fetch("https://api.ayrshare.com/api/post", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_AYRSHARE_API_KEY",
"Content-Type": "application/json",
"X-Twitter-OAuth1-Api-Key": process.env.X_API_KEY,
"X-Twitter-OAuth1-Api-Secret": process.env.X_API_SECRET,
},
body: JSON.stringify({
post: "Hello from my own X App!",
platforms: ["twitter"],
}),
});
```
```python Python theme={"system"}
import os
import requests
headers = {
"Authorization": "Bearer YOUR_AYRSHARE_API_KEY",
"Content-Type": "application/json",
"X-Twitter-OAuth1-Api-Key": os.environ["X_API_KEY"],
"X-Twitter-OAuth1-Api-Secret": os.environ["X_API_SECRET"],
}
response = requests.post(
"https://api.ayrshare.com/api/post",
headers=headers,
json={"post": "Hello from my own X App!", "platforms": ["twitter"]},
)
```
只要你在所有目标为 X 的请求中都带上 API Key 和 API Secret 这两个 header，你现有的自动化流程和工作流就能继续正常工作。
### 迁移已有资料（Business & Enterprise）
如果你已经有一些子资料通过 Ayrshare 关联了 X，那么在你切换到 BYO 密钥之后，这些资料需要重新关联 X 账号。这是因为已有的 access token 是在 Ayrshare 的 X 应用下签发的，无法与你自己的 consumer keys 一起使用（OAuth 1.0a 签名与签发该 token 的应用绑定）。
将 `twitterApiKey` 和 `twitterApiSecret` 添加到你的 [generateJWT](/apis/profiles/generate-jwt#body-parameters-13) 请求体中。它们会在被嵌入 JWT 前加密，不会暴露给你的最终用户。
```json theme={"system"}
{
"domain": "your-domain",
"profileKey": "...",
"privateKey": "...",
"twitterApiKey": "YOUR_X_CONSUMER_KEY",
"twitterApiSecret": "YOUR_X_CONSUMER_SECRET"
}
```
这是唯一一个把 consumer keys 放到请求体的接口。其他所有 X 请求都使用上文描述的 header。
在生成包含密钥的 JWT 之后，你的用户需要通过资料关联页面重新连接他们的 X 账号。OAuth 授权界面现在会显示你的应用名称而不是 Ayrshare 的名称。
为了简化这个过程，你可以：
* 通过 [Unlink API](/apis/profiles/unlink-social-network#unlink-a-social-network) 以编程方式解除关联，然后让用户重新授权
* 在 generateJWT 中使用 [`logout` 参数](/apis/profiles/generate-jwt#param-logout) 强制重新登录
* 使用 [`allowedSocial`](/apis/profiles/generate-jwt#param-allowed-social) 在迁移流程中让关联页面只显示 X
重新关联后，在每一次 API 调用（发帖、分析、评论等）中都要继续携带 `X-Twitter-OAuth1-Api-Key` 和 `X-Twitter-OAuth1-Api-Secret` header。
一旦某个资料在你的 X 应用下重新完成了关联，该资料之后的所有帖子都会使用你的凭证。你可以在 [X Developer Console](https://console.x.com) 的 Usage 页面进行验证。
### 验证你的配置
通过 Ayrshare API 使用新的 header 发起一次测试调用，确认一切正常。[/analytics/social](/apis/analytics/social) 接口是一个不错的轻量级测试，因为它不会创建任何帖子。
## X API 定价方式
以前，Ayrshare 会代你承担 X API 的使用费用。在 X 当前的模式下，每个 Ayrshare 客户都需自行维护自己的 X 开发者账号，并直接向 X 支付其应用发起的 API 请求费用。（一个 X 开发者账号对应一个 Ayrshare 账号，而不是每个最终用户一个。所有子资料共享同一个 X 开发者账号和额度余额。）
X 的定价采用按使用量付费模式：你在 X Developer Console 中购买额度，API 请求发起时会从中扣除。无需签署合同或订阅。
常见操作的费用较低。例如：
| 操作 | 大致成本 |
| ------------ | -------------------------- |
| 创建帖子（纯文本） | 约 \$0.01/条 |
| 创建带媒体的帖子 | 约 \$0.02/条（媒体上传和发帖是两个独立请求） |
| 读取帖子 | 约 \$0.005/次 |
| 用户查询 | 约 \$0.01/次 |
| 发送私信 | 约 \$0.01/条 |
| 读取私信事件 | 约 \$0.01/事件 |
| 用户互动（关注、点赞等） | 约 \$0.015/次 |
以此估算，如果你每月发帖约 100 次，你在 X 上的直接成本大约是 \$1；如果都带媒体，则大约每月 \$2。
X 的按使用量付费定价目前处于试点阶段。费率可能随时调整，也可能引入新的费用项目。请以 Developer Console 中的最新定价为准。参见 [X 的定价信息详解](https://docs.x.com/x-api/fundamentals/pricing)。
我们知道这引入了此前没有的一项成本，我们希望在这方面保持透明。同时，这种模式也带来了在之前共享密钥方案下无法实现的多项优势。
## 使用自己的 X API Key 的好处
使用你自己的 X API 凭证比之前的共享密钥模式提供了更多的控制与可靠性。这包括：
* **品牌化的 OAuth 体验：** 用户在授权访问 X 时会看到你的应用名称与品牌。
* **独立的速率限制：** 你的 API 使用受你自己的 X 开发者账号限额约束，与其他 Ayrshare 用户彼此独立。你可以在 [X Developer Console](https://console.x.com) 中监控用量，并参阅 [X API 速率限制文档](https://developer.x.com/en/docs/x-api/rate-limits)。
* **凭证掌控：** 你的 API Key 与 API Secret 保存在你自己的 X 开发者账号中。Ayrshare 不会存储你的私密密钥。
* **可移植性：** 由于用户是通过你的 X App 进行认证，整个集成始终处于你的完全掌控之下。
* **用量可见性：** 你的 X Developer Dashboard 会展示 API 请求、速率限制与额度使用情况。
X 是首个采用此模式的平台，但会有更多平台转向"自带 API Key"的方式。我们正将这一能力扩展到整个 Ayrshare，让开发者在所有社交平台上都能享有同样的控制与独立性。
## 安全性
* Ayrshare 不会存储你的 API Key 与 API Secret。
* 关于通用的安全最佳实践，请参见 [X 的认证安全指南](https://docs.x.com/resources/fundamentals/authentication)。
## 常见问题
**不需要。** 你只需在自己的 X 账号下**创建一个** X 开发者应用，同一组 **API Key + API Secret** 会在你 Ayrshare 账号下之后关联的每个子资料 / 最终用户之间复用。
* X 开发者应用只需创建**一次**。
* 每次 Ayrshare API 调用都传入同样的两个 header（`X-Twitter-OAuth1-Api-Key` 和 `X-Twitter-OAuth1-Api-Secret`），无论该调用针对哪个子资料。
* 你的最终用户仍需各自完成 OAuth 关联流程来授权他们自己的 X 账号，但他们**不需要**自己的 X 开发者应用或 API Key。他们通过你的应用进行连接。
* 所有子资料共享同一个 X 开发者账号、同一个速率限制以及同一个额度余额。
唯一一次按资料处理密钥的场景是在迁移过程中于 [generateJWT](/apis/profiles/generate-jwt) 的请求体中传入密钥，但仍然是你的同一对密钥，只是让关联页面能够让最终用户在你的应用下重新完成授权。
是的。自 2026 年 3 月 31 日起，所有通过 Ayrshare 进行的 X 操作都需要你自己的 X API 凭证。如果你还没有配置 X 开发者账号，请按上述步骤操作。
通过 Ayrshare 向 X 发帖需要你自己的 X API 凭证。缺少有效 BYO 凭证的请求将被拒绝。向其他平台（Instagram、LinkedIn、Facebook、TikTok 等）发帖不受影响。
X 按每次 API 调用收费。创建一条帖子约 \$0.01，读取一条帖子约 \$0.005。举例来说，每月发布 100 条帖子大约花费 \$1。完整详情请参见 [X 的定价页面](https://docs.x.com/x-api/fundamentals/pricing)。
不会。你的 Ayrshare 订阅价格保持不变。唯一新增的成本是由 X 通过你的开发者账号直接结算的 X API 使用费。
不会。Ayrshare 不会存储你的 API Key 和 API Secret。关于通用的安全最佳实践，请参见 [X 的认证安全指南](https://docs.x.com/resources/fundamentals/authentication)。
可以。你可以使用你现有的 X App，只要它启用了 "Read and write" 权限（若使用私信功能还需 Direct Messages 权限）。
你需要从 X Developer Console 的 Keys and tokens 部分获取 API Key（Consumer Key）和 API Secret（Consumer Secret）。通过 OAuth 关联你的 X 账号，然后在你的 Ayrshare API 请求中包含这两个 header。
如果你在初次配置之后修改过应用权限，请重新关联 X 账号，以便 Access Token 继承更新后的权限。
你需要 API Key（Consumer Key）和 API Secret（Consumer Secret）。上方 [Header 对照表](#header-reference) 说明了每一项对应的具体 Ayrshare header。你可以忽略 Client ID、Client Secret、Bearer Token、Access Token 和 Access Token Secret。
它们是用于不同认证方式的完全不同的凭证：
* **API Key**（也叫 "Consumer Key"）用于 OAuth 1.0a。API Key（Consumer Key）+ API Secret 就是 Ayrshare 所使用的凭证。它支持全部 X 功能，token 永不过期，也无需 refresh 逻辑。
* **Client ID** 用于 OAuth 2.0。Ayrshare 不需要这个。OAuth 2.0 的 token 在短时间后就会过期，还需要管理 refresh token。
对于 Ayrshare，你只需要 API Key 和 API Secret 即可。你可以忽略 Client ID、Client Secret 和 Bearer Token。
OAuth 2.0 的 access token 每 2 小时就会过期，而 X 的 refresh token 是一次性的（每次刷新都会作废旧 token）。这使得在无状态的 BYO 模式下（尤其是对排期帖子）无法实现支持。OAuth 1.0a 的 token 永不过期，支持所有 X 功能，且无需任何 token 管理。
需要。如果你的用户是在你配置 BYO 密钥之前通过 Ayrshare 关联 X 的，那么他们需要重新连接。原有的 access token 是在 Ayrshare 的 X 应用下签发的，无法与你的 consumer keys 一起使用。分步流程请参见上文的 [迁移已有资料](#migrating-existing-profiles-business--enterprise)。
不会。该变更只影响向 X 发帖。Ayrshare 中所有其他平台的集成都会照常运行。
不再支持通过 RSS 自动发帖到 X。RSS 订阅源按计划自动运行，但自带 API Key 的模式要求每次 API 请求都携带凭证。因此，RSS 订阅源在发送帖子时无法完成认证。
如果你之前使用 RSS 向 X 发帖，我们建议切换到 [排期帖子](/apis/post/overview#schedule-posts)，或者使用带上你凭证的直接 API 调用。向其他所有平台的 RSS 自动发帖不受影响。
这表示你的 X 开发者账号没有可用的 API 额度。前往 [console.x.com](https://console.x.com) → **Billing → Credits** 并购买额度。即使 \$5 也足够支持数百次 API 调用。加载额度后重试你的请求。
你的 Access Token 没有正确的权限。这通常意味着以下两种情况之一：
1. **你的应用权限被设为了 "Read" 而不是 "Read and write"。** 在 Developer Console 中打开该应用的 Settings，将其更改为 **Read and write and Direct message**。
2. **你在关联 X 账号之后修改了权限。** Access Token 会保留创建时的权限。请通过 OAuth 重新关联 X 账号，让新的 token 继承更新后的权限。
我们的支持团队乐意提供帮助。如果你在配置过程中有任何问题或遇到障碍，请通过 [support@ayrshare.com](mailto:support@ayrshare.com) 联系我们，我们会协助你完成整个流程。
## 故障排查
请确保你同时发送了两个必需的 header：
* `X-Twitter-OAuth1-Api-Key`
* `X-Twitter-OAuth1-Api-Secret`
如果你看到"配对不匹配"的错误（例如 "You provided Api-Key but not Api-Secret"），说明其中一个缺失。两者始终都必须提供。
错误消息会告诉你具体缺少的是哪一个 header。
如果你在尝试关联 X 账号时看到此错误，请确认你已在 X 开发者应用的设置中（Authentication settings > Callback URI / Redirect URL）添加了必需的回调地址：
* `https://profile.ayrshare.com/social-accounts`
* `https://app.ayrshare.com/social-accounts`
请参见上文的 [回调地址配置步骤](#step-3-configure-app-permissions)。
你的 X 开发者账号没有加载任何 API 额度。前往 [console.x.com](https://console.x.com) → **Billing → Credits** 并购买额度。即使 \$5 也足够支持数百次 API 调用。
你的 Access Token 没有正确的权限。这通常意味着：
1. **你的应用权限被设为了 "Read" 而不是 "Read and write"。** 在 Developer Console 中打开该应用的 Settings，将其更改为 **Read and write and Direct message**。
2. **你在关联 X 账号之后修改了权限。** Access Token 会保留创建时的权限。请通过 OAuth 重新关联 X 账号，让新的 token 继承更新后的权限。
## 需要帮助？
如果你在配置 X API Key 时有任何问题或遇到障碍，我们的工程团队乐意协助。你可以随时通过 [support@ayrshare.com](mailto:support@ayrshare.com) 联系我们。