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

# Endpoint conventions

> Understand APIPod URLs, headers, envelopes, request IDs, and idempotency.

## Base URL and versioning

All endpoints in this documentation use:

```text theme={null}
https://api.apipod.ai
```

Stable public APIs are mounted below `/v1`. Send JSON request bodies as UTF-8 with `Content-Type: application/json`.

An OpenAI-native **synchronous** images API is also available below `/openai/v1` for tools that speak the OpenAI Images API directly — see [OpenAI-compatible images API](/openai-image-sync).

### Long-running synchronous requests

The default host `https://api.apipod.ai` applies a **120-second read timeout** at the edge. Non-streaming requests that can take longer than that — including the OpenAI-compatible synchronous image endpoints (`/openai/v1/images/*`) — must use the dedicated long-request host:

```text theme={null}
https://apid.apipod.ai
```

The same paths and authentication are served on both hosts. Choose `https://apid.apipod.ai` whenever the request can run longer than two minutes; use `https://api.apipod.ai` for short, streaming, or asynchronous task requests.

## Media endpoints

| Method | Path                            | Purpose                                                              |
| ------ | ------------------------------- | -------------------------------------------------------------------- |
| `POST` | `/v1/images/generations`        | Create an asynchronous image task                                    |
| `GET`  | `/v1/images/status/{task_id}`   | Read an image task owned by the authenticated account                |
| `POST` | `/v1/videos/generations`        | Create an asynchronous video task                                    |
| `GET`  | `/v1/videos/status/{task_id}`   | Read a video task owned by the authenticated account                 |
| `POST` | `/openai/v1/images/generations` | Create an image and wait for the result (OpenAI-native, synchronous) |
| `POST` | `/openai/v1/images/edits`       | Edit an image and wait for the result (OpenAI-native, synchronous)   |

## Headers

| Header                | Requirement                              | Description                                       |
| --------------------- | ---------------------------------------- | ------------------------------------------------- |
| `Authorization`       | Required on model and task endpoints     | `Bearer <APIPOD_API_KEY>`                         |
| `Content-Type`        | Required for JSON bodies                 | `application/json`                                |
| `Idempotency-Key`     | Recommended on media create endpoints    | Prevents duplicate task creation across retries   |
| `X-Request-ID`        | Response                                 | Trace identifier generated for the API request    |
| `X-Request-Cost`      | Response on supported billable endpoints | Formatted request cost when available             |
| `X-Idempotent-Replay` | Response on replay                       | `true` when a stored create response was replayed |
| `Retry-After`         | Some retryable errors                    | Suggested wait in seconds                         |

## Response envelopes

Image and video endpoints generally return an APIPod envelope:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

Create and status endpoints use different `data` objects. Use the OpenAPI contract on the exact model or task page instead of assuming that every media endpoint returns the same fields.

## Idempotent media creation

`Idempotency-Key` is optional but strongly recommended for `POST /v1/images/generations` and `POST /v1/videos/generations`.

* Maximum key length is 255 characters.
* The key is scoped to the authenticated API key, HTTP method, and route.
* Repeating the same key with an equivalent JSON body replays the stored response.
* Reusing the key with a different request returns HTTP `409` and `idempotency_conflict`.
* Retrying while the first request is still being processed returns HTTP `409`, `idempotency_in_progress`, and `Retry-After: 1`.
* Completed idempotency records are retained for seven days by the current service implementation.

<Warning>
  A brand-new HTTP request is protected only when it carries the original `Idempotency-Key`. Persist the key with the logical operation before sending the first request.
</Warning>

## IDs and timestamps

* `task_id` identifies the public asynchronous media task and is required for status queries.
* `X-Request-ID` identifies the HTTP request and should be included in operational logs.
* `completed_at` in task status responses is a Unix timestamp in seconds.
* Webhook `created_at` and `completed_at` values are JSON timestamps.