Загрузить файл

POSThttps://api.souz.ai/v1/files

Референс для генераций: картинка (png/jpeg/webp, до 50 МиБ, JPEG до 300 Мп), ролик (mp4/mov, до 200 МиБ), звук (wav/mp3, до 15 МиБ). Полученный file_… подставляется в поля запросов вместо байтов. Файл живёт 1 день. Тяжёлые картинки-референсы загружайте так заранее: тело запроса генерации остаётся маленьким, и запрос принимается сразу. Загрузки аккаунта, срок которых ещё не вышел, — не больше 10 ГБ, после первого пополнения — не больше 50 ГБ; сверх — 413 storage_limit_exceeded. Файлы, присланные в самом запросе, в квоту не входят.

Авторизация

BearerAuth

API-ключ из кабинета souz.ai — запускает модели. Ключ управления здесь не подходит: 403 forbidden с detail[].reason: requires_api_key.

Тело запроса обязательно

multipart/form-data

Схема FileUploadRequest

filestringобязательно

Файл; имя берётся из части формы.

Формат содержимого: application/octet-stream

purposestring

Поле SDK OpenAI; принимается и ни на что не влияет.

Ответы

201Файл сохранён.

application/json

Схема File

bytesinteger · int64обязательно

content_typestringобязательно

Пример: "image/png"

created_atstring · date-timeобязательно

expiredbooleanобязательно

expires_atstring · date-timeобязательно

filenamestringобязательно

heightinteger

Только у картинок.

idstringобязательно

Пример: "file_9f8e7d6c5b4a"

kindstringобязательно

Значения: upload, reference, result

objectstringобязательно

Значение: "file"

urlstring · uri

widthinteger

Только у картинок.

400Запрос отклонён; `error.detail[]` называет поля и допустимые значения.

application/json

Error

401Нет ключа или ключ недействителен.

application/json

Error

403Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли

Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли участника нет права или подпись ссылки на файл не сходится. detail[].reason говорит, что именно: requires_api_key, requires_management_key, cabinet_only (только в кабинете), insufficient_role (в allowed — роли, которым можно), not_key_author (секрет ключа открывает только тот, кто его создал).

application/json

Error

413Тело или файл больше предела (`invalid_input`, `detail[].reason: too_large`) или — только у `POST /v1/files` — загрузки аккаунта заняли квоту (`storage_limit_exceeded`).

application/json

Error

415Тип тела не тот, что принимает метод: `Content-Type: application/json` (у загрузки файла и транскрибации — `multipart/form-data`). В `detail[]` — `{"path": "body", "reason": "unsupported_format"}` и принимаемые типы.

application/json

Error

429Слишком часто — повторите через `Retry-After` секунд. Запуск моделей, задачи и файлы результатов частотой не ограничены (их ограничивают баланс и лимиты трат); здесь 429 — на поток запросов с ключом, который сервер не знает, с одного адреса, и на потоки сверх 1000 одновременных на аккаунт (события задачи, чат с `stream: true`). Пределы — раздел «Лимиты» руководства.

application/json

Error

503Сервер занят большими запросами (`overloaded`) — повторите через `Retry-After`. На

Сервер занят большими запросами (overloaded) — повторите через Retry-After. На плановых работах — maintenance (ответ Maintenance).

application/json

Error

Запрос

curl -X POST 'https://api.souz.ai/v1/files' \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -F 'file=@file.png'

import os
import requests

response = requests.post(
    "https://api.souz.ai/v1/files",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_API_KEY']}"},
    files={"file": open("file.png", "rb")},
)
print(response.json())

import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("file", await openAsBlob("file.png"), "file.png");

const response = await fetch("https://api.souz.ai/v1/files", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SOUZ_API_KEY}` },
  body: form,
});
console.log(await response.json());

Ответ

{
  "error": {
    "code": "capability_mismatch",
    "detail": [
      {
        "allowed": [
          "1:1",
          "16:9",
          "9:16"
        ],
        "path": "aspect_ratio",
        "reason": "unsupported_value"
      }
    ],
    "message": "the model does not support this value",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "forbidden",
    "detail": [
      {
        "reason": "requires_api_key"
      }
    ],
    "message": "this endpoint takes an API key; a management key manages the account only",
    "type": "permission_error"
  }
}