Tệp & Phương Tiện

Tải lên và quản lý tệp từ mã ứng dụng của bạn. Mỗi tệp đều có URL công khai vĩnh viễn.

Proyecta cung cấp một Files API thông qua SDK để quản lý tệp theo chương trình từ mã ứng dụng của bạn.

Tệp đính kèm trong chat

Ô nhập chat chấp nhận hình ảnh trực tiếp — dán ảnh chụp màn hình hoặc kéo tệp ảnh vào ô nhập. Các định dạng được hỗ trợ: PNG, JPEG, WebP, GIF, AVIF. Kích thước tối đa: 10 MB mỗi ảnh.

Tệp đính kèm trong chat là một phần của tin nhắn, không thuộc thư viện tệp của bạn. Để lưu trữ lâu dài, hãy sử dụng SDK.

Files API (SDK)

Mỗi ứng dụng Proyecta đã publish đều có quyền truy cập vào API lưu trữ tệp thông qua Proyecta SDK. SDK hỗ trợ liệt kê, lấy và tải lên tệp. Các tệp được tải lên sẽ có URL công khai vĩnh viễn mà bạn có thể tham chiếu từ ứng dụng của mình.

import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

// List files (supports limit and starting_after for pagination)
const files = await proyecta.files.list();

// Fetch a single file by ID
const file = await proyecta.files.get('1234567890123456789');
console.log(file.url); // permanent public URL

// Upload a file (two-step)
// Step 1: create a placeholder and get a signed upload URL
const { id: fileId, upload_url } = await proyecta.files.create({
    filename: 'avatar.png',
    mime_type: 'image/png',
});

// Step 2: PUT the file bytes directly to the signed URL
await fetch(upload_url, {
    method: 'PUT',
    body: fileBytes,
    headers: { 'Content-Type': 'image/png' },
});

// Step 3: finalize to get the permanent file record
const uploaded = await proyecta.files.finalize({ fileId });
console.log(uploaded.url); // permanent public URL, now populated

Mỗi tệp chứa các thông tin sau:

Trường	Mô tả
id	Định danh duy nhất (chuỗi snowflake dạng số)
url	URL công khai vĩnh viễn (được điền sau bước finalize)
filename	Tên tệp gốc khi tải lên
mime_type	image/jpeg, application/pdf, v.v.
size	Kích thước tính bằng byte
path	Đường dẫn thư mục tùy chọn (ví dụ: /images/blog)
content_hash	SHA-256 của nội dung tệp
metadata	Metadata dạng key/value tùy ý
created	Dấu thời gian tạo theo ISO 8601
updated	Dấu thời gian cập nhật lần cuối theo ISO 8601

Làm thế nào để tải tệp lên ứng dụng của tôi?

Việc tải tệp lên được xử lý thông qua AI builder. Hãy yêu cầu AI xây dựng luồng tải lên cho bạn:

• "Cho phép người dùng tải lên ảnh đại diện và lưu vào Proyecta Files"
• "Thêm thư viện ảnh để người dùng đã đăng nhập có thể tải lên và xem ảnh của họ"
• "Cho phép tôi đính kèm hóa đơn PDF vào các đơn hàng"

AI sẽ tích hợp tính năng tải lên vào mã ứng dụng của bạn bằng cách sử dụng API tải lên hai bước của SDK và tham chiếu đến URL công khai được trả về. Bạn cũng có thể gọi files.create() / files.finalize() trực tiếp từ mã ứng dụng của mình.

Câu hỏi thường gặp

URL tệp có công khai không?

Có. Mọi tệp được trả về bởi Files API đều có URL công khai vĩnh viễn. Đừng tải lên bất kỳ thứ gì bạn không muốn công khai.

Tệp có thể lớn đến mức nào?

Giới hạn kích thước mỗi tệp tùy thuộc vào gói dịch vụ của bạn. Tệp đính kèm trong chat bị giới hạn ở mức 10 MB mỗi ảnh.

Tôi có thể thay đổi kích thước hoặc cắt xén hình ảnh qua URL không?

Tính năng chuyển đổi hình ảnh theo thời gian thực (thay đổi kích thước, cắt xén, chuyển đổi định dạng) đang trong lộ trình phát triển.

Sắp ra mắt

• Chuyển đổi hình ảnh thông qua tham số URL (thay đổi kích thước, cắt xén, chuyển đổi định dạng)
• Tổ chức thư mục — tạo và quản lý đường dẫn thư mục trong bảng điều khiển
• “Add to Chat” từ một hàng tệp, để tài sản trong thư viện có thể được đưa vào cuộc hội thoại với AI