> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aigenda.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Загрузка файла
> Файл любого размера: создаём запись, грузим части в хранилище, подтверждаем загрузку.
Файл уходит не в API, а прямо в объектное хранилище по временным ссылкам. API выдаёт ссылки и принимает подтверждение.
Ваш сервис
API AiGenda
Хранилище
1
POST /audio/
title, size, content\_type
2
id, url\[]
ссылки на части
3
PUT часть
по ссылке url\[i]
4
ETag
в заголовке ответа
5
POST /complete\_upload/
PartNumber и ETag
6
GET /info/
до is\_uploaded: true
1
Ваш сервис → API AiGenda
POST /audio/
title, size, content\_type
2
API AiGenda → Ваш сервис
id, url\[]
ссылки на части
3
Ваш сервис → Хранилище
PUT часть
по ссылке url\[i]
4
Хранилище → Ваш сервис
ETag
в заголовке ответа
5
Ваш сервис → API AiGenda
POST /complete\_upload/
PartNumber и ETag
6
Ваш сервис → API AiGenda
GET /info/
до is\_uploaded: true
## Шаги
```bash theme={null}
curl -X POST https://api.aigenda.tech/api/spaces/1024/audio/ \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{"title": "Планёрка отдела продаж.mp3", "size": 18874368, "content_type": "audio/mpeg"}'
```
| Поле | Правило |
| - | - |
| `title` | До 255 символов. **Заканчивается расширением файла**: `.mp3`, `.m4a`, `.wav`, `.ogg`, `.webm`, `.mp4`. По расширению AiGenda определяет формат |
| `size` | Точный размер файла в байтах |
| `content_type` | MIME-тип: `audio/mpeg`, `audio/mp4`, `audio/wav`, `audio/ogg`, `audio/webm`, `video/mp4` |
```json Ответ 201 theme={null}
{
"id": 51234,
"title": "Планёрка отдела продаж.mp3",
"url": [
"https://storage.yandexcloud.net/aigenda/3f6c1e0a.mp3?partNumber=1&uploadId=…&X-Amz-Signature=…"
],
"created_at": "2026-10-17T09:30:00Z",
"duration": null,
"size": 18874368,
"content_type": "audio/mpeg",
"space_id": 1024,
"is_uploaded": false,
"was_classified": false,
"result_is_ready": false
}
```
`url` всегда массив: по ссылке на каждую часть файла, примерно одна часть на 1 ГБ.
Разделите файл на столько частей, сколько пришло ссылок:
* размер части: `ceil(size / len(url))` байт, последняя часть короче;
* часть с номером `i` (с единицы) уходит на ссылку `url[i-1]`;
* метод `PUT`, тело запроса: байты части, без JSON и multipart-формы;
* из ответа хранилища сохраните заголовок `ETag` вместе с двойными кавычками: `"9b2cf535f27731c974343645a3985328"`.
Ссылки живут **5 часов** с момента создания записи. Хранилище разрешает запросы из браузера (CORS открыт, `ETag` читается), так что грузить можно и с фронтенда.
Передайте номера частей и их `ETag` в том порядке, в котором грузили.
```bash theme={null}
curl -X POST https://api.aigenda.tech/api/spaces/1024/audio/51234/complete_upload/ \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{"parts": [{"PartNumber": 1, "ETag": "\"9b2cf535f27731c974343645a3985328\""}]}'
```
Ответ: `200` с пустым телом.
Опрашивайте [`info/`](/api-reference/audio/info) раз в 2 секунды, пока не придёт `is_uploaded: true`. Обычно это меньше секунды. После этого [запускайте обработку](/processing/start).
## Готовый код
```python Python theme={null}
import math
import os
import time
import requests
API = "https://api.aigenda.tech"
def upload_file(token: str, space_id: int, path: str, content_type: str) -> int:
"""Загружает файл в пространство и возвращает audio_id, когда AiGenda подтвердила файл."""
headers = {"Authorization": f"Bearer {token}"}
size = os.path.getsize(path)
title = os.path.basename(path) # имя с расширением, например «Планёрка.mp3»
r = requests.post(
f"{API}/api/spaces/{space_id}/audio/",
headers=headers,
json={"title": title, "size": size, "content_type": content_type},
timeout=30,
)
r.raise_for_status()
audio = r.json()
urls = audio["url"]
part_size = math.ceil(size / len(urls))
parts = []
with open(path, "rb") as f:
for number, url in enumerate(urls, start=1):
chunk = f.read(part_size)
put = requests.put(url, data=chunk, timeout=900)
put.raise_for_status()
parts.append({"PartNumber": number, "ETag": put.headers["ETag"]})
r = requests.post(
f"{API}/api/spaces/{space_id}/audio/{audio['id']}/complete_upload/",
headers=headers,
json={"parts": parts},
timeout=30,
)
r.raise_for_status()
for _ in range(60):
info = requests.get(
f"{API}/api/spaces/{space_id}/audio/{audio['id']}/info/",
headers=headers,
timeout=30,
).json()
if info.get("is_uploaded"):
return audio["id"]
time.sleep(2)
raise TimeoutError("AiGenda не подтвердила файл за 2 минуты")
```
```javascript JavaScript (Node.js 18+) theme={null}
import { open, stat } from "node:fs/promises";
import { basename } from "node:path";
const API = "https://api.aigenda.tech";
// Загружает файл в пространство и возвращает audioId, когда AiGenda подтвердила файл.
export async function uploadFile(token, spaceId, path, contentType) {
const auth = { Authorization: `Bearer ${token}` };
const json = { ...auth, "Content-Type": "application/json" };
const { size } = await stat(path);
const created = await fetch(`${API}/api/spaces/${spaceId}/audio/`, {
method: "POST",
headers: json,
body: JSON.stringify({ title: basename(path), size, content_type: contentType }),
});
if (!created.ok) throw new Error(`create: ${created.status}`);
const audio = await created.json();
const partSize = Math.ceil(size / audio.url.length);
const parts = [];
const file = await open(path);
try {
for (let i = 0; i < audio.url.length; i++) {
const length = Math.min(partSize, size - i * partSize);
const chunk = Buffer.alloc(length);
await file.read(chunk, 0, length, i * partSize);
const put = await fetch(audio.url[i], { method: "PUT", body: chunk });
if (!put.ok) throw new Error(`part ${i + 1}: ${put.status}`);
parts.push({ PartNumber: i + 1, ETag: put.headers.get("ETag") });
}
} finally {
await file.close();
}
const done = await fetch(`${API}/api/spaces/${spaceId}/audio/${audio.id}/complete_upload/`, {
method: "POST",
headers: json,
body: JSON.stringify({ parts }),
});
if (!done.ok) throw new Error(`complete: ${done.status}`);
for (let attempt = 0; attempt < 60; attempt++) {
const res = await fetch(`${API}/api/spaces/${spaceId}/audio/${audio.id}/info/`, { headers: auth });
const info = await res.json();
if (info.is_uploaded) return audio.id;
await new Promise((resolve) => setTimeout(resolve, 2000));
}
throw new Error("AiGenda не подтвердила файл за 2 минуты");
}
```
## Если что-то пошло не так
| Ситуация | Что делать |
| - | - |
| Хранилище ответило `403` на `PUT` | Ссылки истекли (прошло больше 5 часов). Создайте запись заново, старую [удалите](/api-reference/audio/delete) |
| Ответ на создание записи не пришёл (таймаут, обрыв) | Не создавайте запись вслепую второй раз: каждый вызов добавляет новую запись. Найдите её по названию, см. [Надёжная интеграция](/reference/best-practices) |
| Часть не загрузилась | Повторите `PUT` этой части по той же ссылке, пока ссылки не истекли |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.