Skip to content
PostFlow

Import media from a URL

POST
/media
curl --request POST \
  --url https://postflow.biz.id/api/v1/media \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "example", "name": "example", "width": 1, "height": 1, "durationMs": 1 }'

Downloads a JPEG, PNG, WebP, GIF, MP4, MOV or WebM from a public https URL (images up to 30 MB, videos up to 1 GB with a Content-Length). Send a video’s size and length so pre-flight can check them.

MCP tool: import_media.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
url
required
string
<= 2000 characters
name
string
>= 1 characters <= 200 characters
width
integer
> 0 <= 20000
height
integer
> 0 <= 20000
durationMs
integer
> 0 <= 86400000

Example generated

{
  "url": "example",
  "name": "example",
  "width": 1,
  "height": 1,
  "durationMs": 1
}

Responses

Section titled “Responses”

201

Section titled “201”

OK

Media typeapplication/json
object
id
required

Use in mediaIds.

string
kind
required
string
Allowed values: image video
mime
required
string
Allowed values: image/jpeg image/png image/webp image/gif video/mp4 video/quicktime video/webm
sizeBytes
required
integer
width
required
Any of:
integer
height
required
Any of:
integer
durationMs
required
Any of:
integer
originalName
required
string
parentId
required
Any of:

Set on edited copies (e.g. a crop) of another file.

string
url
required

App path of the file. With the API, download it from /media/{id}/file.

string
thumbUrl
required
Any of:
string
createdAt
required
string format: date-time

Example 

{
  "kind": "image",
  "mime": "image/jpeg"
}

400

Section titled “400”

Validation failed. details lists what to fix.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: UNAUTHENTICATED FORBIDDEN NOT_FOUND VALIDATION CONFLICT SUBSCRIPTION_GRACE SUBSCRIPTION_EXPIRED PLAN_LIMIT RATE_LIMITED INTERNAL
message
required

A sentence you can show to a person.

string
details

Field errors ({ field: [messages] }), or preflight: per-account rule violations with an issue code.

Example 

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

401

Section titled “401”

Missing, invalid, expired or deleted key or token.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: UNAUTHENTICATED FORBIDDEN NOT_FOUND VALIDATION CONFLICT SUBSCRIPTION_GRACE SUBSCRIPTION_EXPIRED PLAN_LIMIT RATE_LIMITED INTERNAL
message
required

A sentence you can show to a person.

string
details

Field errors ({ field: [messages] }), or preflight: per-account rule violations with an issue code.

Example 

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

402

Section titled “402”

Subscription inactive or plan limit reached.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: UNAUTHENTICATED FORBIDDEN NOT_FOUND VALIDATION CONFLICT SUBSCRIPTION_GRACE SUBSCRIPTION_EXPIRED PLAN_LIMIT RATE_LIMITED INTERNAL
message
required

A sentence you can show to a person.

string
details

Field errors ({ field: [messages] }), or preflight: per-account rule violations with an issue code.

Example 

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

403

Section titled “403”

Not allowed: a read-only key, the owner’s approval, or an owner-only action.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: UNAUTHENTICATED FORBIDDEN NOT_FOUND VALIDATION CONFLICT SUBSCRIPTION_GRACE SUBSCRIPTION_EXPIRED PLAN_LIMIT RATE_LIMITED INTERNAL
message
required

A sentence you can show to a person.

string
details

Field errors ({ field: [messages] }), or preflight: per-account rule violations with an issue code.

Example 

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

429

Section titled “429”

More than 120 requests in a minute with this key.

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: UNAUTHENTICATED FORBIDDEN NOT_FOUND VALIDATION CONFLICT SUBSCRIPTION_GRACE SUBSCRIPTION_EXPIRED PLAN_LIMIT RATE_LIMITED INTERNAL
message
required

A sentence you can show to a person.

string
details

Field errors ({ field: [messages] }), or preflight: per-account rule violations with an issue code.

Example 

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}
© 2026 PostFlow