欢迎使用 4o Image API
4o Image API 基于强大的 GPT-4o 模型,为您提供高质量的AI图像生成服务。无论是文本转图像、图像编辑还是图像变体生成,我们的API都能满足您的创作需求。
身份验证
所有 API 请求都需要使用 Bearer 令牌进行身份验证。请从 API 密钥管理页面 获取您的 API 密钥。
请妥善保管您的 API 密钥,切勿公开分享。如果怀疑密钥泄露,请立即重置。
API 基础 URL
身份验证请求头
Authorization: Bearer YOUR_API_KEY
快速开始指南
第一步:生成您的第一个图像
从一个简单的文本转图像生成请求开始:
async function generateImage() {
try {
const response = await fetch('https://api.kie.ai/api/v1/gpt4o-image/generate', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
prompt: '一幅宁静的山景,日落时湖泊倒映着橙色天空,风格写实',
size: '1:1',
nVariants: 1
})
});
const data = await response.json();
if (response.ok && data.code === 200) {
console.log('任务已提交:', data);
console.log('任务ID:', data.data.taskId);
return data.data.taskId;
} else {
console.error('请求失败:', data.msg || '未知错误');
return null;
}
} catch (error) {
console.error('错误:', error.message);
return null;
}
}
generateImage();
第二步:检查任务状态
使用返回的任务ID检查生成状态:
async function checkTaskStatus(taskId) {
try {
const response = await fetch(`https://api.kie.ai/api/v1/gpt4o-image/record-info?taskId=${taskId}`, {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const result = await response.json();
if (response.ok && result.code === 200) {
const taskData = result.data;
switch (taskData.status) {
case 'SUCCESS':
console.log('图像生成成功!');
console.log('图像URLs:', taskData.response.result_urls);
return taskData;
case 'GENERATING':
const progress = taskData.progress ? `${(parseFloat(taskData.progress) * 100).toFixed(0)}%` : '进行中';
console.log(`正在生成中... 进度: ${progress}`);
return taskData;
case 'CREATE_TASK_FAILED':
console.log('创建任务失败');
if (taskData.errorMessage) {
console.error('错误信息:', taskData.errorMessage);
}
return taskData;
case 'GENERATE_FAILED':
console.log('图像生成失败');
if (taskData.errorMessage) {
console.error('错误信息:', taskData.errorMessage);
}
return taskData;
default:
console.log('未知状态:', taskData.status);
if (taskData.errorMessage) {
console.error('错误信息:', taskData.errorMessage);
}
return taskData;
}
} else {
console.error('查询失败:', result.msg || '未知错误');
return null;
}
} catch (error) {
console.error('查询状态失败:', error.message);
return null;
}
}
响应格式
成功响应:
{
"code": 200,
"msg": "success",
"data": {
"taskId": "task_4o_abc123"
}
}
任务状态响应(生成中):
{
"code": 200,
"msg": "success",
"data": {
"taskId": "d231a99a9a9f1dd8f895be1b97be8065",
"paramJson": "{\"callBackUrl\":\"playground\",\"enableFallback\":true}",
"completeTime": null,
"response": null,
"successFlag": 0,
"status": "GENERATING",
"errorCode": null,
"errorMessage": null,
"createTime": 1755572609000,
"progress": "0.48"
}
}
任务状态响应(成功):
{
"code": 200,
"msg": "success",
"data": {
"taskId": "task_4o_abc123",
"status": "SUCCESS",
"response": {
"result_urls": [
"https://example.com/generated-image.png"
]
},
"successFlag": 1,
"progress": "1.00",
"completeTime": 1755572669000,
"createTime": 1755572609000,
"errorCode": null,
"errorMessage": null
}
}
任务状态响应(失败):
{
"code": 200,
"msg": "success",
"data": {
"taskId": "task_4o_abc123",
"status": "GENERATE_FAILED",
"response": null,
"successFlag": 2,
"progress": "0.00",
"completeTime": 1755572669000,
"createTime": 1755572609000,
"errorCode": 400,
"errorMessage": "图像内容违反了内容政策,请修改提示词后重试"
}
}
核心功能
文本转图像
从文本描述生成高质量图像:
{
"prompt": "一只可爱的橙色小猫坐在彩虹上,卡通风格,明亮的色彩",
"size": "1:1",
"nVariants": 2,
"isEnhance": false
}
图像编辑
使用蒙版和提示词编辑现有图像:
{
"filesUrl": ["https://example.com/original-image.jpg"],
"maskUrl": "https://example.com/mask-image.png",
"prompt": "将天空替换成星空夜景",
"size": "3:2"
}
图像变体
基于输入图像生成创意变体:
{
"filesUrl": ["https://example.com/base-image.jpg"],
"prompt": "保持主要元素,改变为水彩画风格",
"size": "2:3",
"nVariants": 4
}
图像尺寸支持
支持三种标准图像比例:
关键参数
图像生成的文本描述。提供详细、具体的描述以获得更好的结果。提示词技巧:
- 描述主要对象和场景
- 指定艺术风格(如”写实”、“卡通”、“水彩”)
- 添加色彩和光线描述
- 包含情绪和氛围要素
图像尺寸比例,必选参数:
1:1 - 方形
3:2 - 横向
2:3 - 纵向
输入图像URL列表,最多支持5张图片。支持格式:.jpg、.jpeg、.png、.webp、.jfif
蒙版图像URL,用于指定需要编辑的区域。黑色区域将被修改,白色区域保持不变。
生成图像的变体数量。可选值:1、2 或 4。默认为 1。
提示词增强选项。对于生成3D图像等特定场景,启用可获得更精细效果。默认为 false。
启用托底机制。当主模型不可用时自动切换到备用模型。默认为 false。
完整工作流程示例
以下是一个完整的图像生成和编辑示例:
class FourOImageAPI {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseUrl = 'https://api.kie.ai/api/v1/gpt4o-image';
}
async generateImage(options) {
const response = await fetch(`${this.baseUrl}/generate`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(options)
});
const result = await response.json();
if (!response.ok || result.code !== 200) {
throw new Error(`生成失败: ${result.msg || '未知错误'}`);
}
return result.data.taskId;
}
async waitForCompletion(taskId, maxWaitTime = 300000) { // 最长等待5分钟
const startTime = Date.now();
while (Date.now() - startTime < maxWaitTime) {
const status = await this.getTaskStatus(taskId);
switch (status.status) {
case 'SUCCESS':
console.log('图像生成成功!');
return status.response;
case 'GENERATING':
const progress = status.progress ? `${(parseFloat(status.progress) * 100).toFixed(0)}%` : '进行中';
console.log(`正在生成中... 进度: ${progress}`);
break;
case 'CREATE_TASK_FAILED':
const createError = status.errorMessage || '创建任务失败';
console.error('错误信息:', createError);
throw new Error(createError);
case 'GENERATE_FAILED':
const generateError = status.errorMessage || '图像生成失败';
console.error('错误信息:', generateError);
throw new Error(generateError);
default:
console.log('未知状态:', status.status);
if (status.errorMessage) {
console.error('错误信息:', status.errorMessage);
}
break;
}
// 等待10秒后再次检查
await new Promise(resolve => setTimeout(resolve, 10000));
}
throw new Error('生成超时');
}
async getTaskStatus(taskId) {
const response = await fetch(`${this.baseUrl}/record-info?taskId=${taskId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${this.apiKey}`
}
});
const result = await response.json();
if (!response.ok || result.code !== 200) {
throw new Error(`查询状态失败: ${result.msg || '未知错误'}`);
}
return result.data;
}
async getDownloadUrl(imageUrl) {
const response = await fetch(`${this.baseUrl}/download-url`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ imageUrl })
});
const result = await response.json();
if (!response.ok || result.code !== 200) {
throw new Error(`获取下载URL失败: ${result.msg || '未知错误'}`);
}
return result.data.downloadUrl;
}
}
// 使用示例
async function main() {
const api = new FourOImageAPI('YOUR_API_KEY');
try {
// 文本转图像生成
console.log('开始生成图像...');
const taskId = await api.generateImage({
prompt: '一个未来主义的城市景观,有飞行汽车和霓虹灯,赛博朋克风格',
size: '16:9',
nVariants: 2,
isEnhance: true,
enableFallback: true
});
// 等待完成
console.log(`任务ID: ${taskId}。等待完成...`);
const result = await api.waitForCompletion(taskId);
console.log('图像生成成功!');
result.result_urls.forEach((url, index) => {
console.log(`图像 ${index + 1}: ${url}`);
});
// 获取下载URL
const downloadUrl = await api.getDownloadUrl(result.result_urls[0]);
console.log('下载URL:', downloadUrl);
// 图像编辑示例
console.log('\n开始图像编辑...');
const editTaskId = await api.generateImage({
filesUrl: [result.result_urls[0]],
prompt: '在天空中添加美丽的彩虹',
size: '3:2'
});
const editResult = await api.waitForCompletion(editTaskId);
console.log('图像编辑成功!');
console.log('编辑后图像:', editResult.result_urls[0]);
} catch (error) {
console.error('错误:', error.message);
}
}
main();
高级功能
蒙版编辑
使用蒙版进行精确的图像编辑:
const editTaskId = await api.generateImage({
filesUrl: ['https://example.com/original.jpg'],
maskUrl: 'https://example.com/mask.png',
prompt: '将蒙版区域替换为美丽的花园',
size: '3:2'
});
蒙版图像中的黑色区域将被编辑,白色区域保持不变。蒙版必须与原图尺寸一致。
托底机制
启用托底机制确保服务可靠性:
const taskId = await api.generateImage({
prompt: '艺术概念设计',
size: '1:1',
enableFallback: true,
fallbackModel: 'FLUX_MAX' // 或 'GPT_IMAGE_1'
});
使用回调
设置webhook回调以获得自动通知:
const taskId = await api.generateImage({
prompt: '数字艺术作品',
size: '1:1',
callBackUrl: 'https://your-server.com/4o-callback'
});
// 您的回调端点将接收:
app.post('/4o-callback', (req, res) => {
const { code, data } = req.body;
if (code === 200) {
console.log('图像准备就绪:', data.info.result_urls);
} else {
console.log('生成失败:', req.body.msg);
}
res.status(200).json({ status: 'received' });
});
了解更多关于回调
设置webhook回调以在图像准备就绪时接收自动通知。
任务状态说明
任务正在处理中,请等待。可通过 progress 字段查看生成进度(0.0-1.0)
图像生成任务成功完成,可获取生成的图像。successFlag 为 1
任务创建失败,请检查参数或联系技术支持。错误详情可查看 errorMessage 字段。successFlag 为 2
图像生成过程失败,可能由于内容违规、资源不足等原因。错误详情可查看 errorMessage 字段。successFlag 为 2
响应字段说明
生成进度,范围从 “0.00” 到 “1.00”,仅在 GENERATING 状态时有意义
最佳实践
- 使用详细、具体的描述
- 包含风格和技法描述(如”写实”、“印象派”、“数字艺术”)
- 指定色彩、光线和构图要求
- 避免过于复杂或矛盾的描述
- 选择合适的尺寸比例适配您的用途
- 对于复杂场景考虑启用提示词增强
- 使用高质量的输入图像进行编辑
- 确保蒙版图像准确标记编辑区域
- 使用回调而不是频繁轮询
- 启用托底机制确保服务可靠性
- 合理设置变体数量平衡质量和成本
- 及时下载图像,避免14天后过期
- 实施适当的重试逻辑,特别是对于网络相关错误
- 监控所有任务状态,包括 GENERATING、SUCCESS、CREATE_TASK_FAILED、GENERATE_FAILED
- 当任务失败时,始终检查并记录 errorMessage 字段的内容
- 验证输入图像的可访问性和格式兼容性
- 对于 CREATE_TASK_FAILED,检查参数是否符合API要求
- 对于 GENERATE_FAILED,检查是否存在内容违规或技术问题
- 记录完整的错误信息用于调试和问题排查
图像存储和下载
生成的图像存储 14天 后自动删除。下载URL有效期为 20分钟。
- 图像URL在生成后14天内保持可访问
- 使用下载URL API解决跨域下载问题
- 下载URL有效期为20分钟
- 建议及时下载并本地存储重要图像
下一步
准备开始创建令人惊叹的AI图像了吗?获取您的API密钥,立即开始创作!