Async task workflow
异步任务调用流程
异步任务不是一个单独的模型接口。你先调用图片、视频或语音创建接口,平台立即返回任务 ID;再用这个 ID 查询,直到拿到结果或错误。
调用顺序
提交生成请求
POST 请求的 JSON Body 带上模型 ID 和该模型支持的参数。
保存任务 ID
HTTP 202 表示请求已受理,从响应中保存 id。
查询同一任务
使用同一把 API Key 请求 GET /v1/aigc/tasks/:id。
读取最终结果
succeeded 读取 output,failed 读取 error。
1. 提交生成请求
三类模型使用不同的创建地址,但都返回相同的异步任务对象。
生成类型POST 地址
图片
/v1/aigc/images视频
/v1/aigc/videos语音
/v1/aigc/audio请求参数放在哪里
参数全部放在 POST 请求的 JSON Body 顶层。下面是一个完整图片请求,不需要再套 data、input 或 params。
字段填写要求说明
model必填模型文档中显示的可调用模型 ID。callback_url可选任务成功或失败时接收 POST 通知的 HTTP/HTTPS 地址。其他字段按模型图片常用 prompt,视频常用 content;完整参数以具体模型文档为准。{
"model": "openai/gpt-image-2/text-to-image",
"prompt": "夜晚森林中的萤火虫,电影感光影",
"aspect_ratio": "1:1",
"resolution": "1k"
}创建成功返回什么
成功提交返回 HTTP 202。此时只是任务已进入队列,并不代表图片已经生成成功;保存响应中的 id 或 status_url。
{
"id": "018f47a2-6c66-7c71-9d43-5e62cb80f120",
"object": "aigc.task",
"type": "image",
"model": "openai/gpt-image-2/text-to-image",
"status": "queued",
"created_at": "2026-09-02T08:00:00Z",
"updated_at": "2026-09-02T08:00:00Z",
"status_url": "https://api.fireflyfusion.ai/v1/aigc/tasks/018f47a2-6c66-7c71-9d43-5e62cb80f120",
"output": [],
"error": null
}2. 查询任务结果
使用创建响应中的 id,携带创建任务时使用的同一把个人 API Key:
项目内容
MethodGETPath/v1/aigc/tasks/:idAuthorizationBearer $FIREFLY_API_KEYBody没有请求 Body。status怎么处理
queued正在排队,等待至少 2 秒后查询同一个任务 ID。running正在生成,等待至少 2 秒后继续查询同一个任务 ID。succeeded停止查询,从 output 数组读取结果 URL。failed停止查询,从 error.code 和 error.message 读取失败原因。轮询间隔
Retry-After 是任务查询接口返回的 HTTP 响应 Header,不在 JSON 正文中。看到 Retry-After: 2 时等待至少 2 秒;没有这个 Header 时也默认等待 2 秒。状态为 failed 时也应立即停止查询。
保存时间
上传资源和生成结果保存 1 天,请及时下载或使用。
{
"id": "018f47a2-6c66-7c71-9d43-5e62cb80f120",
"object": "aigc.task",
"type": "image",
"model": "openai/gpt-image-2/text-to-image",
"status": "succeeded",
"created_at": "2026-09-02T08:00:00Z",
"updated_at": "2026-09-02T08:00:08Z",
"status_url": "https://api.fireflyfusion.ai/v1/aigc/tasks/018f47a2-6c66-7c71-9d43-5e62cb80f120",
"output": [
{
"type": "image",
"url": "https://static.example.com/result.png"
}
],
"error": null
}3. 可直接运行的完整代码
先设置环境变量 FIREFLY_API_KEY。下面四种示例会提交任务、每 2 秒查询状态,并在成功时输出结果 URL;任务失败或接口报错时以非零状态退出。
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"strconv"
"time"
)
type mediaSource struct {
URL string `json:"url"`
}
type imageRequest struct {
Model string `json:"model"`
Prompt string `json:"prompt,omitempty"`
AspectRatio string `json:"aspect_ratio"`
Resolution string `json:"resolution"`
}
type taskResponse struct {
ID string `json:"id"`
Status string `json:"status"`
Output json.RawMessage `json:"output"`
Error json.RawMessage `json:"error"`
}
func requestJSON(client *http.Client, method, url string, payload any) taskResponse {
var body io.Reader
if payload != nil {
encoded, err := json.Marshal(payload)
if err != nil { panic(err) }
body = bytes.NewReader(encoded)
}
request, err := http.NewRequest(method, url, body)
if err != nil { panic(err) }
request.Header.Set("Authorization", "Bearer "+os.Getenv("FIREFLY_API_KEY"))
request.Header.Set("Content-Type", "application/json")
response, err := client.Do(request)
if err != nil { panic(err) }
defer response.Body.Close()
raw, err := io.ReadAll(response.Body)
if err != nil { panic(err) }
if response.StatusCode < 200 || response.StatusCode >= 300 {
fmt.Fprintln(os.Stderr, string(raw))
os.Exit(1)
}
var result taskResponse
if err := json.Unmarshal(raw, &result); err != nil { panic(err) }
return result
}
func main() {
client := &http.Client{Timeout: 60 * time.Second}
task := requestJSON(client, http.MethodPost, "https://api.fireflyfusion.ai/v1/aigc/images", imageRequest{
Model: "openai/gpt-image-2/text-to-image",
Prompt: "夜晚森林中的萤火虫,电影感光影",
AspectRatio: "1:1",
Resolution: "1k",
})
intervalMS, _ := strconv.Atoi(os.Getenv("FIREFLY_POLL_INTERVAL_MS"))
if intervalMS <= 0 { intervalMS = 2000 }
for task.Status == "queued" || task.Status == "running" {
time.Sleep(time.Duration(intervalMS) * time.Millisecond)
task = requestJSON(client, http.MethodGet, "https://api.fireflyfusion.ai/v1/aigc/tasks/"+task.ID, nil)
}
if task.Status == "succeeded" {
fmt.Println(string(task.Output))
return
}
if task.Status == "failed" {
fmt.Fprintln(os.Stderr, string(task.Error))
} else {
fmt.Fprintln(os.Stderr, "未知任务状态:"+task.Status)
}
os.Exit(1)
}任务响应字段
查看全部字段创建响应和查询响应使用同一结构
字段类型返回情况说明
idstring<uuid>始终返回任务 ID,用于查询结果。objectstring始终返回固定为 aigc.task。typestring enum始终返回image、video 或 audio。statusstring enum始终返回queued、running、succeeded 或 failed。modelstring始终返回创建任务时提交的模型 ID。status_urlstring<https-uri>始终返回该任务的完整查询地址。outputarray<object>始终返回成功时包含一个或多个结果项,否则为空数组。output[].typestring enum有结果时image、video 或 audio。output[].urlstring<https-uri>有结果时生成结果的完整 URL。errorobject | null始终返回失败时包含错误信息,其他状态为 null。error.codestring失败时稳定错误码。error.messagestring失败时可读的失败原因。created_atstring<date-time>始终返回任务创建时间。updated_atstring<date-time>始终返回任务最后更新时间。只需要单独查询某个任务时,也可以查看 获取任务详情。