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

# X (Twitter) API Python media tweets & DM attachments

> Upload media with the Xquik Python SDK, post tweets with photos or video, and send DM attachments from a connected X (Twitter) account in your own apps.

> For the complete documentation index, see [llms.txt](https://docs.xquik.com/llms.txt).

This guide builds on the [Python SDK setup](https://docs.xquik.com/sdks/python.md), which covers install and authentication.

## Workflow to post media tweets and DM attachments

Use this workflow to post a media tweet or reply. Use it too to DM 1 uploaded media item.




Tweet and reply media posts use public media URLs directly on `client.x.tweets.create`. Send up to 4 image URLs or exactly 1 MP4 video URL. The video can be up to 100 MB. Do not mix video with other media. Do not upload first when the media URL is already public.

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
import json
import sys
from typing import Any

from x_twitter_scraper import XTwitterScraper

client = XTwitterScraper()

def create_tweet_handoff(
    action: dict[str, Any],
    base: dict[str, Any],
) -> dict[str, Any]:
    result = action.get("result") or {}
    return {
        "status": action["status"],
        "terminal": action["terminal"],
        "safe_to_retry": action["safeToRetry"],
        "write_action_id": action["id"],
        "request_hash": action["request"]["hash"],
        "tweet_id": result.get("id") or action.get("tweetId"),
        "charged": action["billing"]["charged"],
        "charged_credits": action["billing"]["chargedCredits"],
        "poll": None if action["terminal"] else action["statusUrl"],
        **base,
    }
```

Use `with_raw_response.create` to capture the durable write action. Send a unique `Idempotency-Key`. Store `id`, `request.hash`, `billing`, `result`, and `statusUrl`. Poll while `terminal` is false. Retry only when `safeToRetry` is true, using a new key.

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
response = client.x.tweets.with_raw_response.create(
    account="@username",
    text="New demo video is live.",
    media=["https://example.com/product-demo.mp4"],
)
payload = response.json()

tweet_handoff = create_tweet_handoff(
    payload,
    {
        "account": "@username",
        "media": ["https://example.com/product-demo.mp4"],
    },
)

sys.stdout.write(json.dumps(tweet_handoff, ensure_ascii=False) + "\n")
```

To post an image reply, add `reply_to_tweet_id`.

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
response = client.x.tweets.with_raw_response.create(
    account="@username",
    text="Here is the requested screenshot.",
    reply_to_tweet_id="1893704267862470862",
    media=["https://example.com/export-preview.png"],
)
payload = response.json()

reply_handoff = create_tweet_handoff(
    payload,
    {
        "account": "@username",
        "reply_to_tweet_id": "1893704267862470862",
        "media": ["https://example.com/export-preview.png"],
    },
)

sys.stdout.write(json.dumps(reply_handoff, ensure_ascii=False) + "\n")
```

For DM attachments, upload the local file first. Then pass the returned `media.media_id` as the only `media_ids` item.

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
import json
import sys
from pathlib import Path

media = client.x.media.upload(
    account="@username",
    file=Path("./handoff.png"),
)

dm = client.x.dm.send(
    user_id="44196397",
    account="@username",
    text="Here is the asset.",
    media_ids=[media.media_id],
)

dm_handoff = {
    "status": "sent",
    "message_id": dm.message_id,
    "media_id": media.media_id,
    "account": "@username",
    "user_id": "44196397",
}

sys.stdout.write(json.dumps(dm_handoff, ensure_ascii=False) + "\n")
```

`client.x.tweets.create` returns `tweet.tweet_id` for confirmed posts. Raw create responses can also include the pending write fields above while confirmation runs. `client.x.media.upload` returns `media.media_id` for DM attachments. `client.x.dm.send` returns `dm.message_id` for support tickets, CRM records, queue jobs, or agent memory.




Keep DM body text in private systems. Shared logs, public artifacts, queue status, and agent handoffs should omit full DM bodies. They should store `message_id`, optional `media_id`, `account`, `user_id`, and send status. Leave `reply_to_message_id` unset even if generated SDK types expose it. The REST endpoint rejects DM reply threading.




`client.x.dm.delete_message` [deletes a DM](https://docs.xquik.com/api-reference/x-write/delete-dm.md).




Text-only tweet and reply writes cost 30 credits. Tweet media adds 2 credits per started MB across attached files. Uploading media costs 10 credits. Sending the DM costs 10 credits. Do not pass uploaded `media.media_id` values to `client.x.tweets.create`. That method uses `media` with public media URLs.

### REST routes

| Task | REST route | Reference |
| - | - | - |
| Post a media tweet or reply | `POST /x/tweets` | [Create tweet](https://docs.xquik.com/api-reference/x-write/create-tweet.md) |
| Upload a local file | `POST /x/media` | [Upload media](https://docs.xquik.com/api-reference/x-write/upload-media.md) |
| Send a DM attachment | `POST /x/dm/{userId}` | [Send DM](https://docs.xquik.com/api-reference/x-write/send-dm.md) |
| Check a write action | `GET /x/write-actions/{id}` | [Write action status](https://docs.xquik.com/api-reference/x-write/get-write-action-status.md) |
| Delete a DM | `DELETE /x/dm/{userId}/messages/{messageId}` | [Delete DM](https://docs.xquik.com/api-reference/x-write/delete-dm.md) |

## Next steps

* [Python SDK setup](https://docs.xquik.com/sdks/python.md)
* [Tweet search](https://docs.xquik.com/sdks/python-tweet-search.md)
* [Follower export](https://docs.xquik.com/sdks/python-follower-export.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.