API 参考

GrokImagine API

使用统一的 model + input 契约创建 Grok Imagine 图片与视频任务，并通过 Bearer API Key 安全查询结果。

请求契约

model + input

公共端点

POST generate · GET status

可用模型

5

快速开始

选择模型后，示例会同步更新为可直接调用的 cURL。

bash
1curl -X POST 'https://grokimagineapi.com/v1/generate' \
2 -H 'Authorization: Bearer YOUR_API_KEY' \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "model": "grok-imagine/text-to-image",
6 "input": {
7 "prompt": "A cinematic night market in the rain",
8 "aspect_ratio": "16:9"
9 }
10}'

认证

用户 API Key 只能通过 Authorization Bearer header 传入，请求体中的 token 不会被读取。

API Key 仅应保存在服务端。 管理 API Key
http
1Authorization: Bearer YOUR_API_KEY

模型与计费

每个模型使用独立 input 参数；生成请求会按所选模型扣除固定积分。

Model能力积分input
grok-imagine/text-to-image文生图5必填 prompt；aspect_ratio 可选。
grok-imagine/text-to-video文生视频24必填 prompt；aspect_ratio、mode 可选。
grok-imagine/image-to-video图生视频24提供 image_urls，或 task_id（可带 index），两种来源不能同时使用。
grok-imagine/upscale高清放大12必填兼容且已完成任务的 task_id。
grok-imagine/extend视频延长24必填 task_id、prompt；extend_times 可选 "6" 或 "10"。

端点

POST/v1/generate

提交异步任务并返回 task_id。model 和 input 均为必填。

Body ParametersJSON
model:string

枚举值：

input:object

所选模型的参数对象，不能使用旧的平铺 prompt / mode / ratio 契约。

callback_url:optional string

任务完成时接收回调的公网 HTTP(S) URL。

public:optional boolean

是否允许任务结果用于公开展示。

请求示例

5 credits
json
1{
2 "model": "grok-imagine/text-to-image",
3 "input": {
4 "prompt": "A cinematic night market in the rain",
5 "aspect_ratio": "16:9"
6 }
7}

响应示例

任务已创建，使用 task_id 查询进度。

1{
2 "code": 200,
3 "message": "success",
4 "data": {
5 "task_id": "task_example_id",
6 "status": "IN_PROGRESS"
7 }
8}
GET/v1/status

使用生成接口返回的 task_id 轮询任务结果。

Body ParametersJSON
task_id:string

生成接口返回的任务 ID。

必须使用创建任务时的同一个 Bearer API Key；任务不存在或不属于当前 Key 时统一返回 404。

cURL

bash
1curl 'https://grokimagineapi.com/v1/status?task_id=task_example_id' \
2 -H 'Authorization: Bearer YOUR_API_KEY'

响应示例

任务已完成，resultUrls 包含生成结果。

1{
2 "code": 200,
3 "message": "success",
4 "data": {
5 "task_id": "task_example_id",
6 "status": "SUCCESS",
7 "consumed_credits": 5,
8 "error_message": null,
9 "created_at": "2026-07-24T05:00:00.000Z",
10 "request": {
11 "model": "grok-imagine/text-to-image",
12 "input": {
13 "prompt": "A cinematic night market in the rain"
14 }
15 },
16 "response": {
17 "resultUrls": [
18 "https://cdn.example.com/result.webp"
19 ]
20 }
21 }
22}

API Tester

在浏览器中编辑 header、query 和 JSON body 后发送真实请求。请先替换示例 API Key。

API 测试沙盒POST

错误码

BFF 会保留上游服务的 HTTP 状态和 JSON 响应，客户端应同时检查 HTTP status 与 code。

HTTP含义
400 错误请求model、input、callback_url 或 task_id 无效。
401 未授权缺少 Bearer API Key，或 API Key 无效。
402 API Key 积分不足。
404 未找到当前 API Key 下不存在该任务。
429 请求过多请求被服务限流。
500 服务器内部错误BFF 或上游服务异常。