Character design

What you can create

Turn a character brief into a portrait, full-body image, character design sheet, four-view turnaround, equipment and prop sheet, or complete character bible. Start here when you need a new design before animation. For example, a forest ranger brief can produce a full-body pixel character that you reuse in Pro animation.

Input and output requirements

Write the character's occupation, silhouette, clothing, equipment and colors in character. Select an outputType that fits your next step. Use full-body for animation; a multi-panel sheet is a reference document rather than a single animation pose.

Choose style.source: preset, custom, reference or identity. Custom style needs customDirection; reference style needs one to three ready image asset IDs. Identity style requires inputAssetId. An identity reference should show one recognizable character clearly. The service reads image dimensions; you do not need to measure them yourself.

Create it in the workspace

1. Open Character creator.
2. Select the output type, describe the character and choose a style source.
3. Add identity or style references if needed, then select a resolution. Character outputs use a transparent background.
4. Select an existing project or compatible character destination. Review the credit amount, then generate.
5. Wait for the result in the workspace, inspect the design and select an individual image for animation.

Choices, limits and cost

Resolution costs are 3 credits at 1k, 5 at 2k and 20 at 4k. 4k requires the existing premium entitlement. Some sheet formats only support 2k or 4k; facing and camera options also depend on output type. Invalid combinations are rejected before generation. The API accepts only transparent for output.background and defaults to it when omitted. Inspect the finished image and choose a single character pose before making animation inputs.

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 3 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_character",
9  "input": {
10    "outputType": "full-body",
11    "character": {
12      "classOccupation": "Forest ranger",
13      "outfit": "Green cloak and leather boots"
14    },
15    "style": {
16      "source": "preset",
17      "preset": "pixel-16bit"
18    },
19    "output": {
20      "resolution": "1k",
21      "background": "transparent"
22    }
23  }
24}
25JSON
26
27curl --fail-with-body "$BASE_URL/api/v1/estimates" \
28  -H "Authorization: Bearer $SPRITEFLOW_API_KEY" \
29  -H "Content-Type: application/json" --data-binary @request.json
30
31curl --fail-with-body "$BASE_URL/api/v1/tasks" \
32  -H "Authorization: Bearer $SPRITEFLOW_API_KEY" \
33  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
34  -H "Content-Type: application/json" --data-binary @request.json
35

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

1{
2  "name": "generate_character",
3  "arguments": {
4    "input": {
5      "outputType": "full-body",
6      "character": {
7        "classOccupation": "Forest ranger",
8        "outfit": "Green cloak and leather boots"
9      },
10      "style": {
11        "source": "preset",
12        "preset": "pixel-16bit"
13      },
14      "output": {
15        "resolution": "1k",
16        "background": "transparent"
17      }
18    },
19    "idempotencyKey": "example-workflow-001"
20  }
21}

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