API

完整的 API v1 文档，包含认证、发布和排程功能

概述

xAIcreator API v1 提供了多平台认证、内容发布、排程发布和账户管理的 RESTful 接口。所有端点使用 API Key 进行安全认证。

基础 URL: https://xaicreator.com/api/v1

认证

所有 API 请求都需要通过 xai-key 请求头传递 API Key：

curl "https://xaicreator.com/api/v1/twitter/drafts" \
  -H "xai-key: your_api_key_here"

获取 API Key

1. 邮箱登录

POST /api/v1/auth/login

邮箱登录仅适用于已有用户，不支持新用户注册。

curl -X POST "https://xaicreator.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "yourpassword"
  }'

成功响应：

{
  "success": true,
  "user": {
    "uuid": "user-uuid",
    "email": "[email protected]"
  },
  "apiKey": {
    "key": "sk-xxxxx...",
    "name": "Default API Key",
    "createdAt": "2026-01-15T10:00:00Z",
    "lastUsed": null
  },
  "warning": "请妥善保存您的 API Key。这是唯一一次显示完整密钥。"
}

错误响应（用户不存在）：

{
  "success": false,
  "error": "USER_NOT_FOUND",
  "message": "此邮箱未注册。请先在网页上注册。"
}

2. Google OAuth

步骤 1：获取 OAuth URL

POST /api/v1/auth/oauth/google/url

curl -X POST "https://xaicreator.com/api/v1/auth/oauth/google/url" \
  -H "Content-Type: application/json" \
  -d '{"redirectUri": "http://localhost:3000/oauth-callback"}'

响应：

{
  "success": true,
  "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...",
  "state": "server-generated-state"
}

步骤 2：OAuth 回调

POST /api/v1/auth/oauth/google/callback

curl -X POST "https://xaicreator.com/api/v1/auth/oauth/google/callback" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "authorization-code-from-google",
    "state": "state-from-step-1"
  }'

新用户注册成功响应：

{
  "success": true,
  "user": {
    "uuid": "new-user-uuid",
    "email": "[email protected]",
    "provider": "google",
    "isNewUser": true
  },
  "apiKey": {
    "key": "sk-new-user-key...",
    "name": "Default API Key",
    "createdAt": "2026-01-15T10:00:00Z",
    "lastUsed": null
  },
  "message": "账号创建成功。请妥善保存您的 API Key。"
}

3. Twitter OAuth

步骤 1：获取 OAuth URL

POST /api/v1/auth/oauth/twitter/url

curl -X POST "https://xaicreator.com/api/v1/auth/oauth/twitter/url" \
  -H "Content-Type: application/json" \
  -d '{"redirectUri": "http://localhost:3000/oauth-callback?provider=twitter"}'

响应：

{
  "success": true,
  "authUrl": "https://x.com/i/oauth2/authorize?client_id=...",
  "state": "base64url-encoded-state"
}

步骤 2：OAuth 回调

POST /api/v1/auth/oauth/twitter/callback

curl -X POST "https://xaicreator.com/api/v1/auth/oauth/twitter/callback" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "authorization-code-from-twitter",
    "state": "state-from-step-1"
  }'

重要提示：完整的 API Key 仅在注册/登录成功时显示一次，请务必立即保存。

API Key 管理

获取 API Keys 列表

GET /api/v1/auth/api-keys

curl "https://xaicreator.com/api/v1/auth/api-keys" \
  -H "xai-key: sk-your-api-key"

响应：

{
  "success": true,
  "apiKeys": [
    {
      "id": "key-uuid-1",
      "key": "sk-xxxx...abcd",
      "name": "Default API Key",
      "status": "created",
      "lastUsed": "2026-01-15T10:00:00Z",
      "createdAt": "2026-01-14T08:00:00Z"
    }
  ]
}

创建新 API Key

POST /api/v1/auth/api-keys

curl -X POST "https://xaicreator.com/api/v1/auth/api-keys" \
  -H "Content-Type: application/json" \
  -H "xai-key: sk-your-api-key" \
  -d '{"name": "New API Key"}'

响应：

{
  "success": true,
  "apiKey": {
    "id": "key-uuid-3",
    "key": "sk-new-full-key...",
    "keyPreview": "sk-new...key",
    "name": "New API Key",
    "createdAt": "2026-01-15T10:00:00Z"
  },
  "warning": "请立即保存您的 API Key。这是唯一一次显示完整密钥。"
}

删除 API Key

DELETE /api/v1/auth/api-keys/:keyId

curl -X DELETE "https://xaicreator.com/api/v1/auth/api-keys/key-uuid-3" \
  -H "xai-key: sk-your-api-key"

Twitter OAuth 2.0

发起 Twitter OAuth

POST /api/v1/twitter/auth

curl -X POST "https://xaicreator.com/api/v1/twitter/auth" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "socialSetId": "your-social-set-id",
    "mode": "add_to_existing"
  }'

参数

参数	类型	必填	描述
`socialSetId`	`string`	`否`	要绑定的 Social Set ID
`mode`	`string`	`否`	`"create_new"` 或 `"add_to_existing"`（默认）
`followOnX`	`boolean`	`否`	授权后是否关注 X 账号

响应：

{
  "authUrl": "https://x.com/i/oauth2/authorize?...",
  "sessionId": "session_uuid_here"
}

Twitter OAuth 回调

GET /api/v1/twitter/callback

用户授权完成后，Twitter 会使用 code 和 state 参数重定向到您的回调 URL。

curl "https://xaicreator.com/api/v1/twitter/callback?code=xxx&state=xxx"

响应：

{
  "success": true,
  "accountUuid": "account_uuid",
  "socialSetId": "social_set_id"
}

草稿管理

获取草稿列表

GET /api/v1/twitter/drafts

curl "https://xaicreator.com/api/v1/twitter/drafts?socialSetId=xxx" \
  -H "xai-key: your_api_key"

响应：

{
  "drafts": [
    {
      "id": "draft_uuid",
      "title": "我的草稿",
      "status": "draft",
      "tweets": [...],
      "createdAt": "2026-01-14T07:21:26.000Z"
    }
  ]
}

创建草稿

POST /api/v1/twitter/drafts

curl -X POST "https://xaicreator.com/api/v1/twitter/drafts" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "title": "我的草稿",
    "tweets": [{"content": "<p>来自 API 的问候！</p>"}],
    "socialSetId": "social-set-id",
    "scheduledFor": "2026-01-15T10:00:00Z"
  }'

参数

参数	类型	必填	描述
`title`	`string`	`是`	草稿标题
`tweets`	`array`	`是`	推文对象数组，包含 `content` 字段（支持 HTML）
`socialSetId`	`string`	`否`	关联的 Social Set ID
`status`	`string`	`否`	草稿状态（默认：`"draft"`）
`scheduledFor`	`string`	`否`	定时发布的 ISO 8601 日期时间
`selectedAccountIds`	`array`	`否`	要发布到的账号 ID 列表
`templateId`	`string`	`否`	模板 ID（如果从模板创建）

响应：

{
  "draft": {
    "id": "draft_uuid",
    "title": "我的草稿",
    "status": "draft",
    "scheduledFor": null,
    "socialSetId": "social-set-id",
    "selectedAccountIds": [],
    "tweets": [
      {
        "id": "tweet_uuid",
        "content": "<p>来自 API 的问候！</p>",
        "plainText": "来自 API 的问候！",
        "media": [],
        "characterCount": 9,
        "isValid": true,
        "position": 0
      }
    ],
    "createdAt": "2026-01-14T07:21:26.000Z",
    "updatedAt": "2026-01-14T07:21:26.000Z"
  }
}

发布

发布到 Twitter

POST /api/v1/twitter/publish

curl -X POST "https://xaicreator.com/api/v1/twitter/publish" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "draftId": "draft_uuid",
    "accountIds": ["account_id"]
  }'

参数

参数	类型	必填	描述
`draftId`	`string`	`是`	要发布的草稿 ID
`accountIds`	`array`	`否`	特定账号 ID（如省略则使用草稿默认值）
`jobId`	`string`	`否`	用于跟踪的自定义作业 ID
`community`	`object`	`否`	社区元数据（`{id, name, description}`）

引用推文

POST /api/v1/twitter/quote

curl -X POST "https://xaicreator.com/api/v1/twitter/quote" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "content": "很有见地！",
    "quoteTweetId": "quoted_tweet_id",
    "accountId": "your_account_id"
  }'

响应：

{
  "success": true,
  "message": "引用发布成功",
  "tweetId": "new_tweet_id",
  "url": "https://x.com/user/status/new_tweet_id"
}

多平台发布

POST /api/v1/publish/multi-platform

同时发布到多个平台（Twitter、Bluesky、Mastodon、Threads、LinkedIn）。

curl -X POST "https://xaicreator.com/api/v1/publish/multi-platform" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "draftId": "draft_uuid",
    "targetAccounts": [
      {
        "accountId": "twitter_account_id",
        "platform": "twitter",
        "communityId": "community_id"
      },
      {
        "accountId": "bluesky_account_id",
        "platform": "bluesky"
      },
      {
        "accountId": "mastodon_account_id",
        "platform": "mastodon"
      },
      {
        "accountId": "threads_account_id",
        "platform": "threads"
      },
      {
        "accountId": "linkedin_account_id",
        "platform": "linkedin"
      }
    ]
  }'

参数

参数	类型	必填	描述
`draftId`	`string`	`是`	草稿 UUID
`targetAccounts`	`array`	`是`	目标账号列表
`targetAccounts[].accountId`	`string`	`是`	账号 UUID
`targetAccounts[].platform`	`string`	`是`	平台：`twitter`、`bluesky`、`mastodon`、`threads`、`linkedin`
`targetAccounts[].communityId`	`string`	`否`	社区 ID（仅 Twitter）

响应：

{
  "success": true,
  "results": [
    {
      "accountId": "account_uuid",
      "platform": "twitter",
      "success": true,
      "data": { "tweetId": "...", "url": "..." }
    },
    {
      "accountId": "account_uuid",
      "platform": "bluesky",
      "success": true,
      "data": { "uri": "at://...", "cid": "..." }
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

费用：每个平台 10 积分

平台专属发布

Bluesky

POST /api/v1/bluesky/publish

curl -X POST "https://xaicreator.com/api/v1/bluesky/publish" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "accountUuid": "account_uuid",
    "type": "single",
    "text": "你好 Bluesky！",
    "langs": ["zh"]
  }'

参数

参数	类型	必填	描述
`accountUuid`	`string`	`是`	账号 UUID
`type`	`string`	`是`	`single` 或 `thread`
`text`	`string`	`否*`	帖子内容（single 类型必需）
`texts`	`array`	`否*`	Thread 帖子数组（thread 类型必需）
`imageUrls`	`array`	`否`	图片 URL 数组
`langs`	`array`	`否`	语言标签（默认：`["en"]`）

费用：10 积分

Mastodon

POST /api/v1/mastodon/publish

curl -X POST "https://xaicreator.com/api/v1/mastodon/publish" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "accountUuid": "account_uuid",
    "type": "single",
    "text": "你好 Mastodon！"
  }'

参数：与 Bluesky 相同

费用：10 积分

Threads

POST /api/v1/threads/publish

curl -X POST "https://xaicreator.com/api/v1/threads/publish" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "accountId": "account_uuid",
    "text": "你好 Threads！",
    "mediaUrls": ["https://example.com/image.jpg"]
  }'

参数

参数	类型	必填	描述
`accountId`	`string`	`是`	账号 UUID
`draftId`	`string`	`否*`	草稿 UUID（与 text/mediaUrls 二选一）
`text`	`string`	`否*`	帖子文本（最多 500 字符）
`mediaUrls`	`array`	`否`	媒体 URL 数组
`replyControl`	`string`	`否`	`everyone`、`accounts_you_follow`、`mentioned_only`

费用：10 积分

POST /api/v1/linkedin/publish

curl -X POST "https://xaicreator.com/api/v1/linkedin/publish" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "accountId": "account_uuid",
    "text": "你好 LinkedIn！",
    "mediaUrls": ["https://example.com/image.jpg"],
    "visibility": "PUBLIC"
  }'

参数

参数	类型	必填	描述
`accountId`	`string`	`是`	账号 UUID
`draftId`	`string`	`否*`	草稿 UUID（与 text 二选一）
`text`	`string`	`否*`	帖子文本（最多 3000 字符）
`mediaUrls`	`array`	`否`	媒体 URL 数组
`visibility`	`string`	`否`	`PUBLIC`、`CONNECTIONS`、`LOGGED_IN`（默认：`PUBLIC`）

费用：10 积分

排程发布

创建排程

POST /api/v1/twitter/schedule

curl -X POST "https://xaicreator.com/api/v1/twitter/schedule" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "draftId": "draft_uuid",
    "scheduledFor": "2026-01-15T10:00:00Z",
    "targetAccounts": [
      {
        "accountId": "account_id",
        "platform": "twitter"
      }
    ],
    "priority": 0,
    "applyJitter": true
  }'

参数

参数	类型	必填	描述
`draftId`	`string`	`是`	草稿 UUID
`scheduledFor`	`string`	`是`	ISO 8601 日期时间（UTC）
`targetAccounts`	`array`	`否`	目标账号列表（支持多平台）
`accountUuid`	`string`	`否`	单账号模式（向后兼容）
`platform`	`string`	`否`	平台类型（默认：twitter）
`priority`	`number`	`否`	优先级（默认：0）
`applyJitter`	`boolean`	`否`	是否添加随机抖动 ±3 分钟（默认：true）

响应：

{
  "message": "草稿排程成功",
  "queueIds": ["uuid1", "uuid2"],
  "scheduledFor": "2026-01-15T10:00:00.000Z",
  "accountCount": 2
}

取消排程

DELETE /api/v1/twitter/schedule

curl -X DELETE "https://xaicreator.com/api/v1/twitter/schedule?draftId=draft_uuid" \
  -H "xai-key: your_api_key"

响应：

{
  "message": "排程已成功取消"
}

获取排程列表

GET /api/v1/twitter/schedule

curl "https://xaicreator.com/api/v1/twitter/schedule" \
  -H "xai-key: your_api_key"

响应：

{
  "schedules": [
    {
      "id": "queue_uuid",
      "draftId": "draft_uuid",
      "draftTitle": "我的草稿",
      "scheduledFor": "2026-01-15T10:00:00.000Z",
      "priority": 0,
      "attempts": 0,
      "createdAt": "2026-01-14T08:00:00.000Z",
      "platform": "twitter",
      "accountUuid": "account_uuid"
    }
  ]
}

媒体上传

上传媒体

POST /api/v1/twitter/media/upload

curl -X POST "https://xaicreator.com/api/v1/twitter/media/upload" \
  -H "xai-key: your_api_key" \
  -F "files=@/path/to/image.jpg"

限制：

每次请求最多 4 个文件
图片：每个文件 5MB
GIF：每个文件 15MB
视频：每个文件 512MB

响应：

{
  "code": 0,
  "data": {
    "uploads": [
      {
        "mediaId": "media_id_string",
        "url": "https://pbs.twimg.com/...",
        "type": "image"
      }
    ]
  }
}

GET /api/v1/social-sets

curl "https://xaicreator.com/api/v1/social-sets" \
  -H "xai-key: your_api_key"

响应：

{
  "socialSets": [
    {
      "id": "social-set-id",
      "name": "我的 Social Set",
      "accounts": [
        {
          "accountId": "account_id",
          "platform": "twitter",
          "username": "username"
        }
      ]
    }
  ]
}

积分

查询积分余额

POST /api/v1/credits

curl -X POST "https://xaicreator.com/api/v1/credits" \
  -H "xai-key: your_api_key"

响应：

{
  "balance": 150,
  "expiresAt": "2026-02-01T00:00:00Z"
}

错误处理

所有端点可能返回以下格式的错误：

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "人类可读的错误信息"
}

常见错误代码

代码	描述
`INVALID_API_KEY`	API key 缺失、无效或已被撤销
`USER_NOT_FOUND`	邮箱未注册
`INVALID_CREDENTIALS`	邮箱或密码无效
`INSUFFICIENT_CREDITS`	积分不足以执行此操作
`UNAUTHORIZED`	用户无权访问此资源
`NOT_FOUND`	请求的资源不存在
`RATE_LIMITED`	请求过多，请稍后再试
`INVALID_INPUT`	请求验证失败
`TOKEN_EXPIRED`	OAuth 令牌已过期（需要重新认证）
`OAUTH_NOT_CONFIGURED`	OAuth 环境变量未配置

HTTP 状态码

状态	描述
`200`	成功
`400`	请求错误（输入无效）
`401`	未授权（API key 或令牌无效）
`402`	需要付费（积分不足）
`403`	禁止访问（超出限制）
`404`	未找到
`500`	服务器内部错误

速率限制

API 请求按 API Key 进行速率限制：

免费版：100 次/小时
专业版：1,000 次/小时
企业版：自定义限制

速率限制信息包含在响应头中：

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1705272000

最佳实践

保护密钥：切勿在客户端代码或公开仓库中暴露 API Keys
处理错误：始终检查错误响应并妥善处理
检查积分：在执行发布操作前验证积分余额
使用 Webhook：对于长时间运行的操作，考虑设置 Webhook
缓存响应：缓存 Social Set 和账户数据以减少 API 调用
批量操作：尽可能在单个草稿请求中创建推文串
提前排程：使用排程 API 在最佳时间发布
多平台发布：使用 multi-platform 端点同时发布到多个平台

平台参考

平台	最大字符数	最大媒体数	积分费用
`Twitter`	280（Premium 更多）	4 图片 / 1 视频	10
`Bluesky`	300	4 图片	10
`Mastodon`	500（取决于实例）	4 图片	10
`Threads`	500	10 照片 / 1 视频	10
`LinkedIn`	3000	20 图片	10

技术支持

API 问题或咨询：

API

概述

认证

获取 API Key

1. 邮箱登录

2. Google OAuth

3. Twitter OAuth

API Key 管理

获取 API Keys 列表

创建新 API Key

删除 API Key

Twitter OAuth 2.0

发起 Twitter OAuth

Twitter OAuth 回调

草稿管理

获取草稿列表

创建草稿

发布

发布到 Twitter

引用推文

多平台发布

平台专属发布

Bluesky

Mastodon

Threads

LinkedIn

排程发布

创建排程

取消排程

获取排程列表

媒体上传

上传媒体

Social Set

获取 Social Set 列表

积分

查询积分余额

错误处理

常见错误代码

HTTP 状态码

速率限制

最佳实践

平台参考

技术支持