> ## 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>

## Header Parameters

<HeaderAPI noProfileKey={true} />

<ParamField body="Content-Type" type="string" required>
  如果发送 multipart form data,请使用 `multipart/form-data`,详见下文。否则,发送标准的 `application/json`。
</ParamField>

## Body Parameters

<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>