Tool reference
All 41 tools your agent can call, straight from the running server — if it is listed here, it is registered. Authentication is your API key as a bearer token, so no tool takes it as an argument; see Start here for the setup.
Generate
Render media. These are the only tools that spend credits, and only on success.
generate_image
Generate image(s) from text (+ optional reference). Bills only on success.
- prompt strrequired
- model str
- aspect_ratio str
- n int
- reference_id str
- idempotency_key str
generate_video
Submit an async video render. Returns a job_id; poll get_job. Bills only on success.
- prompt str
- model str
- duration_s int
- aspect_ratio str
- input_image_url str
- reference_id str
- idempotency_key str
list_models
List available image/video models with capabilities and coarse cost/latency hints.
- media_type str
estimate_cost
Pre-flight credit estimate for a generate_image|generate_video request, or for a whole visual template via template_id (composite templates sum their generation steps; compose steps contribute 0). Free.
- kind str
- params object
- template_id str
register_reference
Register a character/style reference (v1.1); pass the reference_id to generate_* for consistency across generations.
- kind strrequired
- source_image_url strrequired
- label str
get_job
Poll a job's status; returns assets when succeeded. Free — never bills.
- job_id strrequired
Presets & brand
Multi-step templates that fan out generations and assemble one deliverable, plus the brand kits they render in.
create_visual
Generate an image/carousel/video from a visual template (see list_visual_templates). Renders through the normal generation pipeline — bills like generate_* on success. Poll get_visual_status.
- template_id strrequired
- prompt str
- inputs object
- title str
- idempotency_key str
- brand_id str
get_visual_status
Poll a visual's render: queueing | generating-media | done | creation-from-template-failed. When done, media_url (video) and/or image_urls (slides) plug straight into create_post's media_urls. Free.
- visual_id strrequired
list_visual_templates
List visual templates (id, description, inputs) for create_visual. Each entry carries `spends_credits` and `generation_steps`, so you can tell a free preset from a billed one without pricing all of them — `spends_credits: false` means the render calls no model at all. For an exact number on the rest, `estimate_cost(template_id=...)`. Free.
- search str
- template_id str
upsert_brand_kit
Create or update a brand kit: palette (hex), fonts, logo, tone and standing copy. create_visual binds one via brand_id. boilerplate/default_hashtags are returned to you for create_post.text — SuperGen never appends them itself. Free.
- name strrequired
- brand_id str
- colors object
- fonts object
- logo_url str
- tone str
- boilerplate str
- default_hashtags any[]
list_brand_kits
List this account's brand kits. Free.
delete_brand_kit
Delete a brand kit. Free.
- brand_id strrequired
Accounts
Connect the social accounts you publish to.
connect_account
Start connecting a social account: open the returned authorize_url in a browser and approve access. Platforms: twitter, linkedin, youtube, instagram, tiktok, facebook, threads (new connects route via the upload-post aggregator when configured; native OAuth is the fallback for twitter/youtube/linkedin).
- platform strrequired
connect_telegram_channel
Finish connecting Telegram (see connect_account): pass your @channel username or numeric chat id after adding the bot as an admin. Free.
- channel strrequired
connect_bluesky_account
Connect a Bluesky account with an app password (Settings -> App Passwords on bsky.app — not your login password). Bluesky has no OAuth flow, so there is no authorize URL to open. Free.
- handle strrequired
- app_password strrequired
list_accounts
List the caller's connected social accounts; pass account_id to post_video/post_image.
- platform str
list_youtube_playlists
The connected YouTube channel's playlists; pass ids via create_post's platform_fields.playlist_ids (the YouTube analog of Pinterest boards). Free.
get_user
The authenticated account: email, plan, credit balance, connected social accounts. Use to verify the API key before other operations. Free.
Publish
Post now or hand a finished job straight to a platform.
create_post
Publish a post (text + optional public media URLs) to a connected account now, or schedule it with scheduled_time (ISO 8601, future) or use_next_free_slot. Never bills credits. platform_fields are typed per platform (see MCP_TOOLS §10); an unknown key is an error, not a silent drop. additional_posts ([{text, media_urls}]) posts a thread on twitter/bluesky. Returns a post_ id (published) or sched_ id (scheduled); poll get_post_status.
- account_id strrequired
- text str
- media_urls str[]
- platform_fields object
- scheduled_time str
- additional_posts object[]
- use_next_free_slot bool
post_image
Post a succeeded generate_image job's asset to a connected account (v1.2). Never bills credits. Retrying the same (job_id, account_id) never double-posts.
- job_id strrequired
- account_id strrequired
- platform_fields object
- idempotency_key str
post_video
Post a succeeded generate_video job's asset to a connected account (v1.2). Never bills credits. Retrying the same (job_id, account_id) never double-posts.
- job_id strrequired
- account_id strrequired
- platform_fields object
- idempotency_key str
get_post_status
Status of a create_post submission: scheduled | publishing | published | failed (+ platform_url when published). Free.
- post_submission_id strrequired
list_posts
List posts (scheduled, published, and failed), most recent first. Filters: status (scheduled|published|failed), platform, since/until (ISO 8601). Free.
- status str[]
- platform str[]
- since str
- until str
- limit int
Schedule
Queue posts for later; scheduling runs server-side, so your agent does not have to stay awake.
get_schedule
Get one scheduled post (draft content + scheduled time). Free.
- schedule_id strrequired
list_schedules
List pending scheduled posts, soonest first. Free.
- limit int
update_schedule
Update a pending schedule's content and/or time (ISO 8601, future). At least one field required; only still-scheduled posts are editable.
- schedule_id strrequired
- text str
- media_urls str[]
- platform_fields object
- scheduled_time str
delete_schedule
Delete a pending scheduled post; its publishing job is cancelled. Irreversible.
- schedule_id strrequired
Measure
How published posts performed.
get_post_analytics
Live engagement metrics (likes/comments/views/shares) for a published post. Twitter + YouTube; LinkedIn analytics aren't available self-serve. Free.
- post_id strrequired
list_top_posts
Top published posts ranked by likes_count | comments_count | views_count | shares_count over a time range (metrics fetched live). Each post carries the template_id it was generated from, if any; group_by="template_id" returns per-preset totals instead of individual posts. Free.
- sort_by str
- since str
- until str
- limit int
- platform str
- group_by str
Inbox
Comments and direct messages on what you published.
list_comments
Comments on a published post, newest first (YouTube posts only — of the supported platforms only YouTube has a self-serve comments API). Free.
- post_id strrequired
- limit int
get_comment
One comment by id (from list_comments). YouTube only. Free.
- comment_id strrequired
post_comment
Comment on one of your published posts, or reply to a comment via parent_comment_id. YouTube only. Never bills credits.
- post_id strrequired
- text strrequired
- parent_comment_id str
list_conversations
Direct-message conversations, most recent first (Twitter/X only — of the supported platforms only it has a self-serve DM API). Free.
- limit int
get_conversation
One DM conversation with participant ids (Twitter/X only). Free.
- conversation_id strrequired
list_messages
Direct messages, newest first; filter to one conversation with conversation_id. Each has direction incoming|outgoing (Twitter/X only). Free.
- conversation_id str
- limit int
get_message
One direct message by id (Twitter/X only). Free.
- message_id strrequired
send_message
Send a DM to a platform-native recipient id — an incoming message's sender_id or an outgoing one's recipient (Twitter/X only). Never bills credits.
- recipient_id strrequired
- text strrequired
Media in
Bring media and text into the pipeline: your own files, someone else's post, or a document to write from.
create_upload_url
Presigned URL pair for uploading a local file: HTTP PUT the raw bytes to upload_url (with the returned content_type header), then use public_url as a media_url in create_post. Free.
- filename strrequired
download_media
Download a public video from YouTube, Instagram or TikTok into SuperGen storage; the returned media_url plugs straight into create_post's media_urls (the repost pipeline). Up to 200MB. Free — never bills credits.
- url strrequired
create_source
Extract text content to write posts from. source_type: "text" (raw text), "article" (web page), "pdf", "twitter" (a tweet, via your connected X account), "youtube"/"tiktok" (the platform's caption track). All deterministic and free — billed_credits is always 0. Returns the extracted title/content inline.
- source_type strrequired
- url str
- text str
- custom_instructions str
get_source_status
Re-read a stored source (status, title, extracted content). Free.
- source_id strrequired