Schedule a post for multiple accounts. Posts are stored with source="partner_api" and appear in the dashboard queue immediately.
Body Parameters Text caption applied to every platform.
Max 500 characters (applies to all accounts).
Provide either a single video clip or a slideshow bundle. video or slideshow. Determines which media keys are required.
Required for video. Direct URL to the MP4/MOV/M4V/AVI file. Google Drive
links are supported.
Required for slideshow. Ordered list (1–35) of JPG/JPEG/PNG image URLs.
Optional TikTok post URL (e.g.,
https://www.tiktok.com/@genviral/video/1234567890) used to resolve the
track. The API validates that the link points to TikTok and automatically
ignores it when any Instagram account is targeted.
Up to 10 account objects referencing IDs returned from /accounts. All IDs must belong to the authenticated workspace. Unknown or inactive
accounts cause the request to fail. ISO 8601 timestamp (e.g., 2025-02-01T15:00:00Z). If omitted or within 30
seconds of “now”, the post is treated as pending for immediate publish.
Optional correlation ID to map posts back to your system.
BYO Accounts: Media is automatically ingested into Genviral storage.Hosted-Only: Provided URLs are validated for reachability but not re-hosted unless necessary.Google Drive: Share links are auto-converted to direct download links.
Limits (enforced for all accounts)
Caption: max 500 characters.
Video: MP4/MOV/M4V/AVI, under 100MB. If duration metadata is present, we enforce 15–60 seconds; when duration is missing we proceed with a warning. ~9:16 aspect recommended.
Slideshow: 1–35 images, JPG/JPEG/PNG, each under 5MB. ~9:16 aspect recommended.
Music: blocked when any Instagram account is selected.
Response Successful requests return 201 with:
id — canonical Genviral post IDstatus — either pending or scheduled, matching the scheduling logic abovescheduled_at — ISO timestamp stored on the post (or null when queued
immediately)warnings — optional array describing non-blocking validation issues
Examples Single video post (default) Use a single video object when targeting TikTok, Instagram Reels, or YouTube Shorts. Add music only when all selected accounts support it (TikTok hosted/BYO today).
import fetch from "node-fetch" ; const url = "https://www.genviral.io/api/partner/v1/posts" ; const payload = { caption: "Holiday drops start Monday!" , media: { type: "video" , url: "https://cdn.genviral.com/holidays.mp4" , }, music_url: "https://www.tiktok.com/@genviral/video/1234567890" , accounts: [ { id: "0f4f54d4-8cce-4fb7-8c7b-befbcb8af812" }, { id: "6b0c8c9c-55ac-4fcb-85ec-70b5a8b0d089" }, ], scheduled_at: "2025-02-01T15:00:00Z" , external_id: "partner-run-884" , }; const response = await fetch ( url , { method: "POST" , headers: { Authorization: "Bearer <token>" , "Content-Type" : "application/json" , }, body: JSON . stringify ( payload ), }); console . log ( await response . json ()); curl --request POST \ --url https://www.genviral.io/api/partner/v1/posts \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "caption": "Holiday drops start Monday!", "media": { "type": "video", "url": "https://cdn.genviral.com/holidays.mp4" }, "music_url": "https://www.tiktok.com/@genviral/video/1234567890", "accounts": [ { "id": "0f4f54d4-8cce-4fb7-8c7b-befbcb8af812" }, { "id": "6b0c8c9c-55ac-4fcb-85ec-70b5a8b0d089" } ], "scheduled_at": "2025-02-01T15:00:00Z", "external_id": "partner-run-884" }' Slideshow post (photo carousel) Provide up to 35 slideshow items to schedule a TikTok Photo Mode or Instagram carousel. Order is preserved as given in the media array.
import fetch from "node-fetch" ; const url = "https://www.genviral.io/api/partner/v1/posts" ; const payload = { caption: "3 looks for the long weekend ☀️" , media: { type: "slideshow" , urls: [ "https://cdn.genviral.com/slides/look-01.jpg" , "https://cdn.genviral.com/slides/look-02.jpg" , "https://cdn.genviral.com/slides/look-03.jpg" , ], }, music_url: "https://www.tiktok.com/@genviral/video/9876543210" , accounts: [{ id: "3e30c8d1-0bc0-42d8-9a1a-bb63fe6c3c16" }], scheduled_at: "2025-02-14T18:30:00Z" , external_id: "carousel-campaign-12" , }; const response = await fetch ( url , { method: "POST" , headers: { Authorization: "Bearer <token>" , "Content-Type" : "application/json" , }, body: JSON . stringify ( payload ), }); console . log ( await response . json ()); curl --request POST \ --url https://www.genviral.io/api/partner/v1/posts \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "caption": "3 looks for the long weekend ☀️", "media": { "type": "slideshow", "urls": [ "https://cdn.genviral.com/slides/look-01.jpg", "https://cdn.genviral.com/slides/look-02.jpg", "https://cdn.genviral.com/slides/look-03.jpg" ] }, "music_url": "https://www.tiktok.com/@genviral/video/9876543210", "accounts": [ { "id": "3e30c8d1-0bc0-42d8-9a1a-bb63fe6c3c16" } ], "scheduled_at": "2025-02-14T18:30:00Z", "external_id": "carousel-campaign-12" }' { "ok" : true , "code" : 201 , "message" : "Post scheduled" , "data" : { "id" : "post_789" , "status" : "scheduled" , "scheduled_at" : "2025-02-01T15:00:00Z" , "warnings" : [ { "field" : "media" , "message" : "Video duration metadata is missing" , "code" : "VIDEO_DURATION_MISSING" } ] } } Responses may include a warnings array when media metadata
(size/duration/aspect) is missing. These are informational so you can decide
whether to re-upload media before Hosted Accounts enforce limits.
Error Responses
400 invalid_json — body is not valid JSON422 invalid_payload — schema validation failed (caption/media/accounts)400 unknown_accounts — at least one account.id is not part of the workspace400 validation_failed — caption/media/music rules failed (TikTok-only music, bad aspect ratio, etc.)400 missing_accounts — resolved account array is empty after validation400 invalid_music_url or 400 media_unreachable — media or music URLs failed reachability checks500 create_failed — upstream scheduler error (retry after inspecting logs) 