跳转到主要内容
POST
https://api.aisa.one/apis/v1
/
twitter
/
auth_twitter
关联 X/Twitter 账户(启动 OAuth)
curl --request POST \
  --url https://api.aisa.one/apis/v1/twitter/auth_twitter \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
import requests

url = "https://api.aisa.one/apis/v1/twitter/auth_twitter"

payload = {}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};

fetch('https://api.aisa.one/apis/v1/twitter/auth_twitter', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.aisa.one/apis/v1/twitter/auth_twitter",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([

]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://api.aisa.one/apis/v1/twitter/auth_twitter"

payload := strings.NewReader("{}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/twitter/auth_twitter")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/twitter/auth_twitter")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
{
  "auth_url": "https://twitter.com/i/oauth2/authorize?response_type=code&client_id=AIsa&redirect_uri=https%3A%2F%2Fapi.aisa.one%2Fapis%2Fv1%2Ftwitter%2Foauth_callback&scope=follows.write%20tweet.read%20users.read&state=0c2...d1f&code_challenge=...&code_challenge_method=S256",
  "state": "0c2ad1f...",
  "expires_at": "2026-04-18T07:00:00Z"
}
POST /apis/v1/twitter/auth_twitter 是通过 AIsa 执行任何 X/Twitter 写入操作的第一步。它会返回一个短期有效的 X OAuth 授权 URL——源用户在浏览器中打开该 URL,批准所请求的权限范围,然后 X 会重定向至 AIsa 的固定回调地址。AIsa 会将生成的会话与您的 API 密钥关联存储,后续每次写入调用(例如 POST /twitter/follow_twitter)都会自动使用该会话。

何时调用

  • 每个源用户调用一次,即首次关联其 X 账户时。
  • 如果已存储的会话被撤销、已过期,或者需要其他权限范围集合,则再次调用
无需在每次写入请求前调用此端点。OAuth 会话会与您的 AIsa API 密钥持续关联。

流程

1

启动流程

使用您的 AIsa API 密钥发送 POST /apis/v1/twitter/auth_twitter。可以选择在请求正文中包含 scopes 数组,以请求比默认范围更窄的权限集合。
2

打开授权 URL

响应会返回 auth_urlstate token。在源用户的浏览器中打开 auth_url。X 将显示标准的“授权 AIsa 访问您的账户”页面。
3

用户批准

用户点击授权后,X 会重定向至 AIsa 的固定回调地址(https://api.aisa.one/apis/v1/twitter/oauth_callback)。AIsa 会验证 state token,用授权码交换 token,并将会话与您的 API 密钥关联存储。
4

解锁写入端点

此后,使用您的 AIsa API 密钥调用任何 Twitter 写入端点,都会代表已关联的源用户执行操作。您无需在这些调用的请求正文中传递 OAuth token。

默认权限范围

如果省略 scopes 字段,AIsa 将请求我们公开的所有 Twitter 写入端点所需的完整权限集合:
  • follows.write关注 / 取消关注
  • tweet.read — 读取推文(大多数写入操作均需要)
  • users.read — 解析用户、读取个人资料信息
  • tweet.write — 发布、回复、引用
  • like.write — 点赞 / 取消点赞
  • dm.read — 读取私信会话
  • dm.write — 发送私信
如果只需要部分功能,请传递范围更窄的数组(例如 ["follows.write", "tweet.read", "users.read"])。需要缺失权限范围的写入调用将返回 403

过期时间

此端点返回的 auth_url 短期有效(通常为 10 分钟)。如果用户未在 expires_at 之前完成流程,请再次调用 POST /apis/v1/twitter/auth_twitter 生成新的 URL。 已存储的 OAuth 会话本身有效期更长(受 X 的 token 轮换规则约束)。只要用户未在 X 的应用设置中撤销访问权限,会话就会自动刷新。

相关内容

关注用户

使用此流程所存储会话的第一个写入端点。

Twitter Autopilot 技能

封装完整读取和写入功能的智能体技能。

身份验证

AIsa API 密钥的生命周期和存储最佳实践。

授权

Authorization
string
header
必填

你的 AIsa API 密钥。经过身份验证的源用户(执行关注操作的账户)由附加到你的密钥的 OAuth 会话决定。

请求体

application/json
scopes
string[]

要请求的可选 X OAuth 2.0 scope 列表。默认为 AIsa 的 Twitter 写入端点所需的集合:follows.writetweet.readusers.readtweet.writelike.writedm.readdm.write

示例:
["follows.write", "tweet.read", "users.read"]

响应

已生成授权 URL。

auth_url
string<uri>
必填

短期有效的 X OAuth 授权 URL。在浏览器中打开该 URL,以便源用户批准所请求的权限范围。

state
string
必填

不透明的 CSRF state token,X 重定向回 AIsa 回调地址时,AIsa 将对其进行验证。如果需要关联此流程,请将其存储在客户端。

expires_at
string<date-time>

auth_url 的过期时间。如果用户在此时间之前尚未完成流程,请请求一个新的 URL。