创建 API Key
登录控制台,在令牌管理中创建只用于服务端的密钥。
GPTFuny API 优先覆盖成人向图片效果与动态视频场景,同时提供文生图、图生图、文生视频与图生视频的统一服务端调用方式。 本文档从第一个请求讲到生产级的幂等、轮询、重试、计费和结果持久化。
QUICK START
准备 API Key,提交任务并轮询到终态。生成接口返回的是任务,不会在同一个 HTTP 请求中等待媒体生成完成。
登录控制台,在令牌管理中创建只用于服务端的密钥。
携带 Bearer Token 和唯一幂等键发送 JSON 请求。
保存返回的 taskId,按退避策略查询任务状态。
成功后下载临时 URL,并保存到自己的对象存储。
将 YOUR_API_KEY 替换为控制台创建的密钥。每个新的逻辑任务都应使用新的 Idempotency-Key。
HTTP 成功只代表任务已创建。媒体结果需要通过任务查询接口获取。
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"
}'
{
"id": "task_01JQ9R7KX2Q0M6VZ",
"status": "QUEUED",
"createdAt": "2026-10-13T08:30:00.000Z"
}
{
"id": "task_01JQ9R7KX2Q0M6VZ",
"status": "SUCCEEDED",
"output": {
"images": [{ "url": "https://..." }]
}
}
AUTHENTICATION
除价格、效果目录和公开案例外,业务接口均通过 HTTP Bearer Token 鉴权。
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
curl "https://new-api.gptfuny.com/api/v1/me" \
-H "Authorization: Bearer $GPTFUNY_API_KEY"
CONVENTIONS
请求和响应均使用 UTF-8 JSON;上传文件字节时例外。
时间字段使用 ISO 8601 UTC,例如 2026-10-13T08:30:00.000Z。
金额以字符串返回。业务端使用 Decimal,避免浮点误差。
忽略未知字段,不依赖字段顺序,也不要匹配可读错误文案。
本文示例从 https://new-api.gptfuny.com/api/v1 读取。部署时可在 config.js 中统一修改,不需要逐段编辑文档。
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 | 查询效果目录 | 否 | 否 |
/images/generations
TEXT TO IMAGE
根据提示词生成一张图片。分辨率决定单价,宽高比不影响基础计价。
promptstring · 必填正向提示词,1~2000 字符。
negativePromptstring · 可选不希望出现的元素,最多 1000 字符。
resolutionenum · 默认 1k1k、2k、4k。
aspectRatioenum · 默认 1:11:1、9:16、16:9、4:3、3:4、3:2、2:3、2:1、1:2。
{
"prompt": "未来主义建筑,雨后街道,电影光影,高细节",
"negativePrompt": "模糊,低清晰度,水印",
"resolution": "2k",
"aspectRatio": "16:9"
}
UPLOADS
图生图和图生视频引用平台内的 assetId。先上传并等待状态变为 READY,再提交生成。
POST /uploads声明真实文件类型,获取签名 PUT URL 和 assetId。
PUT {uploadUrl}不携带平台 Token,Content-Type 必须与第一步完全一致。
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 '{}'
签名 URL 通常指向对象存储域名。上传字节时不要发送 GPTFuny API Key,避免凭证泄漏给第三方域名。
/images/transformationsIMAGE TO IMAGE
prompt 与 effectId 至少提供一个。两者同时存在时,自定义提示词会补充效果指令。


{
"assetId": "asset_01JQ9PE7QJAZ7S9E",
"effectId": "EFFECT_ID_FROM_CATALOG",
"prompt": "保留原始背景和人物姿态",
"resolution": "fhd",
"aspectRatio": "3:4"
}
普通图生图可只传 assetId + prompt;效果模式可只传 assetId + effectId。图生图不使用 negativePrompt。
/videos/generationsTEXT TO VIDEO
根据文本生成短视频。视频价格通常按秒计算,轮询间隔应比图片任务更长。
promptstring · 必填视频内容、镜头、运动、光线和风格描述。
resolutionenum · 默认 720p480p、512p、720p、1080p。
aspectRatioenum · 默认 16:916:9、9:16、1:1、4:3、3:4、21:9。
durationSecondsinteger · 默认 54~15 秒;提交前先查询实时价格和可售规格。
{
"prompt": "清晨海面,薄雾缓慢移动,镜头轻微向前推进",
"resolution": "1080p",
"aspectRatio": "21:9",
"durationSeconds": 8
}
/videos/transformationsIMAGE TO VIDEO
从一张已上传图片生成视频。该接口必须提供视频类 effectId,可选提示词用于补充动作或背景要求。
{
"assetId": "asset_01JQ9PE7QJAZ7S9E",
"effectId": "VIDEO_EFFECT_ID",
"prompt": "背景保持稳定,动作自然",
"resolution": "fhd",
"aspectRatio": "3:4",
"durationSeconds": 8
}
effectId 必填,且必须来自视频效果目录。durationSeconds 支持 5 或 8 秒。resolution 使用 hd 或 fhd。READY。ASYNC TASKS
所有生成接口共享同一套任务状态。终态不会再次变化,客户端收到终态后应立即停止轮询。
curl "https://new-api.gptfuny.com/api/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $GPTFUNY_API_KEY"
结果下载地址通常具有时效。需要长期展示时,成功后立即复制到自己的对象存储;地址过期可再次查询任务以获取新链接。
IDEMPOTENCY
网络超时并不代表平台没有接单。幂等键用于让同一个逻辑请求安全重放,避免重复任务和重复扣费。
request A同一请求体order_20261013_001
task_01JQ...只创建一次返回第一次创建的任务,响应可包含 Idempotency-Replayed: true。
返回 409 IDEMPOTENCY_KEY_REUSED,不会创建新任务。
旧键只会取回旧任务;真正重新生成必须使用新的键。
尊重 Retry-After,使用共享限流器、随机抖动和指数退避。
| 场景 | 是否重试 | 做法 |
|---|---|---|
| 连接超时 / 连接中断 | 是 | 相同幂等键、相同请求体 |
| 500 / 503 | 是 | 相同幂等键 + 指数退避 |
| 429 | 是 | 等待 Retry-After 后重试 |
| 400 / 401 / 413 | 修复后 | 先修正字段、凭证或请求大小 |
| 任务 QUEUED / PROCESSING | 不要重提 | 继续轮询现有 taskId |
| 任务 FAILED / CANCELLED | 按需 | 新请求使用新幂等键 |
PRICING
不要把价格写死在业务代码中。页面展示、报价和任务提交前校验应以 GET /pricing 的实时返回为准。
对应分辨率单价
视频费用=每秒单价 × durationSeconds
curl "https://new-api.gptfuny.com/api/v1/pricing"
模型、规格、费率、折扣和可售状态可能调整。产品未出现在实时价格中时,应视为暂不可售,不要自动降级到其他规格。
ERRORS
程序根据稳定的 HTTP 状态码和 code 分支;message 仅用于展示和调试。
{
"code": "PAYMENT_REQUIRED",
"status": 402,
"message": "Your balance is too low to start this generation.",
"requestId": "req_s1383pvtrrae52fa"
}
requestId 或 taskIdBAD_REQUEST修正字段、格式、资源状态或效果类型。
UNAUTHORIZED检查 Bearer Token 是否缺失、过期或错误。
PAYMENT_REQUIRED余额不足;充值后再提交。
NOT_FOUND资源不存在,或不属于当前账户。
CONFLICT状态冲突或幂等键复用方式错误。
PAYLOAD_TOO_LARGE缩短 JSON;图片必须走上传流程。
TOO_MANY_REQUESTS等待 Retry-After,并降低并发。
SERVICE_UNAVAILABLE规格暂不可售或上游暂不可用。
SDK EXAMPLES
以下示例演示创建文生图任务并轮询。生产代码还应加入持久化队列、熔断、指标和业务级超时。
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")
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));
}
}
MEDIA SHOWCASE
成人图片与视频案例置于主要展示区。实际结果受输入素材、效果、模型版本和参数影响。
普通礼服、人物换装与轻量动态效果作为补充案例展示。
PRODUCTION
将同步 HTTP 请求与耗时生成解耦。业务服务负责接单,后台 Worker 负责提交、轮询和结果持久化。
FAQ
媒体生成耗时不稳定,因此接口采用异步任务模型。提交后保存 taskId,再轮询任务接口,能避免长连接超时并支持服务重启后恢复。
可以使用完全相同的请求体和相同的 Idempotency-Key 重试。不要修改参数后继续复用旧键。
输入图片应先走上传流程,获得状态为 READY 的 assetId。这样平台可验证格式、尺寸和文件归属。
结果地址通常是临时签名 URL。长期使用时应在任务成功后下载并复制到自己的对象存储。
分别调用 GET /effects 和 GET /pricing。模型能力、效果目录和价格可能调整,以实时接口及控制台展示为准。
至少应设置成年人年龄门槛,确认输入素材和肖像授权,按运营地区执行内容规则,并建立审核、举报、删除和申诉流程。API Key 只应保存在服务端。