为确保技术标识和代码可直接复制，详细协议参考及代码示例保留英文。

REST API 让脚本、CLI 工具、Agent 和第三方应用能够通过 HTTPS 生成图片并读取账户用量。

基础 URL：

https://www.byheai.com

请在生产环境的 API 请求中使用此 URL。

身份验证

请在 Dashboard 中创建 API key：

登录 byheai。
打开 Dashboard > API keys。
创建一个 key，并在显示时保存完整密钥。完整密钥只会显示一次。

在每个请求中将 key 作为 Bearer token 发送：

curl https://www.byheai.com/api/v1/account \
  -H "Authorization: Bearer $GET_IMAGES_API_KEY"

默认情况下，API key 的速率限制为每分钟 60 次请求。超过限制时，API 会返回 429，并可能包含 Retry-After 响应头。

生成图片

POST /api/v1/images/generate

请求体：

{
  "prompt": "A warm editorial product photo of a ceramic coffee cup on a studio desk",
  "modelId": "google:gemini-2.5-flash-image",
  "aspectRatio": "1:1"
}

示例：

curl https://www.byheai.com/api/v1/images/generate \
  -X POST \
  -H "Authorization: Bearer $GET_IMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A warm editorial product photo of a ceramic coffee cup on a studio desk",
    "modelId": "google:gemini-2.5-flash-image",
    "aspectRatio": "1:1"
  }'

响应：

{
  "image": {
    "id": "0c7f0b4a-2c7b-43b6-9b65-6d4e4d0c4b8b",
    "prompt": "A warm editorial product photo of a ceramic coffee cup on a studio desk",
    "modelId": "google:gemini-2.5-flash-image",
    "providerId": "google",
    "aspectRatio": "1:1",
    "style": null,
    "thinkingLevel": null,
    "mediaType": "image/png",
    "b64_json": "iVBORw0KGgoAAA...",
    "createdAt": "2026-05-13T10:30:00.000Z"
  },
  "credits": {
    "charged": 3,
    "remaining": 97
  }
}

图片字节会以内联 base64 形式返回在 image.b64_json 中。

请求字段

prompt 为必填项，长度必须在 1 到 2,000 个字符之间。

modelId 为必填项。支持的值：

openai:gpt-image-1.5
openai:gpt-image-2
google:gemini-2.5-flash-image
google:gemini-3.1-flash-image-preview
google:gemini-3-pro-image-preview

aspectRatio 为可选项。支持的值：

1:1
3:2
2:3
16:9
9:16
4:3
3:4
21:9

style 为可选项，可以是任意简短的风格指令。

thinkingLevel 为可选项，可以是 default 或 deep。只有 Gemini 3.1 Flash Image 和 Gemini 3 Pro Image 模型支持思考控制。

列出图片

GET /api/v1/images

返回此前生成图片的元数据。列表响应不包含图片字节。

curl "https://www.byheai.com/api/v1/images?limit=20&offset=0" \
  -H "Authorization: Bearer $GET_IMAGES_API_KEY"

响应：

{
  "images": [
    {
      "id": "0c7f0b4a-2c7b-43b6-9b65-6d4e4d0c4b8b",
      "prompt": "A warm editorial product photo of a ceramic coffee cup on a studio desk",
      "modelId": "google:gemini-2.5-flash-image",
      "providerId": "google",
      "aspectRatio": "1:1",
      "style": null,
      "thinkingLevel": null,
      "mediaType": "image/png",
      "creditCost": 3,
      "createdAt": "2026-05-13T10:30:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

分页使用 limit 和 offset。默认 limit 为 20，最大值为 100。

获取单张图片

GET /api/v1/images/{id}

返回元数据和内联 base64 图片字节。

curl https://www.byheai.com/api/v1/images/0c7f0b4a-2c7b-43b6-9b65-6d4e4d0c4b8b \
  -H "Authorization: Bearer $GET_IMAGES_API_KEY"

如只需获取元数据：

curl "https://www.byheai.com/api/v1/images/0c7f0b4a-2c7b-43b6-9b65-6d4e4d0c4b8b?format=metadata" \
  -H "Authorization: Bearer $GET_IMAGES_API_KEY"

账户

GET /api/v1/account

curl https://www.byheai.com/api/v1/account \
  -H "Authorization: Bearer $GET_IMAGES_API_KEY"

响应：

{
  "userId": "user_abc123",
  "email": "person@example.com",
  "creditBalance": 97
}

用量

GET /api/v1/usage

curl "https://www.byheai.com/api/v1/usage?limit=20&offset=0" \
  -H "Authorization: Bearer $GET_IMAGES_API_KEY"

响应：

{
  "transactions": [
    {
      "id": "0f1c89a4-2843-47e2-8b69-6de51b777c07",
      "amount": -3,
      "type": "deduction",
      "description": "Generated image",
      "referenceId": "0c7f0b4a-2c7b-43b6-9b65-6d4e4d0c4b8b",
      "createdAt": "2026-05-13T10:30:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

错误

错误采用一致的 JSON 结构：

{
  "error": {
    "message": "Invalid request body.",
    "details": [
      {
        "path": "prompt",
        "message": "Too small: expected string to have >=1 characters",
        "code": "too_small"
      }
    ]
  }
}

常见状态码：

400 - 无效的 JSON、请求体、分页参数、模型或图片选项。
401 - API key 缺失、无效或已被撤销。
404 - 找不到账户或图片。
429 - 超出 API key 速率限制。
500 - 图片生成发生意外失败。

机器可读 Schema

OpenAPI schema 位于：

/openapi.json

可将其用于 Scalar、Redoc、Swagger UI、OpenAPI Generator 或 openapi-typescript 等工具，以渲染 API 参考文档和生成类型化客户端。