Direct Upload

Overview#

Use direct upload when the file is large or when your client cannot build a base64 string. The flow has three steps:

1. Ask for an upload URL. It is valid for 5 minutes.
2. PUT the raw file bytes to that URL. This request takes no API key; the URL itself is the credential.
3. Confirm the upload. The file is checked and stored in your brand library, the same way the /add endpoints store it.

The same three endpoints work for every asset kind. The image-only paths /images/upload-url, /images/upload and /images/confirm still work for existing clients and behave the same with kind fixed to image.

POST https://api.orshot.com/v1/brand-assets/upload-url
PUT  <uploadUrl from step 1>
POST https://api.orshot.com/v1/brand-assets/confirm

Request#

const { data } = await fetch("https://api.orshot.com/v1/brand-assets/upload-url", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    kind: "video",
    contentType: "video/mp4",
    fileName: "launch-teaser.mp4",
  }),
}).then((r) => r.json());

// data.uploadUrl, data.key, data.maxBytes, data.expiresAt

curl -X PUT "<data.uploadUrl>" \
  -H "Content-Type: video/mp4" \
  --data-binary @launch-teaser.mp4

await fetch("https://api.orshot.com/v1/brand-assets/confirm", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    key: data.key,
    name: "Launch teaser",
    tags: ["launch", "video"],
  }),
});

{
  "data": {
    "kind": "video",
    "asset": {
      "id": 418,
      "name": "Launch teaser",
      "direct_url": "https://storage.orshot.com/cloud/w-50/renders/brand_assets/x9Kq2mVt7Lp.mp4",
      "file_size": 18329044,
      "tags": ["launch", "video"],
      "workspace_id": 50
    },
    "url": "https://storage.orshot.com/cloud/w-50/renders/brand_assets/x9Kq2mVt7Lp.mp4"
  }
}

Step 1: Upload URL parameters#

Response fields:

Step 3: Confirm parameters#

Size limits and formats#

Processing after confirm is the same as for the /add endpoint of each kind: images are optimised and SVGs cleaned, videos may be converted, fonts are parsed for their family name. See Upload Brand Image, Upload Font, Upload Video and Upload Audio for the rules of each kind.

Notes#

• The file type is read from the bytes, not from contentType or the file extension. A file that is not a real image, font, video or audio file is refused at confirm.
• Unconfirmed uploads are deleted automatically. Confirm within a few minutes of the PUT.
• A key can only be confirmed by the workspace that requested it.

Error responses#

Query Parameters#

Pass them on the /confirm call, which is where the asset is created. See Per-User Brand Assets.

Rate Limits#

• Steps 1 and 3: 30 requests per minute per endpoint
• Step 2: 60 PUTs per minute per workspace