> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neural4d.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve a task

> Returns task status and output by batch task ID or child video UUID. Provide exactly one of the id or uuid query parameters.

## Authorizations

<ParamField header="Authorization" type="string" required default={'Bearer ${YOUR_API_KEY}'}>
  Neural4D API key using the Bearer scheme.
</ParamField>

## Query Parameters

<ParamField query="id" type="string">
  Batch task ID returned by a generation request. Provide this or uuid, but not both.

  Example: `"normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d"`.
</ParamField>

<ParamField query="uuid" type="string<uuid>">
  Child video UUID returned in the generation response. Provide this or id, but not both.

  Example: `"7d1fa4bb-41e6-4a5d-88d8-1851f5342e87"`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.neural4d.com/openapi/v1/tasks/task-info?id=normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d' \
    --header 'Authorization: Bearer <token>'
  ```

  ```python Python theme={null}
  import requests

  response = requests.request(
      "GET",
      "https://api.neural4d.com/openapi/v1/tasks/task-info?id=normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d",
      headers={
      "Authorization": "Bearer <token>",
      },
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.neural4d.com/openapi/v1/tasks/task-info?id=normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d", {
    method: "GET",
    headers: {
      "Authorization": "Bearer <token>"
    },
  });
  const data = await response.json();
  console.log(data);
  ```

  ```typescript TypeScript theme={null}
  const response: Response = await fetch("https://api.neural4d.com/openapi/v1/tasks/task-info?id=normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d", {
    method: "GET",
    headers: {
      "Authorization": "Bearer <token>"
    },
  });
  const data = await response.json();
  console.log(data);
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.*;

  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.neural4d.com/openapi/v1/tasks/task-info?id=normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d"))
      .header("Authorization", "Bearer <token>")
      .method("GET", HttpRequest.BodyPublishers.noBody())
      .build();
  HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "io"
    "net/http"
    "strings"
  )

  payload := nil
  req, _ := http.NewRequest("GET", "https://api.neural4d.com/openapi/v1/tasks/task-info?id=normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d", payload)
  req.Header.Set("Authorization", "Bearer <token>")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  bodyBytes, _ := io.ReadAll(resp.Body)
  fmt.Println(string(bodyBytes))
  ```

  ```ruby Ruby theme={null}
  require "net/http"
  require "json"

  uri = URI("https://api.neural4d.com/openapi/v1/tasks/task-info?id=normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d")
  request = Net::HTTP::Get.new(uri)
  request["Authorization"] = "Bearer <token>"

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
  puts response.body
  ```

  ```php PHP theme={null}
  <?php

  $ch = curl_init("https://api.neural4d.com/openapi/v1/tasks/task-info?id=normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d");
  curl_setopt_array($ch, [
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ["Authorization: Bearer <token>"],
  ]);
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
  ```

  ```csharp C# theme={null}
  using System.Net.Http;
  using System.Text;

  using var client = new HttpClient();
  using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.neural4d.com/openapi/v1/tasks/task-info?id=normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d");
  request.Headers.TryAddWithoutValidation("Authorization", "Bearer <token>");
  using var response = await client.SendAsync(request);
  Console.WriteLine(await response.Content.ReadAsStringAsync());
  ```
</RequestExample>

## Response

<Tabs sync={false}>
  <Tab title="200">
    Task details

    <ResponseField name="id" type="string" required>
      Batch task ID returned by a generation request.

      Example: `"normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d"`.
    </ResponseField>

    <ResponseField name="status" type="enum<string>" required>
      Normalized task lifecycle status.

      Available options: `queued`, `processing`, `succeeded`, `failed`.
    </ResponseField>

    <ResponseField name="created_at" type="integer<int64>" required>
      Unix timestamp in seconds.
    </ResponseField>

    <ResponseField name="output" type="object" required>
      Current child video task output, including entries that are still queued or processing.

      <Expandable title="child attributes">
        <ResponseField name="videos" pre={["output."]} type="object[]" required>
          All child video tasks and their current output information. url and format are null until a result file is available.

          <Expandable title="child attributes">
            <ResponseField name="uuid" pre={["output.videos[]."]} type="string<uuid>" required>
              Generated video child UUID.

              Example: `"7d1fa4bb-41e6-4a5d-88d8-1851f5342e87"`.
            </ResponseField>

            <ResponseField name="url" pre={["output.videos[]."]} type="string<uri> | null" required>
              Temporary signed URL for downloading the generated video when available.
            </ResponseField>

            <ResponseField name="format" pre={["output.videos[]."]} type="string | null" required>
              Video file format when known, such as mp4.

              Example: `"mp4"`.
            </ResponseField>

            <ResponseField name="duration" pre={["output.videos[]."]} type="integer | null" required>
              Generated video duration in seconds when available.

              Required range: `0 <= x <= infinity`.
            </ResponseField>

            <ResponseField name="resolution" pre={["output.videos[]."]} type="string | null" required>
              Generated video resolution when available, such as 720p.

              Example: `"720p"`.
            </ResponseField>

            <ResponseField name="aspect_ratio" pre={["output.videos[]."]} type="string | null" required>
              Generated video aspect ratio when available, such as 16:9.

              Example: `"16:9"`.
            </ResponseField>

            <ResponseField name="has_audio" pre={["output.videos[]."]} type="boolean" required>
              Whether native audio generation was enabled for this video.
            </ResponseField>

            <ResponseField name="mode" pre={["output.videos[]."]} type="enum<string>" required>
              Generation mode used for this video.

              Available options: `text_to_video`, `first_frame_image_to_video`, `first_last_frame_image_to_video`, `reference_to_video`.
            </ResponseField>

            <ResponseField name="status" pre={["output.videos[]."]} type="enum<string>" required>
              Current status of this generated video.

              Available options: `queued`, `processing`, `succeeded`, `failed`.
            </ResponseField>

            <ResponseField name="created_at" pre={["output.videos[]."]} type="integer<int64>" required>
              Unix timestamp in seconds when this generated video was created.
            </ResponseField>

            <ResponseField name="updated_at" pre={["output.videos[]."]} type="integer<int64>" required>
              Unix timestamp in seconds when this generated video was last updated.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="mode" type="enum<string>" required>
      Video generation mode used by the task.

      Available options: `text_to_video`, `first_frame_image_to_video`, `first_last_frame_image_to_video`, `reference_to_video`.
    </ResponseField>

    <ResponseField name="model" type="enum<string> | null">
      Video generation model used by the task.

      Available options: `bytedance/seedance-2.0`, `bytedance/seedance-2.0-fast`, `google/veo-3.1`, `xai/grok-imagine`.
    </ResponseField>

    <ResponseField name="updated_at" type="integer<int64>">
      Unix timestamp in seconds.
    </ResponseField>

    <ResponseField name="usage" type="object">
      Credits charged for this task when available.

      <Expandable title="child attributes">
        <ResponseField name="credits" pre={["usage."]} type="number<float>" required>
          Credits charged for the task or submission.

          Required range: `0 <= x <= infinity`.

          Example: `26`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error" type="object">
      Error details when the task fails.

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          Stable machine-readable task failure code.
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          Human-readable explanation of the task failure.
        </ResponseField>

        <ResponseField name="failed_at" pre={["error."]} type="integer<int64>">
          Unix timestamp in seconds when the task failed.
        </ResponseField>

        <ResponseField name="retryable" pre={["error."]} type="boolean">
          Whether retrying the same operation may succeed.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="400">
    Invalid request

    <ResponseField name="error" type="object" required>
      Structured error details.

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          Stable machine-readable error code.

          Example: `"invalid_prompt"`.
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          Human-readable explanation of the error.

          Example: `"prompt is required and must be a non-empty string"`.
        </ResponseField>

        <ResponseField name="doc_url" pre={["error."]} type="string<uri> | null">
          Optional documentation URL with more information about the error.

          Example: `"https://api.neural4d.com/docs/errors#invalid_prompt"`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="401">
    Authentication failed

    <ResponseField name="error" type="object" required>
      Structured error details.

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          Stable machine-readable error code.

          Example: `"invalid_prompt"`.
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          Human-readable explanation of the error.

          Example: `"prompt is required and must be a non-empty string"`.
        </ResponseField>

        <ResponseField name="doc_url" pre={["error."]} type="string<uri> | null">
          Optional documentation URL with more information about the error.

          Example: `"https://api.neural4d.com/docs/errors#invalid_prompt"`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="403">
    The authenticated user cannot access this resource or has insufficient credits

    <ResponseField name="error" type="object" required>
      Structured error details.

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          Stable machine-readable error code.

          Example: `"invalid_prompt"`.
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          Human-readable explanation of the error.

          Example: `"prompt is required and must be a non-empty string"`.
        </ResponseField>

        <ResponseField name="doc_url" pre={["error."]} type="string<uri> | null">
          Optional documentation URL with more information about the error.

          Example: `"https://api.neural4d.com/docs/errors#invalid_prompt"`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="404">
    The requested resource was not found

    <ResponseField name="error" type="object" required>
      Structured error details.

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          Stable machine-readable error code.

          Example: `"invalid_prompt"`.
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          Human-readable explanation of the error.

          Example: `"prompt is required and must be a non-empty string"`.
        </ResponseField>

        <ResponseField name="doc_url" pre={["error."]} type="string<uri> | null">
          Optional documentation URL with more information about the error.

          Example: `"https://api.neural4d.com/docs/errors#invalid_prompt"`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="429">
    Request or quota limit exceeded

    <ResponseField name="error" type="object" required>
      Structured error details.

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          Stable machine-readable error code.

          Example: `"invalid_prompt"`.
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          Human-readable explanation of the error.

          Example: `"prompt is required and must be a non-empty string"`.
        </ResponseField>

        <ResponseField name="doc_url" pre={["error."]} type="string<uri> | null">
          Optional documentation URL with more information about the error.

          Example: `"https://api.neural4d.com/docs/errors#invalid_prompt"`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="500">
    Internal or upstream service error

    <ResponseField name="error" type="object" required>
      Structured error details.

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          Stable machine-readable error code.

          Example: `"invalid_prompt"`.
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          Human-readable explanation of the error.

          Example: `"prompt is required and must be a non-empty string"`.
        </ResponseField>

        <ResponseField name="doc_url" pre={["error."]} type="string<uri> | null">
          Optional documentation URL with more information about the error.

          Example: `"https://api.neural4d.com/docs/errors#invalid_prompt"`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>
</Tabs>

<ResponseExample>
  ```json 200 Example theme={null}
  {
    "id": "normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d",
    "status": "succeeded",
    "mode": "first_frame_image_to_video",
    "model": "bytedance/seedance-2.0-fast",
    "created_at": 1784044800,
    "updated_at": 1784044842,
    "usage": {
      "credits": 26
    },
    "output": {
      "videos": [
        {
          "uuid": "7d1fa4bb-41e6-4a5d-88d8-1851f5342e87",
          "url": "https://cdn.neural4d.com/results/video.mp4",
          "format": "mp4",
          "duration": 5,
          "resolution": "720p",
          "aspect_ratio": "16:9",
          "has_audio": true,
          "mode": "first_frame_image_to_video",
          "status": "succeeded",
          "created_at": 1784044800,
          "updated_at": 1784044842
        }
      ]
    }
  }
  ```

  ```json 400 invalid_prompt theme={null}
  {
    "error": {
      "code": "invalid_prompt",
      "message": "prompt is required and must be a non-empty string"
    }
  }
  ```

  ```json 400 unsupported_model theme={null}
  {
    "error": {
      "code": "unsupported_model",
      "message": "Unsupported modelKey: missing-model"
    }
  }
  ```

  ```json 400 model_unavailable theme={null}
  {
    "error": {
      "code": "model_unavailable",
      "message": "Model is unavailable: veo-3.1"
    }
  }
  ```

  ```json 401 Example theme={null}
  {
    "error": {
      "code": "invalid_api_key",
      "message": "The API key is invalid or expired"
    }
  }
  ```

  ```json 403 Example theme={null}
  {
    "error": {
      "code": "insufficient_credits",
      "message": "Insufficient credits for video generation"
    }
  }
  ```

  ```json 404 Example theme={null}
  {
    "error": {
      "code": "task_not_found",
      "message": "The requested task does not exist"
    }
  }
  ```

  ```json 429 Example theme={null}
  {
    "error": {
      "code": "rate_limit_exceeded",
      "message": "Too many requests. Retry after the indicated interval."
    }
  }
  ```

  ```json 500 Example theme={null}
  {
    "error": {
      "code": "internal_error",
      "message": "An internal error occurred"
    }
  }
  ```
</ResponseExample>