Direction animation

What you can create

Animate one character action in one to eight compass directions. Each selected direction is a separate media task. For example, a four-direction walk produces independent N, E, S and W results, so one failure does not discard successful directions.

Prepare the request

Choose one ready full-body character image, a motion and unique directions. Set mode to classic for Basic or pro for Pro; omitting it selects Pro. Supported actions are idle, walk, run, dash, roll, crouch, punch, hit, interact and death. Directions are N, NE, E, SE, S, SW, W and NW. The service selects the action template and reads input dimensions.

Generate in the workspace

1. Open the Direction animation workflow from the character or generation workspace.
2. Choose the character image and one motion.
3. Select the required directions and review the total cost.
4. Start the batch and inspect the individual direction results.
5. Download successful files even if another direction failed. Inspect failed results before a deliberate retry.

Choices, limits and cost

Basic uses image generation with pose references and costs 4 credits per direction: four directions cost 16; eight cost 32. It produces 4 frames for idle, crouch and hit; 6 for walk, run, dash, punch and interact; and 10 for roll and death, at 8 FPS.

Pro uses video generation and background removal and costs 10 credits per direction: four directions cost 40; eight cost 80. Every action produces 32 transparent frames at 8 FPS from a 4-second video. A deliberate retry is charged according to the selected mode and directions.

Saving to a character action requires an existing compatible action and its current directional reference. A terminal partial success is distinct from a batch still processing. Do not resubmit the complete batch to recover one failed direction; a deliberate retry should select only the failed directions and use a new request identity.

REST and MCP return one accepted batch task ID. Poll that ID with get_task; each item includes its direction, status, credits, refund state and ready asset IDs. Successful items remain downloadable while other directions are processing or have failed. A webhook is emitted once all items are terminal, including task.partially_completed for mixed results. Replaying the same idempotency key and input returns the original batch without another charge.

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 40 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_direction_animation",
9  "input": {
10    "inputAssetId": "00000000-0000-4000-8000-000000000001",
11    "motion": "walk",
12    "directions": [
13      "N",
14      "E",
15      "S",
16      "W"
17    ]
18  }
19}
20JSON
21
22curl --fail-with-body "$BASE_URL/api/v1/estimates" \
23  -H "Authorization: Bearer $SPRITEFLOW_API_KEY" \
24  -H "Content-Type: application/json" --data-binary @request.json
25
26curl --fail-with-body "$BASE_URL/api/v1/tasks" \
27  -H "Authorization: Bearer $SPRITEFLOW_API_KEY" \
28  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
29  -H "Content-Type: application/json" --data-binary @request.json
30

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

1{
2  "name": "generate_direction_animation",
3  "arguments": {
4    "input": {
5      "inputAssetId": "00000000-0000-4000-8000-000000000001",
6      "motion": "walk",
7      "directions": [
8        "N",
9        "E",
10        "S",
11        "W"
12      ]
13    },
14    "idempotencyKey": "example-workflow-001"
15  }
16}

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