Skip ShootAPI docs

Render a product into a scene

Put one product into one scene, on the surface you choose or the first one it fits. Then wait for the image and download it.

Updated

On this page

Prerequisites

Let the API choose the surface

Send just the scene and the product. The product goes on the first surface of the scene it fits: a floor on the floor, a fabric on the furniture, a wallcovering on a wall.

curl -X POST https://www.skipshoot.com/api/v1/renders \
  -H "Authorization: Bearer $SKIPSHOOT_SECRET_KEY" \
  -H "Idempotency-Key: render-812-4410" \
  -H "Content-Type: application/json" \
  -d '{
  "scene_id": 812,
  "product_id": 4410
}'

The answer’s surface says which surface was chosen.

Choose a specific surface

When a room has several surfaces a product fits, such as two sofas or three walls, name the one you want. Read the scene’s surfaces first:

curl https://www.skipshoot.com/api/v1/scenes/812 \
  -H "Authorization: Bearer $SKIPSHOOT_SECRET_KEY"
Surfaces of scene 812
{
  "surfaces": [
    {
      "id": "wall_1",
      "name": "Back wall",
      "type": "wall"
    },
    {
      "id": "wall_2",
      "name": "Left wall",
      "type": "wall"
    },
    {
      "id": "floor_1",
      "name": "Floor",
      "type": "floor"
    },
    {
      "id": "sofa_1",
      "name": "Sofa",
      "type": "furniture"
    },
    {
      "id": "chair_1",
      "name": "Armchair",
      "type": "furniture"
    },
    {
      "id": "scene_lighting",
      "name": "Scene lighting",
      "type": "lighting"
    }
  ]
}

Then pass its id as surface_id:

curl -X POST https://www.skipshoot.com/api/v1/renders \
  -H "Authorization: Bearer $SKIPSHOOT_SECRET_KEY" \
  -H "Idempotency-Key: render-812-4410-armchair" \
  -H "Content-Type: application/json" \
  -d '{
  "scene_id": 812,
  "product_id": 4410,
  "surface_id": "chair_1"
}'

Ask for an upscale

Add upscale: true to ask for an upscaled image, at no extra credit. Check the render’s upscale_status to see whether you got one. Upscaling is not available yet, so for now renders complete at their full 4K resolution and report unavailable. See Upscaling.

curl -X POST https://www.skipshoot.com/api/v1/renders \
  -H "Authorization: Bearer $SKIPSHOOT_SECRET_KEY" \
  -H "Idempotency-Key: render-812-4410-upscaled" \
  -H "Content-Type: application/json" \
  -d '{
  "scene_id": 812,
  "product_id": 4410,
  "upscale": true
}'

Full example

Render, wait for the result and save the image, in one script:

import { randomUUID } from "node:crypto";
import { writeFile } from "node:fs/promises";

const BASE = "https://www.skipshoot.com/api/v1";
const auth = { Authorization: `Bearer ${process.env.SKIPSHOOT_SECRET_KEY}` };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const FINAL = ["completed", "failed", "cancelled"];

const created = await fetch(`${BASE}/renders`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json", "Idempotency-Key": randomUUID() },
  body: JSON.stringify({ scene_id: 812, product_id: 4410 }),
});

if (!created.ok) {
  const { error } = await created.json();
  throw new Error(`${created.status} ${error.type}: ${error.message}`);
}

let [render] = (await created.json()).renders;

for (let wait = 5000; !FINAL.includes(render.status); wait = Math.min(wait * 1.5, 15000)) {
  await sleep(wait);
  ({ render } = await (await fetch(`${BASE}/renders/${render.id}`, { headers: auth })).json());
}

if (render.status === "completed") {
  const image = await fetch(render.image_url);
  await writeFile(`${render.id}.png`, Buffer.from(await image.arrayBuffer()));
  console.log("Saved", `${render.id}.png`);
} else {
  console.error(render.status, render.error);
}

In production, store the Idempotency-Key with your job before you send the request, so a retry after a crash sends the same key. See Idempotent requests.

If the request is refused

A refused request charges nothing. The common causes:

ResponseCauseFix
422The product fits no surface in the scene.Choose a scene with the right kind of surface, such as a room with a visible floor for flooring.
422The product does not suit the surface you named.Name a surface whose type suits it, or leave surface_id out.
422The scene is not ready yet.Wait for the scene's status to be ready. See Poll for results.
404The scene or product is not in your workspace.Check the ids, and that the key belongs to the right workspace.
402Not enough credits.See Credits, billing and refunds.

Every refusal is listed in Error messages by endpoint.

Something these pages do not answer? Email admin@skipshoot.com and we’ll help.