BeatAPI 图片 API

图片 API

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

模型输入模式必填字段主要控制项
nano-banana文本、参考图model, prompt最多 10 张参考图、宽高比、PNG/JPEG
nano-banana-2文本、参考图model, prompt最多 10 张参考图、1K/2K/4K、PNG/JPEG
nano-banana-2-lite文本、参考图model, prompt最多 10 张参考图、固定 1K、PNG/JPEG
nano-banana-pro文本、参考图model, prompt最多 8 张参考图、最高 4K
gpt-image-2文本、参考图model, prompt最多 16 张参考图、多种宽高比、最高 4K
seedream-5-pro文本、参考图model, prompt最多 10 张参考图、1K/2K/4K
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"
1{
2  "data": {
3    "object": "list",
4    "data": [{
5      "id": "gpt-image-2",
6      "object": "generation_model",
7      "name": "GPT Image 2",
8      "media_type": "image",
9      "input_modes": ["text", "image"]
10    }]
11  }
12}

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
401unauthorized检查 Bearer API 密钥
402insufficient_credits充值后再创建任务
409idempotency_conflict仅用完全相同请求体复用该键
429频率或并发错误遵守重试延迟或等待活跃任务结束

错误响应包含 error.code、error.message、error.request_id 和可选的 error.retry_after_seconds。模型页面是最终生产请求契约。