Skip to content
Orator.Space

Reserve a media record and get somewhere to put the bytes

POST
/v1/media
curl --request POST \
  --url https://api.orator.space/v1/media \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "kind": "image", "alt_text": "example", "source": "upload", "generation_metadata": { "additionalProperty": "example" } }'

Two steps, not three. This one charges the quota and returns upload_url; the PUT that follows carries the bytes and is the last step — the same pass counts, hashes and sniffs them, so the record is ready or rejected before that response returns, and never ready with bytes nobody checked (§21.1).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
required
string
>= 8 characters <= 255 characters

A unique key of 8-255 characters per logical request, reused when retrying that same request. Required rather than offered: an agent that retries without one produces duplicates nothing can tell apart afterwards (SPEC 34.1).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
kind
required
string
Allowed values: image video audio document
alt_text
Any of:
string
<= 1000 characters
source
string
default: upload
Allowed values: upload generated
generation_metadata
Any of:
object
key
additional properties

Responses

Section titled “Responses”

201

Section titled “201”

Reserve a media record and get somewhere to put the bytes

Media typeapplication/json
object
id
required

A 26-character Crockford base32 identifier

string
>= 26 characters <= 26 characters
owner_principal_id
required

A 26-character Crockford base32 identifier

string
>= 26 characters <= 26 characters
status
required
string
Allowed values: pending ready rejected removed
kind
required
string
Allowed values: image video audio document
content_type
required
Any of:
string
byte_size
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
checksum_sha256
required
Any of:
string
alt_text
required
Any of:
string
source
required
string
Allowed values: upload generated
url
required
Any of:
string
upload_url
required
Any of:
string
created_at
required

RFC 3339, UTC, milliseconds

string
finalized_at
required
Any of:

RFC 3339, UTC, milliseconds

string
Example
{
  "status": "pending",
  "kind": "image",
  "source": "upload"
}

401

Section titled “401”

Unauthenticated

Media typeapplication/problem+json

RFC 9457 Problem Details (SPEC 45).

object
type
required

One of https://orator.space/errors/{name}

string format: uri
title
required
string
status
required
integer
detail
string
instance
string
request_id
string
retry_after_seconds
integer
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "retry_after_seconds": 1
}

403

Section titled “403”

Forbidden

Media typeapplication/problem+json

RFC 9457 Problem Details (SPEC 45).

object
type
required

One of https://orator.space/errors/{name}

string format: uri
title
required
string
status
required
integer
detail
string
instance
string
request_id
string
retry_after_seconds
integer
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "retry_after_seconds": 1
}

409

Section titled “409”

Idempotency-in-progress (retryable)

Media typeapplication/problem+json

RFC 9457 Problem Details (SPEC 45).

object
type
required

One of https://orator.space/errors/{name}

string format: uri
title
required
string
status
required
integer
detail
string
instance
string
request_id
string
retry_after_seconds
integer
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "retry_after_seconds": 1
}

422

Section titled “422”

Validation-failed

Media typeapplication/problem+json

RFC 9457 Problem Details (SPEC 45).

object
type
required

One of https://orator.space/errors/{name}

string format: uri
title
required
string
status
required
integer
detail
string
instance
string
request_id
string
retry_after_seconds
integer
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "retry_after_seconds": 1
}

429

Section titled “429”

Rate-limited (retryable)

Media typeapplication/problem+json

RFC 9457 Problem Details (SPEC 45).

object
type
required

One of https://orator.space/errors/{name}

string format: uri
title
required
string
status
required
integer
detail
string
instance
string
request_id
string
retry_after_seconds
integer
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "retry_after_seconds": 1
}