API

概述

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。如不传则使用用户默认 Social Set。若用户没有任何 Social Set，将返回 NO_SOCIAL_SET 错误。
status	string	否	草稿状态（默认："draft"）
scheduledFor	string	否	定时发布的 ISO 8601 日期时间
selectedAccountIds	array	否	要发布到的账号 ID 列表
templateId	string	否	模板 ID（如果从模板创建）

注意：创建草稿需要至少一个 Social Set。如果用户尚未绑定任何社交账号，API 将返回 400 错误（错误码 NO_SOCIAL_SET）。请先在网页端绑定社交账号。

响应：

{
  "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"
  }
}

草稿批量创建

批量创建草稿

POST /api/v1/twitter/drafts/batch

在单次请求中创建多个草稿。

curl -X POST "https://xaicreator.com/api/v1/twitter/drafts/batch" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "drafts": [
      {
        "title": "草稿 1",
        "tweets": [{"content": "<p>第一个草稿</p>"}]
      },
      {
        "title": "草稿 2",
        "tweets": [{"content": "<p>第二个草稿</p>"}]
      }
    ],
    "socialSetId": "social-set-id"
  }'

草稿多平台内容

获取平台内容

GET /api/v1/twitter/drafts/:id/platforms

获取草稿的各平台专属内容。发布到多个平台时，每个平台可以有定制化的内容。

curl "https://xaicreator.com/api/v1/twitter/drafts/draft-uuid/platforms" \
  -H "xai-key: your_api_key"

响应：

{
  "platforms": [
    {
      "id": 1,
      "draft_uuid": "draft-uuid",
      "platform": "bluesky",
      "content": "Bluesky 定制内容",
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z"
    }
  ]
}

更新平台内容

PUT /api/v1/twitter/drafts/:id/platforms

设置草稿的各平台专属内容。使用 upsert 逻辑（不存在则创建，存在则更新）。

curl -X PUT "https://xaicreator.com/api/v1/twitter/drafts/draft-uuid/platforms" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "platforms": [
      {
        "platform": "bluesky",
        "content": "Bluesky 定制内容"
      },
      {
        "platform": "linkedin",
        "content": "LinkedIn 定制内容"
      }
    ]
  }'

发布

发布到 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"
}

查询发布进度

GET /api/v1/twitter/publish/progress

查看草稿的发布进度。

curl "https://xaicreator.com/api/v1/twitter/publish/progress?draftId=draft-uuid" \
  -H "xai-key: your_api_key"

响应：

{
  "entries": [
    {
      "id": "queue-uuid",
      "draftId": "draft-uuid",
      "status": "published",
      "platform": "twitter",
      "accountUuid": "account-uuid",
      "scheduledFor": "2026-01-15T10:00:00.000Z",
      "publishedAt": "2026-01-15T10:00:05.000Z"
    }
  ],
  "summary": {
    "total": 2,
    "completed": 2,
    "failed": 0,
    "pending": 0
  }
}

多平台发布

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 积分

LinkedIn

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"
      }
    ]
  }
}

Social Set

获取 Social Set 列表

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"
        }
      ]
    }
  ]
}

创建 Social Set

POST /api/v1/social-sets

curl -X POST "https://xaicreator.com/api/v1/social-sets" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{"name": "新 Social Set"}'

更新 Social Set

PUT /api/v1/social-sets

curl -X PUT "https://xaicreator.com/api/v1/social-sets" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{"id": "social-set-id", "name": "更新名称"}'

删除 Social Set

DELETE /api/v1/social-sets

curl -X DELETE "https://xaicreator.com/api/v1/social-sets" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{"id": "social-set-id"}'

用户信息

获取当前用户

GET /api/v1/me

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

响应：

{
  "uuid": "user-uuid",
  "email": "[email protected]",
  "nickname": "张三",
  "avatar_url": "https://...",
  "timezone": "Asia/Shanghai",
  "credits_balance": 150,
  "locale": "zh",
  "created_at": "2026-01-01T00:00:00.000Z"
}

账号管理

获取已绑定账号列表

GET /api/v1/accounts

获取当前用户在所有平台上绑定的社交账号。

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

响应：

{
  "accounts": [
    {
      "uuid": "account-uuid",
      "platform": "twitter",
      "platform_user_id": "123456",
      "username": "johndoe",
      "display_name": "John Doe",
      "avatar": "https://...",
      "status": "active",
      "followers_count": 1500,
      "following_count": 300,
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

获取账号详情

GET /api/v1/accounts/:id

curl "https://xaicreator.com/api/v1/accounts/account-uuid" \
  -H "xai-key: your_api_key"

解绑账号

DELETE /api/v1/accounts/:id

解绑社交账号。此操作会将账号从所有 Social Set 中移除。

curl -X DELETE "https://xaicreator.com/api/v1/accounts/account-uuid" \
  -H "xai-key: your_api_key"

响应：

{
  "success": true,
  "message": "Account deleted successfully"
}

模板管理

获取模板列表

GET /api/v1/templates

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

响应：

{
  "templates": [
    {
      "uuid": "template-uuid",
      "name": "我的模板",
      "description": "可复用的模板",
      "head_content_plain": "头部文本",
      "tail_content_plain": "尾部文本",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

获取模板详情

GET /api/v1/templates/:id

curl "https://xaicreator.com/api/v1/templates/template-uuid" \
  -H "xai-key: your_api_key"

创建模板

POST /api/v1/templates

curl -X POST "https://xaicreator.com/api/v1/templates" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{
    "name": "我的模板",
    "description": "可复用的模板",
    "headContentPlain": "头部文本",
    "tailContentPlain": "尾部文本"
  }'

参数

参数	类型	必填	描述
name	string	是	模板名称
description	string	否	模板描述
headContentPlain	string	否	头部内容（纯文本）
tailContentPlain	string	否	尾部内容（纯文本）
headContentHtml	string	否	头部内容（HTML）
tailContentHtml	string	否	尾部内容（HTML）

更新模板

PUT /api/v1/templates/:id

curl -X PUT "https://xaicreator.com/api/v1/templates/template-uuid" \
  -H "Content-Type: application/json" \
  -H "xai-key: your_api_key" \
  -d '{"name": "更新后的模板"}'

删除模板

DELETE /api/v1/templates/:id

curl -X DELETE "https://xaicreator.com/api/v1/templates/template-uuid" \
  -H "xai-key: your_api_key"

积分

查询积分余额

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"
}

积分使用记录

GET /api/v1/credits/usage

curl "https://xaicreator.com/api/v1/credits/usage?page=1&limit=20" \
  -H "xai-key: your_api_key"

参数

参数	类型	必填	描述
page	number	否	页码（默认：1）
limit	number	否	每页条数（默认：20，最大：100）
start_date	string	否	按开始日期筛选（ISO 8601）
end_date	string	否	按结束日期筛选（ISO 8601）
trans_type	string	否	按交易类型筛选

响应：

{
  "records": [
    {
      "id": 1,
      "trans_no": "TXN-001",
      "trans_type": "publish",
      "credits": -10,
      "order_no": null,
      "source_type": "twitter",
      "source_detail": "发布草稿：我的草稿",
      "expired_at": null,
      "created_at": "2026-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 50,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

错误处理

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

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

常见错误代码

代码	描述
INVALID_API_KEY	API key 缺失、无效或已被撤销
USER_NOT_FOUND	邮箱未注册
INVALID_CREDENTIALS	邮箱或密码无效
INSUFFICIENT_CREDITS	积分不足以执行此操作
NO_SOCIAL_SET	用户没有 Social Set，请先绑定社交账号再创建草稿
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

最佳实践

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

CLI 工具

@xaicreator/cli npm 包提供了命令行界面，覆盖所有 API 操作，适合人类用户和 AI Agent 使用。

安装

npm install -g @xaicreator/cli
# 或直接运行
npx @xaicreator/cli

认证

# 使用 API Key 登录
xaic login --api-key sk-xxx

# 查看当前用户
xaic whoami

# 登出
xaic logout

常用命令

# 草稿
xaic draft list
xaic draft create --content "Hello world"
xaic draft create --file ./tweet.md          # 从文件创建
xaic draft create --stdin                    # 从标准输入读取（支持管道）
xaic draft get <id>
xaic draft update <id> --content "Updated"
xaic draft delete <id>

# 发布
xaic publish <draft-id>

# 排程
xaic schedule create <draft-id> --at "2026-01-15T10:00:00Z"
xaic schedule list
xaic schedule cancel <id>

# Social Set & 账号
xaic social-set list
xaic account list

# 模板
xaic template list
xaic template get <id>
xaic template create --name "我的模板"

# 积分
xaic credits
xaic credits-usage

全局选项

--output json|table|minimal     # 输出格式（默认：table）
--api-key sk-xxx                # 覆盖已存储的 API Key
--base-url https://...          # 自定义 API 基础 URL
--quiet                         # 静默模式

环境变量

XAIC_API_KEY=sk-xxx             # API Key（替代登录）
XAIC_BASE_URL=https://...       # 自定义 API 基础 URL

SDK 使用

CLI 底层客户端可作为 SDK 导入：

import { XAICreatorClient } from '@xaicreator/cli';

const client = new XAICreatorClient({ apiKey: 'sk-xxx' });
const drafts = await client.listDrafts();
const draft = await client.createDraft({
  title: '你好',
  tweets: [{ content: '你好世界', position: 0 }],
});
await client.publish(draft.draft.id);

推文串支持

使用 --- 分隔符创建多推文串：

echo "第一条推文
---
第二条推文
---
第三条推文" | xaic draft create --stdin

技术支持

API 问题或咨询：

• 邮箱：[email protected]
• 文档：https://xaicreator.com/zh/docs/api
• 状态页：https://xaicreator.com/zh/status