SeeDream Tasks API 集成与使用

在现代应用开发中，任务管理和状态查询是常见需求。SeeDream Tasks API 旨在通过输入由 SeeDream Images Generation API 生成的任务 ID，查询任务的执行状态。本文将详细介绍如何集成 SeeDream Tasks API，帮助开发者轻松实现这一强大功能。

背景

Ace Data Cloud 是一个支持多种数据处理和生成任务的平台。SeeDream Images Generation API 允许用户生成高质量的图像，而 SeeDream Tasks API 则提供了查询这些图像生成任务的状态和结果的能力。通过结合这两个 API，开发者可以高效地管理创作流程，适用于图像生成、数据分析等场景。

应用流程

要使用 SeeDream Tasks API，首先需要访问 SeeDream Images Generation API 的申请页面进行服务申请。接下来，从 SeeDream Images Generation API 中复制任务 ID，如下图所示：

然后，访问 SeeDream Tasks API 页面申请相应服务。在页面中点击“获取”按钮，如下图所示：

如果您尚未登录或注册，系统会自动跳转至 登录页面，邀请您注册并登录。登录成功后，系统将自动返回到当前页面。首次申请用户将获得免费的 API 使用配额。

请求示例

SeeDream Tasks API 可用于查询 SeeDream Images Generation API 的结果。有关如何使用 SeeDream Images Generation API 的更多信息，请参考文档 SeeDream Images Generation API。

假设我们有一个任务 ID：20068983-0cc9-4c6a-aeb6-9c6a3c668be0，以下示例将演示如何传入该任务 ID。

设置请求头和请求体

请求头包括：

• accept: 指定响应格式为 JSON，设置为 application/json。
• authorization: 调用 API 的密钥，申请后可直接获得。

请求体包括：

• id: 上传的任务 ID。
• action: 任务的操作方法。

设置方式如下图所示：

代码示例

页面右侧会自动生成多种语言的代码示例，如下图所示：

以下是一些代码示例：

CURL

curl -X POST 'https://api.acedata.cloud/seedream/tasks' 
-H 'accept: application/json' 
-H 'authorization: Bearer {token}' 
-H 'content-type: application/json' 
-d '{
  "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0",
  "action": "retrieve"
}'

响应示例

成功请求后，API 将返回任务的详细信息，例如：

{
  "success": true,
  "task_id": "84d1544a-9043-4dde-a98b-e889dacd75f6",
  "trace_id": "176acf03-7ca7-4fc6-85db-e3724d4f59eb",
  "data": [
    {
      "prompt": "a white siamese cat",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/6e5f9085-cc4a-4801-b77b-31550129ff19.jpg"
    }
  ]
}

返回结果包含多个字段，具体描述如下：

• success: 当前视频生成任务的状态。
• task_id: 当前视频生成任务的 ID。
• trace_id: 当前视频生成的追踪 ID。
• data: 当前图像生成任务的结果列表。

批量查询操作

批量查询多个任务 ID 的详情，操作方法选择 retrieve_batch。

请求体包括：

• ids: 上传的任务 ID 数组。
• action: 任务的操作方法。

设置方式如下图所示：

代码示例

以下是批量查询的 CURL 示例：

curl -X POST 'https://api.acedata.cloud/seedream/tasks' 
-H 'accept: application/json' 
-H 'authorization: Bearer {token}' 
-H 'content-type: application/json' 
-d '{
  "ids": ["84d1544a-9043-4dde-a98b-e889dacd75f6","84d1544a-9043-4dde-a98b-e889dacd75f6"],
  "action": "retrieve_batch"
}'

响应示例

成功请求后，API 将返回所有批量任务的具体详情，例如：

{
  "items": [
    {
      ...
    }
  ],
  "count": 2
}

返回结果包含多个字段，其中 items 包含所有批量任务的具体信息，count 表示批量查询任务的数量。

错误处理

在调用 API 时，如果发生错误，API 将返回相应的错误代码和消息。例如：

• 400 token_mismatched: 请求错误，可能是缺少或无效参数。
• 401 invalid_token: 未授权，授权令牌无效或缺失。
• 429 too_many_requests: 请求过多，超出速率限制。
• 500 api_error: 内部服务器错误。

错误响应示例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

总结

通过本文，您已经了解了如何使用 SeeDream Tasks API 查询单个或批量任务的具体信息。希望本指南能帮助您更好地集成和使用该 API。如有任何问题，请随时联系技术支持团队。

技术标签：#API #集成 #数据处理 #图像生成 #错误处理