---
title: "Create a video (Reel) from a URL"
method: POST
path: "/v1/videos"
tags: ["Videos"]
---

# Create a video (Reel) from a URL

`POST /v1/videos`

## Request

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

Create a video post (Reel) draft from an existing publicly accessible video URL. Pass videoUrl (or legacy media_url) directly to skip /v1/videos/upload: PostQuick stores the URL as-is and does not copy the media into Supabase. Then call POST /v1/videos/{videoId}/schedule or /publish. Use /v1/videos/upload only when your host is not publicly reachable or a platform requires a PostQuick-hosted URL.

## Request body

- object
  - `contentGroupId` string, required: Content group (app) that owns this video.
  - `videoUrl` string, uri: Publicly accessible HTTP(S) video URL. Use this directly to skip /v1/videos/upload; PostQuick stores the URL without copying the media.
  - `mediaUrl` string, uri: Backward-compatible alias for videoUrl.
  - `media_url` string, uri: Legacy snake_case alias for videoUrl.
  - `title` string: Title (used by YouTube; optional elsewhere).
  - `description` string: Caption / description.
  - `thumbnailUrl` string, uri: Optional thumbnail image URL.
  - `duration` integer: Duration in seconds.
  - `resolution` string: e.g. "1080x1920".
  - `platforms` string[]: Target platforms. Can also be set later via publish/schedule.
  - `visibility` string: Platform visibility, e.g. "public". Default "public".
  - `tags` string[]
  - `category` string
  - `facebookTarget` object: Facebook page publishing target
    - `pageId` string, required
    - `pageName` string
  - `linkedinTarget` object: LinkedIn publishing target
    - `type` 'personal' | 'organization', required
    - `organizationId` string
  - `tiktokSettings` object

## Response `201`

Video draft created.

- object
  - `success` true, required
  - `data` object, required
    - `video` object, required: A video post record
      - `id` string, required
      - `app_id` string, required
      - `title` string, nullable, required
      - `description` string, nullable, 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.
      - `video_url` string, nullable, required
      - `thumbnail_url` string, nullable, required
      - `platforms` string[], nullable, required
      - `posted_platforms` string[], nullable, required
      - `scheduled_for` string, date-time, nullable, required
      - `posted_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
      - `publishing` object, nullable: Durable publishing ledger projection. `needs_review` means an external outcome is uncertain; do not automatically retry it.
        - `state` 'queued' | 'running' | 'published' | 'failed' | 'partial' | 'needs_review', required
        - `platforms` object, required
        - `jobId` 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)