跳转到主要内容
GET
/
api
/
v1
/
jobs
/
recordInfo
获取任务详情
curl --request GET \
  --url https://api.kie.ai/api/v1/jobs/recordInfo \
  --header 'Authorization: Bearer <token>'
{
  "code": 200,
  "message": "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": "",
    "completeTime": 1698765432000,
    "createTime": 1698765400000,
    "updateTime": 1698765432000
  }
}

概述

使用此端点查询通过Market模型API创建的任何任务的状态和结果。这是一个统一的查询接口,适用于Market类别下的所有模型。
此端点适用于所有Market模型,包括Seedream、Grok Imagine、Kling、Claude以及未来添加到Market的任何模型。

API端点

GET https://api.kie.ai/api/v1/jobs/recordInfo

查询参数

taskId
string
required
创建任务时返回的唯一任务标识符。示例: task_12345678

请求示例

curl -X GET "https://api.kie.ai/api/v1/jobs/recordInfo?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应格式

{
  "code": 200,
  "message": "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": "",
    "completeTime": 1698765432000,
    "createTime": 1698765400000,
    "updateTime": 1698765432000
  }
}

响应字段

code
integer
响应状态码。200表示成功。
message
string
响应消息。成功查询通常为"success"
data
object
包含所有任务信息的任务数据对象。

任务状态

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

轮询最佳实践

  • 初始轮询(前30秒): 每2-3秒
  • 30秒后: 每5-10秒
  • 2分钟后: 每15-30秒
  • 最大轮询时长: 10-15分钟后停止并调查
使用指数退避来减少服务器负载和API成本。
对于生产应用,我们强烈建议在创建任务时使用callBackUrl参数:
  • 无需轮询: 您的服务器自动接收通知
  • 降低API成本: 消除持续的轮询请求
  • 更好的性能: 任务完成时立即通知
  • 降低延迟: 完成和通知之间无延迟
查看各个模型文档了解回调实现详情。
statesuccess时:
  1. resultJson字符串解析为JSON
  2. 提取resultUrls数组
  3. 立即下载生成的内容
  4. 将内容存储在您自己的存储中
重要: 生成的内容URL通常在24小时后过期。

错误处理

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "model": "grok-imagine/text-to-image",
    "state": "fail",
    "param": "{\"model\":\"grok-imagine/text-to-image\",\"input\":{\"prompt\":\"...\"}}",
    "resultJson": "",
    "failCode": "422",
    "failMsg": "Invalid prompt: prompt contains prohibited content",
    "completeTime": 1698765432000,
    "createTime": 1698765400000,
    "updateTime": 1698765432000
  }
}

常见错误代码

代码描述解决方案
401未授权 - API密钥无效或缺失检查您的API密钥
404未找到任务验证taskId是否正确
422原始请求中的验证错误查看failMsg了解详情
500内部服务器错误几分钟后重试
501生成失败查看failMsg了解具体错误详情

示例: 完整的轮询流程

Node.js
async function pollTaskStatus(taskId, maxAttempts = 60, interval = 5000) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(
      `https://api.kie.ai/api/v1/jobs/recordInfo?taskId=${taskId}`,
      {
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      }
    );
    
    const result = await response.json();
    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秒
过度轮询可能导致速率限制。生产应用请使用回调。

相关资源

Authorizations

Authorization
string
header
required

所有 API 都需要通过 Bearer Token 进行身份验证。

获取 API Key:

  1. 访问 API Key 管理页面 获取您的 API Key

使用方法: 添加到请求头: Authorization: Bearer YOUR_API_KEY

注意:

  • 请妥善保管您的 API Key,不要与他人共享
  • 如果您怀疑 API Key 已泄露,请立即在管理页面重置

Query Parameters

taskId
string
required

创建任务时返回的唯一任务标识符。

Example:

"task_12345678"

Response

请求成功

code
enum<integer>

响应状态码

  • 200: 成功 - 请求已成功处理
  • 401: 未授权 - 身份验证凭据缺失或无效
  • 402: 积分不足 - 账户没有足够的积分执行操作
  • 404: 未找到 - 请求的资源或端点不存在
  • 422: 验证错误 - 请求参数未通过验证检查
  • 429: 速率限制 - 已超过此资源的请求限制
  • 455: 服务不可用 - 系统正在维护中
  • 500: 服务器错误 - 处理请求时发生意外错误
  • 501: 生成失败 - 内容生成任务失败
  • 505: 功能已禁用 - 请求的功能当前已禁用
可用选项:
200,
401,
402,
404,
422,
429,
455,
500,
501,
505
msg
string

响应消息,失败时为错误描述

Example:

"success"

data
object

包含所有任务信息的数据对象