Scene asset extraction | Sprite Flow Docs

What you can create

Extract reusable objects from an existing scene image. Use automatic detection for an initial pass, manual points for selected objects or boxes for explicit regions. A map result can become the source for extracted trees, chests or buildings.

Prepare the source and selections

Use a ready scene image you own. New requests use version: 3 and resolution 2k or 4k. Automatic mode only needs inputAssetId. Manual and box modes require markedAssetId, a ready annotated copy of that source, plus their points or boxes.

Selection coordinates use a normalized 0–1000 range, not raw image pixels. Manual points contain x and y. Boxes are [left, top, right, bottom], at least two normalized units wide and high. Do not mix fields from different modes.

Extract in the workspace

Open Scene asset extraction and choose the scene.
Select automatic, manual point or box mode.
In manual modes, mark the desired objects and check the selections.
Select resolution and destination, review the cost and start extraction.
Inspect the separated output assets before downloading or reusing them.

Choices, limits and cost

2k costs 4 credits; 4k costs 10. Manual and box requests support up to 32 unique targets. Duplicate selections are rejected. A valid submitted request does not guarantee every visually ambiguous object will be extracted cleanly; check edges, transparency and object completeness in the result.

Parameters

These fields are generated from the same input Schema used by REST and MCP. Nested required fields apply when their parent object or selected variant is present. Business conditions described above are validated before submission.

Field	Type	Required	Default and limits
`characterId`	string	No	minLength: 1; maxLength: 255
`characterTarget`	object / object	No	See the workflow requirements above.
`projectId`	string	No	minLength: 1; maxLength: 255
`folderId`	string / null	No	See the workflow requirements above.
`version`	number	Yes	Must be `3`
`resolution`	string	Yes	`"2k"`, `"4k"`
`mode`	string	Yes	Must be `"auto"`
`inputAssetId`	string	Yes	See the workflow requirements above.
`mode`	string	Yes	Must be `"manual"`
`points`	array	Yes	minItems: 1; maxItems: 32
`points[].x`	number	Yes	minimum: 0; maximum: 1000
`points[].y`	number	Yes	minimum: 0; maximum: 1000
`markedAssetId`	string	Yes	See the workflow requirements above.
`mode`	string	Yes	Must be `"box"`
`boxes`	array	Yes	minItems: 1; maxItems: 32

API example

This example costs 4 credits. A quote does not reserve balance or bypass subscription requirements. Set SPRITEFLOW_API_KEY in your shell. Replace the placeholder asset ID 00000000-0000-4000-8000-000000000001 with a ready asset you own when present. Use a new idempotency key for each intentional generation; keep it unchanged when retrying.

bash

1
2# Use the same BASE_URL for credentials, uploads and generation.
3BASE_URL="https://spriteflow.io"
4IDEMPOTENCY_KEY="example-workflow-001"
5
6cat > request.json <<'JSON'
7{
8  "operation": "extract_scene_assets",
9  "input": {
10    "version": 3,
11    "mode": "auto",
12    "inputAssetId": "00000000-0000-4000-8000-000000000001",
13    "resolution": "2k"
14  }
15}
16JSON
17
18curl --fail-with-body "$BASE_URL/api/v1/estimates" \
19  -H "Authorization: Bearer $SPRITEFLOW_API_KEY" \
20  -H "Content-Type: application/json" --data-binary @request.json
21
22curl --fail-with-body "$BASE_URL/api/v1/tasks" \
23  -H "Authorization: Bearer $SPRITEFLOW_API_KEY" \
24  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
25  -H "Content-Type: application/json" --data-binary @request.json
26

An accepted request returns HTTP 202, Location and Retry-After headers. Example response (IDs are illustrative):

json

1{"taskId":"00000000-0000-4000-8000-000000000002","status":"accepted","statusUrl":"/api/v1/tasks/00000000-0000-4000-8000-000000000002","pollAfterSeconds":10,"replayed":false}

MCP example

Call estimate_cost with the same operation and input, then call extract_scene_assets. The following is a tools/call params object:

json

1{
2  "name": "extract_scene_assets",
3  "arguments": {
4    "input": {
5      "version": 3,
6      "mode": "auto",
7      "inputAssetId": "00000000-0000-4000-8000-000000000001",
8      "resolution": "2k"
9    },
10    "idempotencyKey": "example-workflow-001"
11  }
12}

The tool returns the same task receipt in structuredContent and a JSON text result. Pass taskId to get_task. Tool annotations describe behavior; permissions are still checked on the server.

Completion, download and reuse

Poll the returned statusUrl after pollAfterSeconds. Continue while terminal is false. Read items for per-task results, progress for batch counts and assets for ready files. A batch can be partially_completed: use its successful assets and review each failed item before deciding whether to create a separate retry.

For each returned asset ID, call get_download_url or GET /api/v1/assets/{assetId}/download. Download the temporary URL before it expires. Image assets can be passed into a compatible operation as inputAssetId or a style reference. Do not pass provider task IDs, download URLs or local filesystem paths as asset IDs.

Failures and recovery

INVALID_PARAMETERS: fix the field errors before submitting. Check the business conditions and defaults above.
INPUT_ASSET_UNAVAILABLE: confirm the upload, check ownership and ensure the asset is ready and not trashed.
INSUFFICIENT_CREDITS: add credits before a new request; a cost estimate does not reserve them.
A timeout or lost response: resend the identical request with the original idempotency key. Never invent a new key just because the response was lost.
A terminal generation failure: inspect the item error and refund information. Refund handling uses the existing generation workflow. Do not assume an in-progress or unknown submission is safe to repeat.

Uploads · Tasks · Credits · Idempotency · Save destinations · Download and export