接入指南

适用对象：开发者、产品经理、技术架构师

文档目的：提供 Labnana 图片生成服务的接入流程、核心概念、API 使用与错误处理

技术支持：support@marswave.ai

基础信息

Base URL

https://api.labnana.com

认证与安全

要进行身份验证，您需要添加一个 Authorization 请求头，请求头内容为 Bearer lh_xxxxxxxxx，其中 lh_xxxxxxxxx 是您的 API 密钥 。

Authorization: Bearer ls_xxxxxxxxx

快速开始（5分钟上手）

前置条件

获取 API Key

1. 访问 API Keys 设置页面
2. 点击"创建 API Key"
3. 复制并妥善保管 API Key

安全建议：

• 始终使用 HTTPS 协议
• 不要在前端代码中暴露 API Key
• 不要将 API Key 提交到版本控制系统

第一次 API 调用

获取订阅信息

curl -X GET "https://api.labnana.com/openapi/v1/user/subscription" \
  -H "Authorization: Bearer $YOUR_API_KEY"

成功响应示例：

{
  "code": 0,
  "message": "",
  "data": {
    "subscriptionStartedAt": 1735660800000,
    "subscriptionExpiresAt": 1767196800000,
    "usageAvailableMonthlyCredits": 500,
    "usageTotalMonthlyCredits": 1000,
    "usageAvailablePermanentCredits": 300,
    "usageTotalPermanentCredits": 500,
    "usageAvailableLimitedTimeCredits": 200,
    "totalAvailableCredits": 1000,
    "resetAt": 1735660800000,
    "platform": "web",
    "renewStatus": false,
    "paidStatus": true,
    "subscriptionPlan": {
      "name": "pro",
      "duration": "monthly",
      "platform": "web"
    },
    "freeUsages": {
      "image:gemini-3-pro-image-relax-1k-2k:generation": {
        "remaining": 2,
        "resourceType": "image",
        "resourceKey": "gemini-3-pro-image-relax-1k-2k",
        "unit": "generation"
      }
    }
  }
}

freeUsages 字段返回账户当前的免费用量余额（FREE_USAGE）。API Key 调用与网页端、App 端共用同一份账户级 FREE_USAGE 余额，按对应模型的 resourceKey 计量、remaining 表示剩余可用次数。OpenAPI 图片生成在有匹配的免费额度时会优先消耗 freeUsages，不扣减积分。

The freeUsages field reports the account's current FREE_USAGE balance. API key calls draw down the same account-level FREE_USAGE balance as the website and app — there is no separate API quota. Each entry is keyed by model resourceKey and remaining is the number of free generations left. When a matching free quota exists, image generation consumes freeUsages first and does not deduct credits.

免费额度与计费规则（FREE_USAGE）

API Key 调用消耗的是账户级 FREE_USAGE 余额，可通过 GET /openapi/v1/user/subscription 的 freeUsages 字段查询；该余额与 Labnana 网页端、ListenHub App 完全共用。

• 可获取免费额度的方式：注册、邀请新用户、每日签到累计签到，都可领取 NanoBanana Pro（gemini-3-pro-image-relax-1k-2k）免费额度。新注册用户不再额外发放 Wan 2.7 或 GPT-Image-2 体验额度；如果账户中已经存在历史 Wan 2.7 / GPT-Image-2 免费余额，仍可按 1K / 2K 规则继续使用。
• 尺寸限制：NanoBanana Pro 免费额度仅适用于 1K / 2K，不含 4K；4K 生成始终按积分计费。
• 纯免费用户（从未付费）：消耗 NanoBanana Pro 免费额度时走 PT-only 的低优先级免费通道，忙时或超时会返回 retryable 的「忙时」错误（HTTP 400，业务错误码），此时不扣积分、不消耗免费额度，稍后重试即可；不会回退到按量付费或共享算力。
• 付费 / 充值用户：拥有有效订阅、充值或积分包的账户，消耗同一份免费额度时享受与正常付费生成完全一致的体验——满优先级、正常容量与回退，免费额度只改变计费（不扣积分），不会被免费通道的「忙时」限制阻塞。
• 免费额度可持续领取的含义：NanoBanana Pro 免费额度可以持续通过注册、邀请、签到等方式不断领取，并不代表 OpenAPI 可以无限免费调用，也不代表不限并发或不限尺寸。免费额度用尽后，调用按正常积分计费。

Free usage & billing (FREE_USAGE). API key calls consume the same account-level FREE_USAGE balance exposed by GET /openapi/v1/user/subscription (freeUsages); this balance is shared with the Labnana website and the ListenHub app.

• Earning quota: users earn NanoBanana Pro (gemini-3-pro-image-relax-1k-2k) free quota through registration, inviting new users, and a cumulative check-in streak. New sign-ups no longer receive extra Wan 2.7 or GPT-Image-2 trial quota; legacy Wan 2.7 / GPT-Image-2 balances, if already present, remain usable for 1K / 2K.
• Size limit: NanoBanana Pro free quota applies to 1K / 2K only, not 4K. 4K generation is always charged in credits.
• Pure-free users (never paid): when spending NanoBanana Pro free quota they run on a PT-only, lowest-priority free lane. During busy periods or on timeout the API returns a retryable busy error (HTTP 400 with a business error code); no credits are charged and no free quota is consumed, so the call can be retried later. It never falls back to pay-as-you-go or shared capacity.
• Paid / charged users: accounts with an active subscription, a recharge, or a credit-pack purchase get the normal paid generation experience when spending the same free quota — full priority, normal capacity and fallback. The free quota only changes billing (no credit deduction); they are not placed on the throttled free lane.
• What refillable free quota means: NanoBanana Pro free quota can keep refilling through eligible actions. It does not mean unlimited free OpenAPI calls, unlimited concurrency, or free 4K. Once the free quota is exhausted, calls are charged normally in credits.

618 限时活动（订阅月度积分 +50%）

2026-06-18 至 2026-06-25（共一周，北京时间，结束日不含）期间，有效的 Pro / Max 订阅用户额外获得 50% 月度积分。

• 月付、年付 Pro / Max 都参与；Max 按 Max 自身月度积分额外 +50%。
• 加赠的是正常月度积分，随当前会员月到期重置，不是 NanoBanana Pro 免费额度（FREE_USAGE），也不是永久积分。
• 这是为期一周的限时活动，不会改变订阅计划的长期权益，年付用户也不会一次性获得整年的加赠。

618 campaign (subscription monthly credits +50%). From 2026-06-18 to 2026-06-25 (one week, Asia/Shanghai, end-exclusive), active Pro / Max subscribers receive an extra +50% monthly credits.

• Both monthly and annual Pro / Max billing participate; Max gets +50% based on Max's own monthly entitlement.
• The bonus is ordinary monthly credit value that resets with the current membership month. It is not NanoBanana Pro FREE_USAGE and not permanent credit.
• It is a one-week promotion that does not change the plan's permanent entitlement, and annual subscribers do not receive an upfront annual lump sum.

API 使用示例

完整文档

Labnana OpenAPI 文档

图片生成

POST /openapi/v1/images/generation

特点

• 同步返回：调用后立即返回 base64 编码的图片数据
• 参考图片：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
• 灵活比例：支持多种宽高比
• 多模型：支持 Gemini 系列、GPT-Image-2 和 Wan2.7 Image

请求参数

imageConfig 字段说明

支持的宽高比

GPT-Image-2 支持不传 aspectRatio，此时模型会根据提示词自动选择最合适的画面比例。

Wan2.7 支持 1:1、16:9、9:16、4:3、3:4。传入其他比例会返回参数错误，不会静默退化成正方形。

积分消耗

gemini-3-pro-image（默认）

• 1K - 15 积分
• 2K - 15 积分
• 4K - 30 积分

gemini-3.1-flash-image

• 1K - 10 积分
• 2K - 10 积分
• 4K - 20 积分

GPT-Image-2（gpt-image-2）

• 1K（标清）- 4 积分
• 2K（高清）- 6 积分
• 4K（超高清）- 10 积分

Wan2.7 Image Pro（wan2.7-image-pro）

• 1K - 6 积分
• 2K - 8 积分
• 4K - 12 积分（仅文生图支持；带参考图时不支持 4K）

Wan2.7 Image（wan2.7-image）

• 1K - 4 积分
• 2K - 6 积分
• 不支持 4K

1K / 2K 可使用账户匹配模型的免费额度（FREE_USAGE）抵扣，免费额度需通过注册、邀请、签到等方式领取，余额见上文免费额度与计费规则；4K 始终按积分计费。

1K / 2K can be covered by the account's earned FREE_USAGE balance (see Free usage & billing); 4K is always charged in credits.

使用示例

curl -X POST "https://api.labnana.com/openapi/v1/images/generation" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $YOUR_API_KEY" \
  --data '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "将图片背景改为内蒙古大草原",
    "referenceImages": [
      {
        "fileData": {
          "fileUri": "https://cdn.labnana.com/listenhub-labs-public/banana/generated/680b382171fdab410a560406/695a2da0f5dc9b3afcdb2c47.png",
          "mimeType": "image/png"
        }
      }
    ],
    "imageConfig": {
      "imageSize": "4K",
      "aspectRatio": "16:9"
    }
  }'

import base64
import requests


def main():
    base_url = "https://api.labnana.com/openapi/v1/images/generation"
    headers = {
        "Content-Type": "application/json",
        "Authorization": "Bearer $YOUR_API_KEY",
    }
    payload = {
        "provider": "google",
        "model": "gemini-3-pro-image",
        "prompt": "将图片背景改为内蒙古大草原",
        "referenceImages": [
            {
                "fileData": {
                    "fileUri": "https://cdn.labnana.com/listenhub-labs-public/banana/generated/680b382171fdab410a560406/695a2da0f5dc9b3afcdb2c47.png",
                    "mimeType": "image/png",
                }
            }
        ],
        "imageConfig": {
            "imageSize": "4K",
            "aspectRatio": "16:9",
        },
    }
    response = requests.post(base_url, headers=headers, json=payload)
    response.raise_for_status()

    response_data = response.json()
    candidates = response_data.get("candidates", [])
    parts = candidates[0]["content"]["parts"]
    image_data = None
    mime_type = None

    for part in parts:
        if "inlineData" in part:
            image_data = part["inlineData"]["data"]
            mime_type = part["inlineData"]["mimeType"]
            break

    extension = None
    if mime_type and "/" in mime_type:
        extension = mime_type.split("/")[-1]

    filename = f"image.{extension}"
    image_bytes = base64.b64decode(image_data)
    with open(filename, "wb") as output:
        output.write(image_bytes)

    print(f"图片已保存到 {filename}")


if __name__ == "__main__":
    main()

const fs = require('fs')

async function main() {
  const baseUrl = 'https://api.labnana.com/openapi/v1/images/generation'
  const headers = {
    'Content-Type': 'application/json',
    Authorization: 'Bearer $YOUR_API_KEY',
  }
  const payload = {
    provider: 'google',
    model: 'gemini-3-pro-image',
    prompt: '将图片背景改为内蒙古大草原',
    referenceImages: [
      {
        fileData: {
          fileUri:
            'https://cdn.labnana.com/listenhub-labs-public/banana/generated/680b382171fdab410a560406/695a2da0f5dc9b3afcdb2c47.png',
          mimeType: 'image/png',
        },
      },
    ],
    imageConfig: {
      imageSize: '4K',
      aspectRatio: '16:9',
    },
  }

  try {
    const response = await fetch(baseUrl, {
      method: 'POST',
      headers: headers,
      body: JSON.stringify(payload),
    })

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }

    const responseData = await response.json()
    const candidates = responseData.candidates || []
    const parts = candidates[0]?.content?.parts || []

    let imageData = null
    let mimeType = null

    for (const part of parts) {
      if (part.inlineData) {
        imageData = part.inlineData.data
        mimeType = part.inlineData.mimeType
        break
      }
    }

    let extension = null
    if (mimeType && mimeType.includes('/')) {
      extension = mimeType.split('/')[1]
    }

    const filename = `image.${extension}`
    const imageBuffer = Buffer.from(imageData, 'base64')
    fs.writeFileSync(filename, imageBuffer)

    console.log(`图片已保存到 ${filename}`)
  } catch (error) {
    console.error('错误:', error.message)
  }
}

main()

使用 GPT-Image-2 时，将 provider 改为 "openai"，model 改为 "gpt-image-2" 即可，其余参数和响应格式不变。GPT-Image-2 支持全部 8 种通用宽高比，也可以不传 aspectRatio 让模型自动选择。参考图最多 4 张。

curl -X POST "https://api.labnana.com/openapi/v1/images/generation" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $YOUR_API_KEY" \
  --data '{
    "provider": "openai",
    "model": "gpt-image-2",
    "prompt": "一只柴犬在雪地里奔跑，阳光洒在雪面上",
    "imageConfig": {
      "aspectRatio": "1:1"
    }
  }'

使用 Wan2.7 时，将 provider 改为 "alibaba"，model 改为 "wan2.7-image-pro" 或 "wan2.7-image"。Wan2.7 支持 1:1、16:9、9:16、4:3、3:4；最多 9 张参考图。wan2.7-image 不支持 4K，wan2.7-image-pro 只有文生图（不带参考图）支持 4K。

curl -X POST "https://api.labnana.com/openapi/v1/images/generation" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $YOUR_API_KEY" \
  --data '{
    "provider": "alibaba",
    "model": "wan2.7-image-pro",
    "prompt": "一张电影感产品海报，玻璃材质的未来派耳机漂浮在深色背景中",
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "16:9"
    }
  }'

响应示例

成功响应示例

可参考 Google 官方文档

{
  "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"
}

失败响应示例

失败响应通过 HTTP 400 状态码返回，响应体中包含 code 和 message 字段。

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

定价与限制

• 订阅计划以使用 OpenAPI
• 积分指南

技术支持

文档资源

• API 文档
• 积分指南
• 产品定价

问题反馈

• 技术支持邮箱：support@marswave.ai
• 请提供账户邮箱、API 请求完整日志、错误码和错误信息、预期行为与实际行为对比。