Genviral API – Social Media Posting API for OpenClaw Agents & AI Automation

The social media posting API built for AI agents. Generate TikTok slideshows, post Instagram carousels, schedule YouTube Shorts, publish Pinterest pins, share to LinkedIn, and distribute to Facebook - all from one API. Works with OpenClaw, Claude Code, and any automation pipeline.

​

Why Genviral?

​

What makes Genviral different

• 6 platforms, 1 API - Post to TikTok, Instagram, YouTube, Facebook, Pinterest, and LinkedIn through a single endpoint. No platform-specific OAuth juggling.
• Built for AI agents - Designed from the ground up for OpenClaw agents, Claude Code workflows, and programmatic automation. Simple REST API with clear JSON responses that any AI can parse.
• TikTok slideshow support - Generate and post TikTok photo carousels (the format getting 2.9x more engagement than video). Upload as drafts via MEDIA_UPLOAD mode so you can add trending sounds before publishing.
• Full content pipeline - Don’t just post. Generate AI slideshows, manage image packs, create reusable templates, render final assets, and track analytics - all through the API.
• Hosted accounts included - Use your own connected accounts (BYO) or our managed hosted creator accounts for instant distribution at scale.
• Real analytics - Track views, likes, comments, shares, and engagement rates across all platforms. Your agent can read the data and adapt its strategy automatically.

​

Who uses this API

• OpenClaw agents automating daily TikTok slideshows and Instagram carousels
• Claude Code users building social media automation pipelines
• Indie developers promoting their apps on TikTok, Instagram, and YouTube without manual effort
• Agencies scheduling content across dozens of accounts on all 6 platforms
• Growth teams running programmatic posting campaigns with analytics feedback loops

​

The OpenClaw + Genviral Workflow

1. Agent generates images (via OpenAI, Fal, Replicate, or any image API)
2. Agent calls Genviral to upload images, create slideshows, add text overlays, and render final slides
3. Agent posts to TikTok as a draft (MEDIA_UPLOAD mode), so you can add trending sounds before publishing
4. Agent posts to Instagram, YouTube, Pinterest, LinkedIn, Facebook directly (DIRECT_POST mode)
5. Agent checks analytics via the API to see what’s performing
6. Agent adapts - adjusts hooks, timing, and content based on real performance data

​

Supported Platforms

​

Base URL

https://www.genviral.io/api/partner/v1

​

Authentication & API Keys

1. Sign in at www.genviral.io.
2. Open the API Keys page.
3. Choose key scope:
   • Personal for Creator/Professional usage without workspace selection.
   • Workspace for Business team usage in a specific workspace.
4. Generate a key and store the token (returned once) in your secrets manager.

Authorization: Bearer <public_id>.<secret>

​

Scope-Aware Access

• Accounts: GET /accounts returns accounts in key scope only. Workspace keys return workspace accounts; personal keys return accounts where user_id = owner_user_id and workspace_id IS NULL.
• Posts/files/folders/slideshows/packs/templates: all endpoints enforce the same scope boundary from the key.
• Billing & tiers: Partner API requires an active Creator, Professional, or Business subscription (402 subscription_required when missing). Scheduler tier is blocked (403 tier_not_allowed).

​

Recommended Workflow

1. Discover accounts via GET /accounts and cache the IDs you’ll target.
2. Assemble payloads with captions, media URLs, TikTok-only music metadata, and per-account targeting.
3. Schedule posts through POST /posts, optionally adding scheduled_at and external_id.
4. Track delivery using GET /posts for scope-wide status and GET /posts/{id} for canonical per-account states.
5. Retry or edit posts using the dedicated PATCH /posts/{id} and POST /posts/retry endpoints when platforms require another attempt.

​

Quick Start: Post a TikTok Slideshow

# 1. List your connected TikTok accounts
curl -s https://www.genviral.io/api/partner/v1/accounts \
  -H "Authorization: Bearer $GENVIRAL_TOKEN" | jq '.data.accounts[] | select(.platform == "tiktok")'

# 2. Post a slideshow to TikTok as a draft (so you can add trending sounds)
curl -X POST https://www.genviral.io/api/partner/v1/posts \
  -H "Authorization: Bearer $GENVIRAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "My landlord said I can'\''t change anything so I showed her what AI thinks it could look like",
    "media": {
      "type": "slideshow",
      "urls": [
        "https://your-cdn.com/slide-1.jpg",
        "https://your-cdn.com/slide-2.jpg",
        "https://your-cdn.com/slide-3.jpg",
        "https://your-cdn.com/slide-4.jpg",
        "https://your-cdn.com/slide-5.jpg",
        "https://your-cdn.com/slide-6.jpg"
      ]
    },
    "accounts": [{ "id": "YOUR_TIKTOK_ACCOUNT_ID" }],
    "tiktok": {
      "post_mode": "MEDIA_UPLOAD",
      "privacy_level": "SELF_ONLY"
    }
  }'

​

POST /posts preflight checklist

• caption is 1..500 characters.
• accounts uses canonical shape: [{ "id": "<uuid>" }].
• media is a nested object:
  • video: { "type": "video", "url": "https://..." }
  • slideshow: { "type": "slideshow", "urls": ["https://...", "..."] }
• scheduled_at is omitted for immediate posting, or sent as ISO 8601 string (do not send null).
• every media URL is a real URL string (no serialized fragments, placeholders, or partial fields).
• use tiktok (not tiktok_settings) when sending TikTok options.

​

Postman Collection

• Download collection
• File lives in this repo at genviral-docs/api-reference/postman-collection.json, and the same JSON is mirrored to www.genviral.io/postman-collection.json so partners always have a stable URL to reference.

​

Next Steps

• Response Pattern - learn the ok/code/message contract used everywhere.
• Data Structures - understand the shapes returned for API keys, accounts, posts, and stats.
• Studio AI - generate partner-scoped AI Studio images/videos and poll video jobs by video_id.
• Create Post - start posting to TikTok, Instagram, YouTube, Pinterest, LinkedIn, and Facebook.
• Get Trend Brief - fetch a one-call TikTok trend brief for agent planning.
• Slideshows - generate AI slideshows, manage content, and render final assets.
• OpenClaw Skill - plug in the ready-made skill and let your agent handle the rest.