API Tham khảo
Các điểm cuối, khóa, giới hạn. Tham khảo cho các điểm cuối AI tạo hình ảnh — tạo, xóa, mở rộng — với xác thực, CORS và giới hạn tốc độ.
Morph cung cấp một loạt các điểm kết nối AI-powered tại api.morph.cool. Các điểm kết nối này điều khiển tính năng AI của Artboard và có thể được sử dụng bởi các nhà phát triển xây dựng tích hợp.
https://api.morph.coolTất cả yêu cầu đều sử dụng HTTPS. Yêu cầu HTTP sẽ bị từ chối.
Xác thực
Điểm cuối AI (tạo, xóa, mở rộng) không yêu cầu xác thực cho sử dụng cơ bản. Chúng bị giới hạn tốc độ theo địa chỉ IP. Các điểm cuối sửa đổi dữ liệu người dùng (chuyển đổi, chuông, bảng xếp hạng) yêu cầu token JWT được truyền dưới dạng Bearer token trong header Authorization.
Authorization: Bearer <jwt_token>
Giới hạn tốc độ
Tất cả các điểm kết nối đều bị giới hạn tốc độ để ngăn chặn lạm dụng. Vượt quá giới hạn sẽ trả về trạng thái 429 kèm lỗi JSON.
- Các điểm kết nối Artboard AI — 10 yêu cầu mỗi phút mỗi IP (dựa trên KV).
- Ghi log chuyển đổi — yêu cầu xác thực, không giới hạn IP riêng.
- Báo cáo lỗi — 30 yêu cầu mỗi phút trên mỗi IP.
- Chờ đợi — 10 yêu cầu mỗi phút mỗi IP.
Tạo hình ảnh
POST /artboard/generate
Tạo hình ảnh từ văn bản và chỉnh sửa vùng chọn. Gửi hình ảnh canvas kèm mask để điền vào vùng được chọn dựa trên prompt văn bản. Cũng hỗ trợ chế độ mô tả trả về mô tả văn bản của hình ảnh.
| Trường | Nhập | Mô tả |
|---|---|---|
| gợi ý | string | Mô tả văn bản về nội dung cần tạo. Không bắt buộc khi sử dụng chế độ mô tả. |
| canvasImagebắt buộc | string | PNG được mã hóa Base64 của nội dung canvas. |
| maskImage | string | PNG mã hóa Base64 của mặt nạ chọn lựa. Màu trắng = khu vực cần điền. Bắt buộc cho inpainting, không cần thiết cho describe. |
| chế độ | string | Đặt thành "describe" để kích hoạt chế độ mô tả hình ảnh. Bỏ qua để tạo hình. |
Phản hồi tạo:
{
"result": "<base64_png_string>"
}
Mô tả phản hồi:
{
"result": "A detailed text description of the image content."
}
Xác thực: Trong chế độ mô tả, tệp PNG phải có kích thước tối thiểu 64×64 pixel. Ảnh nhỏ hơn sẽ trả về lỗi REGION_TOO_SMALL.
Xóa đối tượng
POST /artboard/remove
Xóa đối tượng được hỗ trợ AI. Vẽ lên đối tượng trong mask và mô hình sẽ lấp đầy khu vực bằng nội dung phù hợp với ngữ cảnh.
| Trường | Nhập | Mô tả |
|---|---|---|
| canvasImagebắt buộc | string | Ảnh PNG được mã hóa Base64 của canvas. |
| maskImagerequired | string | Mặt nạ PNG được mã hóa Base64. Màu trắng = khu vực cần xóa. |
Phản hồi:
{
"result": "<base64_png_string>"
}
Mở rộng Tạo Giống
POST /artboard/expand
Mở rộng canvas theo một hướng nhất định. AI sẽ lấp đầy khu vực mới với nội dung phù hợp với hình ảnh hiện có. Sử dụng mở rộng pixel cạnh để giữ ngữ cảnh.
| Trường | Nhập | Mô tả |
|---|---|---|
| canvasImagebắt buộc | string | PNG được mã hóa Base64 của canvas. Phải có kích thước từ 64–4096px trên mỗi cạnh. |
| hướng dẫnbắt buộc | string | Một trong các giá trị: left, right, top, bottom, all. |
| expandPxbắt buộc | number | Pixels để mở rộng. Phạm vi: 64–512. |
| gợi ý | string | Mô tả văn bản tùy chọn để hướng dẫn nội dung được tạo. |
Phản hồi:
{
"result": "<base64_png_string>"
}
Xác thực: Ảnh nguồn phải có kích thước từ 64–4096px trên mỗi cạnh. Canvas mở rộng không được vượt quá 4096px ở bất kỳ chiều nào. Vi phạm sẽ trả về lỗi REGION_TOO_SMALL hoặc CANVAS_TOO_LARGE.
Phản hồi lỗi
Tất cả các điểm cuối trả về phản hồi lỗi JSON với trường error:
{
"error": "RATE_LIMITED"
}
Mã lỗi phổ biến:
- ĐÃ ĐẠT GIỚI HẠN TỐC ĐỘ — quá nhiều yêu cầu. Chờ và thử lại.
- REGION_TOO_SMALL — kích thước hình ảnh dưới 64×64px tối thiểu.
- CANVAS_TOO_LARGE — canvas mở rộng vượt quá giới hạn 4096px.
- THIẾU_TRƯỜNG_THÔNG_TIN — một trường bắt buộc không được cung cấp.
Ghi chú
- Mô hình AI — tất cả endpoint inpainting sử dụng Stable Diffusion v1.5 qua Cloudflare Workers AI. Số bước suy diễn được giới hạn tối đa 20.
- Định dạng hình ảnh — tất cả hình ảnh phải là PNG base64.
- Quyền riêng tư — hình ảnh được xử lý trong bộ nhớ và không được lưu, ghi lại hoặc sử dụng để huấn luyện mô hình.
- CORS — endpoint chấp nhận yêu cầu từ
morph.cool,www.morph.cool, vàlocalhost:5173. - Thời gian chờ — client nên thiết lập thời gian chờ 30 giây. Xử lý phía máy chủ hiếm khi vượt quá 15 giây.