# Extract a visual rendition

Read the visual layout of an owned JPEG or PNG image source as a model-generated rendition.

Documentation index: https://webcite.co/llms.txt
Canonical page: https://webcite.co/api-docs/visual-rendition
API origin: https://api.webcite.co
Authentication: x-api-key header. Keep keys on your server.

## When to use it

Send `visual_rendition: true` with an owned `asset_id`, the exact immutable `source_version_id` of that JPEG or PNG source, and an `Idempotency-Key` header. Retrying with the same key and payload replays the stored outcome. The rendition is model-generated: keep `visual_provenance` with it and treat it as a partial reading of the image. Use [Extract document text](/api-docs/extract) for ordinary extraction.

## Request

POST /api/v1/extract/visual-rendition

1 credit for a billable extraction outcome, the same as text extraction.

### curl

```curl
curl --fail-with-body -X POST 'https://api.webcite.co/api/v1/extract/visual-rendition' \
  -H "x-api-key: $WEBCITE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "asset_id": "YOUR_ASSET_ID",
  "source_version_id": "YOUR_SOURCE_VERSION_ID",
  "visual_rendition": true
}'
```

### Node.js

```javascript
const response = await fetch("https://api.webcite.co/api/v1/extract/visual-rendition", {
  method: "POST",
  headers: {
    "x-api-key": process.env.WEBCITE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "asset_id": "YOUR_ASSET_ID",
  "source_version_id": "YOUR_SOURCE_VERSION_ID",
  "visual_rendition": true
}),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());
```

### python

```python
import os
import json
import requests

payload = json.loads("{\n  \"asset_id\": \"YOUR_ASSET_ID\",\n  \"source_version_id\": \"YOUR_SOURCE_VERSION_ID\",\n  \"visual_rendition\": true\n}")
response = requests.post(
    "https://api.webcite.co/api/v1/extract/visual-rendition",
    headers={"x-api-key": os.environ["WEBCITE_API_KEY"]},
    json=payload,
    timeout=(10, 300),
)
response.raise_for_status()
print(response.json())
```

## Response

Returns markdown with extraction_method ocr, state partial and complete: false, plus source_version_id, representation_id, source_units and visual_provenance (origin model_generated). The source remains partial; this call does not select the rendition as the source's reading. The public OpenAPI does not yet define a response schema for this operation.

## Errors

400 when visual_rendition: true, a valid Idempotency-Key, or an owned asset_id matching the exact JPEG/PNG source_version_id is missing; asset_url is not accepted. For 401, check your API key. For 429, wait for the retry interval; this operation uses the stricter plan rate limit. See the errors guide before retrying a billable request.

## OpenAPI operation

```json
{
  "path": "/api/v1/extract/visual-rendition",
  "method": "POST",
  "operation": {
    "operationId": "ApiV1Controller_extractVisualRendition",
    "parameters": [],
    "requestBody": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ExtractRequestDto"
          }
        }
      },
      "required": true
    },
    "responses": {
      "201": {
        "description": ""
      }
    },
    "security": [
      {
        "x-api-key": []
      },
      {
        "bearer": []
      }
    ],
    "tags": [
      "Public API"
    ]
  },
  "schemas": {
    "ExtractRequestDto": {
      "properties": {
        "asset_id": {
          "description": "An uploaded asset id (from POST /upload). One of asset_id / asset_url is required.",
          "type": "string"
        },
        "asset_url": {
          "description": "A direct URL to the file. One of asset_id / asset_url is required.",
          "type": "string"
        },
        "source_version_id": {
          "description": "Exact immutable owned source version for visual_rendition.",
          "type": "string"
        },
        "visual_rendition": {
          "description": "Explicit JPEG/PNG visual layout rendition. Requires owned asset_id, exact source_version_id and Idempotency-Key. Source remains partial; does not select the rendition.",
          "type": "boolean"
        }
      },
      "type": "object"
    }
  }
}
```