GPTFuny API 技术文档

02

QUICK START

五分钟完成首次接入

准备 API Key，提交任务并轮询到终态。生成接口返回的是任务，不会在同一个 HTTP 请求中等待媒体生成完成。

1

创建 API Key

登录控制台，在令牌管理中创建只用于服务端的密钥。

2

提交生成

携带 Bearer Token 和唯一幂等键发送 JSON 请求。

3

轮询任务

保存返回的 taskId，按退避策略查询任务状态。

4

持久化结果

成功后下载临时 URL，并保存到自己的对象存储。

POST

第一个文生图请求

将 YOUR_API_KEY 替换为控制台创建的密钥。每个新的逻辑任务都应使用新的 Idempotency-Key。

返回即接单

HTTP 成功只代表任务已创建。媒体结果需要通过任务查询接口获取。

cURL

curl -X POST "https://new-api.gptfuny.com/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "prompt": "一只红色陶瓷茶壶，木桌，柔和棚拍光",
    "negativePrompt": "模糊，文字，水印",
    "resolution": "2k",
    "aspectRatio": "16:9"
  }'

202 / TASK ACCEPTED

{
  "id": "task_01JQ9R7KX2Q0M6VZ",
  "status": "QUEUED",
  "createdAt": "2026-10-13T08:30:00.000Z"
}

GET /tasks/{taskId}

{
  "id": "task_01JQ9R7KX2Q0M6VZ",
  "status": "SUCCEEDED",
  "output": {
    "images": [{ "url": "https://..." }]
  }
}

03

AUTHENTICATION

认证与 API Key

除价格、效果目录和公开案例外，业务接口均通过 HTTP Bearer Token 鉴权。

请求头格式

HTTP

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

验证凭证与余额

cURL

curl "https://new-api.gptfuny.com/api/v1/me" \
  -H "Authorization: Bearer $GPTFUNY_API_KEY"

KEY

密钥只放在服务端

使用环境变量或密钥管理服务保存。
不同环境、业务和租户使用不同密钥。
日志、异常追踪和客服工单中主动脱敏。
发现泄露后立即撤销并创建新密钥。
不要写入浏览器、移动端或公开仓库。

04

CONVENTIONS

通用请求约定

01

JSON 编码

请求和响应均使用 UTF-8 JSON；上传文件字节时例外。

02

时间格式

时间字段使用 ISO 8601 UTC，例如 2026-10-13T08:30:00.000Z。

03

金额精度

金额以字符串返回。业务端使用 Decimal，避免浮点误差。

04

向前兼容

忽略未知字段，不依赖字段顺序，也不要匹配可读错误文案。

API Base

本文示例从 https://new-api.gptfuny.com/api/v1 读取。部署时可在 config.js 中统一修改，不需要逐段编辑文档。

05

API MAP

接口总览

生成接口创建异步任务；上传接口管理输入资源；任务接口负责查询结果和取消排队任务。

方法	路径	用途	鉴权	幂等
POST	`/images/generations`	文生图	是	是
POST	`/images/transformations`	图生图 / 图片效果	是	是
POST	`/videos/generations`	文生视频	是	是
POST	`/videos/transformations`	图生视频 / 视频效果	是	是
POST	`/uploads`	创建图片上传	是	否
GET	`/uploads/{assetId}`	查询上传状态	是	否
GET	`/tasks/{taskId}`	查询生成任务	是	否
POST	`/tasks/{taskId}/cancel`	取消排队任务	是	否
GET	`/pricing`	查询实时价格	否	否
GET	`/effects`	查询效果目录	否	否

E

EFFECTS

效果目录与调用方式

按图片和视频分类查询完整公开效果，选择条目即可生成服务端 cURL 示例。示例只展示请求，不在浏览器中发送生成任务。

检索效果 ID、名称或用途效果类型

Image Effects · 图片效果

POST /api/v1/images/transformations 的 effectId 可选；普通转换使用 assetId + prompt，无须选择效果。

effectId	Name · 名称	Does · 用途	Presets · 默认参数	Demo · 演示	调用

Video Effects · 视频效果

POST /api/v1/videos/transformations 将已上传图片转成视频，effectId 必填；这里的 Transform Video 不是上传视频进行编辑。

effectId	Name · 名称	Does · 用途	Presets · 默认参数	Demo · 演示	调用

选择效果 → 复制请求 → 查询任务

点击目录中的“生成请求”。请在服务端设置 GPTFUNY_API_KEY、ASSET_ID 和每个业务请求唯一的 IDEMPOTENCY_KEY；同一次请求重试时复用该键。

cURL · 等待选择效果

请先在目录中选择一个效果。

请求体中的 assetId 需属于当前账户并处于 READY。提交响应的 id 是任务 ID，随后调用 GET /api/v1/tasks/{taskId}。参见上传流程、任务状态与轮询。

POST /images/generations

Bearer Token

06

GENERATE IMAGE · TEXT TO IMAGE

Generate Image · 文生图

根据提示词生成一张图片。此接口不接收 effectId；命名图片效果请使用 Effects 与图片转换接口。

请求字段

promptstring · 必填

正向提示词，1～2000 字符。

negativePromptstring · 可选

不希望出现的元素，最多 1000 字符。

resolutionenum · 默认 1k

1k、2k、4k。

aspectRatioenum · 默认 1:1

1:1、9:16、16:9、4:3、3:4、3:2、2:3、2:1、1:2。

JSON

{
  "prompt": "未来主义建筑，雨后街道，电影光影，高细节",
  "negativePrompt": "模糊，低清晰度，水印",
  "resolution": "2k",
  "aspectRatio": "16:9"
}

Generate Image · cURL

curl --fail-with-body -X POST "https://new-api.gptfuny.com/api/v1/images/generations" \
  -H "Authorization: Bearer $GPTFUNY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{"prompt":"a red ceramic teapot on a wooden table","resolution":"1k","aspectRatio":"1:1"}'

以上 cURL 使用 Bash / Git Bash / WSL 语法。先在服务端设置密钥及唯一幂等键。提交响应的 id 用于查询任务，成功图片位于 output.images。

07

UPLOADS

图片上传：创建、PUT、确认

图生图和图生视频引用平台内的 assetId。先上传并等待状态变为 READY，再提交生成。

01

创建上传记录POST /uploads

声明真实文件类型，获取签名 PUT URL 和 assetId。

02

上传原始字节PUT {uploadUrl}

不携带平台 Token，Content-Type 必须与第一步完全一致。

03

完成并校验POST /uploads/{assetId}/complete

平台读取文件头、尺寸和大小；返回 READY 后可复用。

curl -X POST "https://new-api.gptfuny.com/api/v1/uploads" \
  -H "Authorization: Bearer $GPTFUNY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contentType":"image/png"}'

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @photo.png

curl -X POST \
  "https://new-api.gptfuny.com/api/v1/uploads/$ASSET_ID/complete" \
  -H "Authorization: Bearer $GPTFUNY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JPEG / PNG / WebP支持格式

20 MB最大文件

16～8192 px单边尺寸

40 MP最大总像素

15 min上传窗口

不要复用带默认 Authorization 的客户端上传

签名 URL 通常指向对象存储域名。上传字节时不要发送 GPTFuny API Key，避免凭证泄漏给第三方域名。

POST/images/transformations

Bearer Token

08

IMAGE TO IMAGE

Transform Image · 图片转换

prompt 与 effectId 至少提供一个。两者同时存在时，自定义提示词会补充效果指令。

JSON

{
  "assetId": "asset_01JQ9PE7QJAZ7S9E",
  "effectId": "EFFECT_ID_FROM_CATALOG",
  "prompt": "保留原始背景和人物姿态",
  "resolution": "fhd",
  "aspectRatio": "3:4"
}

普通图生图可只传 assetId + prompt；效果模式可只传 assetId + effectId。图生图不使用 negativePrompt。

Transform Image · 字段与默认值

assetIdstring · 必填

当前账户的 READY 图片素材；1～64 字符。

prompt / effectId至少一个

prompt 为 1～2000 字符；effectId 为 1～64 字符。两者并用时提示词补充效果指令。

resolution默认 hd

hd、fhd；与文生图的 1k / 2k / 4k 不同。

aspectRatio默认贴近输入图

1:1、9:16、16:9、4:3、3:4、3:2、2:3。显式传入的参数覆盖效果默认值。

普通转换 · 不选效果 · cURL

curl --fail-with-body -X POST "https://new-api.gptfuny.com/api/v1/images/transformations" \
  -H "Authorization: Bearer $GPTFUNY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data "{\"assetId\":\"${ASSET_ID}\",\"prompt\":\"make the sky look like dusk\"}"

需要效果模式时，在 Image Effects 中选择通用条目生成请求。成功图片位于 output.images。

POST/videos/generations

Bearer Token

09

GENERATE VIDEO · TEXT TO VIDEO

Generate Video · 文生视频

根据文本生成短视频。此接口不接收 effectId；命名视频效果请使用 Effects 与视频转换接口。

promptstring · 必填

视频内容、镜头、运动、光线和风格描述。

resolutionenum · 默认 720p

480p、512p、720p、1080p。

aspectRatioenum · 默认 16:9

16:9、9:16、1:1、4:3、3:4、21:9。

durationSecondsinteger · 默认 5

4～15 秒；提交前先查询实时价格和可售规格。

JSON

{
  "prompt": "清晨海面，薄雾缓慢移动，镜头轻微向前推进",
  "resolution": "1080p",
  "aspectRatio": "21:9",
  "durationSeconds": 8
}

Generate Video · cURL

curl --fail-with-body -X POST "https://new-api.gptfuny.com/api/v1/videos/generations" \
  -H "Authorization: Bearer $GPTFUNY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{"prompt":"a calm sea at dawn, slow drifting clouds","resolution":"720p","aspectRatio":"16:9","durationSeconds":5}'

prompt 为 1～2000 字符；视频接口不使用 negativePrompt。保存提交响应的 id 并查询任务，成功视频位于 output.videos。

POST/videos/transformations

Bearer Token

10

IMAGE TO VIDEO

Transform Video · 图片转视频

从一张已上传图片生成视频。该接口必须提供视频类 effectId，可选提示词用于补充动作或背景要求。

18+ 示例输出ADULT IMAGE → VIDEO

JSON

{
  "assetId": "asset_01JQ9PE7QJAZ7S9E",
  "effectId": "VIDEO_EFFECT_ID",
  "prompt": "背景保持稳定，动作自然",
  "resolution": "fhd",
  "aspectRatio": "3:4",
  "durationSeconds": 8
}

effectId 必填，且必须来自视频效果目录。
durationSeconds 支持 5 或 8 秒。
resolution 使用 hd 或 fhd。
输入图片必须属于当前账户且状态为 READY。

Transform Video · 参数约束

assetId + effectId均必填

每项 1～64 字符；assetId 引用 READY 图片，effectId 来自视频类目录。仅传 prompt 不构成有效请求。

prompt可选 · 1～2000 字符

补充动作、背景等要求，不替换效果本身的指令。

resolution / durationSeconds默认 hd / 5

分辨率为 hd 或 fhd；时长仅为 5 或 8 秒。

aspectRatio默认贴近输入图

16:9、9:16、4:3、3:4、3:2、2:3、1:1。显式传入值覆盖效果默认值。

在 Video Effects 中选择眨眼等通用效果，获得完整 cURL。提交响应使用 id 查询任务，结果位于 output.videos。

11

ASYNC TASKS

异步任务、状态机与结果

所有生成接口共享同一套任务状态。终态不会再次变化，客户端收到终态后应立即停止轮询。

QUEUED等待处理 → PROCESSING正在生成 →

SUCCEEDED生成成功 FAILED生成失败

查询任务

cURL

curl "https://new-api.gptfuny.com/api/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $GPTFUNY_API_KEY"

幂等、安全重试与限流

网络超时并不代表平台没有接单。幂等键用于让同一个逻辑请求安全重放，避免重复任务和重复扣费。

request A同一请求体

Idempotency-Key
order_20261013_001

task_01JQ...只创建一次

相同键 + 相同请求

返回第一次创建的任务，响应可包含 Idempotency-Replayed: true。

相同键 + 不同请求

返回 409 IDEMPOTENCY_KEY_REUSED，不会创建新任务。

失败后重新生成

旧键只会取回旧任务；真正重新生成必须使用新的键。

429 限流

尊重 Retry-After，使用共享限流器、随机抖动和指数退避。

场景	是否重试	做法
连接超时 / 连接中断	是	相同幂等键、相同请求体
500 / 503	是	相同幂等键 + 指数退避
429	是	等待 Retry-After 后重试
400 / 401 / 413	修复后	先修正字段、凭证或请求大小
任务 QUEUED / PROCESSING	不要重提	继续轮询现有 taskId
任务 FAILED / CANCELLED	按需	新请求使用新幂等键

13

PRICING

实时价格、余额与扣费

不要把价格写死在业务代码中。页面展示、报价和任务提交前校验应以 GET /pricing 的实时返回为准。

图片费用=对应分辨率单价 视频费用=每秒单价 × durationSeconds

cURL · 无需鉴权

curl "https://new-api.gptfuny.com/api/v1/pricing"

请求校验不扣费

任务已接受预留费用

任务成功正式扣费

失败 / 排队取消释放预留

商业价格以控制台和实时接口为准

模型、规格、费率、折扣和可售状态可能调整。产品未出现在实时价格中时，应视为暂不可售，不要自动降级到其他规格。

14

ERRORS

错误模型与排查

程序根据稳定的 HTTP 状态码和 code 分支；message 仅用于展示和调试。

{
  "code": "PAYMENT_REQUIRED",
  "status": 402,
  "message": "Your balance is too low to start this generation.",
  "requestId": "req_s1383pvtrrae52fa"
}

排查时保留

requestId 或 taskId
发生时间与时区
接口路径、HTTP 状态和错误码
已脱敏的请求参数

400BAD_REQUEST

修正字段、格式、资源状态或效果类型。

401UNAUTHORIZED

检查 Bearer Token 是否缺失、过期或错误。

402PAYMENT_REQUIRED

余额不足；充值后再提交。

404NOT_FOUND

资源不存在，或不属于当前账户。

409CONFLICT

状态冲突或幂等键复用方式错误。

413PAYLOAD_TOO_LARGE

缩短 JSON；图片必须走上传流程。

429TOO_MANY_REQUESTS

等待 Retry-After，并降低并发。

503SERVICE_UNAVAILABLE

规格暂不可售或上游暂不可用。

15

SDK EXAMPLES

完整接入示例

以下示例演示创建文生图任务并轮询。生产代码还应加入持久化队列、熔断、指标和业务级超时。

Python 3.9+

import os
import time
import uuid
import requests

API_BASE = "https://new-api.gptfuny.com/api/v1"
API_KEY = os.environ["GPTFUNY_API_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

response = requests.post(
    f"{API_BASE}/images/generations",
    headers={
        **HEADERS,
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "prompt": "极简产品摄影，磨砂玻璃香水瓶，暖色侧光",
        "resolution": "2k",
        "aspectRatio": "1:1",
    },
    timeout=30,
)
response.raise_for_status()
task_id = response.json()["id"]

for delay in [2, 3, 5, 8, 10, 15] * 20:
    time.sleep(delay)
    task = requests.get(
        f"{API_BASE}/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    ).json()

    if task["status"] == "SUCCEEDED":
        print(task["output"]["images"][0]["url"])
        break
    if task["status"] in {"FAILED", "CANCELLED"}:
        raise RuntimeError(task.get("error") or task["status"])
else:
    raise TimeoutError(f"task {task_id} is still running")

Node.js 18+

import { randomUUID } from "node:crypto";

const API_BASE = "https://new-api.gptfuny.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.GPTFUNY_API_KEY}`,
  "Content-Type": "application/json",
};

const created = await fetch(`${API_BASE}/images/generations`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": randomUUID() },
  body: JSON.stringify({
    prompt: "极简产品摄影，磨砂玻璃香水瓶，暖色侧光",
    resolution: "2k",
    aspectRatio: "1:1",
  }),
}).then(async (res) => {
  if (!res.ok) throw new Error(await res.text());
  return res.json();
});

const delays = [2000, 3000, 5000, 8000, 10000, 15000];
for (let i = 0; i < 120; i += 1) {
  await new Promise((resolve) =>
    setTimeout(resolve, delays[Math.min(i, delays.length - 1)])
  );
  const task = await fetch(`${API_BASE}/tasks/${created.id}`, {
    headers,
  }).then((res) => res.json());

  if (task.status === "SUCCEEDED") {
    console.log(task.output.images[0].url);
    break;
  }
  if (["FAILED", "CANCELLED"].includes(task.status)) {
    throw new Error(JSON.stringify(task.error ?? task.status));
  }
}

EXAMPLES / TRANSFORM AN IMAGE

图片效果演示

完整展示参考目录中的 113 个图片效果，打开卡片查看输入、结果和调用请求。

EXAMPLES / ANIMATE AN IMAGE

图片动画演示

完整展示参考目录中的 160 个动作效果，打开卡片查看视频与图生视频调用方式。

MEDIA SHOWCASE

创作案例

从输入图片到服装转换与人物动画。

人物动画VIDEO · 展示素材

17

PRODUCTION

生产架构与上线清单

将同步 HTTP 请求与耗时生成解耦。业务服务负责接单，后台 Worker 负责提交、轮询和结果持久化。

业务客户端创建业务任务

→

API 服务鉴权 / 配额 / 入队

→

任务队列削峰 / 重试

→

Worker提交 / 轮询

→

对象存储持久化结果

鉴权

密钥只保存在服务端日志和错误追踪已脱敏环境和租户已隔离

任务

taskId 与业务订单已关联 Worker 重启可恢复轮询终态后立即停止轮询

可靠性

每次生成携带幂等键 429 遵守 Retry-After 已配置退避、熔断和告警

结果

临时 URL 已及时下载结果已复制到自有存储保存 requestId 便于排查

18

FAQ

常见问题

为什么生成接口没有直接返回图片或视频？

媒体生成耗时不稳定，因此接口采用异步任务模型。提交后保存 taskId，再轮询任务接口，能避免长连接超时并支持服务重启后恢复。

网络超时后可以直接重新发送吗？

可以使用完全相同的请求体和相同的 Idempotency-Key 重试。不要修改参数后继续复用旧键。

图生图可以直接传公网图片 URL 吗？

输入图片应先走上传流程，获得状态为 READY 的 assetId。这样平台可验证格式、尺寸和文件归属。

结果 URL 可以永久保存吗？

结果地址通常是临时签名 URL。长期使用时应在任务成功后下载并复制到自己的对象存储。

在哪里查询可用效果和价格？

分别调用 GET /effects 和 GET /pricing。模型能力、效果目录和价格可能调整，以实时接口及控制台展示为准。

用一套接口，连接图片与视频创作

创建 API Key

提交生成

轮询任务

持久化结果

第一个文生图请求

请求头格式

验证凭证与余额

密钥只放在服务端

JSON 编码

时间格式

金额精度

向前兼容

Image Effects · 图片效果

Video Effects · 视频效果

选择效果 → 复制请求 → 查询任务

Generate Image · 文生图

请求字段

Transform Image · 图片转换

Transform Image · 字段与默认值

Generate Video · 文生视频

Transform Video · 图片转视频

Transform Video · 参数约束

查询任务

推荐轮询节奏

鉴权

任务

可靠性

结果

用一套接口，连接
图片与视频创作