Медиа
Прежде чем создать пост, загрузите файлы и получите media_id. Файлы проверяются при загрузке по требованиям
Instagram, поэтому о негодном файле вы узнаете сразу, а не в момент публикации.
Лимиты
Актуальные значения всегда отдаёт GET /v1/platforms/instagram (они берутся из того же манифеста, по которому
проверяются файлы и посты):
| Параметр | Значение |
|---|---|
| Картинки | JPEG, PNG, WebP, до 8 МБ |
| Видео | MP4, MOV, от 3 секунд до 15 минут, до 300 МБ |
| Подпись поста | до 2200 символов, до 30 хэштегов |
| Карусель | от 2 до 20 элементов |
Файл для Instagram хранится у нас 30 дней с момента загрузки (retain_until); после этого статус expired, и пост
с таким файлом создать нельзя — загрузите файл заново.
Загрузка файла
POST /v1/media, multipart/form-data, поле file, обязательный Idempotency-Key. Ответ 201:
# Загрузка файла: multipart/form-data, поле file. Idempotency-Key обязателен на каждом POST
MEDIA_ID=$(curl -sS --fail-with-body -X POST "$API_URL/v1/media" \
-H "$AUTH" -H "Idempotency-Key: $(uuidgen)" \
-F "file=@${MEDIA_FILE};type=image/jpeg" | jq -r '.media_id')
echo "media_id: $MEDIA_ID"
# Загрузка файла: multipart/form-data, поле file
boundary = uuid.uuid4().hex
filename = os.path.basename(media_path)
mime = mimetypes.guess_type(filename)[0] or "application/octet-stream"
with open(media_path, "rb") as file:
payload = (
f'--{boundary}\r\nContent-Disposition: form-data; name="file"; filename="{filename}"\r\n'
f"Content-Type: {mime}\r\n\r\n"
).encode() + file.read() + f"\r\n--{boundary}--\r\n".encode()
media = api(
"POST", "/v1/media",
data=payload, content_type=f"multipart/form-data; boundary={boundary}",
idempotency_key=str(uuid.uuid4()),
)
print("media_id:", media["media_id"])
// Загрузка файла: multipart/form-data, поле file
const form = new FormData();
form.append("file", new Blob([await readFile(mediaPath)], { type: "image/jpeg" }), basename(mediaPath));
const media = await api("POST", "/v1/media", { form, idempotencyKey: randomUUID() });
console.log("media_id:", media.media_id);
// Загрузка файла: multipart/form-data, поле file
$media = api('POST', '/v1/media', ['file' => new CURLFile($mediaPath, mime_content_type($mediaPath), basename($mediaPath))], multipart: true, idempotencyKey: uuid4());
echo 'media_id: ', $media['media_id'], "\n";
// Загрузка файла: multipart/form-data, поле file
file, err := os.ReadFile(mediaPath)
if err != nil {
fail("%v", err)
}
var form bytes.Buffer
writer := multipart.NewWriter(&form)
header := make(textproto.MIMEHeader)
header.Set("Content-Disposition", fmt.Sprintf(`form-data; name="file"; filename="%s"`, filepath.Base(mediaPath)))
header.Set("Content-Type", http.DetectContentType(file))
part, _ := writer.CreatePart(header)
_, _ = part.Write(file)
_ = writer.Close()
var media struct {
MediaID string `json:"media_id"`
}
api("POST", "/v1/media", form.Bytes(), writer.FormDataContentType(), uuid4(), &media)
fmt.Println("media_id:", media.MediaID)
{
"media_id": "01a1ab14-96b9-74f1-bd17-9602e8f39b02",
"kind": "image",
"mime": "image/jpeg",
"size": 31087,
"sha256": "9f2c…",
"width": 1080,
"height": 1080,
"duration_ms": null,
"status": "ready",
"retain_until": "2026-12-05T09:00:00+00:00",
"created_at": "2026-11-05T09:00:00+00:00"
}
kind — image или video; для видео заполнены duration_ms, width, height.
Импорт по ссылке
Если файл уже лежит в интернете, не скачивайте его сами: POST /v1/media:import с телом {"url": "https://…"} скачает
его на сервере. Разрешены только публичные http(s)-адреса на портах 80 и 443; ссылки на внутренние адреса отклоняются
(unsafe_url), таймаут скачивания — 60 секунд.
curl -X POST https://castbase.ru/v1/media:import \
-H "Authorization: Bearer $CASTBASE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/photo.jpg"}'
Карточка и ошибки
GET /v1/media/{id} возвращает ту же карточку. Неподходящий файл — 422 validation_failed с errors[]:
{
"type": "https://castbase.ru/docs/errors#validation_failed",
"title": "Данные не прошли проверку",
"status": 422,
"detail": "Картинка больше 8 МБ.",
"code": "validation_failed",
"errors": [{"field": "file", "code": "too_large", "message": "Картинка больше 8 МБ."}]
}
Коды полей — в каталоге ошибок.