> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiandgpu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Generation - Query Task

## 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 <strong>API Key</strong> is your <a href="https://developer.aiandgpu.com" target="_blank" rel="noopener noreferrer">AGCloud API KEY</a>

Query an image generation task created by `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

<CodeGroup>
  ```shellscript cURL theme={null}
  curl --location 'https://aiandgpu.com/sp/v1/images/generations/gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9' \
  --header 'Authorization: Bearer <YOUR_API_KEY>'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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());
  ```

  ```go Go theme={null}
  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))
  }
  ```

  ```java Java theme={null}
  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 PHP theme={null}
  <?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;
  ```

  ```csharp C# theme={null}
  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);
  ```
</CodeGroup>

## Response Examples

Query requests return `200 OK` when the task is found. Use `status` to determine whether generation is still running, succeeded, or failed.

<CodeGroup>
  ```json 200 - Running theme={null}
  {
    "id": "gen_5a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "object": "image.generation",
    "status": "running",
    "model": "sp-gpt-image-2",
    "created": 1786000000
  }
  ```

  ```json 200 - Succeeded theme={null}
  {
    "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
    }
  }
  ```

  ```json 200 - Failed theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>

## Response Fields

| Field | Type | Description |
| :- | :- | :- |
| `id` | string | Task ID. |
| `object` | string | Always `image.generation`. |
| `status` | string | Task lifecycle status. See [Task Status](#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:

```json theme={null}
{
  "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. |

Terminal task failures may also include these `error.code` values:

| Code | Description |
| :- | :- |
| `invalid_parameter` | Parameter validation failed. |
| `generation_failed` | Image generation failed. |

## Recommended Flow

1. Call `POST /sp/v1/images/generations` to create a task.
2. Store the returned `id`.
3. Poll `GET /sp/v1/images/generations/{id}` every few seconds.
4. When `status` is `succeeded`, read `data[].url` or `data[].b64_json`.
5. When `status` is `failed` or `timeout`, treat the task as failed and read `error`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.