Create a video from a source URL

POST

/videos

curl --request POST \
  --url https://api.devstreamcore.com/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "input": [ { "url": "https://example.com" } ], "title": "example", "description": "example", "playback_policy": "public", "passthrough": "example", "quality": "original" }'

• Production

Ingest a video by URL. Transcoding starts automatically.

Authorizations

• ApiKey

Request Body

Media type application/json

object

input

required

Array<object>

>= 1 items

object

url

required

string format: uri

title

string

>= 1 characters <= 255 characters

description

string

<= 4096 characters

playback_policy

string

default: public

Allowed values: public signed

passthrough

string

<= 2048 characters

quality

string

Allowed values: original 480p 720p 1080p 1440p 4K 8K

Responses

201

Video created (status preparing)

Media type application/json

A video asset. The shape is stable — fields are only ever added.

object

id

required

string

title

required

string

description

required

string | null

thumbnail_url

required

string | null

status

required

string

Allowed values: preparing ready errored reprocessing

progress

required

0–100, aggregated across encode + package jobs

number

transcode_attempts

required

number | null

duration

required

Seconds

number | null

file_size_bytes

required

number | null

video_codec

required

string | null

fps

required

number | null

source_url

required

Public URL of the original upload; null until landed in R2

string | null

source_width

required

Native width of the original upload (px); null when unknown

number | null

source_height

required

Native height of the original upload (px); null when unknown

number | null

creator_username

required

string | null

playback

required

object

hls

required

string | null

dash

required

string | null

mp4

required

Array<object>

object

height

required

number

url

required

string

bitrate_kbps

required

Encode target bitrate in kb/s; null on legacy rows

number | null

hls

required

Per-resolution HLS variant playlist URL; null when ungated

string | null

playback_ids

required

Array<object>

object

id

required

string

policy

required

string

Allowed values: public signed

created_at

required

string

policy

required

string

Allowed values: public signed

passthrough

required

string | null

ingest

required

object

kind

required

string

Allowed values: direct_upload url console

errors

required

Array<object>

object

type

required

string

messages

required

Array<string>

view_count

required

number

tags

required

Array<string>

created_at

required

string

updated_at

required

string

Example

{
  "id": "vid_a1b2c3d4e5f6a1b2c3d4",
  "status": "preparing",
  "playback_ids": [
    {
      "id": "play_a1b2c3d4e5f6a1b2c3d4",
      "policy": "public"
    }
  ],
  "policy": "public",
  "ingest": {
    "kind": "direct_upload"
  }
}

400

Invalid request

Media type application/json

Error envelope — a single error per response.

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found rate_limit_error quota_exceeded api_error

code

string

message

required

string

param

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

401

Missing or invalid API key

Media type application/json

Error envelope — a single error per response.

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found rate_limit_error quota_exceeded api_error

code

string

message

required

string

param

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

402

Quota exceeded (encode minutes / duration / views)

Media type application/json

Error envelope — a single error per response.

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found rate_limit_error quota_exceeded api_error

code

string

message

required

string

param

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

429

Rate limited — apply backoff

Media type application/json

Error envelope — a single error per response.

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found rate_limit_error quota_exceeded api_error

code

string

message

required

string

param

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}