> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 上傳圖片或影片

> 上傳圖片或小型影片檔案以包含在您的貼文中

export const HeaderAPI = ({noProfileKey, profileKeyRequired}) => <>
    <ParamField header="Authorization" type="string" required>
      <a href="/apis/overview#authorization">API Key</a> of the Primary Profile.
      <br />
      <br />
      Format: <code>Authorization: Bearer API_KEY</code>
    </ParamField>
    {!noProfileKey && (profileKeyRequired ? <ParamField header="Profile-Key" type="string" required>
          <a href="/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField> : <ParamField header="Profile-Key" type="string">
          <a href="/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField>)}
  </>;

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

<PlansAvailable plans={["premium"]} maxPackRequired={false} />

此端點可讓您上傳檔案，或上傳圖片、小型影片以包含在您的貼文中。回傳的圖片 URL 可用於 /post 端點。

您可以將檔案以 ***multipart form data*** 作為表單參數傳送，或以 **Base64 編碼的檔案**作為主體參數傳送。

關於媒體上傳的重要說明：

1. 為了達到最佳效能，我們建議
   <ul className="custom-bullets">
     <li>將媒體檔案託管在您自己的伺服器（例如 AWS S3）。</li>
     <li>直接在 [/post](/apis/post/overview) 端點的 `mediaUrls` 參數中傳入媒體 URL。</li>
     <li>此方式比透過此端點上傳檔案更快。</li>
   </ul>

2. 媒體檔案保留期

   <ul className="custom-bullets">
     <li>上傳的檔案會保留 90 天。</li>
     <li>90 天後：</li>

     <ul className="custom-bullets">
       <li>已發布至社群網路的貼文不受影響。</li>
       <li>已排程貼文若引用過期媒體，將無法成功發布。</li>
     </ul>
   </ul>

3. 檔案大小限制
   <ul className="custom-bullets">
     <li>最大檔案大小：30 MB。</li>
     <li>若檔案較大，請參閱我們的[處理大型媒體上傳](/apis/media/upload-large-media)指南。</li>
   </ul>

<Tip>如果您的媒體已可透過外部 URL（例如 S3 儲存桶）存取，就不必再將檔案上傳到 Ayrshare。只要在 POST 到 `/post` 端點時，將外部可存取的 URL 放入 `mediaURLs` 請求主體參數，您的檔案就會被自動上傳。</Tip>

## 標頭參數

<HeaderAPI noProfileKey={true} />

<ParamField body="Content-Type" type="string" required>
  若傳送 multipart form data，請使用 `multipart/form-data` — 請參見下方。否則使用標準的 `application/json`。
</ParamField>

## 主體參數

<ParamField body="file" type="string or object" required>
  最大檔案大小 30 MB。

  我們建議以 multipart form-data 物件傳送，而不是使用 Base64 編碼。
</ParamField>

<ParamField body="fileName" type="string">
  要上傳的檔案名稱。
</ParamField>

<ParamField body="description" type="string">
  檔案的描述。
</ParamField>

### 以 Multipart Form-Data 傳送

以 multipart form-data 物件傳送媒體檔案。請務必依上述指定 `Content-Type`。

### 以 Base64 傳送

將媒體檔案以 Base64 編碼字串作為 Data URI 字串傳送。該字串應以 `data:content/type;base64` 開頭。

以 Data URI 輸出格式進行編碼的範例：

<ul className="custom-bullets">
  <li>圖片：[https://base64.guru/converter/encode/image](https://base64.guru/converter/encode/image)</li>
  <li>影片：[https://base64.guru/converter/encode/video](https://base64.guru/converter/encode/video)</li>
</ul>

注意：/post 端點可透過 `mediaUrls` 參數搭配外部 URL 接受較大的檔案。

<RequestExample>
  ```bash cURL theme={"system"}
  # Send as Multipart Form-Data
  curl \
  -H "Authorization: Bearer API_KEY" \
  -F "file=@test.png" \
  -F "fileName=test.png" \
  -F "description=best image" \
  -X POST https://api.ayrshare.com/api/media/upload

  # Send as Base64
  curl \
  -H "Authorization: Bearer API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...", "fileName": "test.png", "description": "best image"}' \
  -X POST https://api.ayrshare.com/api/media/upload
  ```

  ```javascript JavaScript theme={"system"}
  // Send as Multipart Form-Data
  const FormData = require('form-data');
  const fs = require('fs');

  const API_KEY = "API_KEY";
  const imagePath = './test.png';

  const form = new FormData();
  form.append('file', fs.createReadStream(imagePath));
  form.append('fileName', 'test.png');
  form.append('description', 'best image');

  fetch("https://api.ayrshare.com/api/media/upload", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`
      // Don't set Content-Type header - FormData will set it automatically with boundary
    },
    body: form
  })
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(console.error);

  // Send as Base64
  const API_KEY = "API_KEY";
  const base64 = "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...";

  fetch("https://api.ayrshare.com/api/media/upload", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Authorization": `Bearer ${API_KEY}`
        },
        body: JSON.stringify({
          file: base64,
          fileName: "test.png",
          description: "best image"
        }),
      })
        .then((res) => res.json())
        .then((json) => console.log(json))
        .catch(console.error);
  ```

  ```python Python theme={"system"}
  # Send as Multipart Form-Data
  import requests

  # For a local file:
  files = {
      'file': ('test.png', open('test.png', 'rb')),
  }

  # Form data
  data = {
      'fileName': 'test.png',
      'description': 'best image'
  }
  headers = {
      'Authorization': 'Bearer API_KEY'
  }

  r = requests.post(
      'https://api.ayrshare.com/api/media/upload',
      files=files,
      data=data,
      headers=headers
  )

  print(r.json())

  # Send as Base64
  import requests

  payload = {'file': 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...',
          'fileName': "test.png",
          'description': "best image"}
  headers = {'Content-Type': 'application/json',
          'Authorization': 'Bearer API_KEY'}

  r = requests.post('https://api.ayrshare.com/api/media/upload',
      json=payload,
      headers=headers)

  print(r.json())
  ```

  ```php PHP theme={"system"}
  # Send as Multipart Form-Data
  <?php
    // Generate a boundary string
    $boundary = uniqid();

    // Open the file
    $file = file_get_contents('test.png');

    // Build the multipart form data
    $data = '';
    $data .= "--" . $boundary . "\r\n";
    $data .= 'Content-Disposition: form-data; name="file"; filename="test.png"' . "\r\n";
    $data .= "Content-Type: image/png\r\n\r\n";
    $data .= $file . "\r\n";

    $data .= "--" . $boundary . "\r\n";
    $data .= 'Content-Disposition: form-data; name="fileName"' . "\r\n\r\n";
    $data .= "test.png\r\n";

    $data .= "--" . $boundary . "\r\n";
    $data .= 'Content-Disposition: form-data; name="description"' . "\r\n\r\n";
    $data .= "best image\r\n";

    $data .= "--" . $boundary . "--\r\n";

    // Setup the context for the request
    $options = [
        'http' => [
            'method' => 'POST',
            'header' => "Authorization: Bearer API_KEY\r\n" .
                      "Content-Type: multipart/form-data; boundary=" . $boundary . "\r\n" .
                      "Content-Length: " . strlen($data) . "\r\n",
            'content' => $data
        ]
    ];

    // Send the request
    $context = stream_context_create($options);
    $result = file_get_contents('https://api.ayrshare.com/api/media/upload', false, $context);

    // Print the response
    echo $result;

  # Send as Base64
  <?php
  $data = [
      'file' => 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...',
      'fileName' => "test.png",
      'description' => "best image"
  ];

  $ch = curl_init('https://api.ayrshare.com/api/media/upload');
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Content-Type: application/json',
      'Authorization: Bearer API_KEY'
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
  ```
</RequestExample>

<ResponseExample>
  ```javascript 200: Success theme={"system"}
  {
      "id": "1167335b-6c37-4fc6-ab8a-044e0005d335-jpeg",
      "url": "https://images.ayrshare.com/q3Ls85VTsrbODnGIJHpy7PaHWwA3/1167335b-6c37-4fc6-ab8a-044ed885d.jpeg",
      "fileName": "fun.jpg",
      "description": "good times"
  }
  ```

  ```json 400: Bad Request Error in upload theme={"system"}
  {
    "action": "request",
    "status": "error",
    "code": 101,
    "message": "Missing or incorrect parameters. Please verify with the docs. .../ayrshare.com/rest-api/endpoints"
  }
  ```
</ResponseExample>