ALL3D API reference

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.
bash
export ALL3D_API_KEY="live_..."
curl "https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/account/usage" \
  -H "x-api-key: $ALL3D_API_KEY"

Authentication

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.

  • ALL3D sample sheet: https://docs.google.com/spreadsheets/d/1_TVBJbDNc2gbTRGYsHZP87pRtU0T9F693rf5WtAPCjQ/edit?usp=sharing
  • 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
FieldTypeDescription
accountrequiredobject
account.company_idinteger
account.tierstring or null
keyobject or null
key.prefixstringFirst 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"
Response 200
{
  "account": {
    "company_id": 5083,
    "tier": "default"
  },
  "key": {
    "prefix": "live_abcdef12",
    "label": "Default",
    "created_on": "2026-11-03T10:00:00Z",
    "last_used_at": "2026-11-03T12:30:00Z",
    "expires_at": null
  },
  "credits": {
    "kind": "REMAINING",
    "credits": 120
  },
  "api_usage": {
    "request": {
      "used": 7,
      "limit": 10000,
      "period": "day"
    },
    "product": {
      "used": 3,
      "limit": 500,
      "period": "month"
    }
  }
}

Uploads

Get a temporary URL to upload a file, then reference it from any request.

Generate a presigned S3 PUT URL for a file

POST/uploads/signed-url
Scope
uploads:write
Request body
FieldTypeDescription
filenamerequiredstring
content_typestring
Default: application/octet-stream
Response 200, A presigned URL the caller can PUT the file to
FieldTypeDescription
upload_urlrequiredstring (uri)
methodrequiredstring
One of: PUT
headersobjectHeaders that must be sent unchanged with the PUT, including public-read ACL.
file_urlrequiredstring (uri)
uidstring (uuid)
  • 400 Validation failed
  • 401 Missing or invalid API key
  • 429 Quota or throttle exceeded
Request
curl --request POST \
  'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/uploads/signed-url' \
  --header "x-api-key: $ALL3D_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "filename": "sofa-front.jpg",
  "content_type": "image/jpeg"
}'
Response 200
{
  "upload_url": "https://example.com/file",
  "method": "PUT",
  "headers": {},
  "file_url": "https://example.com/file",
  "uid": "string",
  "filename": "string",
  "expires_in": 0
}

Products

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
FieldTypeDescription
limitinteger · queryPage size.
cursorstring · queryThe `next_cursor` value from the previous page.
updated_sincestring (date-time) · queryOnly 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
FieldTypeDescription
productsrequiredarray of object
products[].product_idrequiredinteger
products[].item_idrequiredstringYour SKU; the same value as brand_id.
products[].brand_idrequiredstringYour SKU as stored by ALL3D.
products[].namerequiredstring
  • 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"
Response 200
{
  "products": [
    {
      "product_id": 18233,
      "item_id": "SKU-1001",
      "brand_id": "SKU-1001",
      "name": "Modern Sofa",
      "category": "seating/sofa",
      "variation_type": null,
      "parent_item_id": null,
      "status": "Model Made by ALL3D",
      "status_code": 5,
      "assets_ready": true,
      "assets": [
        {
          "type": "glb",
          "url": "https://d48f7equ64qjl.cloudfront.net/product_assets/glb/18233.glb",
          "expires_at": null
        },
        {
          "type": "usdz",
          "url": "https://d48f7equ64qjl.cloudfront.net/product_assets/usdz/18233.usdz",
          "expires_at": null
        }
      ],
      "thumbnail_url": "https://d48f7equ64qjl.cloudfront.net/product_assets/thumbnail/18233.jpg",
      "created_at": "2026-10-02T09:14:07Z",
      "updated_at": "2026-11-05T16:40:12Z"
    }
  ],
  "next_cursor": "string"
}

Create a product from URL-referenced files

POST/products

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
FieldTypeDescription
item_idrequiredstringCustomer-side SKU; persisted as brand_id
namerequiredstring
categorystring
dimensionsobjectOptional positive, finite dimensions in inches; centimetre fields are unsupported.
dimensions.height_innumber
Response 202, Product accepted; ingestion may still be in progress
FieldTypeDescription
product_idrequiredinteger
item_idrequiredstring
statusrequiredstring
One of: Submitted, Ingesting
ingestionrequiredobject
ingestion.total_filesinteger
  • 400 Validation failed
  • 401 Missing or invalid API key
  • 429 Quota or throttle exceeded
Request
curl --request POST \
  'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/products' \
  --header "x-api-key: $ALL3D_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "item_id": "SKU-12345",
  "name": "Modern Sofa",
  "category": "seating/sofa",
  "dimensions": {
    "height_in": 36,
    "width_in": 86,
    "depth_in": 38
  },
  "photos": [
    {
      "url": "https://all3d.s3.amazonaws.com/test_files/abc-uuid/front.jpg"
    },
    {
      "url": "https://customer-cdn.com/image2.jpg"
    }
  ],
  "model_files": [
    {
      "url": "https://example.com/raw-sofa.zip"
    }
  ]
}'
Response 202
{
  "product_id": 0,
  "item_id": "string",
  "status": "Submitted",
  "ingestion": {
    "total_files": 0,
    "pending": 0,
    "ready": 0
  }
}

Create a variant of an existing product

POST/products/{id_or_item_id}/variants

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
FieldTypeDescription
id_or_item_idrequiredstring · pathALL3D `product_id` of the parent (digits) or the parent's `item_id`.
Request body
FieldTypeDescription
item_idrequiredstringCustomer-side SKU for the variant; persisted as brand_id
namerequiredstring
variation_typerequiredstringWhy 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
colorobject
color.namestringStored in product.color_name, e.g. 'Red'
Response 202, Variant accepted; ingestion may still be in progress
FieldTypeDescription
product_idrequiredintegerALL3D id of the new variant (separate from the parent)
item_idrequiredstringThe variant's own item_id
parent_product_idrequiredinteger
parent_item_idstring
variation_typerequiredstring
  • 400 Validation failed
  • 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 POST \
  'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/products/SKU-1001/variants' \
  --header "x-api-key: $ALL3D_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "item_id": "SKU-12345-RED",
  "name": "Modern Sofa \u2014 Red",
  "variation_type": "color",
  "color": {
    "name": "Red",
    "hex": "#C42A2A"
  },
  "category": "seating/sofa",
  "dimensions": {
    "height_in": 36,
    "width_in": 86,
    "depth_in": 38
  },
  "photos": [
    {
      "url": "https://all3d.s3.amazonaws.com/test_files/abc-uuid/red-front.jpg"
    }
  ]
}'
Response 202
{
  "product_id": 0,
  "item_id": "string",
  "parent_product_id": 0,
  "parent_item_id": "string",
  "variation_type": "string",
  "status": "Submitted",
  "ingestion": {
    "total_files": 0,
    "pending": 0,
    "ready": 0
  }
}

Look up product status by ALL3D id or customer item_id

GET/products/{id_or_item_id}/status
Scope
products:read
Path and query parameters
FieldTypeDescription
id_or_item_idrequiredstring · pathALL3D product id (digits) or the customer's `item_id`.
Response 200, Current status of the product
FieldTypeDescription
product_idrequiredinteger
item_idrequiredstring
brand_idrequiredstringYour SKU as stored by ALL3D; same value as item_id.
namestring
statusrequiredstringHuman-readable status
  • 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/status' \
  --header "x-api-key: $ALL3D_API_KEY"
Response 200
{
  "product_id": 0,
  "item_id": "string",
  "brand_id": "string",
  "name": "string",
  "status": "string",
  "status_code": 0,
  "parent_item_id": "string",
  "assets_ready": false,
  "assets": [
    {
      "type": "glb",
      "url": "https://example.com/file",
      "expires_at": "2026-11-03T12:00:00Z"
    }
  ],
  "ingestion": {
    "state": "not_required",
    "pending_files": 0,
    "failed_files": 0
  },
  "updated_at": "2026-11-03T12:00:00Z"
}

Get finished model asset URLs

GET/products/{id_or_item_id}/assets

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
FieldTypeDescription
id_or_item_idrequiredstring · pathALL3D product id (digits) or the customer's `item_id`.
Response 200, Product state and available finished assets
FieldTypeDescription
product_idrequiredinteger
item_idrequiredstring
brand_idrequiredstringYour SKU as stored by ALL3D; same value as item_id.
updated_atrequiredstring (date-time)Last change to the product record, UTC.
parent_item_idstringBase 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"
Response 200
{
  "product_id": 0,
  "item_id": "string",
  "brand_id": "string",
  "updated_at": "2026-11-03T12:00:00Z",
  "parent_item_id": "string",
  "status": "string",
  "status_code": 0,
  "assets_ready": false,
  "assets": [
    {
      "type": "glb",
      "url": "https://example.com/file",
      "expires_at": "2026-11-03T12:00:00Z"
    }
  ]
}

Request fixes to a model that is ready for review

POST/products/{id_or_item_id}/revision-requests

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
FieldTypeDescription
id_or_item_idrequiredstring · pathALL3D product id or the customer's `item_id`, including digits-only IDs.
Request body
FieldTypeDescription
revision_detailsrequiredstringClear instructions describing the fixes required from the artist.
reference_filesarray of objectOptional file URLs returned by `/uploads/signed-url`.
reference_files[].urlrequiredstring (uri)
Response 200, Revision request recorded and model returned for fixes
FieldTypeDescription
product_idrequiredinteger
item_idrequiredstring
statusrequiredstring
One of: Being fixed by ALL3D
status_coderequiredinteger
One of: -4
revision_requestedrequiredboolean
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
Request
curl --request POST \
  'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/products/SKU-1001/revision-requests' \
  --header "x-api-key: $ALL3D_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "revision_details": "string",
  "reference_files": [
    {
      "url": "https://example.com/file"
    }
  ]
}'
Response 200
{
  "product_id": 0,
  "item_id": "string",
  "status": "Being fixed by ALL3D",
  "status_code": -4,
  "revision_requested": true
}

Bulk

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
FieldTypeDescription
productsrequiredarray of object
products[].item_idrequiredstring
products[].namerequiredstring
products[].categorystring
products[].dimensionsobjectOptional positive, finite dimensions in inches; centimetre fields are unsupported.
Request body, BulkCsv
FieldTypeDescription
csv_urlrequiredstring (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_versionstringCSV 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
FieldTypeDescription
bulk_request_idrequiredstring
staterequiredstring
One of: queued
submitted_atrequiredstring (date-time)
total_rowsinteger or nullNull for CSV submissions until the worker parses the file.
csv_urlstring (uri)Echoed back when the input was CSV.
  • 400 Validation failed
  • 401 Missing or invalid API key
  • 429 Quota or throttle exceeded
Request
curl --request POST \
  'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/products/bulk' \
  --header "x-api-key: $ALL3D_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "products": [
    {
      "item_id": "SKU-1001",
      "name": "Modern Sofa",
      "photos": [
        {
          "url": "https://all3d.s3.amazonaws.com/test_files/uuid/sofa-front.jpg"
        }
      ]
    },
    {
      "item_id": "SKU-1001-RED",
      "name": "Modern Sofa - Red",
      "is_variant": true,
      "variation_type": "color",
      "parent_item_id": "SKU-1001",
      "color": {
        "name": "Red",
        "hex": "#C42A2A"
      }
    }
  ]
}'
Response 202
{
  "bulk_request_id": "string",
  "state": "queued",
  "submitted_at": "2026-11-03T12:00:00Z",
  "total_rows": 0,
  "csv_url": "https://example.com/file",
  "format_version": "all3d_format",
  "message": "string"
}

Check status of a bulk request

GET/products/bulk/{bulk_request_id}
Scope
products:read
Path and query parameters
FieldTypeDescription
bulk_request_idrequiredstring · path
Response 200, Current state of the bulk job
FieldTypeDescription
bulk_request_idrequiredstring
staterequiredstring
One of: queued, processing, completed, partial, failed
sourcestring
One of: inline, csv
format_versionstringCSV 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_atstring (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"
Response 200
{
  "bulk_request_id": "string",
  "state": "queued",
  "source": "inline",
  "format_version": "all3d_format",
  "submitted_at": "2026-11-03T12:00:00Z",
  "started_at": "2026-11-03T12:00:00Z",
  "completed_at": "2026-11-03T12:00:00Z",
  "error": "string",
  "counts": {
    "total": 0,
    "succeeded": 0,
    "failed": 0,
    "pending": 0
  },
  "items": [
    {
      "row_index": 0,
      "item_id": "string",
      "status": "succeeded",
      "product_id": 0,
      "parent_product_id": 0,
      "error": "string"
    }
  ]
}

Materials

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
FieldTypeDescription
limitinteger · queryPage size.
cursorstring · queryThe `next_cursor` value from the previous page.
updated_sincestring (date-time) · queryOnly 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
FieldTypeDescription
materialsrequiredarray of object
materials[].material_idrequiredinteger
materials[].namerequiredstring
materials[].brand_idstring or nullYour own id for the material, if given.
materials[].categorystring 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"
Response 200
{
  "materials": [
    {
      "material_id": 4210,
      "name": "Walnut veneer",
      "brand_id": "MAT-WAL-01",
      "category": "wood",
      "type": "pbr",
      "status": "Material Made by ALL3D",
      "status_code": 5,
      "files": [
        {
          "name": "walnut-reference.jpg",
          "url": "https://d48f7equ64qjl.cloudfront.net/test_files/5c1e8a52-7e3b-4a0b-9c5e-3f2d1a0b9c8d/walnut-reference.jpg"
        }
      ],
      "swatch_url": "https://d48f7equ64qjl.cloudfront.net/materials/4210/thumbnail.jpg",
      "bundle_url": "https://d48f7equ64qjl.cloudfront.net/materials/4210/4210.zip",
      "created_at": "2026-09-20T11:02:45Z",
      "updated_at": "2026-10-14T08:21:30Z"
    }
  ],
  "next_cursor": "string"
}

Get one material

GET/materials/{material_id}
Scope
materials:read
Path and query parameters
FieldTypeDescription
material_idrequiredinteger · pathALL3D material id, as returned by `GET /materials`.
Response 200, The material
FieldTypeDescription
material_idrequiredinteger
namerequiredstring
brand_idstring or nullYour own id for the material, if given.
categorystring or null
typestring or null
  • 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/materials/4210' \
  --header "x-api-key: $ALL3D_API_KEY"
Response 200
{
  "material_id": 4210,
  "name": "Walnut veneer",
  "brand_id": "MAT-WAL-01",
  "category": "wood",
  "type": "pbr",
  "status": "Material Made by ALL3D",
  "status_code": 5,
  "files": [
    {
      "name": "walnut-reference.jpg",
      "url": "https://d48f7equ64qjl.cloudfront.net/test_files/5c1e8a52-7e3b-4a0b-9c5e-3f2d1a0b9c8d/walnut-reference.jpg"
    }
  ],
  "swatch_url": "https://d48f7equ64qjl.cloudfront.net/materials/4210/thumbnail.jpg",
  "bundle_url": "https://d48f7equ64qjl.cloudfront.net/materials/4210/4210.zip",
  "created_at": "2026-09-20T11:02:45Z",
  "updated_at": "2026-10-14T08:21:30Z"
}

AI Images

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
FieldTypeDescription
workflowrequiredstring`studio`: clean product shots. `lifestyle`: the product in a scene described by the prompt.
One of: studio, lifestyle
sourcerequiredobject
source.product_idrequiredintegerA product in your company's library, including products created with `/ai/assets`.
promptrequiredstring
output_countinteger
Default: 1
Response 202, Job accepted; poll `status_url`
FieldTypeDescription
job_idrequiredstring
kindrequiredstring
One of: image, video, model
workflowrequiredstring
statusrequiredstring
One of: queued, running, succeeded, partially_succeeded, failed
status_urlrequiredstringPath 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"
}'
Response 202
{
  "job_id": "aij_3f9c2b1e8d7a6c5b4a392817",
  "kind": "image",
  "workflow": "lifestyle",
  "status": "succeeded",
  "status_url": "/v1/ai/jobs/aij_3f9c2b1e8d7a6c5b4a392817",
  "created_on": "2026-11-03T10:00:00Z",
  "completed_on": "2026-11-03T10:02:14Z",
  "request": {
    "workflow": "lifestyle",
    "source": {
      "product_id": 14657
    },
    "prompt": "A warm ivory sofa in a sunlit living room",
    "output_count": 2,
    "aspect_ratio": "16:9",
    "model": "auto"
  },
  "outputs": [
    {
      "asset_type": "image",
      "image_id": 90321,
      "url": "https://d48f7equ64qjl.cloudfront.net/renders/90321.png",
      "width": 1920,
      "height": 1080,
      "expires_at": null
    },
    {
      "asset_type": "image",
      "image_id": 90322,
      "url": "https://d48f7equ64qjl.cloudfront.net/renders/90322.png",
      "width": 1920,
      "height": 1080,
      "expires_at": null
    }
  ],
  "billing": {
    "status": "settled",
    "unit": "credits",
    "estimated": 10,
    "charged": 10
  },
  "error": null
}

AI Video

Turn a product image into a short video with a creative brief.

Generate a product video

POST/ai/videos/generations

Queue a video from an existing generated image or a product's photo. Credits are charged per delivered second at the chosen resolution.

Scope
ai:videos:write
Headers
Idempotency-Key required
Request body
FieldTypeDescription
workflowstring
One of: custom
Default: custom
sourcerequiredone ofExactly one of `image_id` (a generated image) or `product_id`.
promptrequiredstring
duration_secondsinteger
Default: 8
resolutionstring
One of: 720p, 1080p
Default: 1080p
Response 202, Job accepted; poll `status_url`
FieldTypeDescription
job_idrequiredstring
kindrequiredstring
One of: image, video, model
workflowrequiredstring
statusrequiredstring
One of: queued, running, succeeded, partially_succeeded, failed
status_urlrequiredstringPath 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/videos/generations' \
  --header "x-api-key: $ALL3D_API_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{
  "source": {
    "image_id": 90321
  },
  "prompt": "Slow camera move around the sofa, morning light.",
  "duration_seconds": 8,
  "resolution": "1080p",
  "aspect_ratio": "match",
  "generate_audio": false
}'
Response 202
{
  "job_id": "aij_3f9c2b1e8d7a6c5b4a392817",
  "kind": "image",
  "workflow": "lifestyle",
  "status": "succeeded",
  "status_url": "/v1/ai/jobs/aij_3f9c2b1e8d7a6c5b4a392817",
  "created_on": "2026-11-03T10:00:00Z",
  "completed_on": "2026-11-03T10:02:14Z",
  "request": {
    "workflow": "lifestyle",
    "source": {
      "product_id": 14657
    },
    "prompt": "A warm ivory sofa in a sunlit living room",
    "output_count": 2,
    "aspect_ratio": "16:9",
    "model": "auto"
  },
  "outputs": [
    {
      "asset_type": "image",
      "image_id": 90321,
      "url": "https://d48f7equ64qjl.cloudfront.net/renders/90321.png",
      "width": 1920,
      "height": 1080,
      "expires_at": null
    },
    {
      "asset_type": "image",
      "image_id": 90322,
      "url": "https://d48f7equ64qjl.cloudfront.net/renders/90322.png",
      "width": 1920,
      "height": 1080,
      "expires_at": null
    }
  ],
  "billing": {
    "status": "settled",
    "unit": "credits",
    "estimated": 10,
    "charged": 10
  },
  "error": null
}

AI 3D Models

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
FieldTypeDescription
sourcerequiredobject
source.product_idrequiredintegerA product in your company's library, including products created with `/ai/assets`.
qualitystring
One of: efficient, ultra
Default: efficient
mesh_modestring`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`
FieldTypeDescription
job_idrequiredstring
kindrequiredstring
One of: image, video, model
workflowrequiredstring
statusrequiredstring
One of: queued, running, succeeded, partially_succeeded, failed
status_urlrequiredstringPath 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/models/generations' \
  --header "x-api-key: $ALL3D_API_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{
  "source": {
    "product_id": 14657
  },
  "quality": "ultra",
  "mesh_mode": "single_mesh"
}'
Response 202
{
  "job_id": "aij_3f9c2b1e8d7a6c5b4a392817",
  "kind": "image",
  "workflow": "lifestyle",
  "status": "succeeded",
  "status_url": "/v1/ai/jobs/aij_3f9c2b1e8d7a6c5b4a392817",
  "created_on": "2026-11-03T10:00:00Z",
  "completed_on": "2026-11-03T10:02:14Z",
  "request": {
    "workflow": "lifestyle",
    "source": {
      "product_id": 14657
    },
    "prompt": "A warm ivory sofa in a sunlit living room",
    "output_count": 2,
    "aspect_ratio": "16:9",
    "model": "auto"
  },
  "outputs": [
    {
      "asset_type": "image",
      "image_id": 90321,
      "url": "https://d48f7equ64qjl.cloudfront.net/renders/90321.png",
      "width": 1920,
      "height": 1080,
      "expires_at": null
    },
    {
      "asset_type": "image",
      "image_id": 90322,
      "url": "https://d48f7equ64qjl.cloudfront.net/renders/90322.png",
      "width": 1920,
      "height": 1080,
      "expires_at": null
    }
  ],
  "billing": {
    "status": "settled",
    "unit": "credits",
    "estimated": 10,
    "charged": 10
  },
  "error": null
}

AI Jobs

Track every AI job, its outputs and what it cost.

List AI jobs

GET/ai/jobs

Newest first. Pass `next_cursor` from the previous page as `cursor`.

Scope
ai:jobs:read
Path and query parameters
FieldTypeDescription
limitinteger · query
cursorstring · queryThe last `job_id` of the previous page.
Response 200, A page of jobs
FieldTypeDescription
jobsrequiredarray of object
jobs[].job_idrequiredstring
jobs[].kindrequiredstring
One of: image, video, model
jobs[].workflowrequiredstring
jobs[].statusrequiredstring
One of: queued, running, succeeded, partially_succeeded, 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/ai/jobs' \
  --header "x-api-key: $ALL3D_API_KEY"
Response 200
{
  "jobs": [
    {
      "job_id": "aij_3f9c2b1e8d7a6c5b4a392817",
      "kind": "image",
      "workflow": "lifestyle",
      "status": "succeeded",
      "status_url": "/v1/ai/jobs/aij_3f9c2b1e8d7a6c5b4a392817",
      "created_on": "2026-11-03T10:00:00Z",
      "completed_on": "2026-11-03T10:02:14Z",
      "request": {
        "workflow": "lifestyle",
        "source": {
          "product_id": 14657
        },
        "prompt": "A warm ivory sofa in a sunlit living room",
        "output_count": 2,
        "aspect_ratio": "16:9",
        "model": "auto"
      },
      "outputs": [
        {
          "asset_type": "image",
          "image_id": 90321,
          "url": "https://d48f7equ64qjl.cloudfront.net/renders/90321.png",
          "width": 1920,
          "height": 1080,
          "expires_at": null
        },
        {
          "asset_type": "image",
          "image_id": 90322,
          "url": "https://d48f7equ64qjl.cloudfront.net/renders/90322.png",
          "width": 1920,
          "height": 1080,
          "expires_at": null
        }
      ],
      "billing": {
        "status": "settled",
        "unit": "credits",
        "estimated": 10,
        "charged": 10
      },
      "error": null
    }
  ],
  "next_cursor": "string"
}

Retrieve an AI job

GET/ai/jobs/{job_id}

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
FieldTypeDescription
job_idrequiredstring · path
Response 200, The job
FieldTypeDescription
job_idrequiredstring
kindrequiredstring
One of: image, video, model
workflowrequiredstring
statusrequiredstring
One of: queued, running, succeeded, partially_succeeded, failed
status_urlrequiredstringPath 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"
Response 200
{
  "job_id": "aij_3f9c2b1e8d7a6c5b4a392817",
  "kind": "image",
  "workflow": "lifestyle",
  "status": "succeeded",
  "status_url": "/v1/ai/jobs/aij_3f9c2b1e8d7a6c5b4a392817",
  "created_on": "2026-11-03T10:00:00Z",
  "completed_on": "2026-11-03T10:02:14Z",
  "request": {
    "workflow": "lifestyle",
    "source": {
      "product_id": 14657
    },
    "prompt": "A warm ivory sofa in a sunlit living room",
    "output_count": 2,
    "aspect_ratio": "16:9",
    "model": "auto"
  },
  "outputs": [
    {
      "asset_type": "image",
      "image_id": 90321,
      "url": "https://d48f7equ64qjl.cloudfront.net/renders/90321.png",
      "width": 1920,
      "height": 1080,
      "expires_at": null
    },
    {
      "asset_type": "image",
      "image_id": 90322,
      "url": "https://d48f7equ64qjl.cloudfront.net/renders/90322.png",
      "width": 1920,
      "height": 1080,
      "expires_at": null
    }
  ],
  "billing": {
    "status": "settled",
    "unit": "credits",
    "estimated": 10,
    "charged": 10
  },
  "error": null
}

Allowed options, prices and balance

GET/ai/capabilities

Workflows, option values, limits and credit prices as they apply to this account.

Scope
ai:jobs:read
Response 200, Capabilities
FieldTypeDescription
imagesobject
images.workflowsarray of string
images.aspect_ratiosarray of string
images.modelsarray of string
images.max_output_countinteger
  • 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/ai/capabilities' \
  --header "x-api-key: $ALL3D_API_KEY"
Response 200
{
  "images": {
    "workflows": [
      "studio",
      "lifestyle"
    ],
    "aspect_ratios": [
      "1:1",
      "16:9",
      "9:16",
      "4:5"
    ],
    "models": [
      "auto",
      "nano_banana",
      "openai",
      "grok"
    ],
    "max_output_count": 4,
    "credits_per_image": 5
  },
  "videos": {
    "workflows": [
      "custom"
    ],
    "resolutions": [
      "720p",
      "1080p"
    ],
    "aspect_ratios": [
      "match",
      "16:9",
      "9:16",
      "1:1"
    ],
    "duration_seconds": {
      "min": 4,
      "max": 30
    },
    "credits_per_second": {
      "720p": 6,
      "1080p": 8
    }
  },
  "models": {
    "qualities": [
      "efficient",
      "ultra"
    ],
    "mesh_modes": [
      "single_mesh",
      "with_parts"
    ],
    "credits": {
      "efficient": {
        "single_mesh": 20,
        "with_parts": 22
      },
      "ultra": {
        "single_mesh": 25,
        "with_parts": 27
      }
    }
  },
  "balance": {
    "kind": "REMAINING",
    "credits": 120,
    "plan": "ai_pro"
  }
}

AI Inputs

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
FieldTypeDescription
namerequiredstring
image_urlrequiredstring (uri)The `file_url` returned by `/uploads/signed-url` after you PUT the photo.
item_idstringYour own SKU for the product.
Response 201, Product created
FieldTypeDescription
asset_idinteger
product_idintegerSame as `asset_id`; use it as `source.product_id`.
item_idstring or null
namestring
image_urlstring (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
  • 429 Quota or throttle exceeded
Request
curl --request POST \
  'https://6iswsytfyd.execute-api.us-west-2.amazonaws.com/production/v1/ai/assets' \
  --header "x-api-key: $ALL3D_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Modern Sofa",
  "image_url": "https://all3d.s3.amazonaws.com/test_files/8f1c2a7b-1a2b-4c3d-9e8f-0a1b2c3d4e5f/sofa-front.jpg"
}'
Response 201
{
  "asset_id": 14657,
  "product_id": 14657,
  "item_id": null,
  "name": "Modern Sofa",
  "image_url": "https://all3d.s3.amazonaws.com/test_files/8f1c2a7b-1a2b-4c3d-9e8f-0a1b2c3d4e5f/sofa-front.jpg",
  "status": "ready"
}

Errors

Error responses are JSON with an error message and, where it helps, a stable code.

StatusCodeMeaning
400—The request body or parameters are malformed. The error message names the field.
401—Missing, revoked or expired API key.
403missing_scopeThe key lacks the scope this endpoint requires.
403insufficient_creditsThe company's credit balance cannot cover the requested generation.
404—The product, job or asset does not exist or belongs to another company.
409—Idempotency-Key reused with a different body, or the resource is in a state that forbids the action.
422—The request is well-formed but the option combination is not supported.
429—Rate limit, concurrency cap or allowance exceeded. Honour Retry-After.
503—A provider or queue is temporarily unavailable. Retry with backoff.