BulkAPIs Documentation

Social media automation + 50 generative AI models in one API. Copy the full reference below and paste it into any AI assistant to generate working integration code instantly.

Overview

BulkAPIs is a unified REST API for social media automation and generative AI. Connect X (Twitter) accounts, send DMs at scale, schedule posts, create comment-to-DM automations, and generate images, video, audio, and chat completions with 50+ AI models — all through one API key.

Base URL
https://bulkapis.com/api/v1


Authentication — Bearer token in every request:
Authorization: Bearer bulk_ak_your_api_key_here


Response envelope — Every response follows this shape:
json
{ "success": true, "data": { ... } }
{ "success": false, "error": { "code": "RATE_LIMITED", "message": "..." } }


Error codes: UNAUTHORIZED FORBIDDEN NOT_FOUND VALIDATION_ERROR RATE_LIMITED ACCOUNT_NEEDS_REAUTH PLATFORM_ERROR INTERNAL_ERROR DUPLICATE

Rate limits: 30 req/min for most endpoints, 5 req/min for bulk. Returned in headers.

Quick Start

1. Get your API key from the dashboard Settings page.

2. List connected accounts:
bash
curl https://bulkapis.com/api/v1/accounts \
  -H "Authorization: Bearer bulk_ak_your_key"


3. Send a DM:
bash
curl -X POST https://bulkapis.com/api/v1/dm/send \
  -H "Authorization: Bearer bulk_ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_ACCOUNT_ID",
    "recipientUserId": "1234567890",
    "text": "Hey! Reaching out about our new product.",
    "idempotencyKey": "outreach-user1234"
  }'


4. Generate an AI image:
bash
curl -X POST https://bulkapis.com/api/v1/ai/generate \
  -H "Authorization: Bearer bulk_ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": { "prompt": "A futuristic city at sunset, cyberpunk" }
  }'


5. Create a scheduled post:
bash
curl -X POST https://bulkapis.com/api/v1/posts \
  -H "Authorization: Bearer bulk_ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "YOUR_ACCOUNT_ID",
    "content": "Just shipped something cool",
    "scheduledFor": "2026-03-07T14:00:00Z"
  }'

AI Models

50+ generative AI models across image, video, video-render, chat, audio, music, and lipsync. All billed with credits (no separate API keys needed).

Pricing: $5 = 1,000 credits. Most models have a fixed credit cost per request. Lipsync and Chatterbox TTS use variable pricing based on output duration or text length.

Model types:
- Async (image, video, video-render, audio, music, lipsync) — Returns a taskId, poll for results
- Sync (chat/LLM) — Returns the response immediately

Image models (per image, resolution-aware — cost multiplied by `num_images`): Nano Banana 2 (10–19 credits by resolution: 1K→10, 2K→15, 4K→19), Nano Banana Pro (21–29 credits: 1K/2K→21, 4K→29), Nano Banana Edit (12–21 credits: 1K→12, 2K→16, 4K→21, supports image_urls array for face swap/multi-image edit), Seedream 3.0 (7 credits), Seedream 4.0-4.5 (8 credits, supports image_urls for editing/face swap), GPT Image 1.5 (18 credits), Flux-2 Pro (15 credits), 4o Image (15 credits), Flux Kontext (12 credits), Grok Imagine (12 credits), Qwen (3 credits), Z-Image (3 credits), Ideogram (10-12 credits), Imagen 4 (10-23 credits), Topaz/Recraft upscale (3-7 credits)

Video models (duration-aware — billed as `creditPerSecond × duration`): Seedance 2.0 (22-48 credits/s by resolution: 480p→22, 720p→48), Seedance 2.0 Fast (18-38 credits/s by resolution: 480p→18, 720p→38), Kling 3.0 (10 credits/s), Kling 2.6 (14 credits/s), Kling 2.5 Turbo (10 credits/s), Kling 2.1 Master (15 credits/s), Sora 2 (5 credits/s), Sora 2 Pro (8 credits/s), Runway Gen-3 (19 credits/s), Seedance 1.5 Pro (19 credits/s), Wan 2.6 (17 credits/s), Wan 2.6 Flash (10 credits/s), Wan 2.2 Turbo (8 credits/s), Hailuo 2.3 (15 credits/s), Hailuo 02 (12 credits/s), ByteDance V1 Pro (15 credits/s), ByteDance V1 Lite (8 credits/s). Flat-priced: Veo 3.1 Fast (69 credits, 8s clip), Veo 3.1 Quality (288 credits, 8s clip), Runway Aleph (115 credits), Grok Imagine Video (58 credits), Topaz Video Upscale (23 credits), Infinitalk (46 credits).

Lipsync models (variable pricing — billed per second of output video):
- OmniHuman v1.5 (38 credits/sec, max 1130 credits) — portrait image + audio → talking head video. Supports 720p/1080p.
- VEED Fabric 1.0 (35 credits/sec 720p, 19 credits/sec 480p, max 1035 credits) — portrait image + audio → talking head video.

Chat models (all support Vision — pass image URLs in messages array): GPT-5.2 (102 credits), Claude Sonnet 4.5 (69 credits), Claude Opus 4.5 (138 credits), Gemini 3 Flash (35 credits), Gemini 3 Pro (115 credits), Gemini 2.5 Flash (23 credits), Gemini 2.5 Pro (92 credits)

Audio models: ElevenLabs V3 (17 credits), ElevenLabs Turbo 2.5 (10 credits), ElevenLabs Multilingual V2 (12 credits), Chatterbox TTS (10 credits/1K chars, max 58 credits — open-source voice cloning), Sound Effect V2 (10 credits), Speech-to-Text (7 credits)

Music models: Suno (3 credits) — text to music, lyrics, covers, extensions

Video Render (Claude + Remotion — AI-composed video from assets + prompts):
- Video Render (8 credits/sec, max 1200 credits) — Send a prompt, system prompt, knowledge base, and media assets (images, audio, video URLs). Claude generates a Remotion composition, which is rendered to MP4. Supports custom dimensions, FPS, and up to 120s duration. Pass webhook_url to receive the rendered video URL asynchronously.

Per-model input/output schemas: Call GET /api/v1/ai/models — each model includes inputSchema (accepted fields with types, defaults, enums) and resultSchema (output shape). This is the source of truth for what each model accepts.

List all AI models with pricing and capabilities

AI Generation

Single endpoint for all AI generation. Routes automatically based on model type.

Async flow (image, video, audio, music, lipsync):
1. POST /api/v1/ai/generate → get taskId
2. Poll GET /api/v1/ai/tasks/{taskId} every 3-5s until status = completed or failed
3. Result contains URLs to generated media (valid 14 days)

Sync flow (chat/LLM):
1. POST /api/v1/ai/generate → immediate response with message

Webhooks: Optionally pass webhook_url to get notified on completion instead of polling.

Credits: Verified before generation. Deducted on completion (async) or immediately (sync).
- Image models with `resolution`: Cost varies by resolution tier (e.g. Nano Banana 2: 1K→9cr, 2K→14cr, 4K→18cr). When num_images > 1, total cost is multiplied.
- Video models with `duration`: Cost = creditPerSecond × duration (e.g. Kling 3.0: 9cr/s × 5s = 45cr, × 10s = 90cr).
- Lipsync models: Max credits reserved upfront, actual cost based on output video duration charged on completion.
- Chatterbox TTS: Cost = creditPerKChars × (textLength / 1000).

Input fields by category (use `GET /api/v1/ai/models` inputSchema for the full per-model spec):
- Image: prompt (required), aspect_ratio, resolution ("1K","2K","4K"), num_images, seed. For img-to-img: Nano Banana Pro/2 use image_input (array of URLs, up to 8/14); Nano Banana Edit uses image_urls (array, first is target, second is source for face swap); Seedream 4.0 uses image_url or image_urls. You can also pass image_url/image_urls to Nano Banana Pro/2 and they'll be auto-converted. See GET /api/v1/ai/models inputSchema for the exact per-model spec.
- Video: prompt (required), duration (5 or 10 — not applicable for Veo 3.1 which always produces 8s clips), aspect_ratio, image_url (for img-to-video), tail_image_url (Kling start+end frame, or Veo last frame when paired with image_url), first_frame_url/last_frame_url (Veo 3.1 first+last frame), image_urls (Veo 3.1: 1=animate, 2=first+last frame, 3=reference — Fast only), generationType (Veo 3.1: TEXT_2_VIDEO, FIRST_AND_LAST_FRAMES_2_VIDEO, REFERENCE_2_VIDEO — auto-detected if omitted; REFERENCE_2_VIDEO is Fast-only), negative_prompt, seed. Veo 3.1 comes in two variants: veo-3-1 (Fast, 69 credits) and veo-3-1-quality (Quality, 288 credits).
- Lipsync: image_url (portrait, required), audio_url (speech audio, required), resolution ("720p","1080p"), turbo_mode (boolean, OmniHuman only)
- Chat/LLM: messages (array, required). For vision: { role: "user", content: [{ type: "text", text: "..." }, { type: "image_url", image_url: { url: "https://..." } }] }. All chat models support vision.
- Audio/TTS: text (required), audio_url (reference voice for cloning), exaggeration, temperature, cfg, seed
- Speech-to-Text: audio_url (required), task ("transcribe"/"translate"), chunk_level ("segment"/"word"), language
- Music: prompt, customMode, instrumental, model ("V4"/"V4_5"/"V5")

Result shapes by category (returned in the result field of the task):
- Image: { "images": [{ "url": "https://...", "content_type": "image/jpeg" }] } — array with one entry per generated image
- Video: { "video": { "url": "https://...", "content_type": "video/mp4" } }
- Lipsync: { "video": { "url": "https://...", "content_type": "video/mp4" } }
- Audio/TTS: { "audio": { "url": "https://...", "content_type": "audio/mpeg" } }
- Speech-to-Text: { "text": "...", "chunks": [{ "text": "...", "timestamp": [0.0, 2.5] }] }
- Music: { "audio": { "url": "https://...", "content_type": "audio/mpeg" } }
- Chat: Returned immediately (not via taskId): { "message": { "role": "assistant", "content": "..." }, "usage": { ... } }

Generate AI content (image, video, chat, audio, music)

List AI tasks

Poll async task status and get results

Credits

Credits power all AI generation. $5 = 1,000 credits. Credits never expire.

Purchase: Dashboard or API. Payments via Stripe.

Tiers: 1,000 ($5) · 4,000 ($20) · 10,000 ($50) · 20,000 ($100) · Custom ($5 min)

Webhooks: Subscribe to credits.low to get notified when balance drops below 50 credits.

Get current credit balance

Purchase credits (opens Stripe checkout)

Credit transaction history

Accounts

Connect and manage social media accounts. Use the OAuth Connect endpoint to let your users connect their X/Twitter accounts without leaving your app.

OAuth Connect flow:
1. Call GET /api/v1/connect/x?redirect_url=https://yourapp.com/callback → returns an authorization_url
2. Redirect your user to that URL — they authorize on X
3. After authorization, X redirects back to your redirect_url with query params: ?connected=x&accountId=THE_BULKAPIS_ACCOUNT_ID&username=THE_X_USERNAME
4. Store the accountId — use it for all subsequent API calls (DMs, posts, etc.)

Initiate OAuth flow to connect an X/Twitter account

List connected social accounts

Get account details (platform, username, displayName, follower counts, needsReauth)

Disconnect an account

Check token health and rate limits

DMs

Send DMs individually or in bulk. Single sends are synchronous — you get back the X conversation ID immediately. Bulk sends are queued asynchronously. Use idempotencyKey to prevent duplicate sends.

Send a DM (synchronous, returns conversationId)

Send up to 100 DMs in one request

Inbox

List DM conversations

Get conversation with messages

Mark as read/archived

List messages in conversation

Send a message in a conversation

Posts

Create, schedule, and manage posts across connected accounts.

List posts

Create a post

Get post details

Update content or reschedule

Delete post

Re-queue a failed post

Publish immediately

Automations

Automations trigger DMs when someone interacts with your posts. Most common: comment-to-DM — someone comments a keyword, they get a DM automatically.

Trigger types: keyword_comment any_comment mention
Template variables: {{username}} {{comment}}

List automation rules

Create automation rule

Get rule with recent logs

Update rule

Delete rule

Execution logs

Comments

Read and reply to comments on posts. Use /comments/recent to list all recent mentions/replies for an account (no postId needed). Use /comments?postId=... to drill into a specific post. The inbox endpoint shows automation execution logs.

List all recent comments/mentions/replies for an account across all posts

List comments/replies for a specific post

List comments for a specific post

Reply to a post or tweet

List automation execution logs

Media

Upload media to attach to posts. Supported: images (JPG, PNG, WEBP ≤ 5 MB), animated GIFs (≤ 15 MB), videos (MP4, MOV ≤ 512 MB). Media is uploaded to X via the v2 API — static images use one-shot upload, videos and GIFs use chunked upload automatically.

List uploads

Initialize upload

Check upload status

Complete upload

Analytics

Post engagement metrics

Follower growth

Recommended posting times

Schedules

Define recurring time slots for auto-posting. When creating a post with queue: true, it's assigned to the next open slot.

List schedule slots

Create schedule

Get schedule

Update schedule

Delete schedule

Next available slot

Webhooks

Webhooks deliver real-time events via HTTP POST. Payloads signed with HMAC-SHA256.

Events: dm.received dm.sent dm.failed post.published post.scheduled post.failed post.deleted comment.received automation.triggered ai.task.completed ai.task.failed credits.low

Signature verification:
javascript
const crypto = require('crypto');
const sig = req.headers['x-bulkapis-signature'];
const expected = crypto.createHmac('sha256', secret)
  .update(JSON.stringify(req.body)).digest('hex');
if (sig !== expected) throw new Error('Invalid signature');


Payload shapes:

dm.received — { event: "dm.received", messageId, conversationId, senderId, text, accountId, platform, receivedAt }

dm.sent — { event: "dm.sent", jobId, messageId, conversationId, recipientUserId, accountId, platform }

dm.failed — { event: "dm.failed", conversationId, recipientId, text, accountId, platform, error, failedAt }

post.published — { event: "post.published", postId, accountId, platform, platformPostId, content, publishedAt }

post.failed — { event: "post.failed", postId, accountId, platform, content, error, failedAt }

comment.received — { event: "comment.received", commentId, postId, authorId, authorUsername, text, accountId, platform, createdAt }

automation.triggered — { event: "automation.triggered", automationId, triggerType, commentId, postId, authorUsername, dmSent, accountId }

ai.task.completed — { event: "ai.task.completed", taskId, model, status: "completed", result: { ... }, creditsUsed } — result shape varies by category (see AI Generation section)

ai.task.failed — { event: "ai.task.failed", taskId, model, status: "failed", error }

credits.low — { event: "credits.low", balance, threshold }

List webhooks

Create webhook

Get webhook

Update webhook

Delete webhook

Send test event

Delivery logs

API Keys

List API keys

Create key

Get key details

Update name/expiry

Revoke key

Usage & Billing

Current plan, usage counts, and limits

Daily usage aggregation