---
title: "Create a Story"
method: POST
path: "/v1/stories"
tags: ["Stories"]
---

# Create a Story

`POST /v1/stories`

## Request

- Base URL: `https://www.postquick.ai/api`
- URL: `https://www.postquick.ai/api/v1/stories`
- Auth: HTTP bearer

Create a Story draft from a publicly accessible media URL. Charges against the image or video generation quota (one upload = one charge). Use POST /v1/stories/{storyId}/publish or /schedule to actually post it.

## Request body

- object
  - `contentGroupId` string, required: Content group to create the story in.
  - `storyType` 'image' | 'video', required: Story media type
  - `mediaUrl` string, uri, required: Publicly accessible URL of the story media. Graph API and TikTok pull from this URL during publishing.
  - `thumbnailUrl` string, uri: Optional thumbnail for video stories.
  - `caption` string
  - `platforms` string[]: Target platforms. Can also be set later via publish/schedule.
  - `duration` integer: Video duration in seconds. Stories must be ≤60s.
  - `mediaFit` 'contain' | 'cover' | 'fill': How non-9:16 media is fitted into the 1080x1920 story frame: contain (letterbox with black bars, default), cover (crop to fill), or fill (stretch).

## Response `201`

Story draft created.

- object
  - `success` true, required
  - `data` object, required
    - `story` object, required: A Story record — short-lived (24h) content for Instagram, Facebook, or TikTok
      - `id` string, required
      - `app_id` string, required
      - `story_type` 'image' | 'video', required: Story media type
      - `image_url` string, nullable, required
      - `video_url` string, nullable, required
      - `thumbnail_url` string, nullable, required
      - `duration` number, nullable, required
      - `aspect_ratio` string, nullable, required
      - `caption` string, nullable, required
      - `platforms` string[], required
      - `posted_platforms` string[], required
      - `status` 'pending' | 'draft' | 'scheduled' | 'processing' | 'posted' | 'published' | 'partial' | 'failed', required: Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown.
      - `scheduled_for` string, date-time, nullable, required
      - `posted_at` string, date-time, nullable, required
      - `expires_at` string, date-time, nullable, required
      - `error_message` string, nullable, required
      - `platform_errors` object, nullable, required: Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`.
      - `platform_post_ids` object, nullable, required
      - `source_post_id` string, nullable, required
      - `source_video_id` string, nullable, required
      - `facebook_target` object, nullable, required: Facebook page publishing target
        - `pageId` string, required
        - `pageName` string
      - `created_at` string, date-time
      - `updated_at` string, date-time

---

[API](https://skmtc.dev/postquick/apis/postquickai-api.md) · [All operations](https://skmtc.dev/postquick/apis/postquickai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postquick/apis/postquickai-api/revisions/d9bc2bcf3042?raw)