> ## 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.

# 查询任务

> 按批次任务 ID 或视频子项 UUID 返回任务状态和输出。id 与 uuid 必须且只能传入一个。

## 授权

<ParamField header="Authorization" type="string" required default={'Bearer ${YOUR_API_KEY}'}>
  使用 Bearer 方式发送的 Neural4D API 密钥。
</ParamField>

## 查询参数

<ParamField query="id" type="string">
  生成请求返回的批次任务 ID。与 uuid 二选一，不能同时传入。

  示例：`"normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d"`。
</ParamField>

<ParamField query="uuid" type="string<uuid>">
  生成响应返回的视频子项 UUID。与 id 二选一，不能同时传入。

  示例：`"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>

## 响应

<Tabs sync={false}>
  <Tab title="200">
    任务详情

    <ResponseField name="id" type="string" required>
      生成请求返回的批次任务 ID。

      示例：`"normal-video-c50fe63e-699d-4d61-93f5-2099ab159d6d"`。
    </ResponseField>

    <ResponseField name="status" type="enum<string>" required>
      标准化后的任务生命周期状态。

      可选值：`queued`、`processing`、`succeeded`、`failed`。
    </ResponseField>

    <ResponseField name="created_at" type="integer<int64>" required>
      Unix 时间戳（秒）。
    </ResponseField>

    <ResponseField name="output" type="object" required>
      当前子视频任务输出，包括仍在排队或处理中的条目。

      <Expandable title="child attributes">
        <ResponseField name="videos" pre={["output."]} type="object[]" required>
          所有子视频任务及其当前输出信息；结果文件可用前 url 和 format 为 null。

          <Expandable title="child attributes">
            <ResponseField name="uuid" pre={["output.videos[]."]} type="string<uuid>" required>
              生成视频子项 UUID。

              示例：`"7d1fa4bb-41e6-4a5d-88d8-1851f5342e87"`。
            </ResponseField>

            <ResponseField name="url" pre={["output.videos[]."]} type="string<uri> | null" required>
              生成视频可用时用于下载的临时签名 URL。
            </ResponseField>

            <ResponseField name="format" pre={["output.videos[]."]} type="string | null" required>
              已知时返回视频文件格式，例如 mp4。

              示例：`"mp4"`。
            </ResponseField>

            <ResponseField name="duration" pre={["output.videos[]."]} type="integer | null" required>
              可用时返回生成视频的时长，单位为秒。

              取值范围：`0 <= x <= infinity`。
            </ResponseField>

            <ResponseField name="resolution" pre={["output.videos[]."]} type="string | null" required>
              可用时返回生成视频的分辨率，例如 720p。

              示例：`"720p"`。
            </ResponseField>

            <ResponseField name="aspect_ratio" pre={["output.videos[]."]} type="string | null" required>
              可用时返回生成视频的宽高比，例如 16:9。

              示例：`"16:9"`。
            </ResponseField>

            <ResponseField name="has_audio" pre={["output.videos[]."]} type="boolean" required>
              此视频是否启用了原生音频生成。
            </ResponseField>

            <ResponseField name="mode" pre={["output.videos[]."]} type="enum<string>" required>
              此视频使用的生成模式。

              可选值：`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>
              此生成视频的当前状态。

              可选值：`queued`、`processing`、`succeeded`、`failed`。
            </ResponseField>

            <ResponseField name="created_at" pre={["output.videos[]."]} type="integer<int64>" required>
              此生成视频的创建时间，Unix 时间戳，单位为秒。
            </ResponseField>

            <ResponseField name="updated_at" pre={["output.videos[]."]} type="integer<int64>" required>
              此生成视频的最后更新时间，Unix 时间戳，单位为秒。
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="mode" type="enum<string>" required>
      任务使用的视频生成模式。

      可选值：`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">
      任务使用的视频生成模型。

      可选值：`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 时间戳（秒）。
    </ResponseField>

    <ResponseField name="usage" type="object">
      可用时返回此任务扣除的点数。

      <Expandable title="child attributes">
        <ResponseField name="credits" pre={["usage."]} type="number<float>" required>
          该任务或请求扣除的点数。

          取值范围：`0 <= x <= infinity`。

          示例：`26`。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error" type="object">
      任务失败时返回的错误详情。

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          稳定且可供程序读取的任务失败代码。
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          便于阅读的任务失败说明。
        </ResponseField>

        <ResponseField name="failed_at" pre={["error."]} type="integer<int64>">
          任务失败时的 Unix 时间戳（秒）。
        </ResponseField>

        <ResponseField name="retryable" pre={["error."]} type="boolean">
          重试相同操作是否可能成功。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="400">
    请求无效

    <ResponseField name="error" type="object" required>
      结构化错误详情。

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          稳定且可供程序读取的错误码。

          示例：`"invalid_prompt"`。
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          便于阅读的错误说明。

          示例：`"prompt is required and must be a non-empty string"`。
        </ResponseField>

        <ResponseField name="doc_url" pre={["error."]} type="string<uri> | null">
          包含此错误更多信息的可选文档 URL。

          示例：`"https://api.neural4d.com/docs/errors#invalid_prompt"`。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="401">
    认证失败

    <ResponseField name="error" type="object" required>
      结构化错误详情。

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          稳定且可供程序读取的错误码。

          示例：`"invalid_prompt"`。
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          便于阅读的错误说明。

          示例：`"prompt is required and must be a non-empty string"`。
        </ResponseField>

        <ResponseField name="doc_url" pre={["error."]} type="string<uri> | null">
          包含此错误更多信息的可选文档 URL。

          示例：`"https://api.neural4d.com/docs/errors#invalid_prompt"`。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="403">
    当前已认证用户无权访问该资源或点数不足

    <ResponseField name="error" type="object" required>
      结构化错误详情。

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          稳定且可供程序读取的错误码。

          示例：`"invalid_prompt"`。
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          便于阅读的错误说明。

          示例：`"prompt is required and must be a non-empty string"`。
        </ResponseField>

        <ResponseField name="doc_url" pre={["error."]} type="string<uri> | null">
          包含此错误更多信息的可选文档 URL。

          示例：`"https://api.neural4d.com/docs/errors#invalid_prompt"`。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="404">
    未找到请求的资源

    <ResponseField name="error" type="object" required>
      结构化错误详情。

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          稳定且可供程序读取的错误码。

          示例：`"invalid_prompt"`。
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          便于阅读的错误说明。

          示例：`"prompt is required and must be a non-empty string"`。
        </ResponseField>

        <ResponseField name="doc_url" pre={["error."]} type="string<uri> | null">
          包含此错误更多信息的可选文档 URL。

          示例：`"https://api.neural4d.com/docs/errors#invalid_prompt"`。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="429">
    已超过请求或配额限制

    <ResponseField name="error" type="object" required>
      结构化错误详情。

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          稳定且可供程序读取的错误码。

          示例：`"invalid_prompt"`。
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          便于阅读的错误说明。

          示例：`"prompt is required and must be a non-empty string"`。
        </ResponseField>

        <ResponseField name="doc_url" pre={["error."]} type="string<uri> | null">
          包含此错误更多信息的可选文档 URL。

          示例：`"https://api.neural4d.com/docs/errors#invalid_prompt"`。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="500">
    内部或上游服务错误

    <ResponseField name="error" type="object" required>
      结构化错误详情。

      <Expandable title="child attributes">
        <ResponseField name="code" pre={["error."]} type="string" required>
          稳定且可供程序读取的错误码。

          示例：`"invalid_prompt"`。
        </ResponseField>

        <ResponseField name="message" pre={["error."]} type="string" required>
          便于阅读的错误说明。

          示例：`"prompt is required and must be a non-empty string"`。
        </ResponseField>

        <ResponseField name="doc_url" pre={["error."]} type="string<uri> | null">
          包含此错误更多信息的可选文档 URL。

          示例：`"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>