跳到导航

BeatAPI 图片 API

图片 API

通过稳定的 BeatAPI 模型 ID 创建一个异步图片生成任务。

模型输入模式必填字段主要控制项
qwen-image-2.1文本、参考图model, prompt最多 10 张参考图、1K/2K、透明 PNG/WebP、按输入条件默认增强提示词
nano-banana文本、参考图model, prompt最多 3 张参考图、固定 1K、PNG/JPEG
nano-banana-2文本、参考图model, prompt最多 14 张参考图、1K/2K/4K、PNG/JPEG
nano-banana-2.1文本、参考图model, prompt字段和价格与 Nano Banana 2 相同。最多 14 张参考图、1K/2K/4K、PNG/JPEG
nano-banana-2-lite文本、参考图model, prompt最多 14 张参考图、固定 1K、PNG/JPEG
nano-banana-pro文本、参考图model, prompt最多 14 张参考图、1K/2K/4K、PNG/JPG
gpt-image-2文本、参考图model, prompt最多 16 张参考图、多种宽高比、最高 4K
gpt-image-2.5-flare文本、参考图model, prompt最多 16 张参考图、16 种宽高比、最高 4K
gpt-image-2.5-sunburst文本、参考图model, prompt最多 16 张参考图、16 种宽高比、最高 4K
seedream-5-pro文本、参考图model, prompt最多 10 张参考图、1K/2K
grok-imagine-image-2.0文本、参考图model, prompt最多 5 张参考图，自动选择编辑模式

每个模型页会列出全部字段、默认值、枚举、组合限制、请求示例、响应和错误行为。

查询可用模型

GET /v1/media/models?media_type=image 无需鉴权。

curl "https://api.beatapi.io/v1/media/models?media_type=image"
{
  "data": {
    "object": "list",
    "data": [{
      "id": "gpt-image-2",
      "object": "generation_model",
      "name": "GPT Image 2",
      "media_type": "image",
      "input_modes": ["text", "image"]
    }, {
      "id": "gpt-image-2.5-flare",
      "object": "generation_model",
      "name": "GPT Image 2.5 Flare",
      "media_type": "image",
      "input_modes": ["text", "image"]
    }, {
      "id": "gpt-image-2.5-sunburst",
      "object": "generation_model",
      "name": "GPT Image 2.5 Sunburst",
      "media_type": "image",
      "input_modes": ["text", "image"]
    }]
  }
}

id 是稳定公开模型别名；input_modes 可能包含 text、image、frames 或 reference。内部供应商路由不属于公开契约。

通用创建契约

POST /v1/images/tasks

请求头类型必填规则
Authorizationstring是Bearer <BEATAPI_API_KEY>
Content-Typestring是application/json
Idempotency-Keystring否，建议使用最长 255 字符；每个逻辑创建使用一个键

请求体必须且只能匹配一个模型参数结构；model 是判别字段，未知字段会被拒绝。

curl https://api.beatapi.io/v1/images/tasks \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Idempotency-Key: image-gpt-image-2-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "暖色石材展台上的编辑风格产品摄影。",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }'

成功请求返回 201 Created 和 data.id。每 5–10 秒轮询 GET /v1/tasks/{task_id}，成功结果位于 data.output.media[] 和 data.output.r2_url。相同幂等请求会返回已接受任务；同一键配不同请求体返回 409 idempotency_conflict。

通用错误

HTTP常见错误码客户端动作
400bad_request修正字段、取值、组合、数量或媒体 URL
400content_policy_violation修改提示词或素材，不要原样重发
401missing_api_key / invalid_api_key补上 Bearer API 密钥，或更换错误、过期、停用、额度用尽的密钥
402insufficient_credits充值后再创建任务
403forbidden密钥或账户无权执行，例如免费额度不能调用该模型
409idempotency_conflict仅用完全相同请求体复用该键
429rate_limit_exceeded遵守 Retry-After
500internal_error退避后重试一次
503processing_unavailable / processing_timeout / processing_failed / result_transfer_failed退避重试，未扣费

错误响应包含 error.code、英文的 error.message、error.retryable、error.request_id，429 时另带 error.retry_after_seconds。任务被接受后才失败的，查询依然返回 200，原因见 data.error_code；全部错误码与重试规则见错误码。模型页面是最终生产请求契约。