> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速入门

> 几分钟内获取 API 密钥，并向 X（Twitter）API 发送第一个请求。

本指南带你从零开始获取第一个响应：创建账号、完成身份验证，然后发送第一个 `GET` 和 `POST` 请求。每一步都提供可用的 cURL、Python 和 JavaScript 示例。

## 第 1 步：获取 API 密钥

1. 打开 [Sorsa 控制台](https://api.sorsa.io/overview)，点击 **Sign in**，使用任意可用方式注册。除了身份验证服务提供的信息，Sorsa 不会要求额外信息。
2. 账号初始包含 **100 次免费请求**。无需信用卡，适用于所有可用端点，并且永不过期，可以立即开始测试。
3. 需要更大用量时，选择套餐（每月 1 万、10 万或 50 万次请求）和计费周期（月付或年付），然后使用银行卡或加密货币支付。

登录后，控制台会显示你的 **API 密钥**和**剩余请求配额**。

> **请妥善保管 API 密钥。** 不要将其暴露在前端代码、公开仓库或客户端 JavaScript 中。请像密码一样保护它。

## 第 2 步：了解基础信息

第一次调用之前，需要了解以下几点。

**基础 URL**

```text theme={null}
https://api.sorsa.io/v3
```

**身份验证**

每个请求都必须在 `ApiKey` 请求头中包含 API 密钥：

```text theme={null}
ApiKey: YOUR_API_KEY
```

**响应格式**

所有端点均返回 JSON。成功请求返回 HTTP `200`。

**速率限制**

所有套餐的上限均为每秒 20 次请求。请求节奏和重试策略请参阅[速率限制](https://docs.sorsa.io/zh-Hans/rate-limits)。

## 第 3 步：发送第一个 GET 请求

**运行示例之前：** 使用 `python -m pip install requests` 安装 Python 的 `requests` 包。在后端使用带 `fetch` 的 Node.js 18+ 运行 JavaScript；使用顶层 `await` 时，将示例保存为 `.mjs` 文件。将 `YOUR_API_KEY` 替换为你的密钥。下方个人资料和推文响应仅为示例。

检查配置是否正确的最快方式，是通过 `/info` 端点获取公开个人资料。

**cURL**

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/info?username=elonmusk' \
  --header 'ApiKey: YOUR_API_KEY'
```

**Python**

```python theme={null}
import requests

response = requests.get(
    "https://api.sorsa.io/v3/info",
    params={"username": "elonmusk"},
    headers={"ApiKey": "YOUR_API_KEY"},
    timeout=30,
)

response.raise_for_status()
data = response.json()
print(data["display_name"])      # Elon Musk
print(data["followers_count"])   # 236021252
```

**JavaScript**

```javascript theme={null}
const response = await fetch(
  "https://api.sorsa.io/v3/info?username=elonmusk",
  { headers: { ApiKey: "YOUR_API_KEY" } }
);

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
console.log(data.display_name);      // Elon Musk
console.log(data.followers_count);   // 236021252
```

**响应示例**

```json theme={null}
{
  "id": "44196397",
  "username": "elonmusk",
  "display_name": "Elon Musk",
  "description": "",
  "location": "",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1234567890/avatar.jpg",
  "profile_background_image_url": "https://pbs.twimg.com/profile_banners/44196397/1700000000",
  "followers_count": 236021252,
  "followings_count": 1292,
  "tweets_count": 98479,
  "favourites_count": 214650,
  "media_count": 4374,
  "verified": true,
  "protected": false,
  "can_dm": false,
  "possibly_sensitive": false,
  "created_at": "2009-06-02T20:12:29Z",
  "bio_urls": [],
  "pinned_tweet_ids": ["2028500984977330453"]
}
```

如果返回包含用户数据的 JSON，就说明密钥有效，可以继续使用。

## 第 4 步：发送第一个 POST 请求

许多推文和搜索端点使用带 JSON 请求体的 `POST`。以下通过 `/search-tweets` 搜索推文：

**cURL**

```bash theme={null}
curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "query": "bitcoin" }'
```

**Python**

```python theme={null}
import requests

response = requests.post(
    "https://api.sorsa.io/v3/search-tweets",
    headers={"ApiKey": "YOUR_API_KEY"},
    json={"query": "bitcoin"},
    timeout=30,
)

response.raise_for_status()
data = response.json()
for tweet in data.get("tweets", []):
    print(tweet["full_text"])
```

**JavaScript**

```javascript theme={null}
const response = await fetch("https://api.sorsa.io/v3/search-tweets", {
  method: "POST",
  headers: {
    ApiKey: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "bitcoin" }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
data.tweets?.forEach((tweet) => console.log(tweet.full_text));
```

**响应示例（已截取）**

```json theme={null}
{
  "tweets": [
    {
      "id": "1782368585664626774",
      "full_text": "Bitcoin just crossed another milestone.",
      "created_at": "2024-01-15T10:30:00Z",
      "lang": "en",
      "likes_count": 200,
      "retweet_count": 50,
      "reply_count": 10,
      "view_count": 10000,
      "user": {
        "id": "44196397",
        "username": "elonmusk",
        "display_name": "Elon Musk",
        "followers_count": 236021252,
        "verified": true
      }
    }
  ],
  "next_cursor": "DAABCgABF7d..."
}
```

若要获取更多结果，在下一个请求中传入返回的 `next_cursor`。完整用法请参阅[分页](https://docs.sorsa.io/zh-Hans/pagination)。

## 第 5 步：检查 API 用量

随时通过 `/key-usage-info` 查看剩余请求次数：

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/key-usage-info' \
  --header 'ApiKey: YOUR_API_KEY'
```

**响应示例**

```json theme={null}
{
  "key_requests": 100000,
  "remaining_requests": 94231,
  "total_requests": 5769,
  "valid_until": "2026-08-01T00:00:00Z"
}
```

建议在运行大批量任务前调用此端点。也可在[控制台](https://api.sorsa.io/overview/usage)查看完整历史记录。

## 常见错误码

| 状态码 | 含义    | 处理方式                        |
| :-- | :---- | :-------------------------- |
| 200 | 成功    | 请求已成功完成                     |
| 400 | 请求无效  | 检查查询参数和请求体                  |
| 401 | 未授权   | API 密钥缺失或无效；检查 `ApiKey` 请求头 |
| 403 | 禁止访问  | 无权访问此资源                     |
| 404 | 未找到   | 检查端点 URL 或资源 ID             |
| 429 | 请求过多  | 已触及速率限制；等待后重试               |
| 500 | 服务器错误 | 稍等后重试；若持续出现，请联系支持团队         |

详细信息和处理策略请参阅[错误码参考](https://docs.sorsa.io/zh-Hans/error-codes)。

## 无需代码即可体验

想先通过界面试用？浏览 [API 参考](https://docs.sorsa.io/zh-Hans/api-reference-guide)中的所有端点，或使用无代码 [API Playground](https://api.sorsa.io/playground)。二者都可以发送真实请求并查看响应，无需编写代码。

## 后续步骤

* [身份验证](https://docs.sorsa.io/zh-Hans/authentication)：安全最佳实践和请求头配置
* [分页](https://docs.sorsa.io/zh-Hans/pagination)：处理游标和分页响应
* [速率限制](https://docs.sorsa.io/zh-Hans/rate-limits)：请求节奏和重试策略
* [API 参考](https://docs.sorsa.io/zh-Hans/api-reference-guide)：所有可用端点及数据结构
* [使用场景指南](https://docs.sorsa.io/zh-Hans/use-cases-overview)：实际实现方式