# Asynchronous tasks
Source: https://docs.apipod.ai/asynchronous-tasks
Create, poll, and complete APIPod image and video tasks.
APIPod image and video generation is asynchronous. A create request returns quickly with a public `task_id`; generation continues after that HTTP request finishes.
```mermaid theme={null}
sequenceDiagram
participant Client
participant APIPod
participant Model as Model provider
Client->>APIPod: POST generation request
APIPod-->>Client: 200 + task_id
APIPod->>Model: Dispatch task
loop Until terminal state
Client->>APIPod: GET status/{task_id}
APIPod-->>Client: pending or processing
end
APIPod-->>Client: completed + result, or failed + error
```
## Lifecycle
| Status | Terminal | Client behavior |
| ------------ | -------- | ---------------------------------------------------------------------- |
| `pending` | No | Wait before polling again |
| `processing` | No | Continue polling with backoff |
| `completed` | Yes | Read and persist the URLs in `result` |
| `failed` | Yes | Inspect the error and decide whether a new logical task is appropriate |
| `cancelled` | Yes | Stop polling |
An internal finalization stage is exposed as `processing`, so clients never need to handle a separate `finalizing` state.
## Polling endpoints
```bash theme={null}
curl "https://api.apipod.ai/v1/images/status/$APIPOD_TASK_ID" \
-H "Authorization: Bearer $APIPOD_API_KEY"
```
```bash theme={null}
curl "https://api.apipod.ai/v1/videos/status/$APIPOD_TASK_ID" \
-H "Authorization: Bearer $APIPOD_API_KEY"
```
Status queries are scoped to the authenticated account. A task from another account is not returned.
## Polling strategy
* Start with a short delay, then use bounded exponential backoff with jitter.
* Stop immediately on a terminal status.
* Honor `Retry-After` when the API supplies it.
* Persist the `task_id` before beginning background polling.
* Set an application deadline appropriate for the selected model; do not assume every model completes within the same duration.
* Treat an empty result as not yet deliverable even if an upstream operation has finished; APIPod keeps finalizing media before exposing it as completed.
## Image and video error fields
Image status responses can expose `error_code` and `error_message` in `data`. Video status responses expose the client-safe message as `error`. Webhooks use `error` and optional `error_code`. Always branch on `status` before reading result or error fields.
Receive terminal task results without continuous polling.
Normalize HTTP, synchronous, and asynchronous failures.
# Authentication
Source: https://docs.apipod.ai/authentication
Authenticate APIPod API requests and protect your credentials.
Create and manage API keys in the [APIPod Console](https://www.apipod.ai/console/api-keys). Server-to-server clients should send the key with the standard Bearer authorization header.
```http theme={null}
Authorization: Bearer
```
```bash theme={null}
curl https://api.apipod.ai/v1/account/status \
-H "Authorization: Bearer $APIPOD_API_KEY"
```
## Supported credential headers
| Method | Intended use |
| ----------------------------- | --------------------------------------------------------------- |
| `Authorization: Bearer ` | Recommended for APIPod and OpenAI-compatible clients |
| `x-api-key: ` | Accepted for Anthropic-compatible clients |
| `x-goog-api-key: ` | Accepted for Gemini-compatible clients |
| `?key=` | Gemini-compatible fallback; avoid it when a header is available |
APIPod management tokens are a separate credential type and cannot be used on model APIs.
## Store keys safely
* Read keys from an environment variable or secret manager on your server.
* Never embed a key in browser JavaScript, mobile binaries, public repositories, logs, or URLs.
* Use separate keys for development, staging, and production.
* Revoke and replace a key immediately if it may have been exposed.
* Configure expiration, model or feature permissions, quota limits, rate limits, and an IP allowlist when appropriate.
## Authentication failures
Authentication failures normally use an OpenAI-compatible error envelope:
```json theme={null}
{
"error": {
"message": "Authentication required. Please provide a valid API key or sign in.",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}
```
An invalid, revoked, expired, IP-restricted, or otherwise ineligible key is rejected before a model request is dispatched. See [Error codes](/error-codes) for client handling guidance.
# Endpoint conventions
Source: https://docs.apipod.ai/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`.
## 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 |
## Headers
| Header | Requirement | Description |
| --------------------- | ---------------------------------------- | ------------------------------------------------- |
| `Authorization` | Required on model and task endpoints | `Bearer ` |
| `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.
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.
## 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.
# Error codes
Source: https://docs.apipod.ai/error-codes
Handle APIPod HTTP, synchronous, and asynchronous errors.
Use the HTTP status to classify transport-level outcomes, then read the machine-readable code when one is present. Keep the human-readable message for logs and diagnostics, not control flow.
## Error envelopes
APIPod media and shared service errors can use the standard envelope:
```json theme={null}
{
"code": 429,
"message": "Rate limit exceeded",
"data": {
"type": "rate_limit_error",
"error_code": "rate_limit_exceeded"
}
}
```
Authentication and protocol-compatible endpoints can use an OpenAI-compatible envelope:
```json theme={null}
{
"error": {
"message": "Authentication required. Please provide a valid API key or sign in.",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}
```
Client normalization should check `error.code`, then `data.error_code`, while always preserving the HTTP status and message.
## HTTP status codes
| Status | Meaning | Typical action |
| ------ | ------------------------------------------------- | --------------------------------------------------- |
| `400` | Invalid JSON or model parameters | Fix the request; do not retry unchanged |
| `401` | Missing or invalid credential | Replace or correct the API key |
| `402` | Insufficient quota | Add balance or change account limits |
| `403` | Account, key, permission, or policy restriction | Review account and key configuration |
| `404` | Model or task is unavailable to the caller | Verify the public model ID or task ownership |
| `409` | Idempotency conflict or request still in progress | Follow the machine code and `Retry-After` |
| `429` | Rate limit exceeded | Back off with jitter and honor `Retry-After` |
| `500` | Internal error | Retry only when the operation is idempotent |
| `503` | Service or idempotency protection unavailable | Retry with the same idempotency key |
| `504` | Upstream timeout | Retry according to your idempotent operation policy |
## Common machine codes
| Code | Meaning |
| ------------------------- | ---------------------------------------------------------------------- |
| `invalid_api_key` | The model API credential is missing, invalid, or ineligible |
| `invalid_request` | The request cannot be processed as supplied |
| `insufficient_quota` | Available quota is not sufficient |
| `rate_limit_exceeded` | The applicable request or token rate limit was exceeded |
| `model_not_available` | The public model ID is not currently available |
| `internal_error` | APIPod could not complete the synchronous operation |
| `invalid_idempotency_key` | The key is malformed or longer than 255 characters |
| `idempotency_conflict` | The same key was used with a different request body |
| `idempotency_in_progress` | The first request using the key has not finished creating its response |
| `idempotency_unavailable` | APIPod cannot currently guarantee idempotency protection |
Provider and model-specific failures can expose additional codes. Treat unknown codes as forward-compatible values and fall back to the HTTP status class.
## Asynchronous failures
A task may be accepted successfully and fail later. Polling and webhook payloads expose the terminal task status separately from the original create response.
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"task_id": "img_example_task_id",
"status": "failed",
"error_code": "UPSTREAM_CAPACITY_EXHAUSTED",
"error_message": "Upstream request failed. Please retry later."
}
}
```
Do not convert capacity or service failures into moderation errors. Preserve an unknown asynchronous `error_code`, show the safe message to operators, and decide retry behavior from the semantic code and task state.
## Retry checklist
* Retry `429`, `503`, and transient `5xx` responses with exponential backoff and jitter.
* Reuse the original `Idempotency-Key` and unchanged body when retrying an ambiguous media create request.
* Do not automatically retry `400`, `401`, `402`, `403`, or `404` without first changing the condition that caused them.
* Put an upper bound on attempts and total elapsed time.
* Log `X-Request-ID`, `task_id`, HTTP status, machine code, and attempt number.
# Gemini Omni Extend
Source: https://docs.apipod.ai/gemini-omni/gemini-omni-extend
api-reference/openapi/gemini-omni--gemini-omni-extend.yaml POST /v1/videos/generations
Gemini Omni Extend is APIPod's video extension and editing routing mode for the configured Gemini Omni channel.
# Gemini Omni Image to Video
Source: https://docs.apipod.ai/gemini-omni/gemini-omni-i2v
api-reference/openapi/gemini-omni--gemini-omni-i2v.yaml POST /v1/videos/generations
Gemini Omni I2V is APIPod's first/last-frame image-to-video routing mode for the configured Gemini Omni channel.
# Gemini Omni Reference to Video
Source: https://docs.apipod.ai/gemini-omni/gemini-omni-r2v
api-reference/openapi/gemini-omni--gemini-omni-r2v.yaml POST /v1/videos/generations
Gemini Omni R2V is APIPod's reference-to-video routing mode for the configured Gemini Omni channel.
Provide between one and five reference images.
# Gemini Omni Text to Video
Source: https://docs.apipod.ai/gemini-omni/gemini-omni-t2v
api-reference/openapi/gemini-omni--gemini-omni-t2v.yaml POST /v1/videos/generations
Gemini Omni T2V is APIPod's text-to-video routing mode for the configured Gemini Omni channel.
# GPT Image 2
Source: https://docs.apipod.ai/gpt-image-2/gpt-image-2
api-reference/openapi/gpt-image-2--gpt-image-2.yaml POST /v1/images/generations
GPT Image 2 is OpenAI's image generation and editing model, exposed through APIPod's primary official-route public ID.
# GPT Image 2 Fast
Source: https://docs.apipod.ai/gpt-image-2/gpt-image-2-fast
api-reference/openapi/gpt-image-2--gpt-image-2-fast.yaml POST /v1/images/generations
GPT Image 2 Fast is APIPod's latency-oriented routing variant for GPT Image 2 rather than a separate OpenAI model.
# GPT Image 2 Lite
Source: https://docs.apipod.ai/gpt-image-2/gpt-image-2-lite
api-reference/openapi/gpt-image-2--gpt-image-2-lite.yaml POST /v1/images/generations
GPT Image 2 Lite is APIPod's cost-oriented routing variant for GPT Image 2 rather than a separate OpenAI model.
# Grok Imagine Video 1.5 Fast
Source: https://docs.apipod.ai/grok-imagine-1-5/grok-imagine-1-5-fast
api-reference/openapi/grok-imagine-1-5--grok-imagine-1-5-fast.yaml POST /v1/videos/generations
Grok Imagine 1.5 Fast is a fast route for longer clips and multiple reference images in xAI's Grok Imagine video family, intended for short clips with coherent...
# Grok Imagine Video 1.5 Preview
Source: https://docs.apipod.ai/grok-imagine-1-5/grok-imagine-1-5-preview
api-reference/openapi/grok-imagine-1-5--grok-imagine-1-5-preview.yaml POST /v1/videos/generations
Grok Imagine 1.5 Preview is a preview route that requires one source image in xAI's Grok Imagine video family, intended for short clips with coherent motion and...
# Grok Imagine 1.5 VIP
Source: https://docs.apipod.ai/grok-imagine-1-5/grok-imagine-1-5-vip
api-reference/openapi/grok-imagine-1-5--grok-imagine-1-5-vip.yaml POST /v1/videos/generations
Grok Imagine 1.5 VIP is APIPod's official-channel image-to-video route for Grok Imagine 1.5.
# Grok Imagine Image to Video
Source: https://docs.apipod.ai/grok-imagine/grok-imagine-i2v
api-reference/openapi/grok-imagine--grok-imagine-i2v.yaml POST /v1/videos/generations
Grok Imagine is a image-to-video route in xAI's Grok Imagine video family, intended for short clips with coherent motion and synchronized audio.
Provide either `image_url`/`image_urls` or `task_id`, but not both. `index` is valid only with `task_id`.
# Grok Imagine Text to Video
Source: https://docs.apipod.ai/grok-imagine/grok-imagine-t2v
api-reference/openapi/grok-imagine--grok-imagine-t2v.yaml POST /v1/videos/generations
Grok Imagine is a text-to-video route in xAI's Grok Imagine video family, intended for short clips with coherent motion and synchronized audio.
# Welcome to APIPod
Source: https://docs.apipod.ai/introduction
Generate images and videos through APIPod's asynchronous media APIs.
APIPod provides one asynchronous task API for the image and video models enabled in your account. Your application chooses a public APIPod model ID; APIPod handles provider selection, authentication, billing, task execution, and request tracing behind the same API host.
```text theme={null}
https://api.apipod.ai
```
Create and poll a GPT Image 2 task with a complete working request.
Create an API key, check account access, and send credentials safely.
Browse image-generation and image-editing models with their exact request schemas.
Browse text, image, and reference-driven video generation models.
## What you can build
| Workload | APIPod entry point | Request behavior |
| ---------------- | ----------------------------- | ----------------------------------------------------- |
| Image generation | `POST /v1/images/generations` | Accepts a request and returns a `task_id` for polling |
| Video generation | `POST /v1/videos/generations` | Accepts a request and returns a `task_id` for polling |
| Price estimate | `POST /v1/pricing/estimate` | Estimates a request cost before execution |
Image and video calls are deliberately asynchronous: the create response acknowledges the task, and a later status response delivers the generated asset.
## Media task workflow
Choose the endpoint that matches the generated asset, then open the exact model page before building the request:
* **Image tasks** use `/v1/images/generations` and `/v1/images/status/{task_id}`.
* **Video tasks** use `/v1/videos/generations` and `/v1/videos/status/{task_id}`.
* **Model pages** define the accepted prompt, media inputs, aspect ratio, duration, resolution, and other model-specific fields.
* **Webhooks** can deliver terminal task events when continuous polling is not practical.
## A request lifecycle that matches APIPod
1. **Authenticate.** Send `Authorization: Bearer ` from a server-side environment. `GET /v1/account/status` is a lightweight credential and account probe.
2. **Discover.** Browse the image and video groups in the API Reference or use the Models link in the header to open the live product catalog.
3. **Select the contract.** Use the model ID exactly as documented, then validate against that page's OpenAPI panel. A model's fields and limits can differ from another model in the same family.
4. **Execute.** Create an image or video task with an `Idempotency-Key` and persist the returned `task_id`.
5. **Complete.** Poll `GET /v1/images/status/{task_id}` or `GET /v1/videos/status/{task_id}`, or configure a webhook for terminal task events.
6. **Persist and observe.** Store output assets in durable storage and log `task_id`, `X-Request-ID`, HTTP status, and machine-readable error codes.
A successful media create response means that APIPod accepted the task. It does not mean that generation has completed. Treat `pending` and `processing` as non-terminal states and stop only at `completed`, `failed`, or `cancelled`.
## Production checklist
* Keep API keys on your backend, outside source control and browser bundles.
* Retry only when the operation is safe to retry. For an ambiguous media create request, reuse the same `Idempotency-Key` and unchanged JSON body.
* Use bounded exponential backoff with jitter for polling and transient `429`, `503`, or `5xx` responses.
* Persist `task_id` before background polling and copy result URLs to storage you control.
* Branch on the response status before reading `result` or error fields; preserve unknown machine codes for forward compatibility.
* Use [webhooks](/webhooks) when continuous polling is not practical, and [error handling](/error-codes) for retry and failure semantics.
Polling, terminal states, and result delivery for media generation.
Model-specific schemas and runnable cURL, Python, Go, Rust, and JavaScript examples.
Review pricing and estimate a request before spending quota.
# Kling 2.6 Motion Control
Source: https://docs.apipod.ai/kling/kling-2-6-motion-control
api-reference/openapi/kling--kling-2-6-motion-control.yaml POST /v1/videos/generations
Kling 2.6 Motion Control transfers motion and timing from a reference video to a character or subject in a reference image, with optional preservation of the...
# MiniMax H3 Image to Video
Source: https://docs.apipod.ai/minimax-h3/minimax-h3-i2v
api-reference/openapi/minimax-h3--minimax-h3-i2v.yaml POST /v1/videos/generations
MiniMax H3 Image to Video is a dedicated mode in MiniMax's multimodal H3 video family that uses a required first frame and an optional last frame.
# MiniMax H3 Reference to Video
Source: https://docs.apipod.ai/minimax-h3/minimax-h3-r2v
api-reference/openapi/minimax-h3--minimax-h3-r2v.yaml POST /v1/videos/genertions
MiniMax H3 Reference to Video is a dedicated mode in MiniMax's multimodal H3 video family that combines image, video, and audio references.
Provide at least one reference asset. The per-media limits are defined by the API schema.
# MiniMax H3 Text to Video
Source: https://docs.apipod.ai/minimax-h3/minimax-h3-t2v
api-reference/openapi/minimax-h3--minimax-h3-t2v.yaml POST /v1/videos/generations
MiniMax H3 T2V is the prompt-only text-to-video mode of MiniMax H3. APIPod exposes 768P and native 2K output with 4-to-15-second generation for this public ID.
# Motion Control M1
Source: https://docs.apipod.ai/motion-control/motion-control-m1
api-reference/openapi/motion-control--motion-control-m1.yaml POST /v1/videos/generations
Motion Control M1 transfers the action and timing of a reference video to a subject supplied in a reference image, producing a new asynchronous video result.
# Nano Banana 2
Source: https://docs.apipod.ai/nano-banana/nano-banana-2
api-reference/openapi/nano-banana--nano-banana-2.yaml POST /v1/images/generations
Nano Banana 2 is Google's general-purpose Gemini image generation and editing model, balancing fast generation with instruction following, text rendering, and...
# Nano Banana Pro
Source: https://docs.apipod.ai/nano-banana/nano-banana-pro
api-reference/openapi/nano-banana--nano-banana-pro.yaml POST /v1/images/generations
Nano Banana Pro is Google's high-quality Gemini image model for complex creative work, with an emphasis on multimodal reasoning, real-world knowledge, precise...
# Query image task
Source: https://docs.apipod.ai/query-image-task
api-reference/openapi/query-image-task.yaml GET /v1/images/status/{task_id}
Retrieve status, progress, results, and errors for an asynchronous image generation task by task_id.
After creating a image task, call this endpoint with the returned `task_id`. Poll at a reasonable interval until the task reaches a terminal state; for production workloads, prefer `callback_url` on the create request.
## Task statuses
| `status` | Meaning | Recommended action |
| ------------ | ------------------------------------------------- | ----------------------------------------- |
| `pending` | The task is queued. | Wait and poll again. |
| `processing` | The provider is generating the result. | Wait and poll again. |
| `completed` | The task completed; outputs are in `data.result`. | Download and persist the outputs. |
| `failed` | The task failed. | Inspect the error fields and request log. |
| `cancelled` | The task was cancelled. | Stop polling. |
# Query video task
Source: https://docs.apipod.ai/query-video-task
api-reference/openapi/query-video-task.yaml GET /v1/videos/status/{task_id}
Retrieve status, progress, results, and errors for an asynchronous video generation task by task_id.
After creating a video task, call this endpoint with the returned `task_id`. Poll at a reasonable interval until the task reaches a terminal state; for production workloads, prefer `callback_url` on the create request.
## Task statuses
| `status` | Meaning | Recommended action |
| ------------ | ------------------------------------------------- | ----------------------------------------- |
| `pending` | The task is queued. | Wait and poll again. |
| `processing` | The provider is generating the result. | Wait and poll again. |
| `completed` | The task completed; outputs are in `data.result`. | Download and persist the outputs. |
| `failed` | The task failed. | Inspect the error fields and request log. |
| `cancelled` | The task was cancelled. | Stop polling. |
# Quickstart
Source: https://docs.apipod.ai/quickstart
Create and poll your first APIPod image task.
This quickstart creates a GPT Image 2 task, captures its APIPod task ID, and polls the result endpoint.
Sign in to the [APIPod Console](https://www.apipod.ai/console/api-keys), create an API key, and copy it when it is displayed.
```bash theme={null}
export APIPOD_API_KEY="your-api-key"
export APIPOD_IDEMPOTENCY_KEY="image-$(date +%s)"
```
Use a stable, unique idempotency key for one logical create operation. If a network failure makes the result ambiguous, retry with the same key and unchanged JSON body.
```bash theme={null}
curl https://api.apipod.ai/v1/images/generations \
-H "Authorization: Bearer $APIPOD_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $APIPOD_IDEMPOTENCY_KEY" \
-d '{
"model": "gpt-image-2",
"prompt": "A clean product photograph of a translucent glass speaker, soft studio lighting",
"aspect_ratio": "1:1",
"resolution": "1K"
}'
```
A successful create response has this envelope:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"task_id": "img_example_task_id"
}
}
```
```bash theme={null}
export APIPOD_TASK_ID="img_example_task_id"
curl "https://api.apipod.ai/v1/images/status/$APIPOD_TASK_ID" \
-H "Authorization: Bearer $APIPOD_API_KEY"
```
Continue polling while the status is `pending` or `processing`. Stop when it becomes `completed`, `failed`, or `cancelled`.
## Completed response
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"task_id": "img_example_task_id",
"status": "completed",
"result": [
"https://example.com/generated-image.png"
],
"completed_at": 1786358400
}
}
```
HTTP `200` from the create endpoint means the task was accepted. It does not mean the image or video has finished generating.
Review every supported field and all five language examples.
Add production polling, webhooks, and terminal-state handling.
# Seedance 2.0 Fast Image to Video
Source: https://docs.apipod.ai/seedance/2-0-fast-image-to-video
api-reference/openapi/seedance--2-0-fast-image-to-video.yaml POST /v1/videos/generations
Seedance 2.0 Fast Image to Video is a lower-latency route that animates a required first-frame image and can use an optional last frame where the public schema...
# Seedance 2.0 Fast Reference to Video
Source: https://docs.apipod.ai/seedance/2-0-fast-reference-to-video
api-reference/openapi/seedance--2-0-fast-reference-to-video.yaml POST /v1/videos/generations
Seedance 2.0 Fast Reference to Video is a lower-latency route that uses reference images, video, or audio to guide subjects, motion, visual style, and sound.
Provide at least one reference asset. The per-media limits are defined by the API schema.
# Seedance 2.0 Fast Text to Video
Source: https://docs.apipod.ai/seedance/2-0-fast-text-to-video
api-reference/openapi/seedance--2-0-fast-text-to-video.yaml POST /v1/videos/generations
Seedance 2.0 Fast Text to Video is a lower-latency route that turns text instructions into video without requiring source media.
# Seedance 2.0 Image to Video
Source: https://docs.apipod.ai/seedance/2-0-image-to-video
api-reference/openapi/seedance--2-0-image-to-video.yaml POST /v1/videos/generations
Seedance 2.0 Image to Video is a standard route that animates a required first-frame image and can use an optional last frame where the public schema allows it.
# Seedance 2.0 Mini Image to Video
Source: https://docs.apipod.ai/seedance/2-0-mini-image-to-video
api-reference/openapi/seedance--2-0-mini-image-to-video.yaml POST /v1/videos/generations
Seedance 2.0 Mini Image to Video is a efficiency-oriented route for scaled workloads that animates a required first-frame image and can use an optional last...
# Seedance 2.0 Mini Reference to Video
Source: https://docs.apipod.ai/seedance/2-0-mini-reference-to-video
api-reference/openapi/seedance--2-0-mini-reference-to-video.yaml POST /v1/videos/generations
Seedance 2.0 Mini Reference to Video is a efficiency-oriented route for scaled workloads that uses reference images, video, or audio to guide subjects, motion,...
Provide at least one reference asset. The per-media limits are defined by the API schema.
# Seedance 2.0 mini Text to Video
Source: https://docs.apipod.ai/seedance/2-0-mini-text-to-video
api-reference/openapi/seedance--2-0-mini-text-to-video.yaml POST /v1/videos/generations
Seedance 2.0 Mini Text to Video is a efficiency-oriented route for scaled workloads that turns text instructions into video without requiring source media.
# Seedance 2.0 Reference to Video
Source: https://docs.apipod.ai/seedance/2-0-reference-to-video
api-reference/openapi/seedance--2-0-reference-to-video.yaml POST /v1/videos/generations
Seedance 2.0 Reference to Video is a standard route that uses reference images, video, or audio to guide subjects, motion, visual style, and sound.
Provide at least one reference asset. The per-media limits are defined by the API schema.
# Seedance 2.0 Text to Video
Source: https://docs.apipod.ai/seedance/2-0-text-to-video
api-reference/openapi/seedance--2-0-text-to-video.yaml POST /v1/videos/generations
Seedance 2.0 Text to Video is a standard route that turns text instructions into video without requiring source media.
# Seedance 1.0 Lite Image to Video
Source: https://docs.apipod.ai/seedance/seedance-1-0-lite-i2v
api-reference/openapi/seedance--seedance-1-0-lite-i2v.yaml POST /v1/videos/generations
Seedance 1.0 Lite Image to Video is a standard route that animates a required first-frame image and can use an optional last frame where the public schema...
# Seedance 1.0 Lite Image to Video Reference
Source: https://docs.apipod.ai/seedance/seedance-1-0-lite-i2v-ref
api-reference/openapi/seedance--seedance-1-0-lite-i2v-ref.yaml POST /v1/videos/generations
Seedance 1.0 Lite Image to Video is a standard route that animates a required first-frame image and can use an optional last frame where the public schema...
# Seedance 1.0 Lite Text to Video
Source: https://docs.apipod.ai/seedance/seedance-1-0-lite-t2v
api-reference/openapi/seedance--seedance-1-0-lite-t2v.yaml POST /v1/videos/generations
Seedance 1.0 Lite Text to Video is a standard route that turns text instructions into video without requiring source media.
# Seedance 1.0 Pro Fast Image to Video
Source: https://docs.apipod.ai/seedance/seedance-1-0-pro-fast-i2v
api-reference/openapi/seedance--seedance-1-0-pro-fast-i2v.yaml POST /v1/videos/generations
Seedance 1.0 Pro Fast Image to Video is a lower-latency route that animates a required first-frame image and can use an optional last frame where the public...
# Seedance 1.0 Pro Fast Text to Video
Source: https://docs.apipod.ai/seedance/seedance-1-0-pro-fast-t2v
api-reference/openapi/seedance--seedance-1-0-pro-fast-t2v.yaml POST /v1/videos/generations
Seedance 1.0 Pro Fast Text to Video is a lower-latency route that turns text instructions into video without requiring source media.
# Seedance 1.0 Pro Image to Video
Source: https://docs.apipod.ai/seedance/seedance-1-0-pro-i2v
api-reference/openapi/seedance--seedance-1-0-pro-i2v.yaml POST /v1/videos/generations
Seedance 1.0 Pro Image to Video is a standard route that animates a required first-frame image and can use an optional last frame where the public schema allows...
# Seedance 1.0 Pro Text to Video
Source: https://docs.apipod.ai/seedance/seedance-1-0-pro-t2v
api-reference/openapi/seedance--seedance-1-0-pro-t2v.yaml POST /v1/videos/generations
Seedance 1.0 Pro Text to Video is a standard route that turns text instructions into video without requiring source media.
# Seedance 1.5 Pro Image to Video
Source: https://docs.apipod.ai/seedance/seedance-1-5-pro-i2v
api-reference/openapi/seedance--seedance-1-5-pro-i2v.yaml POST /v1/videos/generations
Seedance 1.5 Pro Image to Video is a standard route that animates a required first-frame image and can use an optional last frame where the public schema allows...
# Seedance 1.5 Pro Text to Video
Source: https://docs.apipod.ai/seedance/seedance-1-5-pro-t2v
api-reference/openapi/seedance--seedance-1-5-pro-t2v.yaml POST /v1/videos/generations
Seedance 1.5 Pro Text to Video is a standard route that turns text instructions into video without requiring source media.
# Seedream V4.5 Image to Image
Source: https://docs.apipod.ai/seedream/4-5-image-to-image
api-reference/openapi/seedream--4-5-image-to-image.yaml POST /v1/images/generations
Seedream 4.5 Edit is ByteDance's reference-image editing model, designed to preserve subjects and fine details while following transformation instructions...
# Seedream V4.5 Text to Image
Source: https://docs.apipod.ai/seedream/4-5-text-to-image
api-reference/openapi/seedream--4-5-text-to-image.yaml POST /v1/images/generations
Seedream 4.5 is ByteDance's text-to-image model for prompt-faithful composition, detailed visual styles, and text rendering.
# Seedream 5.0 Lite Image to Image
Source: https://docs.apipod.ai/seedream/5-0-lite-image-to-image
api-reference/openapi/seedream--5-0-lite-image-to-image.yaml POST /v1/images/generations
Seedream 5.0 Lite Edit is APIPod's efficiency-oriented Seedream 5 route for reference-guided image editing and subject-consistent transformations.
# Seedream 5.0 Lite Text to Image
Source: https://docs.apipod.ai/seedream/5-0-lite-text-to-image
api-reference/openapi/seedream--5-0-lite-text-to-image.yaml POST /v1/images/generations
Seedream 5.0 Lite is APIPod's efficiency-oriented text-to-image route in the Seedream 5 family, intended for prompt-driven generation with flexible...
# Sora 2 Official API
Source: https://docs.apipod.ai/sora-2/sora-2-vip
api-reference/openapi/sora-2--sora-2-vip.yaml POST /v1/videos/generations
Sora 2 VIP is APIPod's official-provider routing ID for Sora 2. Its public contract supports 4-, 8-, or 12-second clips and an optional first-frame image.
# Veo 3.1 Fast
Source: https://docs.apipod.ai/veo/3-1-fast
api-reference/openapi/veo--3-1-fast.yaml POST /v1/videos/generations
Veo 3.1 Fast is a fast-generation route based on Google Veo 3.1. It supports text or first/last-frame image guidance and can generate video with audio.
# Veo 3.1 Fast 4K
Source: https://docs.apipod.ai/veo/3-1-fast-4k
api-reference/openapi/veo--3-1-fast-4k.yaml POST /v1/videos/generations
Veo 3.1 Fast 4K is a fast-generation route based on Google Veo 3.1. It supports text or first/last-frame image guidance and can generate video with audio, with...
# Veo 3.1 Fast Reference
Source: https://docs.apipod.ai/veo/3-1-fast-ref
api-reference/openapi/veo--3-1-fast-ref.yaml POST /v1/videos/generations
Veo 3.1 Fast Ref is Google Veo 3.1's multi-reference video route, using up to three subject or style images to guide character, lighting, and color consistency.
# VEO 3.1 Lite
Source: https://docs.apipod.ai/veo/3-1-lite
api-reference/openapi/veo--3-1-lite.yaml POST /v1/videos/generations
Veo 3.1 Lite is APIPod's efficiency-oriented routing variant for Google Veo 3.1, not a separate Google model name.
# VEO 3.1 Lite 4K
Source: https://docs.apipod.ai/veo/3-1-lite-4k
api-reference/openapi/veo--3-1-lite-4k.yaml POST /v1/videos/generations
Veo 3.1 Lite 4K is APIPod's efficiency-oriented Veo 3.1 route with a 4K output target, not a separate Google model name.
# Veo 3.1 Quality
Source: https://docs.apipod.ai/veo/3-1-quality
api-reference/openapi/veo--3-1-quality.yaml POST /v1/videos/generations
Veo 3.1 Quality is a quality-focused route based on Google Veo 3.1. It supports text or first/last-frame image guidance and can generate video with audio.
# Veo 3.1 Quality 4K
Source: https://docs.apipod.ai/veo/3-1-quality-4k
api-reference/openapi/veo--3-1-quality-4k.yaml POST /v1/videos/generations
Veo 3.1 Quality 4K is a quality-focused route based on Google Veo 3.1. It supports text or first/last-frame image guidance and can generate video with audio,...
# WAN 2.7 Image to Image
Source: https://docs.apipod.ai/wan/2-7-image-to-image
api-reference/openapi/wan--2-7-image-to-image.yaml POST /v1/images/generations
Wan 2.7 Image Edit is Alibaba's instruction-based image editing model for controlled changes that preserve the source structure and principal subjects.
# WAN 2.7 Image to Image Pro
Source: https://docs.apipod.ai/wan/2-7-image-to-image-pro
api-reference/openapi/wan--2-7-image-to-image-pro.yaml POST /v1/images/generations
Wan 2.7 Image Pro Edit is the quality-oriented editing route in APIPod's Wan 2.7 image family, combining reference images with text instructions for...
# WAN 2.7 Text to Image
Source: https://docs.apipod.ai/wan/2-7-text-to-image
api-reference/openapi/wan--2-7-text-to-image.yaml POST /v1/images/generations
Wan 2.7 Image is Alibaba's text-to-image model with an optional reasoning stage for interpreting prompts and planning composition before rendering.
# WAN 2.7 Text to Image Pro
Source: https://docs.apipod.ai/wan/2-7-text-to-image-pro
api-reference/openapi/wan--2-7-text-to-image-pro.yaml POST /v1/images/generations
Wan 2.7 Image Pro is the high-resolution text-to-image route in APIPod's Wan 2.7 image family, with a 4K output tier for detailed or large-format assets.
# WAN 2.7 Image to Video
Source: https://docs.apipod.ai/wan/wan2-7-i2v
api-reference/openapi/wan--wan2-7-i2v.yaml POST /v1/videos/generations
Wan 2.7 Image to Video is a dedicated task mode in Alibaba's Wan video family that animates a first-frame image and supports last-frame control where exposed.
# WAN 2.7 Text to Video
Source: https://docs.apipod.ai/wan/wan2-7-t2v
api-reference/openapi/wan--wan2-7-t2v.yaml POST /v1/videos/generations
Wan 2.7 Text to Video is a dedicated task mode in Alibaba's Wan video family that creates video directly from text prompts without source media.
# WAN 2.7 Video Edit
Source: https://docs.apipod.ai/wan/wan2-7-videoedit
api-reference/openapi/wan--wan2-7-videoedit.yaml POST /v1/videos/generations
Wan 2.7 Video Edit is a dedicated task mode in Alibaba's Wan video family that edits a source video from text instructions and optional image references.
# WAN 3.0 Image to Video
Source: https://docs.apipod.ai/wan/wan3-0-i2v
api-reference/openapi/wan--wan3-0-i2v.yaml POST /v1/videos/generations
Wan 3.0 Image to Video is a dedicated task mode in Alibaba's Wan video family that animates a first-frame image and supports last-frame control where exposed.
# WAN 3.0 参考生视频
Source: https://docs.apipod.ai/wan/wan3-0-r2v
api-reference/openapi/wan--wan3-0-r2v.yaml POST /v1/videos/generations
Wan 3.0 Reference to Video is a dedicated task mode in Alibaba's Wan video family that uses image, video, audio, file, or web references to guide generation.
# WAN 3.0 Text to Video
Source: https://docs.apipod.ai/wan/wan3-0-t2v
api-reference/openapi/wan--wan3-0-t2v.yaml POST /v1/videos/generations
Wan 3.0 Text to Video is a dedicated task mode in Alibaba's Wan video family that creates video directly from text prompts without source media.
# Webhooks
Source: https://docs.apipod.ai/webhooks
Receive APIPod image and video task completion callbacks.
Add `callback_url` to an image or video generation request to receive a POST request when the task reaches `completed` or `failed`.
```json theme={null}
{
"model": "gpt-image-2",
"prompt": "A technical cutaway illustration of a compact camera",
"callback_url": "https://api.example.com/webhooks/apipod/opaque-route-token"
}
```
## Callback request
APIPod sends `Content-Type: application/json` and `User-Agent: APIPod-Callback/1.0`.
```json theme={null}
{
"task_id": "img_example_task_id",
"request_id": "req_example_request_id",
"status": "completed",
"result": [
"https://example.com/generated-image.png"
],
"created_at": "2026-08-10T09:00:00Z",
"completed_at": "2026-08-10T09:01:30Z"
}
```
A failed task uses the same envelope:
```json theme={null}
{
"task_id": "img_example_task_id",
"request_id": "req_example_request_id",
"status": "failed",
"error": "Upstream request failed. Please retry later.",
"error_code": "UPSTREAM_CAPACITY_EXHAUSTED",
"created_at": "2026-08-10T09:00:00Z",
"completed_at": "2026-08-10T09:01:30Z"
}
```
`error_code` is optional. Do not infer success from its absence; use `status`.
## Delivery behavior
* Any HTTP status from `200` through `299` acknowledges the callback.
* Non-2xx responses and network errors are retried.
* APIPod currently makes up to five delivery attempts with exponential backoff.
* Duplicate delivery is possible, so receivers must be idempotent.
* Callback delivery is asynchronous and does not change the task's terminal state.
## Secure the receiver
The current public callback contract does not include a signature header. Do not claim that a callback is authenticated solely because its JSON shape looks correct.
* Use HTTPS and a high-entropy, unguessable token in the callback path.
* Keep the callback URL server-side; do not expose it in client applications.
* Match `task_id` and `request_id` against tasks your system created.
* Store a processed-event key and make duplicate callbacks return the same successful outcome.
* Validate field types and reject unexpectedly large bodies.
* Return 2xx only after the callback has been durably accepted; process slow work asynchronously.
* If authenticity is critical, query the authenticated status endpoint before applying irreversible business actions.
## Minimal receiver
```javascript theme={null}
import express from "express";
const app = express();
app.use(express.json({ limit: "64kb" }));
app.post("/webhooks/apipod/:token", async (req, res) => {
if (req.params.token !== process.env.APIPOD_WEBHOOK_TOKEN) {
return res.sendStatus(404);
}
const { task_id, request_id, status } = req.body;
if (!task_id || !request_id || !["completed", "failed"].includes(status)) {
return res.sendStatus(400);
}
await persistIdempotently({ task_id, request_id, payload: req.body });
return res.sendStatus(204);
});
```