gpt-image-2
Image Generation - Query Task
GET
/
sp
/
v1
/
images
/
generations
/
{id}
Authorization
- Auth Type:
Bearer Auth(In:header) - Format:
Authorization: Bearer <YOUR_API_KEY> - Description: Use
Bearer <YOUR_API_KEY>. Format:Authorization: Bearer sk-xxxxxx. - API Key: where API Key is your AGCloud API KEY
POST /sp/v1/images/generations. Poll this endpoint every few seconds until status reaches a terminal value.
Path Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✅ | Task ID returned by the create endpoint. Must match ^gen_[A-Za-z0-9_-]{1,128}$. |
Request Example
curl --location 'https://aiandgpu.com/sp/v1/images/generations/gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9' \
--header 'Authorization: Bearer <YOUR_API_KEY>'
import requests
api_key = "<YOUR_API_KEY>"
task_id = "gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9"
response = requests.get(
f"https://aiandgpu.com/sp/v1/images/generations/{task_id}",
headers={"Authorization": f"Bearer {api_key}"},
)
response.raise_for_status()
print(response.json())
const apiKey = "<YOUR_API_KEY>";
const taskId = "gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9";
const response = await fetch(
`https://aiandgpu.com/sp/v1/images/generations/${taskId}`,
{
headers: {
Authorization: `Bearer ${apiKey}`,
},
}
);
console.log(await response.json());
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
apiKey := "<YOUR_API_KEY>"
taskID := "gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9"
req, _ := http.NewRequest(
"GET",
"https://aiandgpu.com/sp/v1/images/generations/"+taskID,
nil,
)
req.Header.Set("Authorization", "Bearer "+apiKey)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}
import okhttp3.*;
OkHttpClient client = new OkHttpClient();
String apiKey = "<YOUR_API_KEY>";
String taskId = "gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9";
Request request = new Request.Builder()
.url("https://aiandgpu.com/sp/v1/images/generations/" + taskId)
.header("Authorization", "Bearer " + apiKey)
.get()
.build();
try (Response response = client.newCall(request).execute()) {
System.out.println(response.body().string());
}
<?php
$apiKey = "<YOUR_API_KEY>";
$taskId = "gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9";
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://aiandgpu.com/sp/v1/images/generations/" . $taskId,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . $apiKey,
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer <YOUR_API_KEY>");
var taskId = "gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9";
var response = await client.GetAsync(
$"https://aiandgpu.com/sp/v1/images/generations/{taskId}"
);
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);
Response Examples
Query requests return200 OK when the task is found. Use status to determine whether generation is still running, succeeded, or failed.
{
"id": "gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9",
"object": "image.generation",
"status": "running",
"model": "sp-gpt-image-2",
"created": 1786000000
}
{
"id": "gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9",
"object": "image.generation",
"status": "succeeded",
"model": "sp-gpt-image-2",
"created": 1786000000,
"data": [
{
"url": "https://cdn.example.com/images/gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9/0.png"
}
],
"usage": {
"prompt_tokens": 11,
"completion_tokens": 397,
"total_tokens": 408
}
}
{
"id": "gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9",
"object": "image.generation",
"status": "failed",
"model": "sp-gpt-image-2",
"created": 1786000000,
"error": {
"type": "api_error",
"code": "generation_failed",
"message": "generation failed"
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Task ID. |
object | string | Always image.generation. |
status | string | Task lifecycle status. See Task Status. |
model | string | Model ID used for the task. |
created | integer | Creation time as Unix seconds. |
data[].url | string | Generated image URL. Returned only when status is succeeded. |
data[].b64_json | string | Base64 image content. Returned only when the image is delivered as base64. |
data[].revised_prompt | string | Revised prompt, when available. |
usage.prompt_tokens | integer | Input token usage, when available. |
usage.completion_tokens | integer | Output token usage, when available. |
usage.total_tokens | integer | Total token usage, when available. |
error.type | string | Error type, usually api_error. |
error.code | string | Error code. |
error.message | string | Error message. |
Task Status
| Status | Description | Terminal |
|---|---|---|
queued | Task has been created and is waiting to run. | - |
running | Task is generating. | - |
succeeded | Task completed successfully; read data. | ✅ |
failed | Task failed; read error. | ✅ |
timeout | Task timed out. | ✅ |
Error Responses
Non-2xx responses use a unified error format:{
"error": {
"type": "api_error",
"code": "invalid_generation_id",
"message": "invalid generation id"
}
}
| HTTP Status | Code | Description |
|---|---|---|
400 | invalid_generation_id | Invalid task ID format in the query path. |
401 | invalid_api_key | API key is missing or invalid. |
402 | insufficient_balance | Account balance or quota is insufficient. |
404 | generation_not_found | The task does not exist or does not belong to the current API key. |
503 | billing_unavailable | Result processing is temporarily unavailable. Retry the query later. |
503 | service_unavailable | Service is temporarily unavailable. Retry later. |
error.code values:
| Code | Description |
|---|---|
invalid_parameter | Parameter validation failed. |
generation_failed | Image generation failed. |
Recommended Flow
- Call
POST /sp/v1/images/generationsto create a task. - Store the returned
id. - Poll
GET /sp/v1/images/generations/{id}every few seconds. - When
statusissucceeded, readdata[].urlordata[].b64_json. - When
statusisfailedortimeout, treat the task as failed and readerror.