> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/start-with-an-ai-agent/faqs.md). # API FAQs Integration answers for authentication, publishing, uploads, visual generation, and errors. For setup, start with [Connect your AI client](/start-with-an-ai-agent/mcp/setup.md). For a tool sequence, use [Agent workflows](/agent-workflows/agent-workflows.md). The answers below cover exceptions and troubleshooting. | Topic | Reference | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | API keys, OAuth, and access | [Authentication](/api-and-mcp-concepts/authentication.md) | | Account IDs and page IDs | [Accounts and identifiers](/api-and-mcp-concepts/accounts-and-identifiers.md) | | Uploads and conversion | [Media guide](/api-and-mcp-concepts/media-uploads-and-conversion.md) | | Publishing fields | [Platform guides](/platform-publishing/platforms.md) | | Processing, timeouts, and retries | [Async jobs](/api-and-mcp-concepts/async-jobs-and-polling.md) and [Errors](/api-and-mcp-concepts/error-handling.md) | | Visual templates and inputs | [Create a visual](/agent-workflows/agent-workflows/visuals.md) | ## Common Questions ### The API setup feels hard -- where do I start? 1. Choose your assistant in [Connect your AI client](/start-with-an-ai-agent/mcp/setup.md). 2. Follow its OAuth or API-key steps. 3. Ask the assistant to list your connected Blotato accounts. For a video walkthrough, watch the [Blotato + Claude setup tutorial](https://youtu.be/1dSNfnFL40c). For agent-readable instructions, use the [API reference for agents](/start-with-an-ai-agent/llm.md). For n8n or Make.com, start with the [official Blotato node install guide](/integrations-and-automation-templates/n8n/n8n-blotato-node.md) instead. *** ### Should I use the REST API or MCP? Use MCP when your assistant supports tool calls and you want to work through conversation. Use REST when your integration sends HTTP requests, including workflow tools and hosted agents. The surfaces overlap, but they do not have identical operations or request shapes. MCP uses named tools with flat arguments. REST uses endpoint-specific bodies, such as the nested `post` object for publishing. Follow [REST versus MCP](/api-and-mcp-concepts/rest-vs-mcp.md) for the differences. *** ### How do I make a high-quality AI avatar? {% embed url="" %} *** ### My AI automation is repeating videos on the same topics, but I want more variety? You may want to tweak the prompt so there's more variety in the video topics. I generally don't want to make templates too complicated; however, most advanced automation builders will have a separate google sheet/airtable to track lists of topics/ideas that have already been covered, so that AI can analyze it and come up with different ideas. Another approach is to have a long list of topics/ideas, stored in a google sheet/airtable, then randomly select one idea from the list, then AI writes a script about it. *** ### How do I manually control the content in slideshows and carousels? #### Using Blotato Web App 1. Follow the [template creation workflow](/web-app-features/videos/make-your-first-ai-video.md). 2. Use the [visual editor](/web-app-features/videos/edit-and-export.md) to change an existing visual before export. #### Using Blotato API (n8n / Make.com) 1. [Inspect the selected template's inputs](/rest-api-reference/create-video.md#inspect-inputs-without-generating-a-visual). 2. Supply values under `inputs`. Field names depend on the template. Image Slideshow with Text Overlays uses `slides[].imageSource` and `slides[].textOverlay`, not generic `text` and `textToImagePrompt` fields. 3. Follow the [manual-input example](/rest-api-reference/create-video.md#2-create-a-visual-with-manual-inputs), then verify the generated output. If your carousel images already exist, skip visual generation and pass their URLs in the publish request's `mediaUrls` array. Check the destination's [image and carousel requirements](/platform-publishing/platforms.md) before publishing. *** ### How do I post to Instagram stories via Blotato API? In n8n or Make.com, open the Instagram publish node, click "Add Option", select "Media Type", and set it to "Story". For REST, set `post.target.mediaType` to `"story"`. For the `blotato_create_post` MCP tool, set the top-level `mediaType` argument to `"story"`. Instagram Stories do not support captions through Meta's publishing API. Set `content.text` to `""`. To display text, render it into the image or video before publishing. Native Story text, link stickers, and other interactive stickers require manual editing in Instagram. See [Instagram Story limitations](/social-accounts-and-platform-faqs/instagram/limitations.md#story-captions-and-text-overlays). See: [Publish Post API Reference](/rest-api-reference/publish-post.md) *** ### After publishing via API, how do I see the status of my post? View your upcoming scheduled posts and published posts in your [Blotato Calendar](https://my.blotato.com/calendar). You can move scheduled posts back to drafts if you need to edit them. To get your post status programmatically via API: 1. In n8n or Make, add the official Blotato **Get Post** node (select "Post" > "Get") 2. Pass in the `postSubmissionId` from your Publish node response 3. The node returns the current status (`in-progress`, `scheduled`, `published`, or `failed`) TikTok and other platforms publish asynchronously. Add a Wait node (10-30 seconds) between Publish and Get Post, or poll until the status reaches `published` or `failed`. API docs: [Get Post](/rest-api-reference/publish-post/get-post.md) *** ### How do I get the URL of a published post via API? Use the official Blotato **Get Post** node to retrieve the published post URL. 1. In n8n or Make, add the Blotato **Get Post** node (select "Post" > "Get") 2. Pass in the `postSubmissionId` from your Publish node response 3. Once the status is `published`, the response includes the live URL (e.g., the direct TikTok or Instagram link) TikTok and other platforms publish asynchronously, so the URL is not available immediately. Add a Wait node (10-30 seconds) between Publish and Get Post, or poll until the status reaches `published`. API docs: [Get Post](/rest-api-reference/publish-post/get-post.md) *** ### How do you get social analytics (views, likes, etc.) via API? Use the Analytics endpoints. Blotato collects engagement metrics (views, likes, comments, shares, reach, watch time, and more) for your published posts. 1. [List Top Performing Posts](/rest-api-reference/analytics.md) (`GET /v2/analytics`) ranks your best posts by likes, comments, views, or reach. 2. [Get Post Analytics](/rest-api-reference/analytics.md) (`GET /v2/posts/{id}/analytics`) returns metrics and snapshot history for a single published post. Metrics refresh at fixed checkpoints after each post publishes, and the schedule depends on your plan. See the [Analytics API reference](/rest-api-reference/analytics.md) for the full metric list, collection schedule, and examples. *** ### Can I read or post comments via the API? Yes, for Instagram and Facebook. Blotato exposes three comment endpoints: 1. [List Comments](/rest-api-reference/comments.md) (`GET /v2/comments`) returns the comments on your published Instagram and Facebook posts, including audience replies and your own. 2. [Get Comment](/rest-api-reference/comments.md#get-comment) (`GET /v2/comments/:commentId`) returns a single comment. 3. [Post Comment](/rest-api-reference/comments.md#post-comment) (`POST /v2/comments`) posts a top-level comment, or a reply when you pass `parentCommentId`, on one of your published Instagram or Facebook posts. Posting is async: the response returns status `queued`. Poll Get Comment with the returned ID until it reaches `posted` or `failed`. See the [Comments API reference](/rest-api-reference/comments.md) for the full request and response shapes and error codes. *** ### Can I read or send direct messages via the API? Yes, for Instagram and Facebook. Blotato exposes five messaging endpoints: 1. [List Conversations](/rest-api-reference/messages.md) (`GET /v2/conversations`) returns your direct-message conversations. 2. [Get Conversation](/rest-api-reference/messages.md#get-conversation) (`GET /v2/conversations/:conversationId`) returns a single conversation. 3. [List Messages](/rest-api-reference/messages.md#list-messages) (`GET /v2/messages`) returns your messages, filterable by conversation. 4. [Get Message](/rest-api-reference/messages.md#get-message) (`GET /v2/messages/:messageId`) returns a single message. 5. [Send Message](/rest-api-reference/messages.md#send-message) (`POST /v2/messages`) sends a direct message to someone already in your conversations. Sending is async: the response returns status `queued`. Poll Get Message until it reaches `sent` or `failed`. You reply to people who already have a conversation with you, and the platform limits who you message and when. See the [Messages API reference](/rest-api-reference/messages.md). *** ### Can I add buttons or quick replies to a message? Yes, on Instagram and Facebook. Set them on the `target` object of [Send Message](/rest-api-reference/messages.md#send-message). **Instagram renders buttons in the Instagram mobile app only.** A recipient reading the conversation on instagram.com in a desktop browser sees the message text with no buttons. To work around this, you can add a URL directly to the message text, and Instagram will render it as a clickable link. Set an `attachment` or put a URL inside `text`, not both, since a message carrying both leaves the URL unclickable on desktop. For more information about how buttons and quick replies in messages work, see [Buttons and Quick Replies](/rest-api-reference/messages.md#buttons-and-quick-replies). *** ### Can I set up DM automations via the API? Yes, for Instagram and Facebook. A DM automation sends one automated direct message to someone who comments on your post or direct messages you. 1. [Create DM Automation](/rest-api-reference/dm-automations.md#create-dm-automation) (`POST /v2/dm-automations`) creates the automation with its triggers, gates, message, and up to 3 link buttons. 2. [List DM Automations](/rest-api-reference/dm-automations.md) (`GET /v2/dm-automations`) lists your automations. 3. [Update DM Automation](/rest-api-reference/dm-automations.md#update-dm-automation) (`PATCH /v2/dm-automations/:id`) edits it. The patch nests under a `patch` key. 4. [Update DM Automation Trigger](/rest-api-reference/dm-automations.md#update-dm-automation-trigger) (`PATCH /v2/dm-automations/:flowId/triggers/:triggerId`) updates a single trigger without editing the automation. 5. [List Runs](/rest-api-reference/dm-automations.md#list-runs) (`GET /v2/dm-automations/:id/runs`) shows each execution and the error on failures. 6. [Get Analytics](/rest-api-reference/dm-automations.md#get-analytics) (`GET /v2/dm-automations/:id/analytics`) returns all-time triggered, completed, and failed totals. An automation is created as a draft unless you pass `isActive: true`. See the [DM Automations API reference](/rest-api-reference/dm-automations.md). Four optional fields extend an automation, and Blotato runs them in a fixed order: * [Follow Gate](/rest-api-reference/dm-automations.md#follow-gate-object): (Instagram only) Holds the message back until the person follows your Instagram account. * [Email Gate](/rest-api-reference/dm-automations.md#email-gate-object): Holds the message back until the person replies with an email address. Blotato saves the first address in their reply. On automations published after September 14, 2026, a contact who already replied with an email address to any email gate on the same connected account skips this gate. * [Comment Reply](/rest-api-reference/dm-automations.md#comment-reply-object): Posts a public reply under the triggering comment right after the first message, which is the gate message when the contact gets one. * [Webhook](/rest-api-reference/dm-automations.md#webhook-object): Calls your own endpoint once the message sends. The body carries `{"email": "them@example.com", "isFollower": true}`. `email` is `null` when Blotato holds no address, and `isFollower` is `null` when no follow gate checked the person. The follow gate waits up to 30 days for a reply, and the email gate up to 72 hours. A run where the person never answers ends as `expired`. *** ### Can I check or buy credits via the API? Yes, for the account your API key belongs to. 1. [Get Credit Balance](/rest-api-reference/credits.md) (`GET /v2/credits`) returns your remaining credits, account email, and current pricing (price per 1,000 credits and the min/max purchase quantity). 2. [Buy Credits](/rest-api-reference/credits.md#buy-credits) (`POST /v2/credits`) with a `quantity` between 1,000 and 10,000 returns a Stripe Checkout link (`checkoutUrl`). Calling Buy Credits does not charge anything. Open the returned `checkoutUrl` in a browser to complete payment. Purchased credits land on the account the API key belongs to, so confirm the account email from Get Credit Balance first. Credits are non-transferable between accounts. *** ### How do I post to a LinkedIn page instead of personal LinkedIn? If you're using a workflow automation tool, there's an additional option to post to your LinkedIn pages. Click "Add Option" and select "LinkedIn Page" from the dropdown. This allows you to specify which LinkedIn company page to post to, instead of your personal profile. *** ### How do I post an Instagram 'story' instead of a 'reel'? Open the Instagram publish node and add the option 'Media Type' and set it to 'Story'. Click "Add Option" in the Options section and select "Media Type" from the dropdown, then set the value to "Story". Text entered in the Caption field does not appear on the published Instagram Story. To display text, render it into the image or video before publishing. *** ### How do I upload a local file (image or video) from my computer? For MCP / Claude / Cursor / Antigravity workflows, see [How do I upload a local file (image or video) from my computer?](/start-with-an-ai-agent/mcp/faqs.md#how-do-i-upload-a-local-file-image-or-video-from-my-computer). For raw API workflows, use the [Presigned Upload (Local Files)](/rest-api-reference/publish-post/upload-media-v2-media.md#presigned-upload-local-files) endpoint. *** ### How do I upload carousel images to Instagram via API? Open your Instagram publish node. Pass a comma-separated list of public image URLs into the `mediaUrls` array: ```json "mediaUrls": ["url1.png", "url2.png", "url3.png"] ``` Instagram will automatically post this as a carousel. *** ### How do I clean up timestamps from YouTube/TikTok transcripts? In the n8n Blotato node, Source > Get provides Clean Transcript, enabled by default. The node removes transcript timestamps, sequence numbers, some Markdown formatting, and excess whitespace from returned content. Turn it off to preserve the returned transcript. REST and MCP do not expose `cleanTranscript`. Retrieve the completed `content`, then clean it in your agent or workflow. This is a client-side transformation, not an API query option. See [Get Source](/rest-api-reference/create-source/get-source.md#clean-transcript-option). ### How do I hide or remove elements from a visual template? All template parameters marked as "not required" are optional. To hide an element, omit the parameter or pass an empty value: * To remove text overlays: omit the parameter or pass an empty array `[]` * To remove a watermark: set the watermark parameter to `""` (empty string) Each template has different parameter names. Check the template's documentation page for the full list of parameters and customization tips: [Visual Templates](/rest-api-reference/visuals.md) *** ## Errors & Issues ### Why am I getting a 401, "invalid API key", or "can't connect to the API"? Blotato API keys sometimes end with one or more `=` characters (base64 padding). The `=` is part of your key. Two things break it: 1. The trailing `=` gets dropped when copying. Copy the full key with the "Copy API Key" button in [Settings > API](https://my.blotato.com/settings/api), not by manual selection. 2. A shell, `.env` file, script, or no-code header field strips or mangles the `=`. Wrap the entire key in single quotes, for example `'abc123=='`, and never remove the `=`. A 401 means the key you sent does not match your real key. Verify your key with `GET /v2/users/me`. *** ### How to troubleshoot API errors? When posts fail via the API, check causes in this order. The first cause is by far the most common. 1. **Open the** [**Logs**](https://my.blotato.com/logs) and click the failed request to see the exact request payload and the platform's actual response. The raw response tells you which of the causes below applies. 2. **Wrong account ID.** If the response says the account is not found, the `accountId` you passed is invalid. Use the official [Blotato n8n node](/integrations-and-automation-templates/n8n/n8n-blotato-node.md) or the [Make.com integration](/integrations-and-automation-templates/make.com.md) to select accounts from a dropdown instead of copy-pasting IDs. 3. **Expired or missing access token.** Reconnect the social account in [Accounts](/settings/social-accounts.md). 4. **Payload schema error.** Field names or types do not match what the endpoint expects. Compare your request to the [API Reference](/rest-api-reference/api-reference.md) and to a working request in the dashboard. 5. **Check the** [**Failed dashboard**](https://my.blotato.com/posts?status=failed) for a list of all failed posts. 6. **Platform outage.** Real Facebook, Instagram, X, or LinkedIn API outages are rare. Only assume an outage if the Logs response shows the platform itself returned a 5xx error or a public outage is reported on [downdetector.com](https://downdetector.com). If a customer-facing tool or AI agent told you "the platform is down" or "Blotato is returning a persistent API error," do not trust that summary. Open the Logs and read the raw response. *** ### "Failed to read media metadata" on POST /v2/media, but my URL is a clean public file. Why does the same call fail sometimes and work other times? If you already confirmed the URL returns the raw media file (for example `curl -I` shows HTTP 200 with `content-type: video/mp4` and no auth or bot protection), accessibility is not the problem. Two remaining causes: 1. **The file host throttles server-side fetches.** CDN or bot protection on the host (GoDaddy-hosted sites behind Cloudflare are a confirmed case) can slow or interfere with Blotato's server-to-server download enough that metadata reading fails, especially on larger files (tens of MB) -- even when your own `curl` returns HTTP 200. Move the file to a host without bot protection (a public S3/GCS bucket or similar), or use presigned upload (below). Also confirm the file is within your plan's upload size cap -- 400MB on Starter, 1GB on Creator and Agency ([Plan Limits](/settings/billing-and-credits.md#plan-limits)). 2. **Intermittent metadata-reader flake.** If the exact same call on the same small file passes sometimes and fails other times (including `Failed to fetch media URL: 415 Unsupported Media Type` on publish), this is a known intermittent issue in Blotato's media metadata reader, not your file or your workflow. Workaround: wrap the `/v2/media` call in a retry, for example 2 attempts with a 3-second delay. The durable fix for both causes is the [Presigned Upload](/rest-api-reference/publish-post/upload-media-v2-media.md#presigned-upload-local-files) flow. It handles large binaries via direct PUT, skips the metadata-fetch step, and runs through a different code path than URL fetch. The official Blotato n8n node has "Presigned Upload" as a resource option. *** ### Do I need to upload media before publishing? No. You can pass any publicly accessible image/video URL directly into the `mediaUrls` parameter in the Publish node. Blotato handles the media transfer automatically. If you are using the n8n "Binary Data" upload option, the file size limit is 15MB. For larger files, host your media on Google Drive, AWS S3, or another cloud storage service and pass the URL instead. Max allowed file size depends on your plan (see [Plan Limits](/settings/billing-and-credits.md#plan-limits)) For local files without a public URL, use the [Presigned Upload](/rest-api-reference/publish-post/upload-media-v2-media.md#presigned-upload-local-files) endpoint (`POST /media/uploads`) to upload directly to Blotato. No Google Drive or S3 needed. Max upload size depends on your plan (see [Plan Limits](/settings/billing-and-credits.md#plan-limits)). MCP users get this through the `blotato_create_presigned_upload_url` tool automatically. The Upload Media endpoint is still available if you prefer to use it: [Upload Media](/rest-api-reference/publish-post/upload-media-v2-media.md) *** ### Can I create a draft post via the API so it lands in my dashboard for review? There is no draft parameter, status field, or draft endpoint on `POST /v2/posts`. If you omit both `scheduledTime` and `useNextFreeSlot`, the post publishes immediately -- it does not save as a draft. Claims elsewhere about omitting these fields to create a draft are wrong. TikTok's `isDraft` target option is the one platform exception, and it creates a TikTok-side draft: the post lands in the TikTok app's notifications inbox, not in your Blotato dashboard. See [How Do I Access TikTok Drafts Published via Blotato?](/social-accounts-and-platform-faqs/tiktok/faqs.md#how-do-i-access-tiktok-drafts-published-via-blotato) Pinterest, Instagram, Facebook, and the other platforms have no draft field. Two workflows give you dashboard review before anything publishes: 1. Save the visual as a draft. Set `isDraft: true` on [Create Visual](/rest-api-reference/create-video.md). The visual is saved without rendering, and you review, render, and attach it to a post from the dashboard. 2. Schedule, then move to drafts. Publish with `scheduledTime` or `useNextFreeSlot` set to a future slot, then open [Posts > Scheduled](https://my.blotato.com/posts?status=scheduled) and use **Move to Drafts** to hold the post for manual review. See [Move Scheduled Post Back to Drafts](/web-app-features/content-calendar/tutorial.md#move-scheduled-post-back-to-drafts). *** ### How do I create videos and carousels in n8n or Make? Use the Blotato CREATE VISUAL node to generate carousels and slideshows from templates: 1. Add a Blotato node and select "Visual" > "Create" 2. Select a template from the dropdown list 3. Keep default inputs and click Execute to instantly make a carousel 4. Update inputs one-by-one to customize 5. Check the [Logs](https://my.blotato.com/logs) to see the JSON payload for each template Tip: Browse all available templates at [Videos > Create New Video](https://my.blotato.com/videos/new) to see how they work before building your automation. *** Those parameters belong to an outdated template format. Switch to the new CREATE VISUAL system instead: 1. Browse all available templates at to see how they look 2. In n8n or Make, add the Blotato CREATE VISUAL node and select a template 3. Start with a carousel template -- carousels render near-instantly, so you get a fast test run 4. Click Execute to generate the carousel 5. Open your [Logs](https://my.blotato.com/logs) to see the JSON payload for each template 6. Override your desired inputs one-by-one If you were making AI story videos, use the template called "AI Video with AI Voice." Full documentation for each template: [Visual Templates](/rest-api-reference/visuals.md) *** ### How do I figure out the correct syntax for visual template inputs? #### Using Blotato Web App 1. Open [Videos > Create New Video](https://my.blotato.com/videos/new). 2. Select the requested template to inspect its form fields. Do not generate a visual solely to inspect those controls. #### Using Blotato API (n8n / Make.com) 1. Call `blotato_list_design_templates`, or `GET /v2/videos/templates?fields=id,name,description,inputs`. 2. Find the selected template by its complete `id`. 3. Read its `inputs` specification before mapping values from earlier workflow steps. This lookup does not generate a visual. Do not remove all parameters and execute Create Visual to learn the schema. The Logs shows requests you submitted, not every field the template accepts. See [Inspect inputs without generating](/rest-api-reference/create-video.md#inspect-inputs-without-generating-a-visual) for lookup examples and template-specific field structures. *** ### Why does the Prompt field rewrite or "wash" my pre-written script? The `prompt` parameter is designed for high-level instructions where AI generates the content. If you paste a full, pre-written script into the Prompt field, the AI will rewrite, condense, or dilute it. **To use your script exactly as-is:** 1. Leave the `prompt` field **empty or blank** 2. Manually specify your scenes in the `inputs` object 3. Use the exact field names from your template (check the [Logs](https://my.blotato.com/logs) to confirm) For example, instead of pasting your script in `prompt`, structure it like this: ```json { "inputs": { "scenes": [ { "script": "Your exact narration text here.", "mediaSource": "Image prompt or URL" }, { "script": "Your second scene narration.", "mediaSource": "Another image prompt" } ] }, "prompt": "" } ``` Manual inputs always take priority over AI generation, so this preserves your script exactly as written. To find the correct field names for your template, see: [How do I figure out the correct syntax for visual template inputs?](#how-do-i-figure-out-the-correct-syntax-for-visual-template-inputs) *** ### My workflow outputs scenes and caption, but my template only accepts title and quotes The output of an earlier workflow step must match the selected template's input specification. | Selected template | Input structure | | ------------------------------------ | ----------------------------------------------------------------- | | AI Video with AI Voice | `scenes`, with `script` and `mediaSource` per scene | | Image Slideshow with Text Overlays | `slides`, with `imageSource` and optional `textOverlay` per slide | | Quote Card with Monocolor Background | `title` and a `quotes` array of strings | For the Quote Card template, transform your content into its `title` and `quotes` fields. To retain scene narration, select AI Video with AI Voice instead. Image Slideshow with Text Overlays reads `slides`, not a `scenes` array. A social-post caption is separate from template inputs. Pass publication text through the [publish workflow](/agent-workflows/agent-workflows/publish.md). [Retrieve the input specification](/rest-api-reference/create-video.md#inspect-inputs-without-generating-a-visual) without starting another generation. For website editing, follow [Edit and export an existing visual](/web-app-features/videos/edit-and-export.md). *** ### How do I set transitions in the Create Visual node? In the Blotato Create Visual node (n8n or Make.com), a REST API request, or the `blotato_create_design` MCP tool, add `transition` as an input parameter with one of these values: `none`, `fade`, `slide`, `zoom`. The default transition is `fade`, which shows a brief black screen at the start of the video. Set `transition: "none"` to remove it. If you get an error after adding the transition parameter, verify: 1. The value is a string (not a number or boolean) 2. The parameter name is `transition` (lowercase) 3. It is inside the `inputs` object alongside your other template parameters All template input parameters (transitions, aspect ratio, AI models, etc.) work the same way across n8n, Make.com, REST API, and MCP. *** ### UPLOAD Step - Most Common Errors (Legacy) Public media URLs go directly in the Publish node's `mediaUrls` array. No upload step required. A local file still needs a completed byte upload. Follow [Media uploads and conversion](/api-and-mcp-concepts/media-uploads-and-conversion.md). For an older workflow with an UPLOAD step: 1. For a `401` response, follow [Authentication troubleshooting](/api-and-mcp-concepts/authentication.md). 2. For an empty URL, inspect the preceding step's response and the field mapping. 3. For a generated visual, read `item.status`, `item.error`, `item.mediaUrl`, and `item.imageUrls` through [Get Visual Status](/rest-api-reference/create-video/find-video.md). 4. Wait only when the job remains unfinished without a failure. A missing URL alone does not establish insufficient credits or unfinished generation. An image/carousel output uses `imageUrls`, while video output uses `mediaUrl`. Do not keep retrying an upload with an empty value. *** ### I'm getting "Account not found" or "Wrong Account ID" when publishing via API Retrieve the current account list using the same credential or MCP connection used by the failing publish step. Match the requested platform and destination, then use the returned account `id` as `accountId`. Check these separately: 1. The publish step's credential belongs to the intended Blotato user. 2. The account ID belongs to the requested platform. 3. A Page ID has not been substituted for `accountId`. 4. A saved workflow does not contain an ID from before the account was reconnected. Official node dropdowns reduce copying, but saved selections still need verification. AI assistants must call the account lookup tool instead of assuming the lookup happened automatically. If the account appears in a fresh lookup but publishing still fails, compare the request's credential, platform, and ID. Different keys are one possible cause, not a conclusion established by this error. Follow [Account not found](/api-and-mcp-concepts/accounts-and-identifiers.md#account-not-found). Do not regenerate keys, reconnect accounts, or resubmit a post before identifying the failing stage and checking the earlier submission's outcome. *** ### API error: "The access token is invalid or not found in the request" Identify which service returned the error. A social-platform token error during a TikTok status check is different from a Blotato API-key `401`. 1. Save the failed request or `postSubmissionId` and the full error. 2. Retrieve the current account list through the same Blotato credential or MCP connection. 3. Match the intended platform and account. Check for a stale ID or an ID from another platform. 4. If the connection is expired or revoked, reconnect the social account in [Accounts](https://my.blotato.com/accounts), then retrieve its current ID. 5. Check [Publishing status](/start-with-an-ai-agent/publishing-status.md) before a new publish attempt. An account dropdown does not guarantee a saved ID or social token remains valid. Do not ask the customer to share tokens, or assert a key mismatch from this message alone. *** ### Why is my custom thumbnail or cover image not applied on Facebook, Instagram, or TikTok? Custom video covers and thumbnails are a platform-by-platform feature. Support differs for each platform: | Platform | Custom cover support | API field | | --------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------- | | Facebook | Not supported. Facebook picks the cover itself. | (none) | | Instagram | Reels only. Feed posts, images, and carousels do not accept a custom cover. | `target.coverImageUrl` (image URL, max 8MB) | | TikTok | Videos: pick a frame by timestamp. Image posts: pick a slide by index. | `target.videoCoverTimestamp` (milliseconds), `target.imageCoverIndex` | | YouTube | Supported with a verified YouTube account. | `target.thumbnailUrl` (JPEG/PNG, max 2MB) | Submitting a cover image for a Facebook post, or for an Instagram feed post or carousel, has no effect β€” the platform ignores it. This is a platform restriction, not a Blotato bug. If a TikTok `videoCoverTimestamp` is valid and in range but the published video still shows the first frame, see [TikTok cover timestamp troubleshooting](/social-accounts-and-platform-faqs/tiktok/faqs.md#why-is-my-tiktok-video-cover-timestamp-ignored-first-frame-shown). Full field reference: [Publish Post](/rest-api-reference/publish-post.md#quick-reference-required-fields-per-platform) *** ### PUBLISH Step - Most Common Errors Use the error from the failed operation to select a check. A successful submission response is not proof of publication. 1. For an account or Page error, retrieve the [current destination IDs](/api-and-mcp-concepts/accounts-and-identifiers.md). Facebook needs `pageId`. LinkedIn needs `pageId` when publishing to a company Page. 2. For malformed JSON, use the node's structured fields or your HTTP client's JSON serializer. Do not build JSON by concatenating unescaped text. 3. For rejected media, inspect the file's metadata and the [target platform requirements](/rest-api-reference/publish-post/media.md). The filename extension alone does not prove its format. 4. For a missing or uncertain result, retain `postSubmissionId` and follow [Publishing status](/start-with-an-ai-agent/publishing-status.md). Do not publish a test video or repeat the write without authorization. 5. For `reached_active_user_cap`, TikTok reports its daily active-user quota. This error does not establish an account warm-up problem. Repeated submissions do not resolve the quota. 6. For other errors, follow [Error handling](/api-and-mcp-concepts/error-handling.md) using the exact returned message. Correct the identified problem before another authorized attempt. Saved node selections and AI-generated requests still require verification. *** ### CREATE FACELESS VIDEO Step - Most Common Errors #### Using Blotato Web App Follow [Make your first AI video](/web-app-features/videos/make-your-first-ai-video.md). For narration, choose AI Video with AI Voice. #### Using Blotato API (n8n / Make.com) 1. For authentication errors, check the credential on the failed creation step, not an unrelated UPLOAD step. 2. For input-validation errors, [retrieve the selected template's input specification](/rest-api-reference/create-video.md#inspect-inputs-without-generating-a-visual). 3. For an accepted job, save `item.id` and read its [status and error](/rest-api-reference/create-video/find-video.md). 4. For an insufficient-credits error, inspect the [credit balance and pricing](/rest-api-reference/credits.md) before requesting another paid attempt. For narration, select AI Video with AI Voice and use its returned template ID. Do not leave `templateId` empty. Waiting longer does not fix an input-validation or terminal generation error. *** ### CREATE CAROUSEL/SLIDESHOW Step - Most Common Errors #### Using Blotato Web App Follow the [template creation workflow](/web-app-features/videos/make-your-first-ai-video.md), then review the images before publishing. #### Using Blotato API (n8n / Make.com) 1. Inspect the error from the creation step. Check that step's authentication if it returned `401`. 2. Compare the submitted `inputs` with the [selected template's specification](/rest-api-reference/create-video.md#inspect-inputs-without-generating-a-visual). A quote array, slide array, and scene array are different structures. 3. Save the accepted job's `item.id`. 4. Check its [status](/rest-api-reference/create-video/find-video.md). Stop on `item.error` or a failure state. 5. On completion, use `item.imageUrls` for image output. Do not require a video `mediaUrl` for a carousel. For TikTok slideshow music, `autoAddMusic` is a publishing option, not a visual-generation input. Use REST `post.target.autoAddMusic` or the MCP `blotato_create_post` tool's `autoAddMusic` argument. See [TikTok publishing](/platform-publishing/platforms/tiktok.md). *** ### CREATE HEYGEN AVATAR VIDEO Step - Most Common Errors Here are the most common reasons the CREATE HEYGEN AVATAR VIDEO step fails πŸ‘‡ 1\) Wrong Heygen API Key and IDs: * check you've copied it correctly without whitespaces * check you've copied the HEYGEN AVATAR ID, not the Heygen Avatar GROUP ID 2\) You're On Heygen Free Plan * HeyGen API requires you to pay for its [$99/mo API plan](https://www.heygen.com/api-pricing). The Free API plan won't work. 3\) Your Avatar Has a Background * if you want to use your avatar's default background, NOT a green screen, you'll need to update CREATE AVATAR VIDEO step * set matting to false * remove the section background 4\) Increase Wait Time * Avatar videos take awhile to make, so I recommend testing with a short script (1 sentence) * When you increase the length of the script, increase the WAIT time accordingly *** ### How Do I Fix Invalid JSON Error? How to fix invalid JSON: 1\) Check your JSON is valid with this free tool: [https://jsonlint.com](https://jsonlint.com/) 2\) Copy and paste the following prompt into ChatGPT to compare your JSON with Blotato's API docs:\ ​ > I need help fixing my JSON request to Blotato API. > > Here's Blotato API docs: [Help guide](/rest-api-reference/api-reference.md)\ > ​\ > Here's my JSON request: > > \ *** ### API Error: "The service is receiving too many requests from you" This API error means you are calling the Blotato API too fast. The Blotato API has a rate limit to prevent spamming and abusing social media endpoints, which helps keep Blotato's integration in good standing with the social platforms. The **Upload Media** endpoint has a user-level **rate limit of 30 requests per minute**. The **Publish Post** endpoint has a user-level **rate limit of 30 requests per minute**. *** ### API Error: "The aspect ratio is not supported" This API error means the video you're trying to upload is not an aspect ratio supported by the platform. For example, a video with dimensions 2160x2880 is 3:4. But the only supported Instagram formats are 1:1, 4:5, 1.91:1, 9:16 (as an example). *** ### Seeing error 400 "body/template/id must be equal to constant"? Check the failed request URL and body together. Legacy `POST /v2/videos/creations` uses a `template` object and a different schema. Current `POST /v2/videos/from-templates` uses `templateId` and `inputs`. 1. Identify which endpoint the workflow called. 2. For the current template workflow, [retrieve a template and its inputs](/rest-api-reference/create-video.md#inspect-inputs-without-generating-a-visual). 3. Use its complete ID in `templateId` and send the matching body to `POST /v2/videos/from-templates`. Do not fix the current endpoint by adding a legacy `template.id` field or copying an ID from an older tutorial. See [Create Visual migration](/rest-api-reference/create-video.md#migrating-from-the-old-api-format). For website creation, use [Videos > Create New Video](https://my.blotato.com/videos/new) instead of editing API request fields. *** ### I'm making faceless videos via API but GET VIDEO node returns an empty/null mediaURL? Read the full [visual status response](/rest-api-reference/create-video/find-video.md), not only `mediaUrl`. 1. Confirm the status lookup uses the accepted creation's `item.id`. 2. If `item.error` or a failure state is present, stop waiting and use the returned error. 3. If the job is unfinished without a failure, poll at least 15 seconds apart within a bounded wait. 4. If the output is an image or carousel, use `item.imageUrls` instead of expecting a video URL. 5. If generation is `done` but the required output is missing, retain the visual ID and response for support. Do not start another paid job automatically. An empty URL does not prove the account ran out of credits. A `render: false` job also does not establish a completed export. For website export, follow [Edit and export an existing visual](/web-app-features/videos/edit-and-export.md). *** ### Seeing error "Error uploading video to TikTok: Please review our URL ownership verification rules"? This error means you're trying to post to TikTok with a URL that TikTok rejects. First, upload your media, then use the Blotato URL to post to TikTok. Here's a sample Blotato video URL to test it out: *** ### API posting succeeded, but you don't see the uploaded video? When posting via Blotato API, if it returns **postSubmissionId**, that means your post successfully joined the publishing queue. However, your post may still be rejected by the social platform (e.g. incorrect format or too many posts from you), in which case you'll see it in your [Failed Posts dashboard](https://my.blotato.com/posts?status=failed). *** ### How do I retry or recover a failed post via API? There is no retry or resubmit endpoint. To retry a failed post, submit a new `POST /v2/posts` request with the same payload. To find out why a post failed: 1. Poll `GET /v2/posts/{postSubmissionId}` -- the response includes `errorMessage` when status is "failed" 2. Open the [Logs](https://my.blotato.com/logs) and click the failed request to see the full error response 3. Fix the issue in your payload 4. Submit a new `POST /v2/posts` request Failed posts are also visible at . *** ### How do I debug API issues (failed requests, unexpected behavior, duplicate posts)? **n8n users β€” try this first:** click the green **FIX MY AUTOMATION** button at the top of any failed request in the [Logs](https://my.blotato.com/logs) and Blotato AI will attempt to fix your n8n workflow automatically. See [Fix My Automation (n8n only)](/integrations-and-automation-templates/n8n/faqs.md#first-step-click-fix-my-automation-in-the-api-dashboard-n8n-only). This feature is n8n only β€” it does not work for Make.com, Claude, MCP, or direct REST API calls. For everyone else (or if Fix My Automation doesn't resolve it): 1. Open the [Logs](https://my.blotato.com/logs) 2. Click on any request to see the full payload, response, and error message 3. Check for duplicate entries -- if you see two requests for the same content, your automation may be sending multiple POST requests 4. For duplicate posts on YouTube or TikTok, verify you only have one account connection per channel in [Accounts](https://my.blotato.com/accounts) If the Logs shows only one request but the platform received two posts, contact support with your postSubmissionId and the duplicate video IDs. *** ### ​Seeing error "TikTok post failed to publish: TikTok's servers may be experiencing issues. This is a retryable error"? This error is directly from TikTok. It happens occasionally when TikTok servers have an issue, failed to process your post, or you are posting too much. *** ### Seeing error "Threads API Feature Not Available: This user does not have access to this Threads API feature"? This error occurs when trying to connect Threads to Blotato. To fix this: 1. **Link Instagram Account**: You need to have a linked Instagram account to connect Threads to Blotato. 2. **Warm Up Your Account**: Ensure your Threads account is warmed up for a few days with posts before connecting to Blotato. *** ### 422 Invalid URL Go to [Logs](https://my.blotato.com/logs) and click the failed /media request. Copy/paste the URL you sent and make sure it's publicly accessible in an incognito browser. **If you're generating video and the URL is empty:** * The video is not done yet, so either: 1. Increase the WAIT time so the video has enough time to finish 2. Check you didn't run out of credits (`GET /v2/credits`) *** ### Images hosted behind Cloudflare are not loading in my visuals If you host images on your own server behind Cloudflare (or another WAF/CDN with bot protection), Blotato's servers may be blocked from fetching your images. This causes visual creation to fail or produce blank slides. To fix this: 1. Add a Cloudflare firewall rule that allows requests from Blotato's servers to access your image URLs 2. Alternatively, allowlist the User-Agent or IP range used by your rendering service 3. Test that your image URLs are accessible from a non-browser context (e.g., `curl ` from a different server) This applies to any CDN or firewall that blocks server-to-server requests, not only Cloudflare. *** ### How do I use local files (photos/videos from my computer) with Blotato API? Use Blotato's presigned upload endpoint. No Google Drive or cloud storage needed. 1. Call `POST /v2/media/uploads` with your filename (e.g., `{"filename": "video.mp4"}`) 2. Upload your file bytes to the returned `presignedUrl` with an HTTP PUT request 3. Use the returned `publicUrl` in your publish request's `mediaUrls` field Upload size depends on your plan (see [Plan Limits](/settings/billing-and-credits.md#plan-limits)). MCP users get this through the `blotato_create_presigned_upload_url` tool automatically. Docs: [Presigned Upload](/rest-api-reference/publish-post/upload-media-v2-media.md#presigned-upload-local-files) *** ### Google Drive file is too large to download? If your Google Drive file exceeds the direct download size limit, Google shows a virus scan warning page instead of serving the file. This breaks the URL for Blotato. Use this URL format instead, replacing `{file_id}` with your Google Drive file ID: `https://drive.usercontent.google.com/download?id={file_id}&export=download&confirm=t` To find the file ID, open the file in Google Drive and copy it from the URL: `https://drive.google.com/file/d/{file_id}/view` *** ### "A media upload for this URL is already in progress, please wait 20000 seconds and try again" This means you tried to upload the same media within 20 seconds, but Blotato is still processing your first request. Please wait a few moments to try uploading the same media again. *** ### "Could not upload video to Facebook: (#100) The global id xxxxxxx is not allowed for this call" Your Facebook Page ID is incorrect. I recommend using the n8n/Make official Blotato nodes. 10x easier because you no longer need to copy/paste keys, IDs, or code around. Check out this tutorial and template: [Help guide](/integrations-and-automation-templates/n8n/n8n-basics.md) See: [Facebook Errors](/social-accounts-and-platform-faqs/facebook/errors.md) *** ### "Please reduce the amount of data you're asking for, then retry your request" (Facebook) Facebook/Meta API server-side error -- not a Blotato bug. This is more common on larger Facebook Pages or groups, often around 5,000+ followers, because Facebook may run out of memory while processing the publish request. It may also appear as "Could not upload video to Facebook: ..." and can affect any post type, not just video. Retry publishing the post -- it often succeeds on a later attempt. First check the Facebook Page, because Facebook sometimes publishes the post even though the API reports a failure. If the post did not publish, wait a few minutes and retry. If the post uses Page mentions, try removing the mention and adding it manually later on Facebook. If the error persists across multiple retries over an hour, submit a support ticket via in-app chat with the post ID, timestamp, and Facebook Page follower count. See: [Facebook Errors](/social-accounts-and-platform-faqs/facebook/errors.md) *** **Didn't find your answer?** * [General FAQs](/support/faqs.md) * [Video FAQs](/web-app-features/videos/faqs.md) * [Make.com FAQs](/integrations-and-automation-templates/make.com/faqs.md) * [n8n FAQs](/integrations-and-automation-templates/n8n/faqs.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.blotato.com/start-with-an-ai-agent/faqs.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.