OpenSkin API endpoint

Queue an item image

POST /v2/renders

Creates an image using one catalog item, saved camera and background settings, and the requested output format. When it finishes, the image is available through a temporary private URL.

Authentication

Send a Platform API key with permission to use this endpoint in the X-API-Key header.

Parameters

Name	Location	Required	Description
`Idempotency-Key`	header	Yes	See the OpenAPI schema for accepted values.

Request body

The example includes every required JSON field. Open OpenAPI JSON to see optional fields, accepted values, and limits.

Response meaning

200: Existing matching request returned
202: Image request accepted
400: Invalid item details, saved settings, or output
401: V2Unauthorized
403: V2Forbidden
409: Idempotency key reused with different content
503: The item files or image service are unavailable

Request example

curl 'https://api-v2.openskin.dev/v2/renders'\
  -X POST\
  -H 'X-API-Key: osk_live_...' \
  -H 'Idempotency-Key: example-Idempotency-Key' \
  -H 'Content-Type: application/json' \
  --data '{"item":{"item":{"family":"weapon","definition_index":1},"state":{}},"scene_id":"00000000-0000-4000-8000-000000000000","output":{"width":64,"height":64,"format":"png","background":"transparent"}}'

Limits and retries

Check the listed status codes before retrying. If a request uses a unique request key, reuse that key only when repeating the same request. If a list returns next_cursor, send it unchanged in the next request.

Last updated 2026-09-04.