curl --request POST \
--url https://api.tokengongfang.com/v1/uploads/images \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/your/image.jpg'
import requests
# 上传图片
with open('image.jpg', 'rb') as f:
response = requests.post(
"https://api.tokengongfang.com/v1/uploads/images",
headers={
"Authorization": "Bearer <token>"
},
files={
"file": f
}
)
result = response.json()
image_url = result['url']
print(f"图片 URL: {image_url}")
# 使用上传的图片进行生成
response = requests.post(
"https://api.tokengongfang.com/v1/images/generations",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
},
json={
"model": "gemini-3-pro-image-preview",
"prompt": "基于这张图片创作变体",
"image_urls": [{"url": image_url}]
}
)
// 上传图片
const formData = new FormData();
formData.append('file', fileInput.files[0]);
const uploadResponse = await fetch('https://api.tokengongfang.com/v1/uploads/images', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>'
},
body: formData
});
const uploadResult = await uploadResponse.json();
const imageUrl = uploadResult.url;
console.log(`图片 URL: ${imageUrl}`);
// 使用上传的图片进行生成
const genResponse = await fetch('https://api.tokengongfang.com/v1/images/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gemini-3-pro-image-preview',
prompt: '基于这张图片创作变体',
image_urls: [{url: imageUrl}]
})
});
{
"url": "https://upload.apimart.ai/f/image/9990000123456-a1b2c3d4-photo.jpg",
"filename": "photo.jpg",
"content_type": "image/jpeg",
"bytes": 235680,
"created_at": 1743436800
}
{
"error": {
"message": "missing or invalid file field: http: no such file",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "unsupported image type: application/pdf, allowed: jpeg, png, gif, webp",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "file size 25165824 exceeds maximum 20971520 bytes",
"type": "invalid_request_error"
}
}
{
"error": {
"code": 429,
"message": "Rate limit exceeded. Please try again later",
"type": "rate_limit_error"
}
}
{
"error": {
"message": "failed to upload image",
"type": "server_error"
}
}
上传管理
上传图片
上传图片获取 URL,用于图像/视频生成接口
POST
/
v1
/
uploads
/
images
curl --request POST \
--url https://api.tokengongfang.com/v1/uploads/images \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/your/image.jpg'
import requests
# 上传图片
with open('image.jpg', 'rb') as f:
response = requests.post(
"https://api.tokengongfang.com/v1/uploads/images",
headers={
"Authorization": "Bearer <token>"
},
files={
"file": f
}
)
result = response.json()
image_url = result['url']
print(f"图片 URL: {image_url}")
# 使用上传的图片进行生成
response = requests.post(
"https://api.tokengongfang.com/v1/images/generations",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
},
json={
"model": "gemini-3-pro-image-preview",
"prompt": "基于这张图片创作变体",
"image_urls": [{"url": image_url}]
}
)
// 上传图片
const formData = new FormData();
formData.append('file', fileInput.files[0]);
const uploadResponse = await fetch('https://api.tokengongfang.com/v1/uploads/images', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>'
},
body: formData
});
const uploadResult = await uploadResponse.json();
const imageUrl = uploadResult.url;
console.log(`图片 URL: ${imageUrl}`);
// 使用上传的图片进行生成
const genResponse = await fetch('https://api.tokengongfang.com/v1/images/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gemini-3-pro-image-preview',
prompt: '基于这张图片创作变体',
image_urls: [{url: imageUrl}]
})
});
{
"url": "https://upload.apimart.ai/f/image/9990000123456-a1b2c3d4-photo.jpg",
"filename": "photo.jpg",
"content_type": "image/jpeg",
"bytes": 235680,
"created_at": 1743436800
}
{
"error": {
"message": "missing or invalid file field: http: no such file",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "unsupported image type: application/pdf, allowed: jpeg, png, gif, webp",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "file size 25165824 exceeds maximum 20971520 bytes",
"type": "invalid_request_error"
}
}
{
"error": {
"code": 429,
"message": "Rate limit exceeded. Please try again later",
"type": "rate_limit_error"
}
}
{
"error": {
"message": "failed to upload image",
"type": "server_error"
}
}
文档 Playground 不支持文件上传:请使用下方的 cURL、Python 或 JavaScript 代码示例进行测试。
重要变更: 为了更好的性能和成本控制,我们不再支持在生成接口中直接传入 base64 图片数据。请使用本接口上传图片,获取 URL 后再调用生成接口。
为什么需要先上传图片?
- 性能优化 - base64 编码会使数据膨胀 33%,先上传可显著减少请求体大小
- 复用图片 - 上传一次,URL 可多次使用,无需重复传输
使用流程
curl --request POST \
--url https://api.tokengongfang.com/v1/uploads/images \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/your/image.jpg'
import requests
# 上传图片
with open('image.jpg', 'rb') as f:
response = requests.post(
"https://api.tokengongfang.com/v1/uploads/images",
headers={
"Authorization": "Bearer <token>"
},
files={
"file": f
}
)
result = response.json()
image_url = result['url']
print(f"图片 URL: {image_url}")
# 使用上传的图片进行生成
response = requests.post(
"https://api.tokengongfang.com/v1/images/generations",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
},
json={
"model": "gemini-3-pro-image-preview",
"prompt": "基于这张图片创作变体",
"image_urls": [{"url": image_url}]
}
)
// 上传图片
const formData = new FormData();
formData.append('file', fileInput.files[0]);
const uploadResponse = await fetch('https://api.tokengongfang.com/v1/uploads/images', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>'
},
body: formData
});
const uploadResult = await uploadResponse.json();
const imageUrl = uploadResult.url;
console.log(`图片 URL: ${imageUrl}`);
// 使用上传的图片进行生成
const genResponse = await fetch('https://api.tokengongfang.com/v1/images/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gemini-3-pro-image-preview',
prompt: '基于这张图片创作变体',
image_urls: [{url: imageUrl}]
})
});
{
"url": "https://upload.apimart.ai/f/image/9990000123456-a1b2c3d4-photo.jpg",
"filename": "photo.jpg",
"content_type": "image/jpeg",
"bytes": 235680,
"created_at": 1743436800
}
{
"error": {
"message": "missing or invalid file field: http: no such file",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "unsupported image type: application/pdf, allowed: jpeg, png, gif, webp",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "file size 25165824 exceeds maximum 20971520 bytes",
"type": "invalid_request_error"
}
}
{
"error": {
"code": 429,
"message": "Rate limit exceeded. Please try again later",
"type": "rate_limit_error"
}
}
{
"error": {
"message": "failed to upload image",
"type": "server_error"
}
}
Authorizations
所有接口均需要使用Bearer Token进行认证获取 API Key:访问 API Key 管理页面 获取您的 API Key使用时在请求头中添加:
Authorization: Bearer YOUR_API_KEY
Body
图片文件支持格式:JPEG (.jpg, .jpeg)、PNG (.png)、WebP (.webp)、GIF (.gif)最大文件大小:20MB
Response
图片的公开访问 URL,可直接用于生成接口(72 小时有效)
原始文件名
检测到的 MIME 类型,如
image/jpeg文件大小(字节)
上传时间的 Unix 时间戳(秒)
完整示例:图生图工作流
Python
import requests
import time
API_KEY = "your-Apimart-key"
BASE_URL = "https://api.tokengongfang.com"
# 第一步:上传参考图片
def upload_image(file_path):
with open(file_path, 'rb') as f:
response = requests.post(
f"{BASE_URL}/v1/uploads/images",
headers={"Authorization": f"Bearer {API_KEY}"},
files={"file": f}
)
return response.json()['url']
# 第二步:创建生成任务
def create_generation(image_url, prompt):
response = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json={
"model": "gemini-3-pro-image-preview",
"prompt": prompt,
"image_urls": [{"url": image_url}],
"size": "16:9"
}
)
return response.json()['id']
# 第三步:轮询任务状态
def wait_for_result(task_id):
while True:
response = requests.get(
f"{BASE_URL}/v1/images/generations/{task_id}",
headers={"Authorization": f"Bearer {API_KEY}"}
)
result = response.json()
if result['status'] == 'completed':
return result['url']
elif result['status'] == 'failed':
raise Exception(f"生成失败: {result.get('fail_reason')}")
time.sleep(2)
# 执行工作流
image_url = upload_image("reference.jpg")
print(f"图片已上传: {image_url}")
task_id = create_generation(image_url, "将这张照片转换为吉卜力动画风格")
print(f"任务已创建: {task_id}")
result_url = wait_for_result(task_id)
print(f"生成完成: {result_url}")
⌘I