cURL · API ghost mannequin

API ghost mannequin với cURL

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

Export PHOTTA_API_KEY, gửi POST đến https://api.photta.app/api/v1/api/v1/ghost-mannequin với body JSON theo tài liệu, lấy generation ID, sau đó lặp lệnh GET trên /api/v1/ghost-mannequin/{id} mỗi 3 giây cho đến khi data.status chuyển thành completed. Kết hợp với jq để trích xuất output URL.

  • Thời gian điển hình: 1.5–4 min
  • Credits: 4 credits ở 2K · 5 credits ở 4K
  • 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/ghost-mannequin
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

# $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
for i in $(seq 1 120); do
  RESULT=$(curl -s "https://api.photta.app/api/v1/ghost-mannequin/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
  sleep 3
done
echo "$RESULT" | jq -r '.data.output_url'

Tổng quan nhanh

Tổng quan nhanh

Endpoint
POST /api/v1/ghost-mannequin
Xác thực
Bearer API key
Xử lý
Bất đồng bộ — polling status endpoint
Thời gian điển hình
1.5–4 min
Credits
4 credits ở 2K · 5 credits ở 4K
Tỷ lệ khung hình
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Giới hạn đầu vào
Tối đa 10 MB mỗi ảnh; JPEG, PNG, WebP
Idempotent
Không

Cơ chế hoạt động

Năm bước trên shell, không phụ thuộc vào bất kỳ công cụ nào ngoài curl và jq.

  1. Bước 1

    Đăng ký và tạo key

    Truy cập ai.photta.app, mở tab Developers, nhấp vào Generate API key. Các key môi trường live sẽ bắt đầu bằng `photta_live_`.

  2. Bước 2

    Export key

    Thêm `export PHOTTA_API_KEY="photta_live_xxx"` vào profile của shell hoặc file `.envrc` để mọi lệnh gọi curl tiếp theo tự động nhận diện key.

    curl --version   # macOS, Linux, WSL and Windows 10+ ship it
    export PHOTTA_API_KEY="photta_live_xxxxx"
  3. Bước 3

    Cố định base URL

    `export PHOTTA_BASE_URL="https://api.photta.app/api/v1"` giúp các lệnh curl luôn ngắn gọn.

    export PHOTTA_BASE_URL="https://api.photta.app/api/v1"
    export AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"
  4. Bước 4

    Gửi request và polling

    POST tới `$PHOTTA_BASE_URL/api/v1/ghost-mannequin` để lấy ID, sau đó lặp `curl $PHOTTA_BASE_URL/api/v1/ghost-mannequin/{id}` mỗi 3 giây. Pipe response sang jq để trích xuất `.data.status` một cách gọn gàng.

    RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
      -H "Authorization: Bearer $PHOTTA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
      "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front",
      "angle": "side",
      "style": "3d",
      "background_color": "white",
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "user_instruction": "closed front, cream interior lining",
      "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
    }')
    ID=$(echo "$RESPONSE" | jq -r '.data.id')
    
    # $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
    for i in $(seq 1 120); do
      RESULT=$(curl -s "https://api.photta.app/api/v1/ghost-mannequin/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
      STATUS=$(echo "$RESULT" | jq -r '.data.status')
      [ "$STATUS" = "completed" ] && break
      [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
      sleep 3
    done
    echo "$RESULT" | jq -r '.data.output_url'
  5. Bước 5

    Lưu trữ kết quả

    Khi job hoàn thành, trích xuất `.data.output_url` bằng jq và chạy `curl -o` để tải byte dữ liệu về bộ nhớ cục bộ — sẵn sàng cho bước tiếp theo trong pipeline.

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.
case "$STATUS_CODE" in
  402) echo "insufficient_credits_error — top up before retrying" ;;
  429) echo "rate_limit_error — wait the Retry-After seconds (30 by default)" ;;
  4??) echo "$BODY" | jq '.error.type, .error.message' ;;
  5??) echo "api_error — retry with backoff" ;;
esac

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.

Vì sao cURL vẫn là cách nhanh nhất để kiểm thử một API

  • Không cần cài đặt — cURL có sẵn trên mọi hệ điều hành phổ biến
  • Kết hợp hoàn hảo với jq cho các pipeline dạng script (CI, cron, shell hook)
  • Cách nhanh nhất để smoke-test một endpoint trước khi tích hợp vào code
  • Mọi lệnh trên trang này đều có thể paste trực tiếp vào bất kỳ POSIX shell nào

Những hạn chế cần lưu ý

  • Vòng lặp polling sẽ block terminal — hãy chuyển sang Node hoặc Python để chạy worker song song
  • Polling là tín hiệu duy nhất để nhận biết hoàn thành; API không gửi webhook
  • Người dùng Windows Command Prompt nên chạy WSL hoặc curl.exe của PowerShell

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

Có công cụ Photta CLI không?

Chưa có — nhưng cURL kết hợp với một bash wrapper mười lăm dòng là đủ cho hầu hết nhu cầu. Tài liệu ưu tiên các ví dụ dùng cURL vì mọi ngôn ngữ đều có thể thực thi subprocess, và shell là mẫu số chung trong các pipeline CI.

Tôi có cần jq để sử dụng API không?

Không bắt buộc — nhưng viết script pipeline sẽ dễ dàng hơn nhiều nếu có nó. jq giúp bạn trích xuất `.data.id`, `.data.status` và `.data.output_url` từ JSON response mà không cần parse thủ công. Cài đặt bằng `brew install jq` trên macOS hoặc `apt install jq` trên Debian/Ubuntu.

Xác thực bằng curl như thế nào?

Thêm `-H "Authorization: Bearer $PHOTTA_API_KEY"` vào mỗi request. Hãy lưu key trong biến môi trường, đừng bao giờ hardcode trực tiếp vào script được commit. `curl --oauth2-bearer` cũng hoạt động nhưng dạng khai báo header tường minh sẽ rõ ràng hơn trong tài liệu và log.

Tôi có thể dùng script dựa trên curl trên production không?

Đối với các tác vụ backfill dữ liệu theo batch chạy một lần hoặc cron job thì có — hàng nghìn đội ngũ kỹ thuật vẫn cập nhật lại danh mục sản phẩm theo cách này. Đối với một ứng dụng chạy liên tục lâu dài, một ngôn ngữ lập trình thực thụ thường tốt hơn vì bạn có cơ chế xử lý lỗi, retry và khả năng quan sát (observability) bài bản. Các ví dụ curl trên trang này vẫn hoàn toàn chính xác kể cả khi bạn chuyển sang Node hoặc Python; cấu trúc request vẫn giữ nguyên.

Polling từ một vòng lặp bash như thế nào?

Sử dụng `for i in $(seq 1 120); do … ; sleep 3; done` với lệnh kiểm tra trạng thái nằm trong thân vòng lặp. Thoát vòng lặp khi `.data.status` chuyển thành `completed` hoặc `failed`. Đoạn code mẫu trên trang này minh họa chính xác pattern đó, bao gồm cả giới hạn thời gian tối đa để job bị kẹt không làm treo script mãi mãi.

Làm sao để đọc response lỗi trong curl?

Sử dụng `curl -w "\n%{http_code}"` để lấy HTTP status code cùng với JSON body. Rẽ nhánh xử lý theo status: 402 cho lỗi không đủ credits, 429 khi bị rate limit (hãy tuân thủ giá trị Retry-After), 5xx cho các lỗi máy chủ tạm thời. Error body luôn chứa trường `error.code` và `error.message`.

Các trang 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ê.

  • 1.5–4 min
  • 4 credits ở 2K · 5 credits ở 4K
  • async, polling
  • 600 requests/min
  • Bearer key