# image2 API

## Documentation Index
Use this file as the authoritative AI-readable index for the current image2 public image generation API.

Fetch the API page at: https://image2.vip/zh/api
Get your API Key at: https://image2.vip/zh/settings/apikeys
View pricing at: https://image2.vip/zh/pricing

Important: this API supports both synchronous generation (default) and asynchronous task queue generation. To perform async image generation, pass "async": true in the request body. You can query status and fetch results via GET /api/v1/images/tasks/{task_id}.

# image2 Image Generation

image2 provides an OpenAI-compatible AI image generation API for turning text prompts into images.

## Base URL

https://image2.vip

## Endpoint

POST /api/v1/images/generations

## Authentication

All requests require Bearer Token authentication.

```
Authorization: Bearer YOUR_API_KEY
```

Get your API Key from:

https://image2.vip/zh/settings/apikeys

## Request Examples

### cURL

```bash
curl -X POST https://image2.vip/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cute cat sitting by the window, warm sunlight on its fur",
    "size": "1024x1024",
    "n": 1
  }'
```

### Python

```python
import requests

url = "https://image2.vip/api/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "gpt-image-2",
    "prompt": "A cute cat sitting by the window, warm sunlight on its fur",
    "size": "1024x1024",
    "n": 1,
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

### JavaScript

```javascript
fetch("https://image2.vip/api/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-image-2",
    prompt: "A cute cat sitting by the window, warm sunlight on its fur",
    size: "1024x1024",
    n: 1
  })
})
  .then((response) => response.json())
  .then((data) => console.log(data));
```

## Body

- model: string, optional, default "gpt-image-2". The current public API uses the configured image generation model.
- prompt: string, required. Text description for image generation. Must contain at least 2 characters after trimming.
- n: integer, optional, default 1. Number of images to generate. Allowed range: 1 to 4.
- size: string, optional, default "auto". Output size or aspect setting accepted by the service.
- quality: string, optional, default "auto". Output quality setting accepted by the service.
- response_format: string, optional, default "url". Allowed values: "url" or "b64_json".
- image: string or array of strings, optional. The reference image URL(s) for image-to-image generation.
- image_urls: array of strings, optional. Alias for 'image' to provide compatibilty with some providers.
- async: boolean, optional, default false. Set to true to submit an asynchronous task and receive a task_id immediately. You must then poll GET /api/v1/images/tasks/{task_id} to query status.

## Successful Response: URL

```json
{
  "created": 1715881600,
  "data": [
    {
      "url": "https://image2.vip/generations/img_abc123.png",
      "revised_prompt": "A cute cat sitting by the window, warm sunlight on its fur"
    }
  ]
}
```

Use data[0].url as the generated image URL.

## Successful Response: Base64

Send "response_format": "b64_json" to receive base64 image data.

```json
{
  "created": 1715881600,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "A cute cat sitting by the window, warm sunlight on its fur"
    }
  ]
}
```

## Asynchronous Task Generation

To generate images asynchronously, pass "async": true in the request body.

### Request Example (Async)

```bash
curl -X POST https://image2.vip/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '''{
    "model": "gpt-image-2",
    "prompt": "A cute cat sitting by the window",
    "async": true
  }'''
```

### Response (Async Task Submitted)

```json
{
  "created": 1715881600,
  "task_id": "batch-uuid-...",
  "status": "pending",
  "data": [
    { "url": null, "status": "pending" }
  ]
}
```

## Query Task Status

### Endpoint

GET /api/v1/images/tasks/{task_id}

### cURL

```bash
curl -X GET https://image2.vip/api/v1/images/tasks/batch-uuid-... \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (Completed)

```json
{
  "created": 1715881600,
  "task_id": "batch-uuid-...",
  "status": "completed",
  "progress": 100,
  "data": [
    {
      "url": "https://image2.vip/generations/img_abc123.png",
      "revised_prompt": "A cute cat sitting by the window",
      "status": "completed"
    }
  ],
  "error": null
}
```

## Error Responses

### 400 Invalid request

```json
{
  "error": {
    "message": "You must provide a 'prompt' parameter with at least 2 characters.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_prompt"
  }
}
```

### 401 Invalid API key

```json
{
  "error": {
    "message": "Incorrect API key provided. You can find your API key at https://image2.vip/settings/api-keys.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
```

### 429 Insufficient credits

```json
{
  "error": {
    "message": "Insufficient credits. You have 0 credits remaining, but this request requires 1.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_credits"
  }
}
```

### 500 Generation failed

```json
{
  "error": {
    "message": "Internal server error during image generation.",
    "type": "server_error",
    "param": null,
    "code": "generation_failed"
  }
}
```

## Notes for AI Agents

1. Always include the Authorization header with a Bearer API key.
2. Use POST https://image2.vip/api/v1/images/generations for image generation.
3. The API returns final image data directly in data[].url or data[].b64_json.
4. To query asynchronous generation task status, use GET /api/v1/images/tasks/{task_id}. Do not poll other undocumented endpoints.
5. Pass reference image URLs in the "image" or "image_urls" parameter (as a string or array of strings) to perform image-to-image generation.
6. Explain 429 insufficient_credits as a credit balance issue and direct users to pricing or account credits.