> ## 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.

# X 文章

一次请求即可获取公开 X 文章的完整内容和元数据。Article 是 X 上的长文章，包含封面图、富文本正文（最多约 100,000 字符），其互动指标与发布文章的公告推文分开。

> **免费试用：** `/article` 可使用初始赠送的 100 次请求，一次性赠送，无需信用卡，永不过期。无论正文多长，获取一篇文章都只算一次请求，不按字符收费，因此最多可免费获取 100 篇完整文章。

> **注意：** 长文章处理的完整指南见博客上的 [X 文章 API：获取 X 长文章](https://api.sorsa.io/blog/x-articles-api)。

***

## 快速入门

```bash theme={null}
curl -X POST https://api.sorsa.io/v3/article \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_link": "https://x.com/SorsaApp/status/1234567890"}'
```

```python theme={null}
import requests

API_KEY = "YOUR_API_KEY"

def get_article(tweet_link):
    resp = requests.post(
        "https://api.sorsa.io/v3/article",
        headers={"ApiKey": API_KEY, "Content-Type": "application/json"},
        json={"tweet_link": tweet_link},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()


article = get_article("https://x.com/SorsaApp/status/1234567890")
print(f"Author: @{article['author']['username']}")
print(f"Published: {article['published_at']}")
print(f"Views: {article['views_count']:,}")
print(f"Body length: {len(article['full_text'])} characters")
```

***

## 端点

```text theme={null}
POST /v3/article
```

### 请求体

| 参数           | 类型     | 必需 | 说明                    |
| :----------- | :----- | :- | :-------------------- |
| `tweet_link` | string | 是  | 公告推文的完整 URL 或数字推文 ID。 |

### 响应

```json theme={null}
{
  "full_text": "this isn't a cosmetic rebrand. it's a response to how crypto twitter actually works in 2026...",
  "preview_text": "this isn't a cosmetic rebrand. it's a response to how crypto twitter actually works in 2026.\nthe old model was simple...",
  "cover_image_url": "https://pbs.twimg.com/media/G-t2hYTaIAAstc8.jpg",
  "published_at": "2026-01-15T16:24:02Z",
  "views_count": 36538,
  "likes_count": 315,
  "bookmark_count": 38,
  "quote_count": 37,
  "reply_count": 80,
  "retweet_count": 41,
  "author": {
    "id": "1934538036466810880",
    "username": "SorsaApp",
    "display_name": "Sorsa",
    "description": "Crypto social analytics made simple...",
    "followers_count": 6050,
    "verified": false
  }
}
```

### 响应字段

| 字段                | 类型                | 说明                           |
| :---------------- | :---------------- | :--------------------------- |
| `full_text`       | string            | 完整文章正文，可能长达数万字符。             |
| `preview_text`    | string            | 时间线中“阅读更多”之前显示的截取片段。         |
| `cover_image_url` | string \| null    | 封面图片 URL，未设置则为 `null`。       |
| `published_at`    | string (ISO 8601) | 发布时间戳，不同于公告推文的 `created_at`。 |
| `likes_count`     | integer           | 点赞数。                         |
| `retweet_count`   | integer           | 转推数。                         |
| `reply_count`     | integer           | 回复数。                         |
| `quote_count`     | integer           | 引用推文数。                       |
| `bookmark_count`  | integer           | 收藏数。                         |
| `views_count`     | integer           | 展示总次数。                       |
| `author`          | object            | 完整作者资料，字段与标准 User 对象相同。      |

> **字段命名。** 文章互动字段 `likes_count`、`retweet_count`、`reply_count`、`quote_count`、`bookmark_count` 与标准 Tweet 对象相同。唯一例外是展示数：文章使用 `views_count`，而推文使用单数形式的 `view_count`。如果文章和推文共用管道，应在采集时统一此字段。完整结构对比见[响应格式](https://docs.sorsa.io/zh-Hans/response-format)。

***

## 区分文章与普通推文

已知内容类型时直接调用对应端点。对于混合输入，下方辅助函数先尝试 `/article`，遇到 `404` 或空文章正文时再回退。`404` 也可能表示资源不可用，因此回退同样可能失败。身份验证、配额、速率限制和服务器错误会继续抛出，不会被静默视为普通推文。

```python theme={null}
def get_content(tweet_link):
    """Fetch a tweet or article, returning the appropriate object."""
    try:
        article = get_article(tweet_link)
        if article.get("full_text"):
            return {"type": "article", "data": article}
    except requests.HTTPError as error:
        if error.response is None or error.response.status_code != 404:
            raise

    resp = requests.post(
        "https://api.sorsa.io/v3/tweet-info",
        headers={"ApiKey": API_KEY, "Content-Type": "application/json"},
        json={"tweet_link": tweet_link},
        timeout=30,
    )
    resp.raise_for_status()
    return {"type": "tweet", "data": resp.json()}
```

***

## 后续步骤

* [搜索推文](https://docs.sorsa.io/zh-Hans/search-tweets)：按关键词查找文章
* [推文互动](https://docs.sorsa.io/zh-Hans/tweet-engagement)：获取文章推文的评论、引用和转推
* [历史数据](https://docs.sorsa.io/zh-Hans/historical-data)：获取数月或数年前发布的文章
* [API 参考](https://docs.sorsa.io/zh-Hans/api-reference-guide)：`/article` 和全部端点的完整规范