> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 只有Instagram帖子或Reel链接，怎样接着读文案、互动和评论？

> 通过 instagram.v2.fetch_post_info 或 instagram.v3.get_post_info 用帖子或 Reel 链接获取详情，核对短码并提取字符串 pk 作为 instagram.fetch_post_comments_v2 的 media_id。

有 Instagram 帖子或 Reel 链接时，把链接作为 `code_or_url` 传给 `instagram.v2.fetch_post_info` 取详情。核对详情里的短码和账号后，再读文案和互动。要查评论，从同一份详情取媒体 `pk`，作为 `instagram.fetch_post_comments_v2` 的 `media_id`。

例如同事发来新品 Reel，查一次详情，就既能留一份当前互动快照，也能拿到评论请求要用的 `media_id`。

## 怎样直接用链接取详情？

把完整帖子链接或 shortcode 作为 `code_or_url` 传给 `data:instagram.v2.fetch_post_info`：

```bash
curl --fail-with-body -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"instagram.v2.fetch_post_info","params":{"code_or_url":"<post_url_or_shortcode>"}}' \
  -o instagram-post.json
```

`data:instagram.v3.get_post_info` 是另一条详情路线，接受 URL 或数字 `media_id`；`url` 的说明列出 `/p/`、`/reel/`、`/reels/`、`/tv/` 路径。传你已有的那一种目标输入，不要混填指向不同作品的值。

## 拿到详情，先确认什么？

核对成功状态、帖子 shortcode、账号和文案。v2 的帖子对象在 `data.data`；v3 要在 `data.items[]` 中找 `code` 匹配的条目，不默认第一项就是目标。`caption.text` 是帖子文案，不是视频逐字字幕。

看互动时，接[快照流程](/zh/guides/instagram-post-snapshot)；看评论时，用下面的 `comment_handoff.py` 从匹配对象取 `pk`。保存详情响应和来源，后续步骤直接复用，不必重新请求详情。

## 只有 Reel 链接，但评论导出器要求 media_id 怎么办？

`instagram.v2.fetch_post_info` 与 `instagram.v3.get_post_info` 接受帖子 URL，而 `instagram.fetch_post_comments_v2` 必须使用数字字符串 `media_id`。复用已保存的成功详情，匹配请求的短码，再读匹配对象的 `pk`：v2 是 `data.data.pk`，v3 是 `data.items[]` 中唯一 `code` 匹配项的 `pk`。不能用作者 ID、复合 item `id`、短码本身，或经过浮点数转换的标识代替。

做指标快照时已经保存过详情的，不要只为 `pk` 再付一次详情费用。在已保存的详情响应旁边新建 `detail-meta.json`，记录实际请求与采集时间：

```json
{"action":"instagram.v2.fetch_post_info","params":{"code_or_url":"https://www.instagram.com/reel/ExampleCode/"},"http_status":200,"collected_at":"2026-11-17T03:45:00+08:00","response_file":"instagram-post.json"}
```

示例 URL 仅作示意，换成你实际请求的短码或链接；v3 则把 `action` 记为 `instagram.v3.get_post_info`，链接放在 `params.url`。把下面的脚本存为 `comment_handoff.py`，执行 `python3 comment_handoff.py detail-meta.json reel-comments`。脚本在 `reel-comments/` 里写入原字节详情证据和评论首页请求，不会发送评论请求。

```python
import hashlib,json,pathlib,re,sys
from datetime import datetime
from urllib.parse import urlsplit
meta_path,target=map(pathlib.Path,sys.argv[1:3])
m=json.loads(meta_path.read_text(encoding='utf-8'));action=m['action'];p=m['params']
if type(m.get('http_status')) is not int or m['http_status']!=200: raise ValueError('Require successful recorded HTTP status')
if action=='instagram.v2.fetch_post_info' and set(p)=={'code_or_url'}:
    supplied=p['code_or_url']
elif action=='instagram.v3.get_post_info' and not set(p)-{'url','media_id'} and p.get('media_id') in (None,''):
    supplied=p.get('url')
else: raise ValueError('Use one URL/shortcode detail input; do not mix identifiers')
if not isinstance(supplied,str) or not supplied: raise ValueError('Missing source target')
if action=='instagram.v2.fetch_post_info' and re.fullmatch(r'[A-Za-z0-9_-]+',supplied):
    code=supplied
else:
    u=urlsplit(supplied);match=re.fullmatch(r'/(?:p|reel|reels|tv)/([A-Za-z0-9_-]+)/?',u.path)
    if u.scheme!='https' or u.hostname not in ('instagram.com','www.instagram.com') or u.username or u.password or u.port not in (None,443) or not match:
        raise ValueError('Require supported Instagram post URL')
    code=match.group(1)
t=datetime.fromisoformat(m['collected_at'].replace('Z','+00:00'))
if t.tzinfo is None: raise ValueError('Use collection time with timezone')
raw=(meta_path.parent/m['response_file']).read_bytes();r=json.loads(raw)
if r.get('status')!='succeeded' or r.get('action')!=action or r.get('error'): raise ValueError('Failed or mismatched detail response')
rid=r.get('request_id')
if not isinstance(rid,str) or not rid.strip(): raise ValueError('Missing request ID')
if action=='instagram.v2.fetch_post_info':
    rows=[r['data']['data']]
else:
    rows=r['data']['items']
if not isinstance(rows,list) or not all(isinstance(x,dict) for x in rows): raise ValueError('Unexpected detail object structure')
matched=[x for x in rows if x.get('code')==code]
if len(matched)!=1: raise ValueError('Exactly one detail object must match the requested shortcode')
pk=matched[0].get('pk')
if not isinstance(pk,str) or not re.fullmatch(r'[1-9][0-9]*',pk):
    raise ValueError('Require original numeric-string pk; do not repair rounded numbers or split id')
request={'action':'instagram.fetch_post_comments_v2','params':{'media_id':pk,'sort_order':'recent'}}
evidence={'code':code,'media_id':pk,'detail_action':action,'detail_request_id':rid,'requested_target':supplied,
 'collected_at':m['collected_at'],'source_sha256':hashlib.sha256(raw).hexdigest(),'comments_requested':False}
target.mkdir(parents=True,exist_ok=False)
(target/'detail-source.json').write_bytes(raw)
for name,value in [('comments-request.json',request),('identity-evidence.json',evidence)]:
    (target/name).write_text(json.dumps(value,ensure_ascii=False,indent=2),encoding='utf-8')
print(json.dumps({'code':code,'comments_requested':False}))

```

检查 `comments-request.json`：`media_id` 必须等于短码匹配对象的原始字符串 `pk`，首页不带 `min_id`。把 `identity-evidence.json`、`detail-source.json` 与后续评论档案放在一起。在评论预算内才发送 `comments-request.json` 的请求体，然后按[一级评论导出指南](/zh/guides/instagram-comment-export)保存实际响应。已保存的详情证明用了哪个返回的媒体 ID，不证明评论一定可取，也不证明已取得所有回复。

新的详情和评论分别按[价格页](https://beatapi.io/zh/pricing)的当前价格计费；已有详情时直接复用，只为实际选用的评论步骤付费。字段缺失或作品匹配不唯一时，先核对原始响应，保留已有资料。

`comment_handoff.py` 只接受合同规定的数字字符串 `pk`。即使 Python 能存下大整数，`comment_handoff.py` 也会拒绝裸 JSON 数字，因为本地脚本无法修复更早环节数值转换造成的精度丢失。`comment_handoff.py` 也不会从通用 `id` 字段拆出 `pk`。