媒體上傳 API

上傳圖片和影片以取得可用於發佈 API 的託管 URL。

概述

媒體上傳 API 允許您直接將檔案上傳到 Boring 的雲端儲存，並取得公開的 URL。適用於以下情況：

您有本地檔案而非公開 URL
您想將媒體檔案託管在 Boring 的 CDN 上
您需要在發佈到社群平台之前先上傳檔案

檔案會自動被分配唯一的隨機檔名（UUID），以避免與其他使用者的檔案衝突。

端點

POST /api/v2/media/upload

認證

需要 API Key 認證：

boring-api-key: boring_xxxxxxxxxxxxx

請求格式

Content-Type

Content-Type: multipart/form-data

表單欄位

欄位	類型	必填	說明
`file`	File	是	要上傳的圖片或影片檔案

支援的檔案類型

圖片：

JPEG (.jpg, .jpeg)
PNG (.png)
GIF (.gif)
WebP (.webp)

影片：

MP4 (.mp4)
MOV (.mov)
AVI (.avi)
WebM (.webm)

檔案大小限制

類型	最大大小
圖片	10 MB
影片	500 MB

回應

成功回應

{
  "success": true,
  "data": {
    "url": "https://storage.googleapis.com/boring-video-uploads/media/550e8400-e29b-41d4-a716-446655440000.jpg",
    "filename": "550e8400-e29b-41d4-a716-446655440000.jpg",
    "content_type": "image/jpeg",
    "size": 102400,
    "uploaded_at": "2024-12-17T10:30:00Z"
  }
}

回應欄位

欄位	類型	說明
`url`	String	上傳檔案的公開 URL
`filename`	String	產生的唯一檔名（UUID 格式）
`content_type`	String	檔案的 MIME 類型
`size`	Integer	檔案大小（位元組）
`uploaded_at`	String	ISO 8601 時間戳記

錯誤回應

400 Bad Request - 未提供檔案：

{
  "success": false,
  "error": "No file provided"
}

400 Bad Request - 無效的檔案類型：

{
  "success": false,
  "error": "Invalid file type. Supported: jpg, jpeg, png, gif, webp, mp4, mov, avi, webm"
}

400 Bad Request - 檔案過大：

{
  "success": false,
  "error": "File too large. Max size: 10MB for images, 500MB for videos"
}

401 Unauthorized：

{
  "success": false,
  "error": "Invalid API key"
}

範例

cURL - 上傳圖片

curl -X POST https://boring.aiagent-me.com/api/v2/media/upload \
  -H "boring-api-key: boring_xxxxxxxxxxxxx" \
  -F "file=@/path/to/image.jpg"

cURL - 上傳影片

curl -X POST https://boring.aiagent-me.com/api/v2/media/upload \
  -H "boring-api-key: boring_xxxxxxxxxxxxx" \
  -F "file=@/path/to/video.mp4"

Python

import requests

api_key = "boring_xxxxxxxxxxxxx"
url = "https://boring.aiagent-me.com/api/v2/media/upload"

# 上傳圖片
with open("image.jpg", "rb") as f:
    response = requests.post(
        url,
        headers={"boring-api-key": api_key},
        files={"file": f}
    )

result = response.json()
if result["success"]:
    media_url = result["data"]["url"]
    print(f"已上傳：{media_url}")

JavaScript (Node.js)

const fs = require('fs');
const FormData = require('form-data');
const fetch = require('node-fetch');

const apiKey = 'boring_xxxxxxxxxxxxx';
const url = 'https://boring.aiagent-me.com/api/v2/media/upload';

const form = new FormData();
form.append('file', fs.createReadStream('image.jpg'));

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'boring-api-key': apiKey,
  },
  body: form,
});

const result = await response.json();
if (result.success) {
  console.log('已上傳：', result.data.url);
}

JavaScript (瀏覽器)

const apiKey = 'boring_xxxxxxxxxxxxx';
const url = 'https://boring.aiagent-me.com/api/v2/media/upload';

// 假設您有一個檔案輸入元素
const fileInput = document.getElementById('fileInput');
const file = fileInput.files[0];

const formData = new FormData();
formData.append('file', file);

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'boring-api-key': apiKey,
  },
  body: formData,
});

const result = await response.json();
if (result.success) {
  console.log('已上傳：', result.data.url);
}

搭配發佈 API 使用

上傳媒體後，使用回傳的 URL 搭配發佈 API：

# 步驟 1：上傳圖片
curl -X POST https://boring.aiagent-me.com/api/v2/media/upload \
  -H "boring-api-key: boring_xxxxxxxxxxxxx" \
  -F "file=@photo.jpg"

# 回應：{"success": true, "data": {"url": "https://storage.googleapis.com/boring-video-uploads/media/550e8400-e29b-41d4-a716-446655440000.jpg", ...}}

# 步驟 2：使用上傳的 URL 發佈
curl -X POST https://boring.aiagent-me.com/api/v2/posts \
  -H "boring-api-key: boring_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "post": {
      "accountId": "your-account-id",
      "content": {
        "text": "看看這張照片！",
        "mediaUrls": ["https://storage.googleapis.com/boring-video-uploads/media/550e8400-e29b-41d4-a716-446655440000.jpg"]
      },
      "target": {
        "targetType": "instagram"
      }
    }
  }'

多檔案上傳

要上傳多個檔案，請為每個檔案發送單獨的請求：

import requests

api_key = "boring_xxxxxxxxxxxxx"
url = "https://boring.aiagent-me.com/api/v2/media/upload"

files_to_upload = ["image1.jpg", "image2.jpg", "image3.jpg"]
uploaded_urls = []

for filepath in files_to_upload:
    with open(filepath, "rb") as f:
        response = requests.post(
            url,
            headers={"boring-api-key": api_key},
            files={"file": f}
        )
        result = response.json()
        if result["success"]:
            uploaded_urls.append(result["data"]["url"])

print(f"已上傳 {len(uploaded_urls)} 個檔案")
# 使用 uploaded_urls 搭配發佈 API

檔案保留

上傳的檔案永久儲存
檔案可透過回傳的 URL 公開存取
無自動清理或過期機制

速率限制

方案	請求/分鐘	最大檔案大小
免費	10	10 MB
Pro	60	500 MB

最佳實踐

本地驗證檔案 - 上傳前先驗證以避免錯誤
使用適當格式 - 照片用 JPEG、圖形用 PNG、影片用 MP4
壓縮大檔案 - 上傳前壓縮以減少上傳時間
儲存回傳的 URL - 以便稍後用於發佈 API
優雅處理錯誤 - 實作失敗上傳的重試邏輯