API で direct-message DM メディアを取得する方法

Quick Answer

TwexAPI の Get DM Media (direct-message v3) endpoint、POST /v3/twitter/dm-media は、dm-history が返した attachment を playable media URL に解決します。必須 fields は conversation_id、media_hash_key、cookie。任意 fields は推奨の key_version、type_name、filename、pin、proxy です。response は url、path、content_type、filename、byte_length、cached を返します。Media response は元の message と attachment metadata に紐づけて保存します。

FAQ

direct-message DM media を解決する endpoint は？

https://api.twexapi.io の POST /v3/twitter/dm-media を使います。Bearer token で認証し、JSON に conversation_id、media_hash_key、cookie を渡します。key_version、type_name、filename、pin、proxy は任意です。

conversation_id と media_hash_key はどこから取得しますか？

POST /v3/twitter/dm-history から取得します。返却された conversation_id と各 message の attachment object を保存します。Attachment は media_hash_key を持ち、key_version、type_name、filename の hint も含む場合があります。

DM media 解決後に保存すべき field は？

元の conversation_id、message ID、利用可能なら attachment ID、media_hash_key、key_version、返却された url、path、content_type、filename、byte_length、cached、resolved time、raw response を保存します。cookie は値ではなく secret reference を保存します。

DM record は text だけでは足りないことがあります。Support case では screenshot が証拠になり、creator review では video clip が届き、compliance export では file がどの conversation から来たかを説明する必要があります。

TwexAPI の Get DM Media (XChat v3) endpoint は、1 つの XChat attachment を playable media URL に解決します。入力は Get DM History (XChat v3) が返す attachments から取得します。message の conversation_id、attachment の media_hash_key、任意ですが推奨される key_version を使います。

この media endpoint は conversation を検索しません。先に conversation history を取得し、attachment metadata を保存し、必要な attachment に対して POST /v3/twitter/dm-media を呼びます。

Endpoint と Request Fields

Answer: Endpoint と Request Fieldsは本ガイドの TwexAPI エンドポイントを Bearer で呼び出して実装します。バッチ/ページングで約 5 Credits/回・20+ QPS です。

1 つの XChat media attachment を取得するには POST /v3/twitter/dm-media を使います。

Basic Request

Answer: Basic Requestとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

1curl --request POST \
2  --url https://api.twexapi.io/v3/twitter/dm-media \
3  --header "Authorization: Bearer $TWEXAPI_BEARER_TOKEN" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "conversation_id": "1928096185664843776:1989842918455291904",
7    "media_hash_key": "blRIlZCVIO",
8    "key_version": "3",
9    "type_name": "VIDEO",
10    "filename": "clip.mp4",
11    "cookie": "auth_token=...; ct0=...; twid=...",
12    "pin": "1234"
13  }'

response は playable URL と file metadata を返します。

1{
2  "code": 200,
3  "msg": "success",
4  "data": {
5    "url": "https://api.twexapi.io/media/xchat/...",
6    "path": "/media/xchat/...",
7    "content_type": "video/mp4",
8    "filename": "clip.mp4",
9    "byte_length": 421299,
10    "cached": true
11  }
12}

返却 metadata は元の message と attachment record に紐づけて保存します。Long-term retention が必要な product では、通常の privacy と retention rule に従い、返却された url から自社 storage に保存します。

Attachment Input From DM History

Answer: Attachment Input From DM Historyとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

/v3/twitter/dm-history は message 上に attachments を返すことがあります。これらの fields が /v3/twitter/dm-media の入力になります。

1{
2  "conversation_id": "1928096185664843776:1989842918455291904",
3  "messages": [
4    {
5      "id": "1234567890123456789",
6      "text": "Here is the video.",
7      "sequence_id": "2076661179334979585",
8      "attachments": [
9        {
10          "attachment_id": "cda5ccdd-af53-48a3-bdd1-5039a73aea25",
11          "conversation_id": "1928096185664843776:1989842918455291904",
12          "filename": "clip.mp4",
13          "filesize_bytes": 421299,
14          "key_version": "3",
15          "media_hash_key": "blRIlZCVIO",
16          "type": "video",
17          "type_name": "VIDEO"
18        }
19      ]
20    }
21  ]
22}

Attachment object に conversation_id がない場合は、page-level の conversation_id を使います。

Python Media Resolver

Answer: Python Media Resolverとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

この script は保存済み DM history attachment object を受け取り、playable URL を解決し、message と一緒に保存できる normalized row を返します。

1import os
2from datetime import datetime, timezone
3from typing import Any
4
5import requests
6
7API_URL = "https://api.twexapi.io/v3/twitter/dm-media"
8BEARER_TOKEN = os.environ["TWEXAPI_BEARER_TOKEN"]
9X_COOKIE = os.environ["TWEXAPI_X_COOKIE"]
10XCHAT_PIN = os.environ.get("TWEXAPI_XCHAT_PIN", "1234")
11PROXY = os.environ.get("TWEXAPI_PROXY")
12
13def build_media_payload(
14    conversation_id: str,
15    attachment: dict[str, Any],
16) -> dict[str, Any]:
17    media_hash_key = attachment.get("media_hash_key")
18    if not media_hash_key:
19        raise ValueError("attachment.media_hash_key is required")
20
21    payload: dict[str, Any] = {
22        "conversation_id": attachment.get("conversation_id") or conversation_id,
23        "media_hash_key": media_hash_key,
24        "cookie": X_COOKIE,
25        "pin": XCHAT_PIN,
26    }
27
28    for field in ("key_version", "type_name", "filename"):
29        if attachment.get(field):
30            payload[field] = attachment[field]
31
32    if PROXY:
33        payload["proxy"] = PROXY
34
35    return payload
36
37def fetch_dm_media(
38    conversation_id: str,
39    attachment: dict[str, Any],
40) -> dict[str, Any]:
41    response = requests.post(
42        API_URL,
43        headers={
44            "Authorization": f"Bearer {BEARER_TOKEN}",
45            "Content-Type": "application/json",
46            "Accept": "application/json",
47        },
48        json=build_media_payload(conversation_id, attachment),
49        timeout=60,
50    )
51    response.raise_for_status()
52    data = response.json()
53
54    if data.get("code") != 200:
55        raise RuntimeError(data.get("msg", "TwexAPI returned an error"))
56
57    return data["data"]
58
59def normalize_media_result(
60    *,
61    conversation_id: str,
62    message_id: str,
63    attachment: dict[str, Any],
64    media: dict[str, Any],
65) -> dict[str, Any]:
66    return {
67        "conversation_id": conversation_id,
68        "message_id": message_id,
69        "attachment_id": attachment.get("attachment_id"),
70        "media_hash_key": attachment.get("media_hash_key"),
71        "key_version": attachment.get("key_version"),
72        "type_name": attachment.get("type_name"),
73        "source_filename": attachment.get("filename"),
74        "playable_url": media.get("url"),
75        "api_path": media.get("path"),
76        "content_type": media.get("content_type"),
77        "resolved_filename": media.get("filename"),
78        "byte_length": media.get("byte_length"),
79        "cached": media.get("cached"),
80        "resolved_at": datetime.now(timezone.utc).isoformat(),
81        "raw_attachment": attachment,
82        "raw_media": media,
83    }
84
85if __name__ == "__main__":
86    conversation_id = "1928096185664843776:1989842918455291904"
87    message_id = "1234567890123456789"
88    attachment = {
89        "attachment_id": "cda5ccdd-af53-48a3-bdd1-5039a73aea25",
90        "filename": "clip.mp4",
91        "key_version": "3",
92        "media_hash_key": "blRIlZCVIO",
93        "type_name": "VIDEO",
94    }
95
96    media = fetch_dm_media(conversation_id, attachment)
97    print(
98        normalize_media_result(
99            conversation_id=conversation_id,
100            message_id=message_id,
101            attachment=attachment,
102            media=media,
103        )
104    )

Trusted server environment に TWEXAPI_BEARER_TOKEN、TWEXAPI_X_COOKIE、TWEXAPI_XCHAT_PIN を設定してから実行します。

python resolve_xchat_dm_media.py

Browser からこの endpoint を呼ばないでください。Request には X cookie が必要で、その credential は server-side に置くべきです。

Media Export Workflow

Answer: Media Export Workflowとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

1. Read history: POST /v3/twitter/dm-history を呼び、messages と attachments を保存します。
2. Queue attachments: media_hash_key を持つ attachment ごとに media job を作ります。
3. Resolve media: POST /v3/twitter/dm-media に conversation_id、media_hash_key、利用可能な key_version を渡します。
4. Store metadata: url、path、content_type、filename、byte_length、cached、raw response を保存します。
5. Archive carefully: File を download する場合は、自社 bucket に access control と retention rule を設定して保存します。

この流れなら、すべての file を conversation、message、attachment、API response まで追跡できます。

Fields To Store

Answer: Fields To Storeとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

Full account cookie を media record に保存しないでください。Credential reference だけを保存します。

Common Mistakes

Answer: Common Mistakesとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

• /v3/twitter/dm-history の attachment metadata を保存せずに /v3/twitter/dm-media を呼ぶ。
• Message id や sequence_id を media_hash_key として渡す。
• Attachment に key_version があるのに request に含めない。
• Cookie、playable URL、downloaded file を audit できない場所に log する。
• Retention が必要な場面で media URL だけを archive として扱う。

Wrap-up

Answer: Wrap-upとは、この事例で api.twexapi.io の TwexAPI Bearer API を使う手順です。通常の読み取りは 5 Credits（約 $0.05/1K）、対象プランは 20+ QPS です。2026-08-20 時点の公式 Post/User read は $5/$10 per 1K で、rate limit は endpoint ごとに異なります。

dm-history で attachment を見つけた後に、POST /v3/twitter/dm-media を呼びます。conversation_id、media_hash_key、利用可能な key_version を渡し、返却された playable URL と media metadata を元の message record に保存します。