Khả năng · Ảnh chi tiết

Product detail photo API dành cho ảnh cận cảnh

Tóm tắt trong một câu

Detail photo API của Photta render ảnh cận cảnh của một vùng được chỉ định trên sản phẩm. Lượt gọi analyze miễn phí sẽ gợi ý các chi tiết đáng chụp; lượt gọi generate có giá cố định 3 credits, không phân tầng độ phân giải.

  • Thời gian điển hình: 20–60 sec
  • Credits: 3 credits
  • Xử lý: async, polling
  • Giới hạn: 600 requests/min
  • Xác thực: Bearer key

Mọi số liệu trên trang này đều lấy từ tài liệu Photta API · đã kiểm tra

POST/api/v1/detail-photos
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

Tổng quan nhanh

Tổng quan nhanh

Endpoint
POST /api/v1/detail-photos
Xác thực
Bearer API key
Xử lý
Bất đồng bộ — polling status endpoint
Thời gian điển hình
20–60 sec
Credits
3 credits
Giới hạn đầu vào
Tối đa 10 MB mỗi ảnh; JPEG, PNG, WebP
Idempotent
Không

Request và response

Request

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Completed

{
  "data": {
    "id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
    "status": "processing",
    "detail_label": "collar stitching",
    "framing": "extreme-closeup",
    "credits_used": 3,
    "created_at": "2026-07-30T14:20:00Z"
  },
  "request_id": "req_dtl001"
}

Tham số request

product_image

Kiểu: stringBắt buộc

The source image — a completed generation's output_url or any product photo. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.

detail_label

Kiểu: stringBắt buộc

The area to zoom into, e.g. "collar stitching", "cuff detail", "fabric weave on the chest", "pendant clasp". Max 100 characters.

detail_description

Kiểu: string

Extra guidance for the close-up. Max 400 characters.

framing

Kiểu: string

How tight the crop is: "extreme-closeup" — the detail fills ~90% of the frame (near-macro); "closeup" — ~70% with some surrounding context; "medium-closeup" — ~50% with body/outfit visible.

= medium-closeup

Giá trị: extreme-closeupcloseupmedium-closeup
source_type

Kiểu: string

Tunes what is preserved in the close-up.

= apparel

Giá trị: appareljewelry

Lỗi

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_error
An internal server error occurred. Retry later.

Giới hạn

  • 600 request mỗi phút trên mỗi API key (Fixed window; giới hạn như nhau trên mọi gói)
  • Mã 429 kèm header Retry-After: 30 giây
  • Tối đa 10 MB mỗi ảnh
  • Định dạng: JPEG, PNG, WebP
  • Batch đồng thời theo từng gói: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Chỉ hỗ trợ polling — API không gửi webhook.

Hỏi xem chi tiết nào đáng chụp, sau đó chụp nó

Phân tích miễn phí, chọn một chi tiết, gửi yêu cầu, polling, tải xuống.

  1. Bước 1

    Tạo một API key

    Ảnh chi tiết sử dụng cùng thông tin xác thực và cùng số dư credit như mọi tính năng khác của Photta.

  2. Bước 2

    Hỏi xem nên chụp những chi tiết nào

    POST `/api/v1/detail-photos/analyze` với `product_image`. Endpoint này trả về đồng bộ các giá trị `detail_label`, `detail_description` và `framing` được gợi ý cho sản phẩm đó mà hoàn toàn không tính phí.

  3. Bước 3

    POST ảnh cận cảnh

    POST tới `/api/v1/detail-photos` với `product_image` và `detail_label`. Đặt `framing` thành `extreme-closeup`, `closeup` hoặc `medium-closeup`, `source_type` thành `apparel` hoặc `jewelry`, và thêm tối đa 400 ký tự cho `detail_description`.

  4. Bước 4

    Polling cho đến khi tác vụ hoàn thành

    GET `/api/v1/detail-photos/:id` mỗi 3 giây cho đến khi `data.status` là `completed` hoặc `failed`; thời gian hoàn thành thông thường là 20 đến 60 giây.

  5. Bước 5

    Tải xuống và lưu trữ lâu dài

    Body khi hoàn thành chứa `output_url`. Ảnh chi tiết khớp nối trực tiếp vào gallery của PDP ngay cạnh ảnh chụp chính.

Câu hỏi lập trình viên thường đặt ra trước khi triển khai ảnh chi tiết

Detail photo API là gì?

Một endpoint render ảnh cận cảnh của một vùng được chỉ định trên sản phẩm — đường may cổ áo, móc khóa, kiểu dệt trên ngực — từ một bức ảnh chụp góc rộng duy nhất, thay vì phải thực hiện một buổi chụp studio thứ hai với ống kính macro.

Một bức ảnh chi tiết có giá bao nhiêu?

Cố định 3 credits. Không có phân tầng độ phân giải trên endpoint này, và lệnh gọi analyze gợi ý chi tiết là hoàn toàn miễn phí.

Endpoint analyze trả về những gì?

Một danh sách các gợi ý, mỗi gợi ý gồm `detail_label`, `detail_description` giải thích lý do vùng đó đáng hiển thị, và một `framing` được đề xuất. Bạn có thể đưa trực tiếp bất kỳ gợi ý nào vào lệnh gọi generate.

Mỗi tùy chọn framing chụp cận đến mức nào?

`extreme-closeup` lấp đầy gần như toàn bộ khung hình bằng chi tiết, `closeup` giữ lại một chút bối cảnh xung quanh, và `medium-closeup` hiển thị chi tiết trong tổng thể trang phục hoặc món đồ xung quanh. Hãy chọn theo từng chi tiết, không phải theo từng sản phẩm.

Hình ảnh nguồn có thể là ảnh được AI tạo ra không?

Có. `product_image` chấp nhận `output_url` của một lượt tạo đã hoàn thành cũng như bất kỳ ảnh sản phẩm nào của riêng bạn, dưới dạng URL https hoặc base64 data URI.

Tôi thực hiện polling để lấy kết quả như thế nào?

GET `/api/v1/detail-photos/:id` mỗi 3 giây cho đến khi `data.status` là `completed` hoặc `failed`. Lượt gọi analyze là đồng bộ và không cần polling.

Các tính năng liên quan

Mọi số liệu trên trang này đều lấy từ tài liệu Photta API · đã kiểm tra

Thử nghiệm API trong năm phút

Tạo một Photta API key, dán đoạn mã cURL ở trên, và bạn sẽ nhận được bức ảnh mẫu mặc đồ đầu tiên trước khi pha xong ly cà phê.

  • 20–60 sec
  • 3 credits
  • async, polling
  • 600 requests/min
  • Bearer key