Авторизация

Для выполнения любых запросов к API требуется аутентификация с помощью уникального Bearer-токена. Управлять токенами можно в панели управления API.

Передача токена

Стандартный и рекомендуемый метод — передача токена в HTTP-заголовке Authorization. Если ваша архитектура или библиотека не поддерживает отправку пользовательских заголовков, допускается передача ключа в теле POST-запроса (параметр token).

Authorization: Bearer ВАШ_API_ТОКЕН

Коды ошибок авторизации

Система лимитов и квоты

Платформа использует гибкую систему тарификации. Каждый API-токен имеет индивидуальные настройки, которые вы самостоятельно конфигурируете в панели управления.

Настройки токена

• Максимум файлов за запрос: Физический предел файлов, отправляемых за один вызов API (от 5 до 100). Для загрузки объемов, превышающих данный лимит (например, 500 файлов), необходимо разделить их отправку на несколько последовательных запросов.
• Срок хранения: Максимальное время жизни загруженных файлов (от 3 дней до бесконечности). При отправке запроса вы можете программно указать меньший срок хранения, если файлы требуются временно.
• Месячная квота: Лимит успешных загрузок файлов, доступный вам в течение календарного месяца.

Защита от злоупотреблений (Rate Limits)

Для обеспечения стабильности серверов действуют следующие системные ограничения:

Вызов API: Загрузка файлов

Единый метод для загрузки медиафайлов. Позволяет загружать файлы массивами, автоматически формируя новые альбомы или выполняя безопасную дозагрузку в существующие альбомы вашего токена.

Параметры тела запроса (multipart/form-data)

Структура ответа (return_type = "album")

Компактный ответ, оптимизированный для случаев, когда требуется предоставить пользователю общую ссылку на галерею.

{
  "success": true,
  "album_id": "zX9k1",
  "album_url": "https://pixsafe.online/i/zX9k1",
  "uploaded_count": 5,
  "limits_applied": {
    "max_files_allowed": 50,
    "max_storage_days": 30,
    "applied_storage_days": 14,
    "monthly_quota_used": "125 / 5000"
  }
}

Структура ответа (return_type = "direct")

Развернутый ответ. Содержит массив files с прямыми ссылками и массив failed_files, в который помещаются файлы, отклоненные сервером (например, из-за неверного расширения или нулевого размера).

{
  "success": true,
  "album_id": "zX9k1",
  "album_url": "https://pixsafe.online/i/zX9k1",
  "uploaded_count": 2,
  "limits_applied": {
    "max_files_allowed": 50,
    "max_storage_days": "forever",
    "applied_storage_days": "forever",
    "monthly_quota_used": "unlimited"
  },
  "files": [
    {
      "original_name": "screen.png",
      "file_name": "screen_A1b2c.png",
      "direct_url": "https://cdn.pixsafe.online/albums/zX9k1/screen_A1b2c.png",
      "type": "image"
    },
    {
      "original_name": "video.mp4",
      "file_name": "video_F9d8a.mp4",
      "direct_url": "https://cdn.pixsafe.online/albums/zX9k1/video_F9d8a.mp4",
      "type": "video"
    }
  ],
  "failed_files": [
    {
      "name": "document.pdf",
      "reason": "Extension not allowed"
    }
  ]
}

Примеры реализации (Code Snippets)

curl --location 'https://pixsafe.online/api/v1/upload.php' \
--header 'Authorization: Bearer ВАШ_API_ТОКЕН' \
--form 'files[]=@"/path/to/image1.jpg"' \
--form 'files[]=@"/path/to/image2.png"' \
--form 'return_type="direct"' \
--form 'retention_days="7"'

import requests

url = "https://pixsafe.online/api/v1/upload.php"
headers = {"Authorization": "Bearer ВАШ_API_ТОКЕН"}
data = {
    "return_type": "direct",
    "retention_days": 7
}
files = [
    ("files[]", ("image1.jpg", open("image1.jpg", "rb"), "image/jpeg")),
    ("files[]", ("image2.png", open("image2.png", "rb"), "image/png"))
]

response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())

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

let data = new FormData();
data.append('files[]', fs.createReadStream('/path/to/image1.jpg'));
data.append('files[]', fs.createReadStream('/path/to/image2.png'));
data.append('return_type', 'direct');
data.append('retention_days', 7);

axios.post('https://pixsafe.online/api/v1/upload.php', data, {
  headers: {
    'Authorization': 'Bearer ВАШ_API_ТОКЕН',
    ...data.getHeaders()
  }
}).then(response => {
  console.log(response.data);
}).catch(error => {
  console.log(error.response.data);
});

$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://pixsafe.online/api/v1/upload.php',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => [
    'files[0]' => new CURLFile('/path/to/image1.jpg'),
    'files[1]' => new CURLFile('/path/to/image2.png'),
    'return_type' => 'direct',
    'retention_days' => 7
  ],
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ВАШ_API_ТОКЕН'
  ],
]);

$response = curl_exec($curl);
echo $response;

package main

import (
  "bytes"
  "fmt"
  "io"
  "mime/multipart"
  "net/http"
  "os"
  "path/filepath"
)

func main() {
  url := "https://pixsafe.online/api/v1/upload.php"
  
  payload := &bytes.Buffer{}
  writer := multipart.NewWriter(payload)
  
  // Добавление файла
  file, _ := os.Open("/path/to/image.jpg")
  defer file.Close()
  part, _ := writer.CreateFormFile("files[]", filepath.Base(file.Name()))
  io.Copy(part, file)
  
  // Добавление параметров
  writer.WriteField("return_type", "direct")
  writer.WriteField("retention_days", "7")
  writer.Close()

  req, _ := http.NewRequest("POST", url, payload)
  req.Header.Add("Authorization", "Bearer ВАШ_API_ТОКЕН")
  req.Header.Set("Content-Type", writer.FormDataContentType())

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  
  fmt.Println(string(body))
}