ModelFold Docs

简体中文

English

简体中文

English

Appearance

获取任务详情 ​

本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。

接口 ​

GET /jobs/recordInfo

完整 URL: https://ai.modelfold.online/v1/jobs/recordInfo

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

概述 ​

使用此端点查询通过Market模型API创建的任何任务的状态和结果。这是一个统一的查询接口，适用于Market类别下的所有模型。

INFO

适用于所有通过 POST /api/v1/jobs/createTask 创建的任务。聊天模型为同步接口，没有可查询的任务。

任务状态 ​

状态描述操作
waiting任务已排队等待处理继续轮询
queuing任务在处理队列中继续轮询
generating任务正在处理中继续轮询
success任务成功完成解析resultJson获取结果
fail任务失败查看failCode和failMsg了解详情

轮询最佳实践 ​

推荐的轮询间隔

  • 初始轮询（前30秒）: 每2-3秒
  • 30秒后: 每5-10秒
  • 2分钟后: 每15-30秒
  • 轮询时长: 部分视频任务耗时超过 10 分钟，请持续轮询直至 state 为 success 或 fail。

TIP

使用指数退避来减少服务器负载和API成本。

使用回调而非轮询

对于生产应用，我们强烈建议在创建任务时使用callBackUrl参数：

  • 无需轮询: 您的服务器自动接收通知
  • 降低API成本: 消除持续的轮询请求
  • 更好的性能: 任务完成时立即通知
  • 降低延迟: 完成和通知之间无延迟

查看各个模型文档了解回调实现详情。

处理已完成的任务

当state为success时：

  1. 将resultJson字符串解析为JSON
  2. 提取resultUrls数组
  3. 立即下载生成的内容
  4. 将内容存储在您自己的存储中

重要: 生成文件保留 14 天。

错误处理 ​

json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_12345678",
    "model": "grok-imagine/text-to-image",
    "state": "fail",
    "param": "{\"model\":\"grok-imagine/text-to-image\",\"input\":\"{\\\"prompt\\\":\\\"...\\\"}\"}",
    "resultJson": null,
    "failCode": "400",
    "failMsg": "&lt;error detail&gt;",
    "completeTime": 1698765432000,
    "createTime": 1698765400000,
    "updateTime": 1698765432000
  }
}

常见错误代码 ​

出错时 HTTP 状态仍为 200，请以 code 判断。

代码描述解决方案
401未授权 - API密钥无效或缺失检查您的API密钥
422缺少 taskId，或任务不存在 / 不属于当前账号检查 taskId 是否正确
500内部服务器错误几分钟后重试
501生成失败查看failMsg了解具体错误详情

示例: 完整的轮询流程 ​

javascript
async function pollTaskStatus(taskId, maxAttempts = 60, interval = 5000) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(
      `https://ai.modelfold.online/v1/jobs/recordInfo?taskId=${taskId}`,
      {
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      }
    );
    
    const result = await response.json();
    if (result.code !== 200) throw new Error(result.msg);
    const { state, resultJson, failMsg } = result.data;
    
    console.log(`尝试 ${attempt + 1}: 状态 = ${state}`);
    
    if (state === 'success') {
      const results = JSON.parse(resultJson);
      console.log('✅ 任务完成!');
      console.log('结果:', results.resultUrls);
      return results;
    }
    
    if (state === 'fail') {
      console.error('❌ 任务失败:', failMsg);
      throw new Error(failMsg);
    }
    
    // 仍在处理中，等待下次轮询
    await new Promise(resolve => setTimeout(resolve, interval));
  }
  
  throw new Error('任务在最大尝试次数后超时');
}

// 使用方法
try {
  const results = await pollTaskStatus('task_12345678');
  console.log('生成的内容URL:', results.resultUrls);
} catch (error) {
  console.error('错误:', error.message);
}

速率限制 ​

  • 最大查询速率: 每个API密钥每秒10次请求
  • 推荐间隔: 轮询之间间隔2-5秒

WARNING

过度轮询可能导致速率限制。生产应用请使用回调。

相关资源 ​

请求参数 ​

Path / Query / Header ​

参数类型必填说明
query.taskIdany是创建任务时返回的唯一任务标识符。 位置: query

响应 ​

200 — 请求成功 ​

参数类型必填说明
codeinteger是请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。 可选值：200 / 401 / 402 / 404 / 422 / 429 / 433 / 455 / 500 / 501 / 505。 示例：200。
msgstring是响应消息，失败时的错误描述
dataobject是包含所有任务信息的数据对象
  data.taskIdstring否此任务的唯一标识符 示例：task_12345678。
  data.modelstring否此任务使用的模型（例如 grok-imagine/text-to-image、seedream-4.0、kling-1.0） 示例：bytedance/seedance-2-5。
  data.statestring否任务的当前状态。请以 state 判断任务结果。 可选值：waiting / queuing / generating / success / fail。 示例：success。
  data.paramstring否包含创建任务时使用的原始请求参数的JSON字符串。其中的 input 仍是 JSON 字符串，需要再解析一次。 示例：{"model":"grok-imagine/text-to-image","callBackUrl":"https://your-domain.com/api/callback","input":"{\"prompt\":\"电影肖像...\",\"aspect_ratio\":\"3:2\"}"}。
  data.resultJsonstring否结果 JSON 字符串。state 为 success 时返回；失败时可能为 null 或空字符串。
结构如下：
- 图像/媒体/视频：{resultUrls: []}
- Seedance 2.x 开启 return_last_frame 时：{resultUrls: [], lastFrameUrl: []}
- 文本类型：{resultObject: {}}
针对 OmniHuman 系列模型，响应说明如下：
- OmniHuman 1.5 Subject Detection（主体检测模型）：响应结构为 {resultObject: {mask_urls: ["url1", "url2", ...]}}，返回检测到的主体对应的掩码图 URL 列表。该模型返回的 URL 有效期为 1 小时。
- OmniHuman 1.5 Human Identification（人物识别模型）：响应结构为 {resultObject: {subject_status: 1}}，其中 subject_status 含义为 0 = 不含主体，1 = 含主体，用于标识图片中是否检测到人物主体。 示例：{"resultUrls":["https://example.com/generated-content.jpg"]}。
  data.responseobject否resultJson 的解析结果，仅在 state 为 success 时返回。
  data.failCodestring否失败码（数字字符串，如 "500"）。state 为 fail 时返回；成功时可能为 null 或空字符串。 示例：``。
  data.failMsgstring否失败原因。state 为 fail 时返回；成功时可能为 null 或空字符串。 示例：``。
  data.costTimeinteger否处理耗时（秒），成功和失败的任务都会返回。 示例：15。
  data.completeTimeinteger否完成时间戳（Unix时间戳，毫秒） 示例：1698765432000。
  data.createTimeinteger否创建时间戳（Unix时间戳，毫秒） 示例：1698765400000。
  data.creditsConsumednumber否本次任务消耗的积分详情，表示任务执行过程中实际扣除的积分数量。
json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_12345678",
    "model": "grok-imagine/text-to-image",
    "state": "success",
    "param": "{\"model\":\"grok-imagine/text-to-image\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":\"{\\\"prompt\\\":\\\"电影肖像...\\\",\\\"aspect_ratio\\\":\\\"3:2\\\"}\"}",
    "resultJson": "{\"resultUrls\":[\"https://example.com/generated-content.jpg\"]}",
    "failCode": "",
    "failMsg": "",
    "costTime": 15,
    "completeTime": 1698765432000,
    "createTime": 1698765400000,
    "updateTime": 1698765432000,
    "progress": 45,
    "creditsConsumed": 50
  }
}

401 — 未授权 - API密钥无效或缺失 ​

参数类型必填说明
codeinteger是—
msgstring是—
json
{
  "code": 401,
  "msg": "Unauthorized"
}

429 — 速率限制 - 请求过于频繁 ​

参数类型必填说明
codeinteger是—
msgstring是—
json
{
  "code": 429,
  "msg": "Rate limit exceeded"
}

500 — 服务器错误 ​

ModelFold — 一个 API，接入所有主流 AI 模型。

© 2026 ModelFold