API Documentation
Build on StudioSizer. Generate mockups, manage library assets, create listings, run exports, and submit print orders — all programmatically.
Quick Start
The StudioSizer API is a REST API. All requests and responses use JSON unless otherwise noted. The base URL is:
https://studiosizer.com/api
1. Create an API key at Settings → API Keys
2. Include it in every request:
# List your library projects curl -H "Authorization: Bearer sk_live_YOUR_KEY" \ https://studiosizer.com/api/library/projects
3. Parse the JSON response:
{
"ok": true,
"projects": [
{ "id": "clx...", "name": "My Art Collection", "createdAt": "2026-01-15T..." }
]
}Authentication
All authenticated endpoints accept a Bearer token in the Authorization header:
Authorization: Bearer sk_live_YOUR_API_KEY
API keys are scoped. When creating a key, assign only the scopes your integration needs:
| Scope | Access |
|---|---|
| read | Read projects, library, presets |
| write | Create/update projects, presets, library assets |
| mockups | Generate mockups and render scenes |
| listings | Manage Shopify draft listings |
| orders | Submit and track print orders |
| exports | Run file exports and conversions |
If a request lacks a required scope, the API returns 403 Forbidden with a description of the missing scope.
Error Handling
All error responses follow a consistent shape:
{
"ok": false,
"error": "Human-readable error message"
}| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad request — check params |
| 401 | Unauthorized — invalid or missing API key |
| 402 | Payment required — insufficient credits |
| 403 | Forbidden — missing scope |
| 413 | Payload too large — plan limit exceeded |
| 422 | Validation error — check error details |
| 429 | Rate limited — slow down |
| 500 | Internal error |
Rate Limits
API requests are rate-limited per API key. Some AI-powered endpoints (listing generation, SEO analysis) consume credits from your account balance.
When rate limited, the response includes a Retry-After header with the wait time in seconds.
Projects
/api/projectsAuth RequiredCreate a new project.
Request Body
| Param | Type | Description |
|---|---|---|
| name | string | Project name (default: "Untitled Project") |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| project | object | Created project with id, name, createdAt |
Library
/api/library/projectsAuth RequiredList all library projects for the authenticated user.
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| projects | array | Array of project objects |
/api/library/projectsAuth RequiredCreate a new library project with image artifacts.
Request Body
| Param | Type | Description |
|---|---|---|
| name* | string | Project name |
| artifacts* | array | Array of artifacts (max 50), each with name, mime, and either data (base64) or storageKey |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| project | object | Created project record |
/api/library/listAuth RequiredList all library projects (compact format with preview thumbnails).
Response
| Field | Type | Description |
|---|---|---|
| [] | array | Array of { id, name, preview } |
/api/library/signed-urlAuth RequiredGet a signed CDN URL for an asset's storage key.
Request Body
| Param | Type | Description |
|---|---|---|
| storageKey* | string | Storage key (e.g. "mockups/userId/file.jpg") |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| url | string | Signed or CDN URL |
| storageKey | string | Cleaned storage key |
Mockups
/api/mockups/renderAuth RequiredRender a mockup from a design image and template. Supports single or batch rendering.
Request Body
| Param | Type | Description |
|---|---|---|
| design* | object | Design image — provide url, base64-encoded data, or buffer |
| templateId* | string | Template to render against |
| options | object | Render options (size, color, etc.) |
| batch | array | Additional templates for batch rendering (plan-limited) |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| renders | array | Array of { templateId, url, key, format, outPx, watermarked } |
Free plan: single render only. Pro/Studio: batch rendering available. Returns 402 if plan limit reached.
/api/mockups/render/batchAuth RequiredOptimized concurrent batch rendering. Use for large template sets.
Request Body
| Param | Type | Description |
|---|---|---|
| design* | object | Design buffer |
| items* | array | Array of { templateId, options } |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| results | array | Render results with status, url, and error for failures |
Max duration: 5 minutes. Returns partial results if some templates fail.
/api/mockups/batchAuth RequiredGenerate batch mockups with scene, frame, and paper options. Returns a job ID for async polling.
Request Body
| Param | Type | Description |
|---|---|---|
| imageKeys* | string[] | Storage keys for images (1–10) |
| sceneId* | string | Scene identifier |
| sizes* | array | Target sizes |
| frame* | string | Frame type: black, white, oak, none |
| matIn | number | Mat inset (0–3) |
| paperLook | string | matte, luster, fineart, canvas |
| outputs* | object | { framed, unframed, transparent, printPresets300DPI } |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| jobId | string | Job ID for status polling |
/api/mockups/render/status?jobId=<id>Poll the status of an async mockup render job.
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| job.status | string | "pending", "done", or "error" |
| job.progress | number | 0–100 progress percentage |
| job.items | array | Render results when complete |
/api/mockups/suggestAuth RequiredGet AI-powered mockup scene suggestions for a product.
Request Body
| Param | Type | Description |
|---|---|---|
| productName* | string | Product name |
| category | string | Product category |
| keywords | string[] | Keywords for context |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| suggestions | array | AI-generated scene suggestions |
| creditsDebited | number | Credits consumed (0.1) |
Costs 0.1 credit per request.
Listings
/api/listings/listAuth RequiredList all Shopify draft listings.
Response
| Field | Type | Description |
|---|---|---|
| [] | array | Array of { id, title, thumbnail, status, seoScore, seoOptimizedAt } |
/api/listings/generateAuth RequiredGenerate an AI-powered product listing (title, description, tags).
Request Body
| Param | Type | Description |
|---|---|---|
| productName* | string | Product name |
| category | string | Product category |
| tags | string[] | Seed tags |
| marketplace* | string | Target marketplace (shopify, etsy, etc.) |
| studioBoost | boolean | Use Studio AI boost (costs boost token) |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| title | string | Generated title |
| description | string | Generated description |
| tags | string[] | Generated tags |
| modelUsed | string | AI model used |
| creditsDebited | number | Credits consumed |
Credit cost varies by plan and model.
/api/listings/exportAuth RequiredExport listings as Shopify CSV or image ZIP.
Request Body
| Param | Type | Description |
|---|---|---|
| items | array | Image items with targets: { name, fileUrl, targets: [{ w, h, format, quality }] } |
| format | string | Export format (e.g. "shopify" for CSV) |
Response
| Field | Type | Description |
|---|---|---|
| (binary) | application/zip | ZIP file stream |
Asset count limited by plan tier.
/api/listings/multi-exportAuth RequiredExport multiple listings as a Shopify-compatible CSV.
Request Body
| Param | Type | Description |
|---|---|---|
| listingIds* | string[] | Array of listing IDs to export |
| format | string | Export format (default: "shopify") |
Response
| Field | Type | Description |
|---|---|---|
| (text) | text/csv | CSV file |
Exports
/api/exportsAuth RequiredQueue a batch export job for file conversion/processing.
Request Body
| Param | Type | Description |
|---|---|---|
| projectId* | string | Project ID |
| fileIds* | string[] | File IDs to export (1–10) |
| presets | string[] | Preset IDs to apply |
| operations.prodigi | object | Prodigi-specific export: { variants, minMarginPct, shippingMethod, ... } |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| jobId | string | Job ID for polling status |
Prodigi exports enforce margin guardrails — returns 422 with failure details if margin is too low.
Orders
/api/orders?cursor=<n>Auth RequiredList print orders with cursor-based pagination (25 per page).
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| orders | array | Order objects |
| nextCursor | number | Cursor for next page (null if last) |
/api/ordersAuth RequiredPreview order routing without creating the order.
Request Body
| Param | Type | Description |
|---|---|---|
| (items) | object | Order items with routing info |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| preview | object | Routed items breakdown |
/api/orders/submitAuth RequiredSubmit an order for print production.
Request Body
| Param | Type | Description |
|---|---|---|
| orderId* | string | Order ID |
| sellPriceCents* | number | Sale price in cents |
| shippingCents | number | Shipping cost in cents (default: 0) |
| discountsCents | number | Discount in cents (default: 0) |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| orderId | string | Order identifier |
| status | string | Current order status |
| ledger | object | Revenue/cost breakdown |
| providerRef | string | Provider reference ID |
| providerDashboardUrl | string | Link to provider dashboard |
Enforces margin guard — returns 422 if sell price is below minimum margin.
SEO
/api/seo/analyzeAuth RequiredAI-powered SEO analysis with grade, score, and improvement suggestions.
Request Body
| Param | Type | Description |
|---|---|---|
| title* | string | Product title |
| description* | string | Product description |
| tags | string[] | Tags/keywords |
| marketplace | string | Target marketplace (default: shopify) |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| grade | string | Letter grade (A–F) |
| score | number | Score 0–100 |
| metrics | object | Detailed metrics (titleLength, keywordCoverage, etc.) |
| suggestions | string[] | AI improvement suggestions |
| addKeywords | string[] | Recommended keywords to add |
| creditsDebited | number | Credits consumed (0.3) |
Costs 0.3 credits per request.
API Keys
/api/api-keysAuth RequiredList all API keys for the authenticated user. Never returns the key hash.
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| keys | array | Array of { id, name, keyPrefix, scopes, expiresAt, lastUsedAt, revokedAt, createdAt } |
/api/api-keysAuth RequiredCreate a new API key. The raw key is returned only in this response — save it immediately.
Request Body
| Param | Type | Description |
|---|---|---|
| name* | string | Descriptive name for the key |
| scopes | string[] | Scopes to grant (default: ["read"]) |
| expiresAt | string | ISO date for key expiry (optional) |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| key | string | The raw API key (shown ONCE) |
| record | object | Key metadata: { id, name, keyPrefix, scopes, expiresAt, createdAt } |
Maximum 10 active keys per user.
/api/api-keys/<keyId>Auth RequiredRevoke an API key (soft delete). The key stops working immediately.
Request Body
| Param | Type | Description |
|---|---|---|
| action* | string | Must be "revoke" |
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| message | string | Confirmation message |
/api/api-keys/<keyId>Auth RequiredPermanently delete an API key.
Response
| Field | Type | Description |
|---|---|---|
| ok | boolean | Success flag |
| message | string | Confirmation message |
Questions? Reach out at Contact or email support@studiosizer.com