Skip to Content

Start one job or a batch

Needs the scope jobs:write

Start one job, or up to 50 as { jobs: [...] }. Jobs run our production services on a delivered product: packshot renders, AI scenes, image edits, videos and 3D exports. Every job type runs.

  • Jobs queue, and the results are added to the product: new images appear in images[] with the job's id, asset.images.updated is sent, and job.succeeded carries the job with its outputs.
  • Pictures are made in the order asked, and each is saved under its fileName from the start.
  • A batch answers a results array like POST /api/v1/products.
  • A product without a delivered model answers 409 not_ready (edit jobs work on an image and need no model).
  • AI jobs (scenes, edits, scene videos) run for an account with an allowance of their kind; without one they answer 403 forbidden.
  • An export to a format not switched on for your account answers 403 forbidden.

Header Parameters

Idempotency-Key?string

A unique value such as a UUID. A retry with the same key within 24 hours returns the original answer and runs nothing twice; the same key with a different body is refused with 409 idempotency_conflict.

Lengthlength <= 128

Request Body

application/json
  1. body
type*string

packshot: studio images from the model. scene: AI lifestyle images with the product. edit: a change to an image. video: a turntable or a scene video. export: the model in other file formats.

Value in"packshot""scene""edit""video""export"
articleId*string

The product to work on. It must be delivered, except for edit jobs, which work on an image.

variant?string

Your variant code, for models with several material variants.

Lengthlength <= 64
options?||||

The options of the job type. Anything left out takes the default.

naming?

A naming template for this job only.

metadata?

Up to 20 key and value pairs of your own, such as an order number. Returned on the job and in its events.

Response Body

Accepted

application/json
  1. response
id*string
Formatuuid
type*string
Value in"packshot""scene""edit""video""export"
articleId*string
variant*string|null
status*string
Value in"queued""running""succeeded""failed""cancelled"
options*

The options as applied, defaults filled in.

naming*|null
metadata*
createdAt*string
Formatdate-time
startedAt*|null
finishedAt*|null
outputs*array<>

The files made, in the order asked for. Empty until the job finishes; a failed job lists the files it did make.

error*|

Why the job failed, when it did.

Example Request
curl -sS -X POST https://platform.charpstar.co/api/v1/jobs \  -H "Authorization: Bearer $CHARPSTAR_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "type": "export", "articleId": "CH-1001", "options": { "formats": ["fbx", "obj", "glb"] } }'
Example Response
{  "id": "5c0e2f9a-7b14-4d3e-a8c1-93f6e2b7d045",  "type": "packshot",  "articleId": "CH-1001",  "variant": null,  "status": "queued",  "options": {    "views": [      "front",      "left",      "back"    ],    "background": "transparent",    "size": 4096,    "aspectRatio": "1:1",    "format": "png",    "shadows": true,    "lighting": "studio",    "preset": "Marketplace (GS1)"  },  "naming": {    "preset": "gs1"  },  "metadata": {    "purchaseOrder": "PO-88213"  },  "createdAt": "2026-11-02T08:00:00.000Z",  "startedAt": null,  "finishedAt": null,  "outputs": [],  "error": null}