Everything your integration can call, with request fields, example payloads and responses generated from the API contract. Send your key in the x-api-key header on every request.
Base URLhttps://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1
Need a key? A company admin creates it in the portal under Developers → API key.
Getting started
The ALL3D API lets your own systems create product images, videos and 3D models, order human-made models, and track every job, using the same account and credits as the ALL3D portal.
Sign in to the ALL3D portal. A company admin opens Developers → API key and creates the company's key. The secret is shown once; store it in your secret manager.
Call GET /account/usage to confirm the key works and see your credit balance and API allowances.
Upload any input files through POST /uploads/signed-url, then submit a job with the returned file URL.
Poll the job or product status endpoint until it reaches a final state, then download the results.
Every request carries your key in the x-api-key header. Requests without a valid key return 401. Keys are scoped to one company and carry a set of scopes; a request outside the key's scopes returns 403.
http
x-api-key: live_<your key>
Keep the key on your server. Never ship it in a browser, mobile app or public repository.
One key per company. Rotating from the portal issues a new secret and revokes the old one immediately, so update every integration before relying on the new key.
Revoking stops new requests at once. Jobs already accepted still finish.
Never put the key in a query string; only the header is accepted.
Credits and limits
Two separate meters apply. AI credits are the company's shared balance, the same one the portal shows, and are spent only when a generation produces billable output. API allowances count requests and operations per day or month and protect the service from runaway clients.
403 insufficient_credits: the company has no credits for the requested operation. Top up or change plan in the portal.
429: an allowance or rate limit was hit. Wait for the Retry-After header, then retry.
Polling status endpoints and reading usage count as API requests but never spend credits.
A failed or rejected request is never charged. Partial results are charged only for the outputs delivered.
GET /account/usage returns both meters for the current period so you can display them or alert before an integration stalls.
Asynchronous jobs
Generation and model orders take minutes, so submit endpoints answer 202 Accepted with an identifier and a status URL. Poll that URL until the state is final. A reasonable cadence is every 5 to 15 seconds for images and every 30 seconds for video and 3D.
AI jobs move through queued → running → succeeded, partially_succeeded or failed.
Model orders report customer-facing statuses: In Draft, Being made by ALL3D, Ready to Review on ALL3D, Being fixed by ALL3D, Model Made by ALL3D.
Result URLs may expire; fetch the job again to refresh them. Download and store outputs you need to keep.
Webhooks are not available at launch. Polling is the supported way to learn that a job finished.
Idempotency and retries
Network errors can hide whether a submission was accepted. Model endpoints detect a repeated identical request from the same key and return the original result instead of creating a duplicate. AI generation endpoints require an Idempotency-Key header; resending the same key with the same body returns the same job, and the same key with a different body returns 409.
Generate one UUID per logical submission and reuse it on every retry of that submission.
Retry 429 and 503 responses with exponential backoff, starting at one second.
Do not retry 400, 401, 403, 404 or 422; fix the request first.
Uploading files
Ask for a signed upload URL, PUT the file bytes to it with the returned headers, then reference the returned file URL in your request. Do not send your API key to the upload URL. Uploaded files are stored with the same public-read behaviour as portal uploads.
bash
# 1. Get an upload URL
curl -X POST "$BASE/uploads/signed-url" -H "x-api-key: $ALL3D_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filename":"sofa-front.jpg","content_type":"image/jpeg"}'
# 2. PUT the bytes to upload_url with the returned headers
# 3. Use file_url in your next request
Syncing your catalogue
GET /products and GET /materials list everything your company owns, newest first, with status, update times and download URLs for finished files. For a scheduled sync, store the time your last run started and pass it as updated_since so only changed items come back. Pages are cursor based: keep calling with the returned next_cursor until it is null. These reads count against your daily request allowance but never spend credits.
bash
curl "$BASE/products?updated_since=2026-11-01T00:00:00Z&limit=100" \
-H "x-api-key: $ALL3D_API_KEY"
# then follow next_cursor until it is null
curl "$BASE/products?updated_since=2026-11-01T00:00:00Z&limit=100&cursor=18233" \
-H "x-api-key: $ALL3D_API_KEY"
Bulk CSV formats
POST /products/bulk accepts inline rows or an uploaded CSV. The default all3d_format uses ALL3D column names. The 3d_cloud_format adapter accepts the 3D Cloud template, where row 1 holds field descriptions, row 2 the column names, and products start on row 3.
3D Cloud sample sheet: https://docs.google.com/spreadsheets/d/10GKiyRotPNcaeqd8oZyn_i9deKEqE4TUJEOP7i5MnFM/
Export the sheet to CSV and upload it first; a Google Sheets edit link is not a valid csv_url.
3D Cloud variants: Variant + Color only is a colour variant; Variant + Size only is a size variant; a Product whose SKU ends in _<number> is a state variant. Rows with both Color and Size fail validation.
Account
Check what your key can spend before you build on it.
Current credits, API allowances and key metadata
GET/account/usage
Read-only view of what this key can spend. `credits` is the company's
shared AI credit balance, the same balance the ALL3D portal shows.
`api_usage` counts requests and operations against the account's
allowances for the current day or month; a null `limit` means the
allowance is unlimited. Polling this endpoint never consumes credits.
Scope
usage:read
Response 200, Usage summary
Field
Type
Description
accountrequired
object
account.company_id
integer
account.tier
string or null
key
object or null
key.prefix
string
First 12 characters of the key.
401 Missing or invalid API key
403 Key lacks the `usage:read` scope
429 Quota or throttle exceeded
Request
curl --request GET \
'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/account/usage' \
--header "x-api-key: $ALL3D_API_KEY"
Order human-made 3D models for your products, track progress, retrieve finished assets and request revisions.
List products
GET/products
Every product and variant your company owns, newest first, with its
status, finished model files and update time. Pass `updated_since` to
fetch only what changed since your last sync, and the previous page's
`next_cursor` as `cursor` until it comes back null. Listing never
spends credits.
Scope
products:read
Path and query parameters
Field
Type
Description
limit
integer · query
Page size.
cursor
string · query
The `next_cursor` value from the previous page.
updated_since
string (date-time) · query
Only items changed at or after this ISO 8601 date or date-time. A value without an offset is read as UTC.
Response 200, A page of products
Field
Type
Description
productsrequired
array of object
products[].product_idrequired
integer
products[].item_idrequired
string
Your SKU; the same value as brand_id.
products[].brand_idrequired
string
Your SKU as stored by ALL3D.
products[].namerequired
string
400 Validation failed
401 Missing or invalid API key
429 Quota or throttle exceeded
Request
curl --request GET \
'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/products' \
--header "x-api-key: $ALL3D_API_KEY"
Returns `202 Accepted`. Files hosted outside ALL3D's S3 buckets are
re-uploaded asynchronously. After the pending automatic-submission rollout,
products request submission with model_status 2 once files are ready;
normal image preprocessing may store status 7. Failed ingestion
leaves them Draft. Poll `/products/{id}/status`
or use the `product_id` to track progress.
Scope
products:write
Request body
Field
Type
Description
item_idrequired
string
Customer-side SKU; persisted as brand_id
namerequired
string
category
string
dimensions
object
Optional positive, finite dimensions in inches; centimetre fields are unsupported.
dimensions.height_in
number
Response 202, Product accepted; ingestion may still be in progress
Create an alternate version of an existing product — typically a new
colour, material, finish, or size. The parent is identified by either
its ALL3D `product_id` or the customer's `item_id`. Returns
`202 Accepted`; ingestion is asynchronous on the same pipeline as
`POST /v1/products`. Returns `404` if the parent doesn't exist or
isn't owned by this API key's company.
Scope
products:write
Path and query parameters
Field
Type
Description
id_or_item_idrequired
string · path
ALL3D `product_id` of the parent (digits) or the parent's `item_id`.
Request body
Field
Type
Description
item_idrequired
string
Customer-side SKU for the variant; persisted as brand_id
namerequired
string
variation_typerequired
string
Why this variant differs from the parent; case is normalized.
State instructions belong in guidelines with optional state_references.
One of: color, material, finish, size, state, custom_request, ar_conversion, high_conversion
color
object
color.name
string
Stored in product.color_name, e.g. 'Red'
Response 202, Variant accepted; ingestion may still be in progress
Field
Type
Description
product_idrequired
integer
ALL3D id of the new variant (separate from the parent)
item_idrequired
string
The variant's own item_id
parent_product_idrequired
integer
parent_item_id
string
variation_typerequired
string
400 Validation failed
401 Missing or invalid API key
404 Resource not found or not owned by this API key
Returns downloadable URLs once the product reaches `status_code: 5`
(Model Made by ALL3D) and a GLB is present. Before then,
`assets_ready` is false and `assets` is empty. Each asset explicitly
reports its expiry time, or null when the URL does not expire.
Scope
products:read
Path and query parameters
Field
Type
Description
id_or_item_idrequired
string · path
ALL3D product id (digits) or the customer's `item_id`.
Response 200, Product state and available finished assets
Field
Type
Description
product_idrequired
integer
item_idrequired
string
brand_idrequired
string
Your SKU as stored by ALL3D; same value as item_id.
updated_atrequired
string (date-time)
Last change to the product record, UTC.
parent_item_id
string
Base product SKU; present only for variants.
401 Missing or invalid API key
404 Resource not found or not owned by this API key
Request
curl --request GET \
'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/products/SKU-1001/assets' \
--header "x-api-key: $ALL3D_API_KEY"
Available only while the product is at `status_code: 4`. Records the
customer's revision instructions for the artist and moves the product
to `status_code: -4` (`Being fixed by ALL3D`). Reference files must
first be uploaded through `/uploads/signed-url`.
Scope
products:write
Path and query parameters
Field
Type
Description
id_or_item_idrequired
string · path
ALL3D product id or the customer's `item_id`, including digits-only IDs.
Request body
Field
Type
Description
revision_detailsrequired
string
Clear instructions describing the fixes required from the artist.
reference_files
array of object
Optional file URLs returned by `/uploads/signed-url`.
reference_files[].urlrequired
string (uri)
Response 200, Revision request recorded and model returned for fixes
Field
Type
Description
product_idrequired
integer
item_idrequired
string
statusrequired
string
One of: Being fixed by ALL3D
status_coderequired
integer
One of: -4
revision_requestedrequired
boolean
One of: true
400 Validation failed
401 Missing or invalid API key
404 Resource not found or not owned by this API key
409 Product is not currently ready for customer review
429 Quota or throttle exceeded
502 The downstream rejection workflow could not be completed
Submit many products and variants in one request from JSON rows or a CSV.
Bulk-create products and variants
POST/products/bulk
Submit many products and/or variants in one call. Two input modes:
an inline `products[]` array (≤ 500 rows) or a `csv_url` referencing
a CSV uploaded via `/uploads/signed-url`. Returns immediately with
a `bulk_request_id`; processing is asynchronous. Poll
`/products/bulk/{bulk_request_id}` for progress. CSV submissions default
to `all3d_format`; select `3d_cloud_format` explicitly for that adapter.
Scope
products:write
Request body, BulkInline
Field
Type
Description
productsrequired
array of object
products[].item_idrequired
string
products[].namerequired
string
products[].category
string
products[].dimensions
object
Optional positive, finite dimensions in inches; centimetre fields are unsupported.
Request body, BulkCsv
Field
Type
Description
csv_urlrequired
string (uri)
URL of a CSV uploaded via `/v1/uploads/signed-url`. Column schema
described in `CUSTOMER-API-GUIDE.md` §4b and the sample at
`docs/examples/bulk-products-sample.csv`.
format_version
string
CSV layout adapter. `all3d_format` is the original ALL3D column set.
`3d_cloud_format` accepts the 3D Cloud template: row 1 field
descriptions, row 2 column names, data from row 3. Applies only to
`csv_url` submissions; inline `products[]` always use `all3d_format`.
One of: all3d_format, 3d_cloud_format
Default: all3d_format
Response 202, Bulk job accepted
Field
Type
Description
bulk_request_idrequired
string
staterequired
string
One of: queued
submitted_atrequired
string (date-time)
total_rows
integer or null
Null for CSV submissions until the worker parses the file.
One of: queued, processing, completed, partial, failed
source
string
One of: inline, csv
format_version
string
CSV layout adapter. `all3d_format` is the original ALL3D column set.
`3d_cloud_format` accepts the 3D Cloud template: row 1 field
descriptions, row 2 column names, data from row 3. Applies only to
`csv_url` submissions; inline `products[]` always use `all3d_format`.
One of: all3d_format, 3d_cloud_format
Default: all3d_format
submitted_at
string (date-time)
401 Missing or invalid API key
404 Resource not found or not owned by this API key
Request
curl --request GET \
'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/products/bulk/bulk_80c340b3b6084891887a34f44b185148' \
--header "x-api-key: $ALL3D_API_KEY"
Read the materials your company has uploaded or ordered, with their files.
List materials
GET/materials
Materials your company uploaded or ordered, newest first. Uploaded
source files are always listed; `swatch_url` and `bundle_url` are set
once ALL3D has delivered the material (`status_code: 5`). Supports the
same `updated_since` and cursor paging as `GET /products`.
Scope
materials:read
Path and query parameters
Field
Type
Description
limit
integer · query
Page size.
cursor
string · query
The `next_cursor` value from the previous page.
updated_since
string (date-time) · query
Only items changed at or after this ISO 8601 date or date-time. A value without an offset is read as UTC.
Response 200, A page of materials
Field
Type
Description
materialsrequired
array of object
materials[].material_idrequired
integer
materials[].namerequired
string
materials[].brand_id
string or null
Your own id for the material, if given.
materials[].category
string or null
400 Validation failed
401 Missing or invalid API key
429 Quota or throttle exceeded
Request
curl --request GET \
'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/materials' \
--header "x-api-key: $ALL3D_API_KEY"
Studio or lifestyle product photography from a product in your library. Asynchronous: submit, then poll the job.
Generate product images
POST/ai/images/generations
Queue studio or lifestyle images for a product in your library. The job
draws on the company's shared credit balance; credits are charged only
for delivered images. Send a unique `Idempotency-Key` header: resending
it with the same body returns the same job, a different body returns 409.
Scope
ai:images:write
Headers
Idempotency-Key required
Request body
Field
Type
Description
workflowrequired
string
`studio`: clean product shots. `lifestyle`: the product in a scene described by the prompt.
One of: studio, lifestyle
sourcerequired
object
source.product_idrequired
integer
A product in your company's library, including products created with `/ai/assets`.
promptrequired
string
output_count
integer
Default: 1
Response 202, Job accepted; poll `status_url`
Field
Type
Description
job_idrequired
string
kindrequired
string
One of: image, video, model
workflowrequired
string
statusrequired
string
One of: queued, running, succeeded, partially_succeeded, failed
status_urlrequired
string
Path to poll, relative to the base URL.
400 Validation failed
401 Missing or invalid API key
403 Missing scope, or the credit balance cannot cover the request (`code` is `insufficient_credits`)
404 Resource not found or not owned by this API key
409 Idempotency-Key reused with a different body
422 The request is well-formed but an option is not supported; `field` names it
429 Quota or throttle exceeded
Request
curl --request POST \
'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/ai/images/generations' \
--header "x-api-key: $ALL3D_API_KEY" \
--header "Idempotency-Key: $(uuidgen)" \
--header "Content-Type: application/json" \
--data '{
"workflow": "lifestyle",
"source": {
"product_id": 14657
},
"prompt": "A warm ivory sofa in a sunlit Scandinavian living room, soft natural shadows.",
"output_count": 2,
"aspect_ratio": "16:9",
"model": "auto"
}'
Generate a GLB and USDZ mesh from a product's photos.
Generate a 3D model from product photos
POST/ai/models/generations
Queue an AI-generated mesh for a product. `efficient` and `ultra`
quality use fixed credit prices; `with_parts` adds a surcharge and
returns a segmented mesh. Outputs are GLB and USDZ files.
Scope
ai:models:write
Headers
Idempotency-Key required
Request body
Field
Type
Description
sourcerequired
object
source.product_idrequired
integer
A product in your company's library, including products created with `/ai/assets`.
quality
string
One of: efficient, ultra
Default: efficient
mesh_mode
string
`with_parts` returns a segmented mesh and adds a surcharge.
One of: single_mesh, with_parts
Default: single_mesh
Response 202, Job accepted; poll `status_url`
Field
Type
Description
job_idrequired
string
kindrequired
string
One of: image, video, model
workflowrequired
string
statusrequired
string
One of: queued, running, succeeded, partially_succeeded, failed
status_urlrequired
string
Path to poll, relative to the base URL.
400 Validation failed
401 Missing or invalid API key
403 Missing scope, or the credit balance cannot cover the request (`code` is `insufficient_credits`)
404 Resource not found or not owned by this API key
409 Idempotency-Key reused with a different body
422 The request is well-formed but an option is not supported; `field` names it
Current state, outputs and billing of one job. Poll until `status`
is `succeeded`, `partially_succeeded` or `failed`. Polling never
spends credits. A job reports success once its outputs are billed,
usually seconds after they finish. A job that was never handed to
generation fails after five minutes; submit it again with a new
`Idempotency-Key`.
Scope
ai:jobs:read
Path and query parameters
Field
Type
Description
job_idrequired
string · path
Response 200, The job
Field
Type
Description
job_idrequired
string
kindrequired
string
One of: image, video, model
workflowrequired
string
statusrequired
string
One of: queued, running, succeeded, partially_succeeded, failed
status_urlrequired
string
Path to poll, relative to the base URL.
401 Missing or invalid API key
404 Resource not found or not owned by this API key
429 Quota or throttle exceeded
Request
curl --request GET \
'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/ai/jobs/aij_3f9c2b1e8d7a6c5b4a392817' \
--header "x-api-key: $ALL3D_API_KEY"
Register an uploaded photo as a product you can generate from.
Register an uploaded photo as a product
POST/ai/assets
Create a library product from one photo uploaded through
`/uploads/signed-url`, so image, video and 3D generation can reference
it as `source.product_id`. External URLs are rejected; upload first.
The product joins your AI product library like a portal upload; it is
not an order for an ALL3D-made model. Resending the same body returns
the product created the first time.
Scope
ai:assets:write
Request body
Field
Type
Description
namerequired
string
image_urlrequired
string (uri)
The `file_url` returned by `/uploads/signed-url` after you PUT the photo.
item_id
string
Your own SKU for the product.
Response 201, Product created
Field
Type
Description
asset_id
integer
product_id
integer
Same as `asset_id`; use it as `source.product_id`.
item_id
string or null
name
string
image_url
string (uri)
400 Validation failed
401 Missing or invalid API key
422 The request is well-formed but an option is not supported; `field` names it