Skip to Content

Start and follow jobs

Start packshot, turntable, AI scene, AI edit, scene video and export jobs on your delivered models, and follow them until they finish.

Jobs work on your delivered models: packshots and turntable videos, made by the same studio that makes the product pictures in your CharpstAR account, AI scenes of the product, and 3D exports, the model in other file formats. A job queues, and job.succeeded carries it with its outputs. Packshots, turntables and scenes are added to the product: they appear in images with the job's jobId and asset.images.updated is sent, and so do edits and scene videos.

Start jobs

POST/api/v1/jobsjobs:write

The reference page lists every field of a job. A packshot job looks like this:

{
  "type": "packshot",
  "articleId": "CH-1001",
  "options": { "views": ["front", "left", "back"], "background": "transparent", "size": 4096 },
  "naming": { "preset": "gs1" },
  "metadata": { "purchaseOrder": "PO-88213" }
}
  • Views: front, back, left, right and top, three_quarter_left and three_quarter_right, table (straight on at table height), or your own angle as { "yaw": 35, "pitch": 12 }. One picture per view.
  • Presets: name one of yours in options.preset and its light, camera, background, size and file type apply; the options you send win. Without one, a job makes a white, square 2048 px PNG of the front with a soft floor shadow.
  • The same picture again: a new packshot of a view replaces the one made with the same preset. It keeps the file name, so the copy in your storage is replaced too; it gets a new id and address. The preset's other views stay as they are.
  • Allowance: when your allowance of pictures is used up, a job answers 402 allowance_reached with the numbers in details (see Plan and usage).
  • Exports: { "type": "export", "articleId": "CH-1001", "options": { "formats": ["fbx", "obj", "glb"] } }. One file per format: fbx with its textures inside, obj and 3ds as a zip with their textures, blend, and glb and usdz, your live model files, which are ready at once (a job of only those succeeds as it starts). An export usually takes under a minute. Formats to convert are the ones switched on for your account; another answers 403 forbidden with the formats in details. An export is of the model as delivered, so it takes no variant.
  • Turntables: { "type": "video", "articleId": "CH-1001", "options": { "kind": "turntable" } }. One turn of the product from the preset's first view (the front for the house preset), as a looping MP4 in the preset's light, background and shadow, 1080 px on the short side (resolution: "720p" for 720), the turn in the seconds you send (3, 5 or 8), else the preset's own, else 3. It is added to the product as a video with its first frame as posterUrl, and a new turntable with the same preset replaces it. It takes a few minutes and counts as a video, not as pictures.
  • AI scenes: { "type": "scene", "articleId": "CH-1001", "options": { "prompt": "Bright Scandinavian living room, morning light" } }. Each is made from the product's main picture, so make a packshot first if it has none; a style from GET /styles gives a range one look. count makes up to 4, each counted. A scene takes about a minute and a half. AI jobs run for an account with an allowance of them (see Plan and usage); without one a job answers 403 forbidden, past it 402. More products in one scene (withArticles) come in a later release.
  • AI edits: { "type": "edit", "articleId": "CH-1001", "options": { "imageId": "…", "instruction": "Make the light warmer" } } changes one of the product's pictures, named by its images id. With a region (fractions of width and height from the top left) only that part changes, its edge blended in; draw it around free space, since an object that reaches across its edge can come out cut. The edited picture is a new image of type edit at the original's size, and a picture with a transparent background keeps it; the original stays as it was. Pictures up to 25 megapixels can be edited. An edit takes under a minute.
  • Scene videos: { "type": "video", "articleId": "CH-1001", "options": { "kind": "scene", "sourceImageId": "…" } } makes an 8-second 16:9 video of the product in the setting of one of its scenes (an image of type scene or edit), without sound, at 1080p (or 720p). It is added to the product as a video with the scene as its still, and takes a few minutes. Edits and scene videos need an allowance of their own kind, like scenes.
  • Export file names: each output's fileName follows your naming (CH-1001.fbx, CH-1001_obj.zip; with gs1, 09521234567806_3DR.fbx). Save the file under its fileName: the address keeps the model's own name, and a live glb or usdz is the address your 3D viewer uses. A format that could not be made fails the job with the formats in error.details; the files that were made are in outputs.

A batch of up to 50 jobs goes as { "jobs": [...] } and answers a results array, like a batch of products. Pictures are made in the order asked, and each is saved under its fileName from the start.

Follow jobs

GET/api/v1/jobs/{jobId}jobs:read

The reference page lists every field of a job: its status, the options as applied, the outputs once it succeeded, and the error when it failed. The status is queued, running, succeeded, failed or cancelled.

GET/api/v1/jobsjobs:read

Your jobs come newest first, with their status and outputs. You can filter by article, type, status, or changes since a time.

Cancel a job

POST/api/v1/jobs/{jobId}/canceljobs:write

You can cancel a job while it is queued. A job that has started answers 409 not_cancellable. job.cancelled is sent. Cancelling a cancelled job answers it again.

On this page