giggle-official/x2c-socialposter

简体中文 | English

X2C Social Poster

Source: storyclaw-official/skills · Dashboard: x2creel.ai

Publish posts, manage comments, and upload media to 13+ social platforms via X2C Open API. Features smart upload (auto-selects pre-signed URL for large files), per-platform validation, and one-step publish with local files.

---

Installation Requirements

| Requirement | Value | |-------------|-------| | Binary | python3 | | Environment | X2C_API_KEY (required; obtain from X2C Dashboard) | | Pip | requests |

Set X2C_API_KEY before use. The script will prompt if not configured.

---

First-Time Setup Guide

When the user invokes this skill for the first time, follow these onboarding steps IN ORDER:

Step 0: Check API Key

python3 scripts/x2c_social.py --action check-key

• If the key is set → proceed to Step 1.
• If the key is NOT set → guide the user:

🔑 X2C API Key is not configured yet. Let's set it up:

1. Go to https://www.x2creel.ai/social-accounts and sign up / log in
2. Click "Link Account" to connect your social media accounts (TikTok, Instagram, etc.)
3. On the same page, scroll down to "Developer API Key" section and click "Get API Key"
4. Copy your X2C Open API Key and paste it here

Once you provide the key, I'll save it for you.

Step 1: Verify Linked Accounts

python3 scripts/x2c_social.py --action status

Display the linked platforms. If none are linked:

⚠️ No social accounts linked yet.
Please visit https://www.x2creel.ai/social-accounts to link your accounts.

---

Platform Requirements Quick Reference

Before publishing, always check the target platform's requirements and guide the user accordingly.

| Platform | ID | Media Required | Text Limit | Max Media | Supported Types | Key Constraints | |----------|-----|:---:|---:|:---:|---|---| | YouTube | youtube | ✅ (video) | title:100 desc:5,000 | 1 video | MP4, MOV, AVI, WMV | --title required (auto-gen if missing, max 100 chars). Default visibility = public. | | Instagram | instagram | ✅ | 2,200 | 10 (carousel) | JPEG, PNG, MP4 | Must be Business/Creator. No text-only. Max 5 hashtags, 3 @mentions. | | TikTok | tiktok | ✅ | 2,200 | 1 video or 35 images | MP4, JPG, JPEG, WEBP | Images & video can't mix. No PNG. No \n in text. AI content must mark --ai-generated. | | X (Twitter) | twitter | ❌ | 280 | 4 images or 1 video | JPEG, PNG, GIF, MP4 | Images and videos can't mix. BYO API keys required. Use longPost for >280 chars. | | Facebook | facebook | ❌ | 63,206 | 10+ | JPEG, PNG, MP4 | Must be a Page (not personal). | | LinkedIn | linkedin | ❌ | 3,000 | 9 | JPEG, PNG, GIF, MP4 | Personal or Company page. | | Pinterest | pinterest | ✅ | 500 | 5 (carousel) | JPEG, PNG | Image required. Video requires --thumbnail. | | Reddit | reddit | ❌ | title:300 post:40,000 | 1 | JPEG, PNG, GIF, MP4 | --title required. --subreddit required. | | GMB | gmb | ❌ | 1,500 | 1 | JPEG, PNG, MP4 | Verified business. No phone numbers in text. | | Bluesky | bluesky | ❌ | 300 | 4 | JPEG, PNG, MP4 | 300 chars including links. | | Threads | threads | ❌ | 500 | 10 (carousel) | JPEG, PNG, MP4 | Linked to Instagram account. | | Snapchat | snapchat | ✅ | 160 | 1 | JPEG, PNG, MP4 | Exactly 1 media item. | | Telegram | telegram | ❌ | 4,096 | 1 | JPEG, PNG, GIF, MP4 | Bot + Channel/Group. |

⚠️ Multi-Platform Posting Caveat

When posting to multiple platforms simultaneously, content guards apply sequentially — the shortest character limit wins and will truncate for all platforms. If you need different text per platform, make separate publish calls.

Platform-Specific Parameters

When publishing to these platforms, the script automatically validates and builds platform options:

| Parameter | Platforms | Description | |-----------|-----------|-------------| | --title | YouTube, Reddit | Post/video title (required). YouTube auto-generates from post text if missing (max 100 chars). | | --subreddit | Reddit | Target subreddit without r/ (required) | | --visibility | YouTube, TikTok | public/unlisted/private (YT), PUBLIC_TO_EVERYONE/SELF_ONLY etc. (TT) | | --thumbnail | Pinterest | Thumbnail URL for video pins (required for video) | | --ai-generated | TikTok | Mark content as AI-generated (recommended for AI content) |

---

Media Upload

The script uses smart upload — automatically selects the best method based on file size:

| Method | File Size | Limit | How It Works | |--------|-----------|-------|-------------| | Direct upload | ≤ 50MB | ~50MB | One-step multipart upload | | Pre-signed URL | > 50MB | 5GB | Gets S3 pre-signed URL → PUT directly to S3 |

This is handled automatically — the user just provides a file path and the script picks the right method.

Standalone Upload

# Small file → direct upload
python3 scripts/x2c_social.py --action upload --file /path/to/image.jpg

# Large file → auto pre-signed upload
python3 scripts/x2c_social.py --action upload --file /path/to/large_video.mp4 --folder videos

One-Step Publish with Local Files

When publishing, local files are auto-uploaded before publishing — no separate upload step needed:

# 75MB video → auto pre-signed upload → publish
python3 scripts/x2c_social.py --action publish \
  --platforms tiktok instagram \
  --post "Check this out! 🎬" \
  --media-files /path/to/large_video.mp4

Output flow:

{"status": "uploading", "file": "large_video.mp4", "size_mb": 75.2, "method": "presigned", "message": "..."}
{"status": "uploaded", "file": "large_video.mp4", "url": "https://v.arkfs.co/.../large_video.mp4", "method": "presigned"}
{"success": true, "data": {"id": "post_abc123", "postIds": [...]}}

---

Commands

1. Check Linked Accounts

python3 scripts/x2c_social.py --action status

2. Publish Post

# Text-only (works for: twitter, facebook, linkedin, reddit, gmb, bluesky, threads, telegram)
python3 scripts/x2c_social.py --action publish \
  --platforms twitter facebook \
  --post "Hello world! 🚀"

# With local file — auto-uploaded (any size up to 5GB)
python3 scripts/x2c_social.py --action publish \
  --platforms tiktok instagram \
  --post "Watch this! 🎬" \
  --media-files /path/to/video.mp4

# With remote URL
python3 scripts/x2c_social.py --action publish \
  --platforms tiktok instagram \
  --post "Watch this! 🎬" \
  --media-urls "https://example.com/video.mp4"

# Mix local + remote
python3 scripts/x2c_social.py --action publish \
  --platforms facebook \
  --post "Double media! 🎬" \
  --media-files /local/video.mp4 \
  --media-urls "https://cdn.example.com/image.jpg"

# YouTube — title required
python3 scripts/x2c_social.py --action publish \
  --platforms youtube \
  --post "Video description here" \
  --title "My YouTube Video" \
  --visibility public \
  --media-files /path/to/video.mp4

# Reddit — title + subreddit required
python3 scripts/x2c_social.py --action publish \
  --platforms reddit \
  --post "Post body text" \
  --title "Discussion: AI in 2026" \
  --subreddit technology

# TikTok — mark AI content
python3 scripts/x2c_social.py --action publish \
  --platforms tiktok \
  --post "AI generated content" \
  --ai-generated \
  --media-files /path/to/ai_video.mp4

# Scheduled post
python3 scripts/x2c_social.py --action publish \
  --platforms tiktok instagram \
  --post "Coming soon! ⏰" \
  --media-files /path/to/video.mp4 \
  --schedule "2026-04-01T12:00:00Z"

# Shorten links
python3 scripts/x2c_social.py --action publish \
  --platforms twitter linkedin \
  --post "Read our blog: https://example.com/very-long-url" \
  --shorten-links

3. Get Post History

python3 scripts/x2c_social.py --action posts
python3 scripts/x2c_social.py --action posts --platform tiktok

4. Delete Post

python3 scripts/x2c_social.py --action delete-post --post-id post_abc123
python3 scripts/x2c_social.py --action delete-post --post-id post_abc123 --bulk

5. Post Comment

python3 scripts/x2c_social.py --action comment \
  --post-id post_abc123 --platforms tiktok --comment "Great! 🔥"

6. Get Comments

python3 scripts/x2c_social.py --action comments --post-id post_abc123 --platform tiktok

7. Reply to Comment

python3 scripts/x2c_social.py --action reply \
  --comment-id comment_xyz --platforms tiktok --comment "Thanks!"

8. Delete Comment

python3 scripts/x2c_social.py --action delete-comment --comment-id comment_xyz

9. Upload Media (standalone)

python3 scripts/x2c_social.py --action upload --file /path/to/file.mp4 --folder videos

---

Parameter Reference

| Parameter | Required | Description | |-----------|----------|-------------| | --action | ✅ | Action to perform | | --post | for publish | Post text content | | --platforms | for publish | Space-separated target platforms | | --platform | for filtering | Single platform filter | | --media-urls | ❌ | Remote URLs or local paths (auto-uploaded) | | --media-files | ❌ | Local file paths to auto-upload and attach | | --schedule | ❌ | ISO 8601 date for scheduled posting | | --shorten-links | ❌ | Shorten URLs in post text | | --title | YouTube, Reddit | Post/video title | | --subreddit | Reddit | Target subreddit (without r/) | | --visibility | YouTube, TikTok | Post visibility setting | | --thumbnail | Pinterest | Video thumbnail URL | | --ai-generated | TikTok | Mark as AI-generated content | | --post-id | for post ops | Ayrshare post ID | | --comment-id | for comment ops | Comment ID | | --comment | for comment/reply | Comment or reply text | | --bulk | ❌ | Delete from all platforms | | --file | for upload | Local file path to upload | | --folder | ❌ | Upload subfolder (default: uploads) |

---

Interaction Guide

When the user request is vague, guide per the steps below. If the user has provided enough info, run the command directly.

Step 1: Onboarding Check

Always run the First-Time Setup Guide first. Verify API key and linked accounts.

Step 2: Determine Intent

What would you like to do?
Options:
  📝 Publish a post
  📊 View post history
  💬 Manage comments
  📤 Upload media
  🔗 Check linked accounts

Step 3: For Publishing — Platform-Aware Guidance

1. Ask which platforms → show only linked platforms from status check.

2. Check platform requirements and proactively ask for required fields:

   • YouTube → ask for --title and --visibility
   • Reddit → ask for --title and --subreddit
   • Instagram/TikTok/Pinterest/Snapchat → remind media is required
   • TikTok with AI content → suggest --ai-generated

3. Ask for post content → check text length against platform limits.

4. Ask about media → accept local files or remote URLs. Local files auto-upload (any size).

5. Ask about scheduling → publish now or schedule for later.

Step 4: Execute and Display

Run the command. The script will:

1. Auto-upload local files (smart method selection)
2. Validate against platform requirements
3. Build platform-specific options
4. Publish and return per-platform results

Display results clearly, highlighting any per-platform success/failure.

---

Error Handling

| Code | Meaning | Action | |------|---------|--------| | 400 | Missing/invalid parameters | Check platform requirements and fix | | 401 | Invalid API key | Guide user to verify/reset key | | 500 | Server error | Retry or inform user |

The script also performs client-side validation before calling the API:

• Text length per platform
• Media required check
• Required fields (title, subreddit)
• Media count limits (Snapchat = 1)

Fatal validation errors block the publish. Warnings are displayed but don't block.