Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.genviral.io/llms.txt

Use this file to discover all available pages before exploring further.

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?

OpenClaw agents are automating social media at scale - generating images, writing captions, and posting daily content without manual effort. But wiring up separate APIs for TikTok, Instagram, YouTube, Pinterest, LinkedIn, and Facebook is a pain. Genviral gives you one unified API that handles all six platforms. Your OpenClaw agent - or any AI agent, cron job, or automation script - generates the content, calls our API, and we handle the rest.

​
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

Here’s how a typical OpenClaw agent uses the Genviral API to automate social media posting across all 6 platforms:
  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
The entire loop runs autonomously. Your agent does 95% of the work. You add the finishing touches. We also have an official OpenClaw skill for Genviral that wraps the full API into 42+ commands your agent can use out of the box - covering accounts, slideshows, posts, image packs, templates, and analytics.

​
Supported Platforms

PlatformPostingAnalyticsSlideshow / Carousel
TikTokYesYesYes (Photo Mode)
InstagramYesYesYes (Carousel)
YouTubeYesYesYes (Shorts)
FacebookYes-Yes
PinterestYes-Yes (Idea Pins)
LinkedInYes-Yes

​
Base URL

All requests target the main Genviral origin. Scope is inferred from the API key metadata (scope, workspace_id, owner_user_id): 
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.
Keys are formatted as <public_id>.<secret> (for example, gva_live_x1y2z3.abcd1234) and must be passed in the Authorization header: 
Authorization: Bearer <public_id>.<secret>
API keys are single-scope credentials. A key is either workspace-scoped (workspace_id set) or personal-scoped (owner_user_id set). Requests never fall through to unscoped data.

​
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).
  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.
music_url is TikTok-only today. Instagram’s official publishing API does not expose music/sound selection for carousel posts or Reels, so if you want TikTok music and Instagram delivery for the same creative, send separate platform-specific requests.
Building an OpenClaw agent? Use our official Genviral skill to skip the boilerplate. It wraps every API endpoint into simple commands your agent can call directly - including automated posting loops with analytics-driven strategy adjustment.

​
Quick Start: Post a TikTok Slideshow

Here’s the fastest path from zero to a TikTok slideshow post - the exact workflow an OpenClaw agent would run: 
# 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

Before posting, validate this checklist:
  • caption is always required. The final allowed length depends on the targeted accounts: Hosted Accounts 500; Facebook 63,206; Instagram 2,200; TikTok 2,200 for video captions / 4,000 for photo-post descriptions; LinkedIn 3,000; Pinterest 800; YouTube 5,000 bytes.
  • 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.
  • only tiktok and pinterest platform-specific objects are accepted today. facebook, instagram, linkedin, and youtube settings objects are rejected with 422 invalid_payload.
That’s it. Six slides, one API call, posted to TikTok drafts. Open TikTok, add a trending sound, and publish. Your agent handles everything else.

​
Postman Collection

Import the curated collection (accounts, files, folders, Studio AI generation, posts, slideshows, analytics, trends, packs, and templates) in seconds:
  • 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.
After importing, fill in the collection variables (base_url, partner_api_token, post_id, slideshow_id, pack_id, template_id, image_id, slide_index, video_id, folder_id, analytics_target_id, analytics_refresh_id) and you’ll be able to run the end-to-end workflow described above.

​
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.