Videos

Videos are the content units within a bundle. Each video occupies a specific position (1-indexed) in the bundle and represents a single piece of content to be published on a creator's social media account.

Video Types

Every video has a video_type that determines what content it contains:

Platform-Specific Behavior

Each platform supports different combinations of video types and has its own requirements.

TikTok

Instagram

Instagram requires the instagram_content_type field to distinguish between reels and feed posts:

INFO: Reel Fixed Photos vs Post Carousel On Instagram, video_type: "carousel" behaves differently depending on instagram_content_type:

• With "reel": Instagram creates a video from your images (Fixed Photos — not swipeable). This is a Reel, not a carousel.
• With "post": Instagram creates a swipeable photo carousel in the feed.

Instagram also supports video_type: "story" (one video or one image, no instagram_content_type). See Configure Videos → Story Fields.

YouTube

YouTube accounts cannot be ordered through the API. Public bundle creation supports TikTok and Instagram only, and a YouTube bundle is rejected with YOUTUBE_DELAYED — even though GET /credit-costs lists a YouTube price, the price is real but the order path is not open. YouTube accounts are delivered through a separate, non-API flow; talk to the team. You may still see reserved YouTube fields in templates and generated schemas.

Video Status Lifecycle

Each video progresses through the following statuses:

pending → configured → published → accepted → in_review → finalized

The 72-hour window starts when the video listing enters in_review. Inconclusive TikTok sound checks are an exception: they require an explicit client review and never finalize automatically, as explained below. Finalize it to approve it immediately, or request corrections before the window expires. If neither action is taken, finalization is automatic — this applies regardless of auto_finalize_videos, which does not switch automatic finalization off.

TikTok sound verification

For manager-published TikTok videos and carousels with a requested sound, TokPortal checks the attached sound ID. Original and added audio levels are checked only when volume instructions were supplied. An unavailable metadata read is not proof of a wrong sound or an unavailable sound.

Inconclusive sound reviews are never automatically approved, including after the usual 72-hour review period and when auto_finalize_videos is enabled. The client can approve or request corrections directly; no separate staff approval is required. The original post URL and submission timestamp are retained, and the manager can continue other tasks.

An unavailable-sound report needs no screenshot or routine staff review. The return to configured is a request for your new instructions, not an approval of a substitute post. Its webhook includes:

• sound_unavailable_reason: unavailable_for_use or country_restricted;
• restriction_verified: true for verified restriction evidence, false when the manager reported the restriction and automatic verification could not confirm it;
• requested_sound_url and sound_report_id for the affected instructions.

A manager declaration is never reused as verified evidence for another task or account. No alternative recording is selected without your instructions. Existing post references remain reserved, so this workflow does not create duplicate publications or bypass checks on earlier public copies.

Subscribe to both video.in_review and video.configured. Their event IDs are stable across delivery retries; deduplicate by the envelope's id.

Volume instructions keep the API's existing 0–200 scale. No client input is rewritten. A missing volume instruction skips volume comparison only; it does not skip the requested sound ID check.

Platform Signals

Once a video is live, TokPortal checks what the platform did with it: about 48 hours after posting and again after 7 days, plus whenever the post is scraped for analytics. The result is returned on every video as platform_signals, also on the order progress page and in Analytics. The object is always present; every field is null until the first check — null means not checked yet, never no.

"platform_signals": {
  "checked_at": "2026-09-22T05:47:52Z",
  "not_recommended": true,
  "not_recommended_since": "2026-09-19T05:28:00Z",
  "ai_label": null,
  "sound": "non_commercial",
  "sound_reason": "Can't promote due to audio copyright issue"
}

The same observations are pushed as webhooks the moment they are detected: video.not_recommended, video.ai_labeled and video.sound_restricted. Portfolio-wide, GET /analytics/signals lists every flagged post.

Publish Date Rules

The target_publish_date field controls when the video should be published.

• Account still being created (not yet delivered): minimum 3 days from today.
• Account already delivered, or a bundle running on an existing account: minimum 1 day from today.

A bundle can also carry at most 3 videos targeting the same day. Dates earlier than the allowed minimum are rejected with a VALIDATION_ERROR.

List All Videos in a Bundle

Retrieve every video configured for a bundle.

GET /bundles/:id/videos

curl -X GET https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos \
  -H "X-API-Key: sk_xxx"

Response:

{
  "data": [
    {
      "position": 1,
      "video_type": "video",
      "status": "configured",
      "description": "Unboxing the new product line",
      "target_publish_date": "2026-03-15",
      "video_url": "https://pub-xxx.r2.dev/videos/abc123.mp4",
      "external_ref": "campaign-42-v1",
      "download_issue": false,
      "download_issue_comment": null
    },
    {
      "position": 2,
      "video_type": "carousel",
      "status": "pending",
      "description": null,
      "target_publish_date": null,
      "video_url": null,
      "external_ref": null,
      "download_issue": false,
      "download_issue_comment": null
    }
  ]
}

Get a Single Video

GET /bundles/:id/videos/:position

curl -X GET https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos/1 \
  -H "X-API-Key: sk_xxx"

Response:

{
  "data": {
    "position": 1,
    "video_type": "video",
    "status": "configured",
    "description": "Unboxing the new product line",
    "target_publish_date": "2026-03-15",
    "video_url": "https://pub-xxx.r2.dev/videos/abc123.mp4",
    "tiktok_sound_url": "https://www.tiktok.com/music/original-sound-123",
    "editing_instructions": "Add brand logo at the end",
    "external_ref": "campaign-42-v1",
    "download_issue": false,
    "download_issue_comment": null,
    "platform_signals": {
      "checked_at": null,
      "not_recommended": null,
      "not_recommended_since": null,
      "ai_label": null,
      "sound": null,
      "sound_reason": null
    }
  }
}

What's Next