API /api/v1 cho pipeline

Mọi tính năng của Media Studio đều gọi được qua REST API - đây là cách pipeline viết bài tự lấy ảnh, banner, biểu đồ và video.

Xác thực

• Tạo key trong Cài đặt → API keys (mỗi dịch vụ một key). Gửi header x-api-token: <key>.
• Fail-closed: chưa tạo key nào thì API bị khoá, không phải mở.
• Không cần key: GET /api/v1/info, /api/v1/openapi.json, /api/v1/docs, /api/v1/health.

curl https://media.phatdev.net/api/v1/info          # mọi tham số + endpoint
curl https://media.phatdev.net/api/v1/openapi.json  # đặc tả OpenAPI 3.0
curl https://media.phatdev.net/api/v1/health        # phiên bản, engine sẵn sàng, hạn mức

Job nền & chống gen trùng

Các việc lâu (review-pack 4-5 phút, render video) dễ bị cắt kết nối giữa chừng. Nên dùng:

• "async": true → nhận 202 + jobId, rồi hỏi GET /api/v1/jobs/:id.
• Header x-idempotency-key → gọi lại cùng key sẽ nhận lại kết quả cũ, không gen thêm.
• Không gửi key: request y hệt đang chạy sẽ chờ chung; vừa xong mà client đã ngắt thì lần gửi lại nhận luôn kết quả (trong 30 phút).
• "returnB64": false để response nhẹ, chỉ trả url.
• Header x-engine (giá trị xem ở GET /api/v1/info) → chỉ nhận ảnh từ engine chính; engine chính hết hạn mức thì trả 503 ngay.

Mọi response tạo ảnh có field engine cho biết engine nào đã vẽ (engine chính hay engine dự phòng).

Endpoint chính

Nhóm	Endpoint
Ảnh sản phẩm	POST /generate · /review-pack · /bg-swap · /knowledge-pack · /create · /compare-ref · /qa
Banner & biểu đồ	POST /banner · /chart
Video	POST /auto-script · /html-video/render · /render-video · /render-pro · GET /html-video/templates
Kịch bản & giọng	POST /script · /script/srt · /tts · /tts/summary · /tts/podcast · /transcribe · /transcribe/srt
Xử lý ảnh	POST /remove-bg · /upscale · /tinypng
Người mẫu & thương hiệu	GET/POST /models · POST /models/:id/pose · /models/:id/uniform · GET /brands · GET/POST /wallpapers
Thư viện	GET /library · GET /image/:id?res=2k|4k · DELETE /library/:id · GET /jobs/:id

Đã gỡ: POST /video (Grok Imagine) trả 410 từ v1.13.3; render-pro chế độ clip Grok tự chạy chế độ ảnh + Ken Burns.

Ví dụ

# Bộ ảnh review + ảnh Featured trong 1 lần gọi (chạy nền)
curl -X POST https://media.phatdev.net/api/v1/review-pack \
  -H 'Content-Type: application/json' -H 'x-api-token: <key>' \
  -H 'x-idempotency-key: rog-scar18-2026-10' \
  -d '{"refUrls":["https://.../anh-H1.jpg"],"spaceId":"studio","productName":"ROG Strix SCAR 18","featured":{"title":"Đánh giá ROG Strix SCAR 18"},"async":true}'
# → 202 { jobId }  → GET /api/v1/jobs/<jobId>

# Kịch bản video từ link sản phẩm (trả tiến trình dạng SSE)
curl -N -X POST https://media.phatdev.net/api/v1/auto-script \
  -H 'Content-Type: application/json' -H 'x-api-token: <key>' \
  -d '{"productUrl":"https://hungphatlaptop.com/...","brandName":"Hưng Phát Laptop"}'

Mã lỗi

Mã	Ý nghĩa	Pipeline nên
400	Tham số sai (khung ảnh, ảnh tham chiếu hỏng…)	Sửa request
401	Thiếu / sai key	Kiểm tra x-api-token
410	Tính năng đã gỡ	Bỏ gọi
422	Kết quả không dùng được (vd PNG trong suốt rỗng)	Thử lại với ảnh khác
503	Engine quá tải / hết hạn mức	Chờ rồi thử lại (kèm idempotency key)