Build with pFrame
Upload product references, choose looks, generate photos and retrieve results from your scripts or agents.
Authentication
Create an API key in your account settings. Send it in X-API-Key or as an Authorization bearer token. Every request uses the key owner’s permissions and credit balance.
export PFRAME_API_URL=https://pframeai-production.up.railway.app
export PFRAME_API_KEY='YOUR_PRIVATE_KEY'
# Send X-API-Key: $PFRAME_API_KEY
# Or Authorization: Bearer $PFRAME_API_KEYThe full key is returned once. Store it securely on your server; keep it out of browser code and shared repositories.
Upload a product
POST /api/v1/public/products
Send one image and a product_name (1–255 characters) as multipart form data. Optional fields: category, sku and description. Upload creates your product and its primary original; it does not generate photos.
curl "$PFRAME_API_URL/api/v1/public/products" \
-H "X-API-Key: $PFRAME_API_KEY" \
-F 'product_name=Rope toy' -F 'category=TOY' \
-F 'image=@/absolute/path/original.jpg'201: product_id, primary_image_id, product_name and original_url. Stored references are resized to a maximum 2048-pixel side.
Choose a look
GET /api/v1/public/looks
Get the enabled catalogue. product_type can be all (default), pet or general; filtered lists include universal looks. Use returned identifiers in generation requests.
curl "$PFRAME_API_URL/api/v1/public/looks?product_type=pet" \
-H "X-API-Key: $PFRAME_API_KEY"200: an array of {scene_id, style, label}. Labels describe the current selectable looks.
Generate photos
POST /api/v1/public/generations
Use an owned product UUID, scene_configs with style_name and quantity, and optional global_modifiers, custom_prompt, aspect_ratio, resolution, exclude_animals and exclude_people. Square 1K is shown below; the default resolution is 2K.
curl "$PFRAME_API_URL/api/v1/public/generations" \
-H "X-API-Key: $PFRAME_API_KEY" -H 'Content-Type: application/json' \
-d '{"product_id":"YOUR_PRODUCT_UUID","resolution":"1k","aspect_ratio":"1:1","scene_configs":[{"scene_id":"studio","styles":[{"style_name":"white","quantity":1}]}]}'200: job_id, status, product_id and images with id, url, thumbnail_url and scene_type. Keep job_id to check progress and retrieve results.
Retrieve results
GET /api/v1/public/generations/{job_id}
Request your job UUID. Only jobs owned by your key’s account are visible.
curl "$PFRAME_API_URL/api/v1/public/generations/$JOB_ID" \
-H "X-API-Key: $PFRAME_API_KEY"200: job_id, status, progress_percentage, total_images, successful_images, failed_images and images with result URLs.
Credits and limits
Upload, look listing and status requests cost 0 generation credits. Standard generation costs 1 credit per requested image at 1K or 2K. 4K/8K adds 1 credit per image where your account permits that resolution. Generation uses the same reserve, generate and commit billing flow as the app.
The default limit is 60 requests per minute per account, shared across its API keys. A 429 response includes Retry-After; your deployment can configure a different limit.
Generated scenes use AI. Review product details before publishing. The API returns the outputs your account is entitled to view.
Errors and retries
400: invalid upload or job ID. 401: missing, invalid, revoked or expired key. 402: insufficient credits. 403: product ownership or account restrictions. 404: unknown product or unavailable job. 422: invalid fields. 429: rate limit. 500: upload, catalogue or generation failure.
Read the response detail and respect Retry-After. Generation requests do not expose an idempotency key: do not blindly retry a timed-out POST, which can create another billed generation. Check a returned job_id before submitting again.