Sprite recolor & prop replacement

What you can edit

Change the color of a specific part of a sprite or sprite sheet, replace existing equipment, or add a new prop. The generation instructions preserve the character, art style, poses and sheet layout while applying the edit across frames.

Prepare the images

Provide exactly one source: inputAssetId for a ready image you own, or imageUrl for a public image URL. Asset IDs can come from a confirmed upload, search_assets or a completed task.

For prop mode, optionally provide referenceAssetId or referenceUrl for the desired prop, but not both. Asset references must belong to your account. You can mix the two source types, such as an owned sprite asset with a public prop reference URL. The reference guides the new prop's appearance; the source sprite supplies the character and art style.

Public URLs must serve PNG, JPEG or WebP files directly over HTTPS on port 443, without authentication or redirects. Each file must be at most 20 MiB and readable within 10 seconds after DNS validation. IP address literals, private network destinations, embedded credentials and URL fragments are rejected. Before charging, the service checks public DNS addresses, file size and image signatures, saves a copy in its input-image storage, and validates the image through the media service.

Keep URLs accessible until the submission returns an accepted task. Generation uses the stored copies, which are not added to the searchable asset library. Local paths and Base64 data URLs are not supported. See Uploads and public URLs for the shared contract across image tools.

Choose the edit

• mode: "color": set target to the part to recolor, such as red cloak, and replacement to the desired color, such as forest green. The target cannot be empty. Reference images are not supported in this mode.
• mode: "prop" with a nonempty target: describe the existing item in target and the new item in replacement.
• mode: "prop" with target: "": describe the prop to add and its placement in replacement. The empty target must still be included.

target allows up to 300 characters. replacement requires 1–500 characters after trimming whitespace. version defaults to 1.

Edit in the workspace

1. Open Sprite recolor & prop replacement and select a sprite or sprite sheet.
2. Choose color or prop mode and describe the edit. Add a reference image if needed for a prop.
3. Select the output resolution, review the credit cost and submit.
4. Inspect the resulting image before downloading it or using it in another generation.

Output, cost and limitations

Set resolution to 1k, 2k or 4k, costing 2, 4 or 10 credits respectively. The result is an edited PNG image saved to your default project. This operation does not accept a custom project, folder or character destination.

A sprite sheet is returned as one image. The API does not split frames or export an animation. The selected resolution controls the generated size; it does not guarantee the original pixel dimensions. Check transparency, frame alignment and whether the edit is consistent across poses before importing the result into your game.

Public URL example

Replace the example URLs with direct image links. Pass this object to estimate_cost or POST /api/v1/estimates before submitting it to POST /api/v1/tasks with an Idempotency-Key header. Estimates validate the parameter contract without fetching the images; URL reachability and content checks run on submission.

1{
2  "operation": "generate_sprite_replacement",
3  "input": {
4    "imageUrl": "https://cdn.example.com/sprites/ranger.png",
5    "mode": "prop",
6    "target": "wooden staff",
7    "replacement": "silver spear matching the reference",
8    "referenceUrl": "https://cdn.example.com/props/spear.webp",
9    "resolution": "2k"
10  }
11}

For MCP, call generate_sprite_replacement with the same input and a separate idempotencyKey argument. Keep that key and the input unchanged if the response is lost. Use a new key only for an intentional new edit. An optional webhookUrl belongs beside operation and input in REST, or beside input and idempotencyKey in MCP.

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.

API example

This example costs 2 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.

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": "generate_sprite_replacement",
9  "input": {
10    "inputAssetId": "00000000-0000-4000-8000-000000000001",
11    "mode": "color",
12    "target": "red cloak",
13    "replacement": "forest green",
14    "resolution": "1k"
15  }
16}
17JSON
18
19curl --fail-with-body "$BASE_URL/api/v1/estimates" \
20  -H "Authorization: Bearer $SPRITEFLOW_API_KEY" \
21  -H "Content-Type: application/json" --data-binary @request.json
22
23curl --fail-with-body "$BASE_URL/api/v1/tasks" \
24  -H "Authorization: Bearer $SPRITEFLOW_API_KEY" \
25  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
26  -H "Content-Type: application/json" --data-binary @request.json
27

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

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 generate_sprite_replacement. The following is a tools/call params object:

1{
2  "name": "generate_sprite_replacement",
3  "arguments": {
4    "input": {
5      "inputAssetId": "00000000-0000-4000-8000-000000000001",
6      "mode": "color",
7      "target": "red cloak",
8      "replacement": "forest green",
9      "resolution": "1k"
10    },
11    "idempotencyKey": "example-workflow-001"
12  }
13}

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.

Related guides

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