# Async Inference (V2)

The V2 async API lets you submit a request, get a `request_id` immediately, and poll for the result when it's ready. No long-lived HTTP connections needed.

## Quick Start

### 1. Submit a request

```bash
curl -X POST "https://api.segmind.com/v2/seedream-4.5" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a red rose on a wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "seed": 123
  }'
```

**Response:**

```json
{
  "request_id": "2c7f59ea-13f1-402c-9353-915a2b5a2124",
  "status": "QUEUED",
  "poll_url": "https://api.segmind.com/v1/requests/2c7f59ea-...",
  "status_url": "https://api.segmind.com/v2/requests/2c7f59ea-.../status",
  "response_url": "https://api.segmind.com/v2/requests/2c7f59ea-..."
}
```

| Field          | Description                                  |
| -------------- | -------------------------------------------- |
| `request_id`   | Unique identifier for this request           |
| `status`       | Always `QUEUED` on submit                    |
| `poll_url`     | V1 poll endpoint (backward compatible)       |
| `status_url`   | Lightweight status check (no output payload) |
| `response_url` | Full result endpoint (output + metadata)     |

### 2. Check status (lightweight)

Use `status_url` for efficient polling — it returns only status and metrics, no output payload.

```bash
curl "https://api.segmind.com/v2/requests/2c7f59ea-.../status" \
  -H "x-api-key: YOUR_API_KEY"
```

**While processing:**

```json
{
  "status": "QUEUED",
  "request_id": "2c7f59ea-...",
  "status_url": "https://api.segmind.com/v2/requests/2c7f59ea-.../status",
  "response_url": "https://api.segmind.com/v2/requests/2c7f59ea-...",
  "metrics": {}
}
```

**When done:**

```json
{
  "status": "COMPLETED",
  "request_id": "2c7f59ea-...",
  "metrics": { "inference_time": 13.06 }
}
```

### 3. Fetch the result

Once status is `COMPLETED`, fetch the full result from `response_url`.

```bash
curl "https://api.segmind.com/v2/requests/2c7f59ea-..." \
  -H "x-api-key: YOUR_API_KEY"
```

**Image result:**

```json
{
  "status": "COMPLETED",
  "images": [
    {
      "url": "https://segmind-inference-io.s3.amazonaws.com/e17ba-output.jpg",
      "content_type": "image/jpeg",
      "file_size": "868446"
    }
  ],
  "output": "https://segmind-inference-io.s3.amazonaws.com/e17ba-output.jpg",
  "seed": "123",
  "prompt": "a red rose on a wooden table, studio lighting",
  "timings": { "inference": 13.06 },
  "metrics": { "inference_time": 13.06 }
}
```

## Response Formats by Modality

The result shape depends on what the model produces.

### Image models

```json
{
  "status": "COMPLETED",
  "images": [{ "url": "...", "content_type": "image/jpeg", "file_size": "..." }],
  "output": "https://...",
  "seed": "123",
  "prompt": "...",
  "timings": { "inference": 13.06 },
  "metrics": { "inference_time": 13.06 }
}
```

### Video models

```json
{
  "status": "COMPLETED",
  "video": { "url": "...", "content_type": "video/mp4", "file_name": "output.mp4", "file_size": 5757619 },
  "output": "https://..."
}
```

### LLM / text models

```json
{
  "status": "COMPLETED",
  "output": "The generated text...",
  "reasoning": null,
  "partial": false,
  "error": null
}
```

The `output` field is always present across all modalities for backward compatibility.

## Status Values

| Status       | Description                            |
| ------------ | -------------------------------------- |
| `QUEUED`     | Request accepted, waiting for a worker |
| `PROCESSING` | A worker has picked up the request     |
| `COMPLETED`  | Inference finished, result available   |
| `FAILED`     | Inference failed (see `error` field)   |

## Result Expiry

Request status and results are stored for **1 hour** after submission. After that, the status key expires and polling any endpoint will return HTTP `404`. Make sure to fetch your results within this window.

## Error Handling

**Failed requests** return HTTP `422` on V2 endpoints:

```json
{
  "status": "FAILED",
  "error": "Prompt is Mandatory and must be string",
  "metrics": {}
}
```

**Not found** returns HTTP `404`:

```json
{
  "error": "Request 00000000-... not found"
}
```

## Endpoints Summary

| Endpoint                   | Method | Description                            |
| -------------------------- | ------ | -------------------------------------- |
| `/v2/{model}`              | POST   | Submit async request                   |
| `/v2/requests/{id}/status` | GET    | Lightweight status + metrics           |
| `/v2/requests/{id}`        | GET    | Full result (when COMPLETED)           |
| `/v1/requests/{id}`        | GET    | Legacy poll (status + output combined) |

## Python Example

```python
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.segmind.com"

# Submit
resp = requests.post(
    f"{BASE}/v2/seedream-4.5",
    headers={"x-api-key": API_KEY},
    json={"prompt": "a beautiful sunset", "aspect_ratio": "16:9"}
)
data = resp.json()
request_id = data["request_id"]
print(f"Submitted: {request_id}")

# Poll
while True:
    status = requests.get(
        f"{BASE}/v2/requests/{request_id}/status",
        headers={"x-api-key": API_KEY}
    ).json()
    
    if status["status"] in ("COMPLETED", "FAILED"):
        break
    time.sleep(2)

# Fetch result
if status["status"] == "COMPLETED":
    result = requests.get(
        f"{BASE}/v2/requests/{request_id}",
        headers={"x-api-key": API_KEY}
    ).json()
    print(f"Image URL: {result['images'][0]['url']}")
    print(f"Inference time: {result['timings']['inference']}s")
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.segmind.com/api-reference/async-inference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.