文档目录

Async task workflow

异步任务调用流程

异步任务不是一个单独的模型接口。你先调用图片、视频或语音创建接口,平台立即返回任务 ID;再用这个 ID 查询,直到拿到结果或错误。

调用顺序

01

提交生成请求

POST 请求的 JSON Body 带上模型 ID 和该模型支持的参数。

02

保存任务 ID

HTTP 202 表示请求已受理,从响应中保存 id

03

查询同一任务

使用同一把 API Key 请求 GET /v1/aigc/tasks/:id

04

读取最终结果

succeeded 读取 outputfailed 读取 error

1. 提交生成请求

三类模型使用不同的创建地址,但都返回相同的异步任务对象。

生成类型POST 地址
图片/v1/aigc/images
视频/v1/aigc/videos
语音/v1/aigc/audio

请求参数放在哪里

参数全部放在 POST 请求的 JSON Body 顶层。下面是一个完整图片请求,不需要再套 datainputparams

字段填写要求说明
model必填模型文档中显示的可调用模型 ID。
callback_url可选任务成功或失败时接收 POST 通知的 HTTP/HTTPS 地址。
其他字段按模型图片常用 prompt,视频常用 content;完整参数以具体模型文档为准。
JSON 请求 Body
{
  "model": "openai/gpt-image-2/text-to-image",
  "prompt": "夜晚森林中的萤火虫,电影感光影",
  "aspect_ratio": "1:1",
  "resolution": "1k"
}

创建成功返回什么

成功提交返回 HTTP 202。此时只是任务已进入队列,并不代表图片已经生成成功;保存响应中的 idstatus_url

HTTP 202 JSON 响应
{
  "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:

项目内容
MethodGET
Path/v1/aigc/tasks/:id
AuthorizationBearer $FIREFLY_API_KEY
Body没有请求 Body。
status怎么处理
queued正在排队,等待至少 2 秒后查询同一个任务 ID。
running正在生成,等待至少 2 秒后继续查询同一个任务 ID。
succeeded停止查询,从 output 数组读取结果 URL。
failed停止查询,从 error.codeerror.message 读取失败原因。
轮询间隔

Retry-After 是任务查询接口返回的 HTTP 响应 Header,不在 JSON 正文中。看到 Retry-After: 2 时等待至少 2 秒;没有这个 Header 时也默认等待 2 秒。状态为 failed 时也应立即停止查询。

保存时间

上传资源和生成结果保存 1 天,请及时下载或使用。

成功任务 JSON 响应
{
  "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始终返回imagevideoaudio
statusstring enum始终返回queuedrunningsucceededfailed
modelstring始终返回创建任务时提交的模型 ID。
status_urlstring<https-uri>始终返回该任务的完整查询地址。
outputarray<object>始终返回成功时包含一个或多个结果项,否则为空数组。
output[].typestring enum有结果时imagevideoaudio
output[].urlstring<https-uri>有结果时生成结果的完整 URL。
errorobject | null始终返回失败时包含错误信息,其他状态为 null
error.codestring失败时稳定错误码。
error.messagestring失败时可读的失败原因。
created_atstring<date-time>始终返回任务创建时间。
updated_atstring<date-time>始终返回任务最后更新时间。

只需要单独查询某个任务时,也可以查看 获取任务详情