Developer guide
Fashion Collections API
Connect saved garment originals, catalogue generation and merchant review without losing the record of retries.
Base URL: https://api.pixelapi.dev/v1/fashion-collections. Send Authorization: Bearer YOUR_API_KEY for all account operations. Use your own key on your server; do not embed it in a public page. GET /options returns the currently available controls, limits and credit estimates without authentication.
| Method and path | Purpose |
|---|---|
| POST / | Create a collection with name, idempotency_key and optional brief. |
| GET / | List only the authenticated owner's collections. |
| GET /{collection_id} | Read products, attempts, review results and metrics. |
| PATCH /{collection_id}/brief | Save choices for future attempts. Earlier snapshots remain unchanged. |
| POST /{collection_id}/products | Multipart image, sku, category, garment_type and notes. |
| GET /{collection_id}/products/{product_id}/original | Authenticated original image, sent with private/no-store cache headers. |
| POST /{collection_id}/attempts | Submit one format with a stable idempotency_key. |
| PATCH /{collection_id}/attempts/{attempt_id}/review | Record a merchant review without changing billing or delivery. |
| GET /{collection_id}/manifest | Export the private collection, lineage, reviews and economics. |
Create, upload and generate
POST /v1/fashion-collections
{"name":"Autumn catalogue","idempotency_key":"collection-autumn-001"}
POST /v1/fashion-collections/{collection_id}/products
Content-Type: multipart/form-data
image: [garment file]
sku: SHIRT-NAVY-001
category: upperbody
garment_type: cotton shirt
notes: Inspect the chest embroidery and sleeve seams.
POST /v1/fashion-collections/{collection_id}/attempts
{"product_id":"PRODUCT_UUID","tool":"flat-lay",
"idempotency_key":"shirt-navy-flatlay-attempt-001"}Accepted tools: flat-lay, ghost-mannequin, ai-fashion-model, image-to-video. Categories: upperbody, lowerbody, dress. Use /options for model, pose and background identifiers. Notes are review metadata, not a free-form generation prompt.
Recovery and idempotency
Persist the request key before submitting. If the connection drops, repeat the same request with the same key. An identical retry returns the original attempt; conflicting parameters return HTTP 409. Do not create a new key just because an HTTP request timed out.
Poll the collection for status and output links. A request interrupted before a job is recorded can enter needs_reconciliation; it is not automatically charged again. Resolve that state with support before trying a new key. A duplicate SKU with identical bytes and metadata reuses the existing product; changed details require a new SKU.
Review a delivered output
PATCH /v1/fashion-collections/{collection_id}/attempts/{attempt_id}/review
{"decision":"approved",
"checks":{"colour":"pass","print_logo":"pass","cut_shape":"pass",
"fabric_detail":"pass","overall":"pass"},
"notes":"Compared with the original at full size.","review_seconds":45}Decisions: approved, rejected, unreviewed. Check values: pass, fail, not_assessable. Approval requires all five checks, no failed checks and notes explaining any unassessable detail. Identical review retries do not add duplicate review events.
Animate a selected still
{"product_id":"PRODUCT_UUID","tool":"image-to-video",
"source_attempt_id":"APPROVED_STILL_ATTEMPT_UUID",
"video_prompt":"Gentle movement; preserve the garment details.",
"idempotency_key":"shirt-navy-video-attempt-001"}The selected still must belong to the same owner, collection and product, be approved and have an output. Paid-plan, moderation, credit and external-generation protections still apply. Video uses the existing image-to-video service: 5 seconds at 720p. Internal automation cannot invoke paid external generation.
Interpret the metrics correctly
recorded_net_credits sums recorded generation credits less recorded refunds across all attempts. credits_per_approved_output divides that by approved outputs. credits_per_approved_product_format divides it by distinct approved product/format pairs. Zero approvals return null, not zero cost. Prices shown in options are estimates, not the final accounting record.
Acceptance uses only reviewed outputs. Customer wait is attempt submission to completion; processing time is reported separately. Review time is user-reported and is not processing latency. Internal runs report credit estimates, not cash spending. Subscription fees, provider invoices and labour costs are not included.
Privacy and retention
The saved-original endpoint requires owner authentication; collection manifests do not reveal storage paths. Generation tools can create shareable processing-input and output links under their existing delivery policy. Those links are not authenticated private storage. Review never publishes an original automatically. Account deletion revokes access and follows PixelAPI's existing human-reviewed retention and purge process.
Workflow overview · Evidence and evaluation method
Original-image storage is limited to 1 GB per account, with up to 200 collections and 100 products per collection. Contact support if you need a larger collection allowance.