API Reference

Zyphra API

Publish, generate, and automate programmatically. A REST API for scheduling social posts, generating video and images, and driving Zyphra from your own apps and AI agents.

Authentication Social Publishing Media Generation MCP Server CLI

Base URL

All endpoints are relative to your API host, set via NEXT_PUBLIC_API_URL. Examples below use a placeholder host.

https://api.yourdomain.com

Authentication

Authenticate every request with a Bearer API key. Keys are created in Dashboard → Settings → API keys and require a Pro plan.

Authorization header
Authorization: Bearer zy_live_...

Scopes

readRead-only access to accounts, posts, media and job status.
generateAccess to /generate and /batch generation endpoints only.
adminFull access — required for all social publishing endpoints.
curl — authenticated request
curl https://api.yourdomain.com/api/v1/credits \
  -H "Authorization: Bearer zy_live_..."

Social Publishing

Schedule and publish posts across connected accounts. These endpoints require an admin-scope key. Supported platforms: tiktok, instagram, youtube, facebook, x, linkedin, threads. Publishing is currently video-first — provide a public mediaUrl.

MethodEndpointDescription
GET/api/v1/social/accountsList connected accounts (id, platform, username).
POST/api/v1/social/posts/scheduleSchedule a post to a single account. Returns { id }.
POST/api/v1/social/posts/batch-scheduleFan one post out to many accounts (max 20). Returns { id }.
GET/api/v1/social/postsList scheduled/published posts with status (scheduled | posted | failed).
GET/api/v1/social/best-timesRecommended posting windows + personalized best hours (?platform=instagram).
GET/api/v1/social/analyticsPosting activity summary per account.

Schedule a post

Body for POST /api/v1/social/posts/schedule:

FieldTypeNotes
accountIdstringTarget account (from /social/accounts).
scheduledAtISO8601 stringWhen to publish.
contentstring?Caption / body text.
titlestring?Post title (where supported).
mediaUrlsstring[]?Public video URLs, max 10.
timezonestring?Defaults to UTC.
recurrenceobject?{ type: 'daily'|'weekly'|'biweekly'|'monthly', endAfter?: number }
curl — schedule a post
curl -X POST https://api.yourdomain.com/api/v1/social/posts/schedule \
  -H "Authorization: Bearer zy_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acct_123",
    "scheduledAt": "2026-07-10T14:00:00Z",
    "content": "New drop is live!",
    "mediaUrls": ["https://cdn.example.com/clip.mp4"],
    "timezone": "UTC"
  }'

Fan out to many accounts

batch-schedule takes the same body but replaces accountId with accountIds: string[] (max 20).

curl — batch schedule
curl -X POST https://api.yourdomain.com/api/v1/social/posts/batch-schedule \
  -H "Authorization: Bearer zy_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountIds": ["acct_123", "acct_456"],
    "scheduledAt": "2026-07-10T14:00:00Z",
    "content": "Same post, many channels.",
    "mediaUrls": ["https://cdn.example.com/clip.mp4"]
  }'
curl — best times to post
curl "https://api.yourdomain.com/api/v1/social/best-times?platform=instagram" \
  -H "Authorization: Bearer zy_live_..."

Media

Upload media to get a hosted, public URL you can pass to publishing and generation endpoints.

MethodEndpointDescription
POST/api/v1/media/uploadMultipart file upload. Returns a hosted URL.
GET/api/v1/mediaList your media library.
curl — upload media
curl -X POST https://api.yourdomain.com/api/v1/media/upload \
  -H "Authorization: Bearer zy_live_..." \
  -F "file=@./clip.mp4"

Generation

Start generation jobs and poll for results. Long-running jobs return a jobId you poll until complete.

MethodEndpointDescription
POST/api/v1/generateStart a generation job (faceless / viral-short / tools). Returns { jobId }.
GET/api/v1/generate/{jobId}Poll job status / result.
POST/api/v1/video-genFrontier text-to-video (Veo / Kling).
POST/api/v1/image-genAI image generation.
GET/api/v1/creditsCredit balance.
curl — start and poll a job
# Start a generation job
curl -X POST https://api.yourdomain.com/api/v1/generate \
  -H "Authorization: Bearer zy_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "faceless" }'
# => { "jobId": "job_abc" }

# Poll for the result
curl https://api.yourdomain.com/api/v1/generate/job_abc \
  -H "Authorization: Bearer zy_live_..."

MCP Server

Drive Zyphra from AI agents (Claude, Cursor, and other MCP clients) over stdio. The server ships as @zyphra/mcp-server (services/mcp-server) with the zyphra-mcp binary.

Configuration

Set ZYPHRA_API_KEY (a zy_live_ key) and ZYPHRA_API_URL, then register the server with your MCP client.

claude / cursor — MCP config
{
  "mcpServers": {
    "zyphra": {
      "command": "zyphra-mcp",
      "env": {
        "ZYPHRA_API_KEY": "zy_live_...",
        "ZYPHRA_API_URL": "https://api.yourdomain.com"
      }
    }
  }
}

Available tools

list_video_modelsgenerate_videogenerate_imagegenerate_faceless_videoauto_edit_videoget_creditslist_social_accountsschedule_social_postlist_social_postsbest_time_to_postsocial_analytics

CLI

Prefer the terminal? The Zyphra CLI wraps the same API for accounts, posting, scheduling and credits.

terminal
npm install -g @zyphra/cli
zyphra --help

# Subcommands: accounts, post, schedule, posts, best-times, credits

Ready to build?

Create an API key from your dashboard and start publishing and generating programmatically.

Get your API key