seedance_get_task

Instructions

Use this to check if a generation is complete and retrieve the resulting
video URLs, thumbnails, and other metadata.

Use this when:
- You want to check if a generation has completed
- You need to retrieve video URLs from a previous generation
- You want to get the full details of a generated video

Task statuses:
- 'running': Generation is still in progress
- 'succeeded': Generation finished successfully
- 'failed': Generation failed (check error message)

Returns:
    Task status and generated video information including URLs and metadata.

Implementation Reference

• tools/task_tools.py:13-54 (handler)

  Main handler function for the seedance_get_task tool. Queries a single task by ID via the Seedance API client, throttles polling with a 5-second sleep if the task is incomplete, and formats the result.

  @mcp.tool()
  async def seedance_get_task(
      task_id: Annotated[
          str,
          Field(
              description=(
                  "The task ID returned from a generation request. "
                  "This is the 'task_id' field from any seedance_generate_* "
                  "tool response."
              )
          ),
      ],
  ) -> str:
      """Query the status and result of a video generation task.
  
      Use this to check if a generation is complete and retrieve the resulting
      video URLs, thumbnails, and other metadata.
  
      Use this when:
      - You want to check if a generation has completed
      - You need to retrieve video URLs from a previous generation
      - You want to get the full details of a generated video
  
      Task statuses:
      - 'running': Generation is still in progress
      - 'succeeded': Generation finished successfully
      - 'failed': Generation failed (check error message)
  
      Returns:
          Task status and generated video information including URLs and metadata.
      """
      result = await client.query_task(
          id=task_id,
          action="retrieve",
      )
      # Throttle polling: sleep 5s for incomplete tasks so LLM clients
      # don't burn through poll attempts in seconds.
      response = result.get("response", {})
      is_complete = response.get("success", False)
      if not is_complete:
          await asyncio.sleep(5)
      return format_task_result(result)

• tools/task_tools.py:13-14 (registration)

  Registration via the @mcp.tool() decorator which registers seedance_get_task as an MCP tool.

  @mcp.tool()
  async def seedance_get_task(

• tools/task_tools.py:15-24 (schema)

  Input schema for seedance_get_task - a single required string parameter 'task_id' with Pydantic Field validation.

  task_id: Annotated[
      str,
      Field(
          description=(
              "The task ID returned from a generation request. "
              "This is the 'task_id' field from any seedance_generate_* "
              "tool response."
          )
      ),
  ],

• core/utils.py:74-87 (helper)

  Helper function that formats the task query result with polling guidance metadata injected by _with_task_guidance.

  def format_task_result(data: dict[str, Any]) -> str:
      """Format task query result as JSON.
  
      Args:
          data: API response dictionary
  
      Returns:
          JSON string representation of the result
      """
      return json.dumps(
          _with_task_guidance(data, "seedance_get_task", "seedance_get_tasks_batch"),
          ensure_ascii=False,
          indent=2,
      )

• core/utils.py:33-55 (helper)

  Utility that injects mcp_task_polling metadata (including poll_tool reference) into the task query response to guide the LLM on next steps.

  def _with_task_guidance(
      data: dict[str, Any], poll_tool: str, batch_poll_tool: str | None = None
  ) -> dict[str, Any]:
      payload = dict(data)
      task_id = payload.get("id") or payload.get("task_id")
      if not task_id:
          return payload
  
      payload["mcp_task_polling"] = {
          "task_id": task_id,
          "poll_tool": poll_tool,
          "batch_poll_tool": batch_poll_tool,
          "polling_interval_seconds": 15,
          "max_poll_attempts": 100,
          "next_step": (
              f"The task is still pending or processing. "
              f'Wait 15 seconds, then call {poll_tool}(task_id="{task_id}") again. '
              f"IMPORTANT: Media generation typically takes 1-5 minutes. "
              f"Keep polling — do NOT give up or tell the user it failed. "
              f"You should poll at least 100 times before considering the task stuck."
          ),
      }
      return payload