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:writeThe 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,rightandtop,three_quarter_leftandthree_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.presetand 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
idand address. The preset's other views stay as they are. - Allowance: when your allowance of pictures is used up, a job answers
402 allowance_reachedwith the numbers indetails(see Plan and usage). - Exports:
{ "type": "export", "articleId": "CH-1001", "options": { "formats": ["fbx", "obj", "glb"] } }. One file per format:fbxwith its textures inside,objand3dsas a zip with their textures,blend, andglbandusdz, 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 answers403 forbiddenwith the formats indetails. An export is of the model as delivered, so it takes novariant. - 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 thesecondsyou send (3, 5 or 8), else the preset's own, else 3. It is added to the product as avideowith its first frame asposterUrl, 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; astylefromGET /stylesgives a range one look.countmakes 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 answers403 forbidden, past it402. 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 itsimagesid. With aregion(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 typeeditat 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 typesceneoredit), without sound, at 1080p (or720p). 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
fileNamefollows your naming (CH-1001.fbx,CH-1001_obj.zip; withgs1,09521234567806_3DR.fbx). Save the file under itsfileName: the address keeps the model's own name, and a liveglborusdzis the address your 3D viewer uses. A format that could not be made fails the job with the formats inerror.details; the files that were made are inoutputs.
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:readThe 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.
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:writeYou 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.