Task result API
获取任务详情
通过任务 ID 获取图片、视频或语音任务的当前状态、错误信息和生成结果。
接口
项目内容
MethodGETPath/v1/aigc/tasks/:id:id创建任务时响应中的 id，必须使用 URL 路径编码。AuthorizationBearer $FIREFLY_API_KEY，使用创建任务的同一把个人 API Key。运行前设置 FIREFLY_API_KEY 和创建任务返回的 FIREFLY_TASK_ID。代码中的请求地址会自动使用当前站点对应的 API 地址。
package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
taskID := os.Getenv("FIREFLY_TASK_ID")
if taskID == "" {
panic("请先设置 FIREFLY_TASK_ID")
}
request, err := http.NewRequest(http.MethodGet, "https://api.fireflyfusion.ai/v1/aigc/tasks/"+taskID, nil)
if err != nil {
panic(err)
}
request.Header.Set("Authorization", "Bearer "+os.Getenv("FIREFLY_API_KEY"))
response, err := http.DefaultClient.Do(request)
if err != nil {
panic(err)
}
defer response.Body.Close()
body, err := io.ReadAll(response.Body)
if err != nil {
panic(err)
}
if response.StatusCode < 200 || response.StatusCode >= 300 {
fmt.Fprintln(os.Stderr, string(body))
os.Exit(1)
}
fmt.Println(string(body))
}响应处理
任务状态客户端处理
queued任务已创建但尚未开始，等待至少 2 秒后查询同一个任务 ID。running任务正在生成，等待至少 2 秒后继续查询同一个任务 ID。succeeded从 output 数组读取结果。一个任务可能返回多个结果项。failed读取 error.code 和 error.message，根据 error.retryable 决定是否重试。不要只判断 HTTP 状态码
任务查询成功返回 HTTP 200 只代表“查询成功”。是否生成成功必须判断响应中的 status。
响应字段
字段类型说明
idstring<uuid>任务 ID。objectstring固定为 aigc.task。typestring enumimage、video 或 audio。modelstring客户提交的公共模型 ID。statusstring enumqueued、running、succeeded 或 failed。status_urlstring<https-uri>该任务的完整查询地址。outputarray<object>成功时的结果数组；每项包含 type 和 url。output[].typestring enumimage、video 或 audio。output[].urlstring<https-uri>生成结果的完整 URL。errorobject | null失败时返回错误对象，成功时为 null。error.codestring稳定错误码。error.messagestring可读的失败原因。error.phasestring enum失败所处的处理阶段。error.retryableboolean是否适合在修正问题或等待后重新提交。created_atstring<date-time>任务创建时间。updated_atstring<date-time>任务最后更新时间。{
"id": "<task_id>",
"object": "aigc.task",
"type": "image | video | audio",
"model": "<public_model_id>",
"status": "queued | running | succeeded | failed",
"status_url": "https://api.fireflyfusion.ai/v1/aigc/tasks/<task_id>",
"created_at": "2026-08-18T08:00:00Z",
"updated_at": "2026-08-18T08:00:08Z",
"output": [
{ "type": "image", "url": "https://..." }
],
"error": null
}轮询建议
- 提交任务后保存
id，不要创建新的任务来代替查询。 Retry-After是 HTTP 响应 Header，不在 JSON 正文中。看到Retry-After: 2时，等待至少 2 秒，再查询同一个任务 ID。- 如果响应中没有
Retry-After，也默认每隔 2 秒查询一次，不要连续快速请求。 - 进入
succeeded或failed后停止轮询。
可选：使用回调
callback_url 填在创建任务请求的 JSON Body 顶层，与 model 同级，不要放进 content、images 或其他参数对象中。图片、视频和语音创建接口都支持这个可选字段。
{
"model": "模型文档中的可调用模型 ID",
"prompt": "生成内容说明",
"callback_url": "https://customer.example.com/firefly/callback"
}任务进入 succeeded 或 failed 后，平台会向该地址发送 POST，请求体为完整任务对象。
项目规则
协议支持 http 和 https。请求方法固定为 POST，Content-Type 为 application/json。触发时机只在 succeeded 或 failed 时发送。失败处理平台最多重试 3 次；回调失败不改变任务状态，仍可使用本页 GET 接口查询。建议保留 GET 查询
回调只是主动通知，客户服务应使用任务 ID 做幂等处理，并在需要时通过 GET 接口重新读取任务详情。