火星电波 Labnana OpenAPI 接口文档 (1.0.0)

Download OpenAPI specification:

Marswave Team: support@marswave.ai License: Apache 2.0

此文档是火星电波 Labnana OpenAPI 接口文档。

完整接入指南：https://labnana.com/docs/openapi/guide

Authentication

使用 APIKey 认证, 格式为 Authorization: Bearer <your api key>

获取 API Key：访问 API Keys 设置页面

user

用户相关接口

获取用户订阅详情

获取当前用户的订阅状态以及积分使用情况。

Authorizations:

ApiKeyAuth

Responses

Response samples

200

Content type

application/json

{"code": 0,
"message": "",
"data": {"subscriptionStartedAt": 1718230400000,
"subscriptionExpiresAt": 1720918800000,
"usageAvailableMonthlyCredits": 80,
"usageTotalMonthlyCredits": 100,
"usageAvailablePermanentCredits": 50,
"usageTotalPermanentCredits": 50,
"usageAvailableLimitedTimeCredits": 20,
"totalAvailableCredits": 150,
"freeUsages": {"image:gpt-image-2:generation": {"remaining": 3,
"unlimited": false,
"resourceType": "image",
"resourceKey": "gpt-image-2",
"unit": "generation"
}
},
"resetAt": 1721005200000,
"platform": "web",
"renewStatus": true,
"paidStatus": true,
"subscriptionPlan": {"name": "pro",
"duration": "monthly",
"platform": "web"
}
}
}

images

图片生成接口

预估图片生成所需积分

根据 provider、模型、尺寸、宽高比、质量等参数预估生成图片所需的积分。

同步返回，不实际生成图片、不扣除积分
请求参数与 POST /openapi/v1/images/generation 一致

Authorizations:

ApiKeyAuth

Request Body schema: application/json
required

provider required	string Enum: "google" "openai" "alibaba" 图片模型提供商。实际模型通道路由由 model 字段决定；gpt-image-2 请求会由服务记录为 openai，Wan2.7 请求会由服务记录为 alibaba。
model	string Default: "gemini-3-pro-image" Enum: "gemini-3-pro-image" "gemini-3.1-flash-image" "gpt-image-2" "wan2.7-image-pro" "wan2.7-image" 图片生成模型。gpt-image-2 使用 OpenDev/OpenAI 通道，最多支持 4 张参考图；wan2.7-image / wan2.7-image-pro 使用 Alibaba DashScope 通道，最多支持 9 张参考图。
prompt required	string 图片生成提示词
	Array of objects or objects (ReferenceImage) <= 14 items 参考图片，用于引导生成。Gemini 最多 14 张；gpt-image-2 最多 4 张；Wan2.7 最多 9 张。inlineData 适合小图，完整 JSON 请求体公开上限为 20 MB；更大的参考图请使用 fileData.fileUri。Gemini 推荐使用 gs://bucket/object；已上传到 ListenHub/Labnana GCS bucket 的 storage.googleapis.com、assets.listenhub.ai、staging-assets.listenhub.ai、cdn.labnana.com、cdn.listenhub.ai URL 会在服务端尽量转换为 gs:// 后发送给 Vertex。外部 HTTPS 签章 URL 会保持原样发送给 Vertex；Wan2.7 会按请求 URL 或 inlineData 交给 DashScope 处理。
	object 图片生成配置（可选）

Responses

Request samples

Payload

Content type

application/json

{"provider": "google",
"model": "gpt-image-2",
"prompt": "A beautiful sunset over the sea.",
"imageConfig": {"imageSize": "2K",
"aspectRatio": "16:9"
}
}

Response samples

200
400

Content type

application/json

{"code": 0,
"message": "string",
"data": {"model": "string",
"imageSize": "string",
"aspectRatio": "string",
"quality": "string",
"pixels": {"width": 0,
"height": 0,
"size": "string"
},
"credits": 0,
"canGenerate": true,
"requiresSubscription": true,
"pricing": { },
"warnings": ["string"
]
}
}

生成图片

特点：

同步返回：调用后立即返回 base64 编码的图片数据
模型选择：支持 Gemini、GPT-Image-2、Wan2.7 Image 模型
参考图片：Gemini 最多支持 14 张参考图，GPT-Image-2 最多支持 4 张参考图，Wan2.7 最多支持 9 张参考图
多种尺寸：Gemini、GPT-Image-2、Wan2.7 Image Pro 支持 1K、2K、4K；Wan2.7 Image 支持 1K、2K
灵活比例：支持多种宽高比
响应兼容：GPT-Image-2 与 Wan2.7 会转换成与 Gemini 相同的 candidates/inlineData 结构

积分计算：

Gemini 根据图片尺寸消耗不同积分
- 1K - 15 积分
- 2K - 15 积分
- 4K - 30 积分
GPT-Image-2 根据图片尺寸消耗不同积分
- 1K - 4 积分
- 2K - 6 积分
- 4K - 10 积分
Wan2.7 Image Pro 根据图片尺寸消耗不同积分
- 1K - 6 积分
- 2K - 8 积分
- 4K - 12 积分（仅文生图支持；带参考图时不支持 4K）
Wan2.7 Image 根据图片尺寸消耗不同积分
- 1K - 4 积分
- 2K - 6 积分
- 不支持 4K

Authorizations:

ApiKeyAuth

Request Body schema: application/json
required

provider required	string Enum: "google" "openai" "alibaba" 图片模型提供商。实际模型通道路由由 model 字段决定；gpt-image-2 请求会由服务记录为 openai，Wan2.7 请求会由服务记录为 alibaba。
model	string Default: "gemini-3-pro-image" Enum: "gemini-3-pro-image" "gemini-3.1-flash-image" "gpt-image-2" "wan2.7-image-pro" "wan2.7-image" 图片生成模型。gpt-image-2 使用 OpenDev/OpenAI 通道，最多支持 4 张参考图；wan2.7-image / wan2.7-image-pro 使用 Alibaba DashScope 通道，最多支持 9 张参考图。
prompt required	string 图片生成提示词
	Array of objects or objects (ReferenceImage) <= 14 items 参考图片，用于引导生成。Gemini 最多 14 张；gpt-image-2 最多 4 张；Wan2.7 最多 9 张。inlineData 适合小图，完整 JSON 请求体公开上限为 20 MB；更大的参考图请使用 fileData.fileUri。Gemini 推荐使用 gs://bucket/object；已上传到 ListenHub/Labnana GCS bucket 的 storage.googleapis.com、assets.listenhub.ai、staging-assets.listenhub.ai、cdn.labnana.com、cdn.listenhub.ai URL 会在服务端尽量转换为 gs:// 后发送给 Vertex。外部 HTTPS 签章 URL 会保持原样发送给 Vertex；Wan2.7 会按请求 URL 或 inlineData 交给 DashScope 处理。
	object 图片生成配置（可选）

Responses

Request samples

Payload

Content type

application/json

{"provider": "google",
"model": "gemini-3-pro-image",
"prompt": "Change the hairstyle of the person in the picture.",
"referenceImages": [{"fileData": {"fileUri": "gs://listenhub-labs/banana/reference-images/user-id/reference1.png",
"mimeType": "image/png"
}
}
],
"imageConfig": {"imageSize": "2K",
"aspectRatio": "1:1"
}
}

Response samples

200
400

Content type

application/json

{"candidates": [{"content": {"role": "model",
"parts": [{"inlineData": {"mimeType": "image/jpeg",
"data": "<BASE64_IMAGE_DATA>"
},
"thoughtSignature": "string"
}
]
},
"finishReason": "STOP",
"safetyRatings": [{"category": "HARM_CATEGORY_HARASSMENT",
"probability": "NEGLIGIBLE"
}
]
}
],
"promptFeedback": {"safetyRatings": null
},
"usageMetadata": {"promptTokenCount": 100,
"candidatesTokenCount": 1290,
"totalTokenCount": 1390
},
"modelVersion": "gemini-3-pro-image",
"responseId": "string"
}

异步生成图片

创建图片生成任务并立即返回 taskId。客户端可轮询 GET /openapi/v1/images/generation/tasks/{taskId} 查询状态。

任务成功后，详情中的 images 为公开图片链接数组，域名为配置的 ListenHub 资产域名，可直接下载图片文件。

Authorizations:

ApiKeyAuth

Request Body schema: application/json
required

provider required	string Enum: "google" "openai" "alibaba" 图片模型提供商。实际模型通道路由由 model 字段决定；gpt-image-2 请求会由服务记录为 openai，Wan2.7 请求会由服务记录为 alibaba。
model	string Default: "gemini-3-pro-image" Enum: "gemini-3-pro-image" "gemini-3.1-flash-image" "gpt-image-2" "wan2.7-image-pro" "wan2.7-image" 图片生成模型。gpt-image-2 使用 OpenDev/OpenAI 通道，最多支持 4 张参考图；wan2.7-image / wan2.7-image-pro 使用 Alibaba DashScope 通道，最多支持 9 张参考图。
prompt required	string 图片生成提示词
	Array of objects or objects (ReferenceImage) <= 14 items 参考图片，用于引导生成。Gemini 最多 14 张；gpt-image-2 最多 4 张；Wan2.7 最多 9 张。inlineData 适合小图，完整 JSON 请求体公开上限为 20 MB；更大的参考图请使用 fileData.fileUri。Gemini 推荐使用 gs://bucket/object；已上传到 ListenHub/Labnana GCS bucket 的 storage.googleapis.com、assets.listenhub.ai、staging-assets.listenhub.ai、cdn.labnana.com、cdn.listenhub.ai URL 会在服务端尽量转换为 gs:// 后发送给 Vertex。外部 HTTPS 签章 URL 会保持原样发送给 Vertex；Wan2.7 会按请求 URL 或 inlineData 交给 DashScope 处理。
	object 图片生成配置（可选）

Responses

Request samples

Payload

Content type

application/json

{"provider": "google",
"model": "wan2.7-image-pro",
"prompt": "Change the hairstyle of the person in the picture.",
"referenceImages": [{"fileData": {"fileUri": "https://storage.googleapis.com/bucket/image.png",
"mimeType": "image/png"
},
"inlineData": {"data": "string",
"mimeType": "image/png"
}
}
],
"imageConfig": {"imageSize": "2K",
"aspectRatio": "1:1"
}
}

Response samples

202
400

Content type

application/json

{"code": 0,
"message": "",
"data": {"taskId": "665e3b2d9a7d4a0012c34567",
"status": "pending"
}
}

获取图片生成任务列表

按创建时间倒序返回当前 API Key 用户的图片生成任务。

Authorizations:

ApiKeyAuth

query Parameters

page	integer >= 1 Default: 1
pageSize	integer [ 1 .. 100 ] Default: 20
status	string Enum: "pending" "generating" "success" "fail"

Responses

Response samples

200

Content type

application/json

{"code": 0,
"message": "string",
"data": {"items": [{"taskId": "string",
"status": "pending",
"images": [{"url": "http://example.com",
"mimeType": "string"
}
],
"failMsg": "string",
"createdAt": 0,
"completedAt": 0
}
],
"page": 0,
"pageSize": 0,
"total": 0
}
}

获取图片生成任务详情

查询图片生成任务状态。任务成功后通过 images 数组获取公开图片链接。

Authorizations:

ApiKeyAuth

path Parameters

taskId

required

string

Responses

Response samples

200
400

Content type

application/json

{"code": 0,
"message": "",
"data": {"taskId": "665e3b2d9a7d4a0012c34567",
"status": "success",
"images": [{"url": "https://assets.listenhub.ai/listenhub-public-prod/openapi/images/.../0.png",
"mimeType": "image/png"
}
],
"createdAt": 1718230400000,
"completedAt": 1718230460000
}
}

📘 错误码说明

系统级错误码

错误码	说明	处理建议
21007	API Key 无效	检查 API Key 是否正确配置
26004	积分不足	检查账户积分余额，升级套餐或联系客服
29003	参数错误	验证请求参数格式和必填项
29998	请求过于频繁	实现指数退避重试，建议间隔 20-30 秒

错误响应格式

当 HTTP 响应状态码为 400 时，将返回错误信息，并通过 code 字段区分不同错误类型。

{
  "code": 21007,
  "message": "Invalid API Key or malformed Authorization header"
}

火星电波 Labnana OpenAPI 接口文档 (1.0.0)

Authentication

user

获取用户订阅详情

Authorizations:

Responses

Response samples

images

预估图片生成所需积分

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

生成图片

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

异步生成图片

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

获取图片生成任务列表

Authorizations:

query Parameters

Responses

Response samples

获取图片生成任务详情

Authorizations:

path Parameters

Responses

Response samples

📘 错误码说明

系统级错误码

错误响应格式

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required