Understand APIPod URLs, headers, envelopes, request IDs, and idempotency.
Base URL and versioning
All endpoints in this documentation use:
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.
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:
https://api-sync.apipod.ai
The same paths and authentication are served on both hosts. Choose https://api-sync.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:
{ "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.
Was this page helpful?
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"APIPod Docs","description":"APIPod API documentation for image and video generation models.","colors":{"primary":"#7F22FE","light":"#A684FF","dark":"#7008E7"},"logo":{"light":"https://mintcdn.com/apipod/eQooMSJ0T7lbhJsR/logo.svg?fit=max\u0026auto=format\u0026n=eQooMSJ0T7lbhJsR\u0026q=85\u0026s=8c3136fb3cec60f625ec4693d5313b42","dark":"https://mintcdn.com/apipod/eQooMSJ0T7lbhJsR/logo.svg?fit=max\u0026auto=format\u0026n=eQooMSJ0T7lbhJsR\u0026q=85\u0026s=8c3136fb3cec60f625ec4693d5313b42","href":"https://www.apipod.ai"},"favicon":"https://mintcdn.com/apipod/eQooMSJ0T7lbhJsR/favicon.ico?fit=max\u0026auto=format\u0026n=eQooMSJ0T7lbhJsR\u0026q=85\u0026s=f81f92481d656456460373ccf2fe85d0","api":{"openapi":["api-reference/openapi/gpt-image-2--gpt-image-2.yaml","api-reference/openapi/gpt-image-2--gpt-image-2.zh.yaml","api-reference/openapi/gpt-image-2.5--gpt-image-2.5-flare.yaml","api-reference/openapi/gpt-image-2.5--gpt-image-2.5-flare.zh.yaml","api-reference/openapi/gpt-image-2.5--gpt-image-2.5-flare-lite.yaml","api-reference/openapi/gpt-image-2.5--gpt-image-2.5-flare-lite.zh.yaml","api-reference/openapi/gpt-image-2.5--gpt-image-2.5-sunburst.yaml","api-reference/openapi/gpt-image-2.5--gpt-image-2.5-sunburst.zh.yaml","api-reference/openapi/gpt-image-2.5--gpt-image-2.5-sunburst-lite.yaml","api-reference/openapi/gpt-image-2.5--gpt-image-2.5-sunburst-lite.zh.yaml","api-reference/openapi/gpt-image-2.6--gpt-image-2.6-flare.yaml","api-reference/openapi/gpt-image-2.6--gpt-image-2.6-flare.zh.yaml","api-reference/openapi/gpt-image-2.6--gpt-image-2.6-flare-hd.yaml","api-reference/openapi/gpt-image-2.6--gpt-image-2.6-flare-hd.zh.yaml","api-reference/openapi/gpt-image-2.6--gpt-image-2.6-flare-lite.yaml","api-reference/openapi/gpt-image-2.6--gpt-image-2.6-flare-lite.zh.yaml","api-reference/openapi/gpt-image-2.6--gpt-image-2.6-sunburst.yaml","api-reference/openapi/gpt-image-2.6--gpt-image-2.6-sunburst.zh.yaml","api-reference/openapi/gpt-image-2.6--gpt-image-2.6-sunburst-hd.yaml","api-reference/openapi/gpt-image-2.6--gpt-image-2.6-sunburst-hd.zh.yaml","api-reference/openapi/gpt-image-2.6--gpt-image-2.6-sunburst-lite.yaml","api-reference/openapi/gpt-image-2.6--gpt-image-2.6-sunburst-lite.zh.yaml","api-reference/openapi/gpt-image-2--gpt-image-2-lite.yaml","api-reference/openapi/gpt-image-2--gpt-image-2-lite.zh.yaml","api-reference/openapi/gpt-image-2--gpt-image-2-1k.yaml","api-reference/openapi/gpt-image-2--gpt-image-2-1k.zh.yaml","api-reference/openapi/gpt-image-2--gpt-image-2-fast.yaml","api-reference/openapi/gpt-image-2--gpt-image-2-fast.zh.yaml","api-reference/openapi/nano-banana--nano-banana-2.yaml","api-reference/openapi/nano-banana--nano-banana-2.zh.yaml","api-reference/openapi/nano-banana--nano-banana-2-lite.yaml","api-reference/openapi/nano-banana--nano-banana-2-lite.zh.yaml","api-reference/openapi/nano-banana--nano-banana-pro.yaml","api-reference/openapi/nano-banana--nano-banana-pro.zh.yaml","api-reference/openapi/nano-banana--nano-banana-2.1.yaml","api-reference/openapi/nano-banana--nano-banana-2.1.zh.yaml","api-reference/openapi/seedream--4-5-text-to-image.yaml","api-reference/openapi/seedream--4-5-text-to-image.zh.yaml","api-reference/openapi/seedream--4-5-image-to-image.yaml","api-reference/openapi/seedream--4-5-image-to-image.zh.yaml","api-reference/openapi/seedream--5-0-lite-text-to-image.yaml","api-reference/openapi/seedream--5-0-lite-text-to-image.zh.yaml","api-reference/openapi/seedream--5-0-lite-image-to-image.yaml","api-reference/openapi/seedream--5-0-lite-image-to-image.zh.yaml","api-reference/openapi/seedream--5-0-pro-text-to-image.yaml","api-reference/openapi/seedream--5-0-pro-text-to-image.zh.yaml","api-reference/openapi/seedream--5-0-pro-image-to-image.yaml","api-reference/openapi/seedream--5-0-pro-image-to-image.zh.yaml","api-reference/openapi/seedream--5-0-pro-layer.yaml","api-reference/openapi/seedream--5-0-pro-layer.zh.yaml","api-reference/openapi/seedream--5-0-flash-text-to-image.yaml","api-reference/openapi/seedream--5-0-flash-text-to-image.zh.yaml","api-reference/openapi/seedream--5-0-flash-image-to-image.yaml","api-reference/openapi/seedream--5-0-flash-image-to-image.zh.yaml","api-reference/openapi/seedream--5-0-flash-layer.yaml","api-reference/openapi/seedream--5-0-flash-layer.zh.yaml","api-reference/openapi/wan--2-7-text-to-image.yaml","api-reference/openapi/wan--2-7-text-to-image.zh.yaml","api-reference/openapi/wan--2-7-image-to-image.yaml","api-reference/openapi/wan--2-7-image-to-image.zh.yaml","api-reference/openapi/wan--2-7-text-to-image-pro.yaml","api-reference/openapi/wan--2-7-text-to-image-pro.zh.yaml","api-reference/openapi/wan--2-7-image-to-image-pro.yaml","api-reference/openapi/wan--2-7-image-to-image-pro.zh.yaml","api-reference/openapi/query-image-task.yaml","api-reference/openapi/query-image-task.zh.yaml","api-reference/openapi/veo--3-1-fast.yaml","api-reference/openapi/veo--3-1-fast.zh.yaml","api-reference/openapi/veo--3-1-fast-4k.yaml","api-reference/openapi/veo--3-1-fast-4k.zh.yaml","api-reference/openapi/veo--3-1-fast-ref.yaml","api-reference/openapi/veo--3-1-fast-ref.zh.yaml","api-reference/openapi/veo--3-1-quality.yaml","api-reference/openapi/veo--3-1-quality.zh.yaml","api-reference/openapi/veo--3-1-quality-4k.yaml","api-reference/openapi/veo--3-1-quality-4k.zh.yaml","api-reference/openapi/seedance--2-0-text-to-video.yaml","api-reference/openapi/seedance--2-0-text-to-video.zh.yaml","api-reference/openapi/seedance--2-0-image-to-video.yaml","api-reference/openapi/seedance--2-0-image-to-video.zh.yaml","api-reference/openapi/seedance--2-0-reference-to-video.yaml","api-reference/openapi/seedance--2-0-reference-to-video.zh.yaml","api-reference/openapi/seedance--2-0-fast-text-to-video.yaml","api-reference/openapi/seedance--2-0-fast-text-to-video.zh.yaml","api-reference/openapi/seedance--2-0-fast-image-to-video.yaml","api-reference/openapi/seedance--2-0-fast-image-to-video.zh.yaml","api-reference/openapi/seedance--2-0-fast-reference-to-video.yaml","api-reference/openapi/seedance--2-0-fast-reference-to-video.zh.yaml","api-reference/openapi/grok-imagine--grok-imagine-t2v.yaml","api-reference/openapi/grok-imagine--grok-imagine-t2v.zh.yaml","api-reference/openapi/grok-imagine--grok-imagine-i2v.yaml","api-reference/openapi/grok-imagine--grok-imagine-i2v.zh.yaml","api-reference/openapi/grok-imagine-1-5--grok-imagine-1-5-fast.yaml","api-reference/openapi/grok-imagine-1-5--grok-imagine-1-5-fast.zh.yaml","api-reference/openapi/grok-imagine-1-5--grok-imagine-1-5-preview.yaml","api-reference/openapi/grok-imagine-1-5--grok-imagine-1-5-preview.zh.yaml","api-reference/openapi/sora-2--sora-2-vip.yaml","api-reference/openapi/sora-2--sora-2-vip.zh.yaml","api-reference/openapi/gemini-omni--gemini-omni-t2v.yaml","api-reference/openapi/gemini-omni--gemini-omni-t2v.zh.yaml","api-reference/openapi/gemini-omni--gemini-omni-i2v.yaml","api-reference/openapi/gemini-omni--gemini-omni-i2v.zh.yaml","api-reference/openapi/gemini-omni--gemini-omni-r2v.yaml","api-reference/openapi/gemini-omni--gemini-omni-r2v.zh.yaml","api-reference/openapi/gemini-omni--gemini-omni-extend.yaml","api-reference/openapi/gemini-omni--gemini-omni-extend.zh.yaml","api-reference/openapi/gemini-omni-flash-1.1--gemini-omni-flash-1.1-t2v.yaml","api-reference/openapi/gemini-omni-flash-1.1--gemini-omni-flash-1.1-t2v.zh.yaml","api-reference/openapi/gemini-omni-flash-1.1--gemini-omni-flash-1.1-i2v.yaml","api-reference/openapi/gemini-omni-flash-1.1--gemini-omni-flash-1.1-i2v.zh.yaml","api-reference/openapi/gemini-omni-flash-1.1--gemini-omni-flash-1.1-r2v.yaml","api-reference/openapi/gemini-omni-flash-1.1--gemini-omni-flash-1.1-r2v.zh.yaml","api-reference/openapi/gemini-omni-flash-1.1-lite--gemini-omni-flash-1.1-lite-t2v.yaml","api-reference/openapi/gemini-omni-flash-1.1-lite--gemini-omni-flash-1.1-lite-t2v.zh.yaml","api-reference/openapi/gemini-omni-flash-1.1-lite--gemini-omni-flash-1.1-lite-i2v.yaml","api-reference/openapi/gemini-omni-flash-1.1-lite--gemini-omni-flash-1.1-lite-i2v.zh.yaml","api-reference/openapi/gemini-omni-flash-1.1-lite--gemini-omni-flash-1.1-lite-r2v.yaml","api-reference/openapi/gemini-omni-flash-1.1-lite--gemini-omni-flash-1.1-lite-r2v.zh.yaml","api-reference/openapi/gemini-omni-flash-1.2-lite--gemini-omni-flash-1.2-lite-t2v.yaml","api-reference/openapi/gemini-omni-flash-1.2-lite--gemini-omni-flash-1.2-lite-t2v.zh.yaml","api-reference/openapi/gemini-omni-flash-1.2-lite--gemini-omni-flash-1.2-lite-i2v.yaml","api-reference/openapi/gemini-omni-flash-1.2-lite--gemini-omni-flash-1.2-lite-i2v.zh.yaml","api-reference/openapi/gemini-omni-flash-1.2-lite--gemini-omni-flash-1.2-lite-r2v.yaml","api-reference/openapi/gemini-omni-flash-1.2-lite--gemini-omni-flash-1.2-lite-r2v.zh.yaml","api-reference/openapi/gemini-omni-flash-1.2-lite--gemini-omni-flash-1.2-lite-edit.yaml","api-reference/openapi/gemini-omni-flash-1.2-lite--gemini-omni-flash-1.2-lite-edit.zh.yaml","api-reference/openapi/gemini-omni-flash-1.2-lite--gemini-omni-flash-1.2-lite-extend.yaml","api-reference/openapi/gemini-omni-flash-1.2-lite--gemini-omni-flash-1.2-lite-extend.zh.yaml","api-reference/openapi/gemini-omni-flash-1.1--gemini-omni-flash-1.1-extend.yaml","api-reference/openapi/gemini-omni-flash-1.1--gemini-omni-flash-1.1-extend.zh.yaml","api-reference/openapi/minimax-h3--minimax-h3.yaml","api-reference/openapi/minimax-h3--minimax-h3.zh.yaml","api-reference/openapi/minimax-h3--minimax-h3-t2v.yaml","api-reference/openapi/minimax-h3--minimax-h3-t2v.zh.yaml","api-reference/openapi/minimax-h3--minimax-h3-i2v.yaml","api-reference/openapi/minimax-h3--minimax-h3-i2v.zh.yaml","api-reference/openapi/minimax-h3--minimax-h3-r2v.yaml","api-reference/openapi/minimax-h3--minimax-h3-r2v.zh.yaml","api-reference/openapi/query-video-task.yaml","api-reference/openapi/query-video-task.zh.yaml","api-reference/openapi/ark-query-video-task.yaml","api-reference/openapi/ark-query-video-task.zh.yaml","api-reference/openapi/grok-imagine-1-5--grok-imagine-1-5-vip.yaml","api-reference/openapi/grok-imagine-1-5--grok-imagine-1-5-vip.zh.yaml","api-reference/openapi/kling--kling-2-6-motion-control.yaml","api-reference/openapi/kling--kling-2-6-motion-control.zh.yaml","api-reference/openapi/kling-3.0--kling-3.0-t2v.yaml","api-reference/openapi/kling-3.0--kling-3.0-t2v.zh.yaml","api-reference/openapi/kling-3.0--kling-3.0-i2v.yaml","api-reference/openapi/kling-3.0--kling-3.0-i2v.zh.yaml","api-reference/openapi/kling-3.0--kling-3.0-turbo-t2v.yaml","api-reference/openapi/kling-3.0--kling-3.0-turbo-t2v.zh.yaml","api-reference/openapi/kling-3.0--kling-3.0-turbo-i2v.yaml","api-reference/openapi/kling-3.0--kling-3.0-turbo-i2v.zh.yaml","api-reference/openapi/kling-3.0--kling-3.0-omni-t2v.yaml","api-reference/openapi/kling-3.0--kling-3.0-omni-t2v.zh.yaml","api-reference/openapi/kling-3.0--kling-3.0-omni-i2v.yaml","api-reference/openapi/kling-3.0--kling-3.0-omni-i2v.zh.yaml","api-reference/openapi/kling-3.0--kling-3.0-omni-r2v.yaml","api-reference/openapi/kling-3.0--kling-3.0-omni-r2v.zh.yaml","api-reference/openapi/kling-3.0--kling-3.0-omni-edit.yaml","api-reference/openapi/kling-3.0--kling-3.0-omni-edit.zh.yaml","api-reference/openapi/kling-4.0--kling-4.0-t2v.yaml","api-reference/openapi/kling-4.0--kling-4.0-t2v.zh.yaml","api-reference/openapi/kling-4.0--kling-4.0-i2v.yaml","api-reference/openapi/kling-4.0--kling-4.0-i2v.zh.yaml","api-reference/openapi/kling-4.0--kling-4.0-r2v.yaml","api-reference/openapi/kling-4.0--kling-4.0-r2v.zh.yaml","api-reference/openapi/motion-control--motion-control-m1.yaml","api-reference/openapi/motion-control--motion-control-m1.zh.yaml","api-reference/openapi/seedance--doubao-seedance-1-0-pro-fast-i2v.yaml","api-reference/openapi/seedance--doubao-seedance-1-0-pro-fast-i2v.zh.yaml","api-reference/openapi/seedance--seedance-1-0-lite-i2v.yaml","api-reference/openapi/seedance--seedance-1-0-lite-i2v.zh.yaml","api-reference/openapi/seedance--seedance-1-0-lite-i2v-ref.yaml","api-reference/openapi/seedance--seedance-1-0-lite-i2v-ref.zh.yaml","api-reference/openapi/seedance--seedance-1-0-lite-t2v.yaml","api-reference/openapi/seedance--seedance-1-0-lite-t2v.zh.yaml","api-reference/openapi/seedance--seedance-1-0-pro-fast-i2v.yaml","api-reference/openapi/seedance--seedance-1-0-pro-fast-i2v.zh.yaml","api-reference/openapi/seedance--seedance-1-0-pro-fast-t2v.yaml","api-reference/openapi/seedance--seedance-1-0-pro-fast-t2v.zh.yaml","api-reference/openapi/seedance--seedance-1-0-pro-i2v.yaml","api-reference/openapi/seedance--seedance-1-0-pro-i2v.zh.yaml","api-reference/openapi/seedance--seedance-1-0-pro-t2v.yaml","api-reference/openapi/seedance--seedance-1-0-pro-t2v.zh.yaml","api-reference/openapi/seedance--seedance-1-5-pro-i2v.yaml","api-reference/openapi/seedance--seedance-1-5-pro-i2v.zh.yaml","api-reference/openapi/seedance--seedance-1-5-pro-t2v.yaml","api-reference/openapi/seedance--seedance-1-5-pro-t2v.zh.yaml","api-reference/openapi/seedance--2-0-mini-image-to-video.yaml","api-reference/openapi/seedance--2-0-mini-image-to-video.zh.yaml","api-reference/openapi/seedance--2-0-mini-reference-to-video.yaml","api-reference/openapi/seedance--2-0-mini-reference-to-video.zh.yaml","api-reference/openapi/seedance--2-0-mini-text-to-video.yaml","api-reference/openapi/seedance--2-0-mini-text-to-video.zh.yaml","api-reference/openapi/seedance--seedance-2-0-t2v-vip.yaml","api-reference/openapi/seedance--seedance-2-0-t2v-vip.zh.yaml","api-reference/openapi/seedance--2-0-lite-text-to-video.yaml","api-reference/openapi/seedance--2-0-lite-text-to-video.zh.yaml","api-reference/openapi/seedance--2-0-lite-image-to-video.yaml","api-reference/openapi/seedance--2-0-lite-image-to-video.zh.yaml","api-reference/openapi/seedance--2-0-lite-reference-to-video.yaml","api-reference/openapi/seedance--2-0-lite-reference-to-video.zh.yaml","api-reference/openapi/seedance--2-0-fast-lite-text-to-video.yaml","api-reference/openapi/seedance--2-0-fast-lite-text-to-video.zh.yaml","api-reference/openapi/seedance--2-0-fast-lite-image-to-video.yaml","api-reference/openapi/seedance--2-0-fast-lite-image-to-video.zh.yaml","api-reference/openapi/seedance--2-0-fast-lite-reference-to-video.yaml","api-reference/openapi/seedance--2-0-fast-lite-reference-to-video.zh.yaml","api-reference/openapi/seedance--2-0-mini-lite-text-to-video.yaml","api-reference/openapi/seedance--2-0-mini-lite-text-to-video.zh.yaml","api-reference/openapi/seedance--2-0-mini-lite-image-to-video.yaml","api-reference/openapi/seedance--2-0-mini-lite-image-to-video.zh.yaml","api-reference/openapi/seedance--2-0-mini-lite-reference-to-video.yaml","api-reference/openapi/seedance--2-0-mini-lite-reference-to-video.zh.yaml","api-reference/openapi/seedance--2-5-text-to-video.yaml","api-reference/openapi/seedance--2-5-text-to-video.zh.yaml","api-reference/openapi/seedance--2-5-image-to-video.yaml","api-reference/openapi/seedance--2-5-image-to-video.zh.yaml","api-reference/openapi/seedance--2-5-reference-to-video.yaml","api-reference/openapi/seedance--2-5-reference-to-video.zh.yaml","api-reference/openapi/seedance--2-5-video-edit.yaml","api-reference/openapi/seedance--2-5-video-edit.zh.yaml","api-reference/openapi/seedance--2-5-video-extend.yaml","api-reference/openapi/seedance--2-5-video-extend.zh.yaml","api-reference/openapi/seedance--2-5-draft.yaml","api-reference/openapi/seedance--2-5-draft.zh.yaml","api-reference/openapi/seedance--2-5-lite-text-to-video.yaml","api-reference/openapi/seedance--2-5-lite-text-to-video.zh.yaml","api-reference/openapi/seedance--2-5-lite-image-to-video.yaml","api-reference/openapi/seedance--2-5-lite-image-to-video.zh.yaml","api-reference/openapi/seedance--2-5-lite-reference-to-video.yaml","api-reference/openapi/seedance--2-5-lite-reference-to-video.zh.yaml","api-reference/openapi/veo--3-1-lite.yaml","api-reference/openapi/veo--3-1-lite.zh.yaml","api-reference/openapi/veo--3-1-lite-4k.yaml","api-reference/openapi/veo--3-1-lite-4k.zh.yaml","api-reference/openapi/wan--wan2-7-i2v.yaml","api-reference/openapi/wan--wan2-7-i2v.zh.yaml","api-reference/openapi/wan--wan2-7-t2v.yaml","api-reference/openapi/wan--wan2-7-t2v.zh.yaml","api-reference/openapi/wan--wan2-7-videoedit.yaml","api-reference/openapi/wan--wan2-7-videoedit.zh.yaml","api-reference/openapi/wan--wan3-0-video.yaml","api-reference/openapi/wan--wan3-0-video.zh.yaml","api-reference/openapi/wan--wan3-0-i2v.yaml","api-reference/openapi/wan--wan3-0-i2v.zh.yaml","api-reference/openapi/wan--wan3-0-r2v.yaml","api-reference/openapi/wan--wan3-0-r2v.zh.yaml","api-reference/openapi/wan--wan3-0-t2v.yaml","api-reference/openapi/wan--wan3-0-t2v.zh.yaml","api-reference/openapi/wan--wan3-0-video-prime.yaml","api-reference/openapi/wan--wan3-0-video-prime.zh.yaml","api-reference/openapi/wan--wan3-0-prime-i2v.yaml","api-reference/openapi/wan--wan3-0-prime-i2v.zh.yaml","api-reference/openapi/wan--wan3-0-prime-r2v.yaml","api-reference/openapi/wan--wan3-0-prime-r2v.zh.yaml","api-reference/openapi/wan--wan3-0-prime-t2v.yaml","api-reference/openapi/wan--wan3-0-prime-t2v.zh.yaml","api-reference/openapi/seedance--2-0-spicy-text-to-video.yaml","api-reference/openapi/seedance--2-0-spicy-text-to-video.zh.yaml","api-reference/openapi/seedance--2-0-spicy-image-to-video.yaml","api-reference/openapi/seedance--2-0-spicy-image-to-video.zh.yaml","api-reference/openapi/seedance--2-0-spicy-reference-to-video.yaml","api-reference/openapi/seedance--2-0-spicy-reference-to-video.zh.yaml","api-reference/openapi/seedance--2-5-spicy-text-to-video.yaml","api-reference/openapi/seedance--2-5-spicy-text-to-video.zh.yaml","api-reference/openapi/seedance--2-5-spicy-image-to-video.yaml","api-reference/openapi/seedance--2-5-spicy-image-to-video.zh.yaml","api-reference/openapi/seedance--2-5-spicy-reference-to-video.yaml","api-reference/openapi/seedance--2-5-spicy-reference-to-video.zh.yaml","api-reference/openapi/seedance--2-5-spicy-video-edit.yaml","api-reference/openapi/seedance--2-5-spicy-video-edit.zh.yaml","api-reference/openapi/seedance--2-5-spicy-video-extend.yaml","api-reference/openapi/seedance--2-5-spicy-video-extend.zh.yaml","api-reference/openapi/seedance--2-0-x-text-to-video.yaml","api-reference/openapi/seedance--2-0-x-text-to-video.zh.yaml","api-reference/openapi/seedance--2-0-x-reference-to-video.yaml","api-reference/openapi/seedance--2-0-x-reference-to-video.zh.yaml","api-reference/openapi/seedance--2-5-x-text-to-video.yaml","api-reference/openapi/seedance--2-5-x-text-to-video.zh.yaml","api-reference/openapi/seedance--2-5-x-reference-to-video.yaml","api-reference/openapi/seedance--2-5-x-reference-to-video.zh.yaml","api-reference/openapi/wan--wan3-0-spicy-t2v.yaml","api-reference/openapi/wan--wan3-0-spicy-t2v.zh.yaml","api-reference/openapi/wan--wan3-0-spicy-i2v.yaml","api-reference/openapi/wan--wan3-0-spicy-i2v.zh.yaml","api-reference/openapi/wan--wan3-0-spicy-r2v.yaml","api-reference/openapi/wan--wan3-0-spicy-r2v.zh.yaml","api-reference/openapi/wan--wan3-0-video-spicy.yaml","api-reference/openapi/wan--wan3-0-video-spicy.zh.yaml","api-reference/openapi/wan--wan3-0-pro-spicy-t2v.yaml","api-reference/openapi/wan--wan3-0-pro-spicy-t2v.zh.yaml","api-reference/openapi/wan--wan3-0-pro-spicy-i2v.yaml","api-reference/openapi/wan--wan3-0-pro-spicy-i2v.zh.yaml","api-reference/openapi/wan--wan3-0-pro-spicy-r2v.yaml","api-reference/openapi/wan--wan3-0-pro-spicy-r2v.zh.yaml","api-reference/openapi/wan--wan3-0-video-pro-spicy.yaml","api-reference/openapi/wan--wan3-0-video-pro-spicy.zh.yaml","api-reference/openapi/wan--wan3-0-prime-spicy-t2v.yaml","api-reference/openapi/wan--wan3-0-prime-spicy-t2v.zh.yaml","api-reference/openapi/wan--wan3-0-prime-spicy-i2v.yaml","api-reference/openapi/wan--wan3-0-prime-spicy-i2v.zh.yaml","api-reference/openapi/wan--wan3-0-prime-spicy-r2v.yaml","api-reference/openapi/wan--wan3-0-prime-spicy-r2v.zh.yaml","api-reference/openapi/wan--wan3-0-video-prime-spicy.yaml","api-reference/openapi/wan--wan3-0-video-prime-spicy.zh.yaml","api-reference/openapi/muse-video--muse-video-t2v.yaml","api-reference/openapi/muse-video--muse-video-t2v.zh.yaml","api-reference/openapi/muse-video--muse-video-i2v.yaml","api-reference/openapi/muse-video--muse-video-i2v.zh.yaml","api-reference/openapi/muse-video--muse-video-r2v.yaml","api-reference/openapi/muse-video--muse-video-r2v.zh.yaml","api-reference/openapi/gemini-omni-flash-1.2--gemini-omni-flash-1.2-edit.yaml","api-reference/openapi/gemini-omni-flash-1.2--gemini-omni-flash-1.2-edit.zh.yaml","api-reference/openapi/gemini-omni-flash-1.2--gemini-omni-flash-1.2-extend.yaml","api-reference/openapi/gemini-omni-flash-1.2--gemini-omni-flash-1.2-extend.zh.yaml","api-reference/openapi/gemini-omni-flash-1.2--gemini-omni-flash-1.2-i2v.yaml","api-reference/openapi/gemini-omni-flash-1.2--gemini-omni-flash-1.2-i2v.zh.yaml","api-reference/openapi/gemini-omni-flash-1.2--gemini-omni-flash-1.2-r2v.yaml","api-reference/openapi/gemini-omni-flash-1.2--gemini-omni-flash-1.2-r2v.zh.yaml","api-reference/openapi/gemini-omni-flash-1.2--gemini-omni-flash-1.2-t2v.yaml","api-reference/openapi/gemini-omni-flash-1.2--gemini-omni-flash-1.2-t2v.zh.yaml","api-reference/openapi/seedance--2-5-flash-text-to-video.yaml","api-reference/openapi/seedance--2-5-flash-text-to-video.zh.yaml","api-reference/openapi/seedance--2-5-flash-image-to-video.yaml","api-reference/openapi/seedance--2-5-flash-image-to-video.zh.yaml","api-reference/openapi/seedance--2-5-flash-reference-to-video.yaml","api-reference/openapi/seedance--2-5-flash-reference-to-video.zh.yaml","api-reference/openapi/seedance--2-5-flash-video-edit.yaml","api-reference/openapi/seedance--2-5-flash-video-edit.zh.yaml","api-reference/openapi/seedance--2-5-flash-video-extend.yaml","api-reference/openapi/seedance--2-5-flash-video-extend.zh.yaml","api-reference/openapi/seedance--2-5-flash-spicy-text-to-video.yaml","api-reference/openapi/seedance--2-5-flash-spicy-text-to-video.zh.yaml","api-reference/openapi/seedance--2-5-flash-spicy-image-to-video.yaml","api-reference/openapi/seedance--2-5-flash-spicy-image-to-video.zh.yaml","api-reference/openapi/seedance--2-5-flash-spicy-reference-to-video.yaml","api-reference/openapi/seedance--2-5-flash-spicy-reference-to-video.zh.yaml","api-reference/openapi/seedance--2-5-flash-spicy-video-edit.yaml","api-reference/openapi/seedance--2-5-flash-spicy-video-edit.zh.yaml","api-reference/openapi/seedance--2-5-flash-spicy-video-extend.yaml","api-reference/openapi/seedance--2-5-flash-spicy-video-extend.zh.yaml"],"playground":{"display":"interactive","proxy":false},"examples":{"defaults":"required","languages":["curl","python","go","rust","javascript"]},"url":"full"},"navbar":{"links":[{"href":"https://www.apipod.ai/models","label":"Models"},{"href":"https://www.apipod.ai/pricing","label":"Pricing"},{"href":"mailto:[email protected]","label":"Support"}],"primary":{"type":"button","label":"Console","href":"https://www.apipod.ai/console"}},"footer":{"socials":{"github":"https://github.com/APIPod"}},"search":{"prompt":"Search APIPod documentation"},"seo":{"indexing":"navigable"},"icons":{"library":"lucide"},"contextual":{"options":["copy","view","chatgpt","claude","cursor"],"display":"header"},"styling":{"latex":false},"navigation":{"languages":[{"language":"en","default":true,"href":"introduction"},{"language":"zh-CN","href":"zh-CN/introduction"}]}},"deployment":{"deploymentMetadataValue":{"subdomain":"apipod","hasAudioNarration":false,"actualSubdomain":"apipod","customDomains":["docs.apipod.ai"],"gitSource":{"type":"github","owner":"apipodai","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"feedback":{"thumbs":true,"agentFeedback":true},"entitlements":{},"buildId":"6afd152c5ec46423cf3ba590","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"en","tag":"API Reference","count":133},{"language":"zh-CN","tag":"API 参考","count":133},{"language":"en","tag":"Videos","count":95},{"language":"zh-CN","tag":"视频","count":95},{"language":"en","tag":"Images","count":36},{"language":"en","tag":"Seedance","count":36},{"language":"zh-CN","tag":"图片","count":36},{"language":"zh-CN","tag":"Seedance","count":36},{"language":"en","tag":"Seedance 2.5","count":22},{"language":"zh-CN","tag":"Seedance 2.5","count":22},{"language":"en","tag":"Seedance 2.0","count":11},{"language":"zh-CN","tag":"Seedance 2.0","count":11},{"language":"en","tag":"Kling 3.0","count":10},{"language":"en","tag":"Seedream","count":10},{"language":"zh-CN","tag":"Kling 3.0","count":10},{"language":"zh-CN","tag":"Seedream","count":10},{"language":"en","tag":"Wan Video","count":9},{"language":"zh-CN","tag":"Wan Video","count":9},{"language":"en","tag":"Get Started","count":7},{"language":"zh-CN","tag":"开始使用","count":7}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"endpoint-conventions","slug":"/endpoint-conventions","pageMetadata":{"title":"Endpoint conventions","description":"Understand APIPod URLs, headers, envelopes, request IDs, and idempotency.","icon":"route","href":"/endpoint-conventions"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Understand APIPod URLs, headers, envelopes, request IDs, and idempotency.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`2`,id:`base-url-and-versioning`,children:`Base URL and versioning`}),`\n`,_jsx(_components.p,{children:`All endpoints in this documentation use:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`2`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`https://api.apipod.ai`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[`Stable public APIs are mounted below `,_jsx(_components.code,{children:`/v1`}),`. Send JSON request bodies as UTF-8 with `,_jsx(_components.code,{children:`Content-Type: application/json`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`An OpenAI-native `,_jsx(_components.strong,{children:`synchronous`}),` images API is also available below `,_jsx(_components.code,{children:`/openai/v1`}),` for tools that speak the OpenAI Images API directly — see `,_jsx(_components.a,{href:`/openai-image-sync`,children:`OpenAI-compatible images API`}),`.`]}),`\n`,_jsx(Heading,{level:`3`,id:`long-running-synchronous-requests`,children:`Long-running synchronous requests`}),`\n`,_jsxs(_components.p,{children:[`The default host `,_jsx(_components.code,{children:`https://api.apipod.ai`}),` applies a `,_jsx(_components.strong,{children:`120-second read timeout`}),` at the edge. Non-streaming requests that can take longer than that — including the OpenAI-compatible synchronous image endpoints (`,_jsx(_components.code,{children:`/openai/v1/images/*`}),`) — must use the dedicated long-request host:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`2`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`https://api-sync.apipod.ai`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[`The same paths and authentication are served on both hosts. Choose `,_jsx(_components.code,{children:`https://api-sync.apipod.ai`}),` whenever the request can run longer than two minutes; use `,_jsx(_components.code,{children:`https://api.apipod.ai`}),` for short, streaming, or asynchronous task requests.`]}),`\n`,_jsx(Heading,{level:`2`,id:`media-endpoints`,children:`Media endpoints`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Method`}),_jsx(_components.th,{children:`Path`}),_jsx(_components.th,{children:`Purpose`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`POST`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`/v1/images/generations`})}),_jsx(_components.td,{children:`Create an asynchronous image task`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`GET`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`/v1/images/status/{task_id}`})}),_jsx(_components.td,{children:`Read an image task owned by the authenticated account`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`POST`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`/v1/videos/generations`})}),_jsx(_components.td,{children:`Create an asynchronous video task`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`GET`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`/v1/videos/status/{task_id}`})}),_jsx(_components.td,{children:`Read a video task owned by the authenticated account`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`POST`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`/openai/v1/images/generations`})}),_jsx(_components.td,{children:`Create an image and wait for the result (OpenAI-native, synchronous)`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`POST`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`/openai/v1/images/edits`})}),_jsx(_components.td,{children:`Edit an image and wait for the result (OpenAI-native, synchronous)`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`headers`,children:`Headers`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Header`}),_jsx(_components.th,{children:`Requirement`}),_jsx(_components.th,{children:`Description`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`Authorization`})}),_jsx(_components.td,{children:`Required on model and task endpoints`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`Bearer \u003cAPIPOD_API_KEY>`})})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`Content-Type`})}),_jsx(_components.td,{children:`Required for JSON bodies`}),_jsx(_components.td,{children:_jsx(_components.code,{children:`application/json`})})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`Idempotency-Key`})}),_jsx(_components.td,{children:`Recommended on media create endpoints`}),_jsx(_components.td,{children:`Prevents duplicate task creation across retries`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`X-Request-ID`})}),_jsx(_components.td,{children:`Response`}),_jsx(_components.td,{children:`Trace identifier generated for the API request`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`X-Request-Cost`})}),_jsx(_components.td,{children:`Response on supported billable endpoints`}),_jsx(_components.td,{children:`Formatted request cost when available`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`X-Idempotent-Replay`})}),_jsx(_components.td,{children:`Response on replay`}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`true`}),` when a stored create response was replayed`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`Retry-After`})}),_jsx(_components.td,{children:`Some retryable errors`}),_jsx(_components.td,{children:`Suggested wait in seconds`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`response-envelopes`,children:`Response envelopes`}),`\n`,_jsx(_components.p,{children:`Image and video endpoints generally return an APIPod envelope:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`5`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"code\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`200`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"success\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"data\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {}`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Create and status endpoints use different `,_jsx(_components.code,{children:`data`}),` objects. Use the OpenAPI contract on the exact model or task page instead of assuming that every media endpoint returns the same fields.`]}),`\n`,_jsx(Heading,{level:`2`,id:`idempotent-media-creation`,children:`Idempotent media creation`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`Idempotency-Key`}),` is optional but strongly recommended for `,_jsx(_components.code,{children:`POST /v1/images/generations`}),` and `,_jsx(_components.code,{children:`POST /v1/videos/generations`}),`.`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Maximum key length is 255 characters.`}),`\n`,_jsx(_components.li,{children:`The key is scoped to the authenticated API key, HTTP method, and route.`}),`\n`,_jsx(_components.li,{children:`Repeating the same key with an equivalent JSON body replays the stored response.`}),`\n`,_jsxs(_components.li,{children:[`Reusing the key with a different request returns HTTP `,_jsx(_components.code,{children:`409`}),` and `,_jsx(_components.code,{children:`idempotency_conflict`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Retrying while the first request is still being processed returns HTTP `,_jsx(_components.code,{children:`409`}),`, `,_jsx(_components.code,{children:`idempotency_in_progress`}),`, and `,_jsx(_components.code,{children:`Retry-After: 1`}),`.`]}),`\n`,_jsx(_components.li,{children:`Completed idempotency records are retained for seven days by the current service implementation.`}),`\n`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`A brand-new HTTP request is protected only when it carries the original `,_jsx(_components.code,{children:`Idempotency-Key`}),`. Persist the key with the logical operation before sending the first request.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`ids-and-timestamps`,children:`IDs and timestamps`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`task_id`}),` identifies the public asynchronous media task and is required for status queries.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`X-Request-ID`}),` identifies the HTTP request and should be included in operational logs.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`completed_at`}),` in task status responses is a Unix timestamp in seconds.`]}),`\n`,_jsxs(_components.li,{children:[`Webhook `,_jsx(_components.code,{children:`created_at`}),` and `,_jsx(_components.code,{children:`completed_at`}),` values are JSON timestamps.`]}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Endpoint conventions","description":"Understand APIPod URLs, headers, envelopes, request IDs, and idempotency.","icon":"route","href":"/endpoint-conventions"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Base URL and versioning","slug":"base-url-and-versioning","depth":2,"children":[{"title":"Long-running synchronous requests","slug":"long-running-synchronous-requests","depth":3,"children":[]}]},{"title":"Media endpoints","slug":"media-endpoints","depth":2,"children":[]},{"title":"Headers","slug":"headers","depth":2,"children":[]},{"title":"Response envelopes","slug":"response-envelopes","depth":2,"children":[]},{"title":"Idempotent media creation","slug":"idempotent-media-creation","depth":2,"children":[]},{"title":"IDs and timestamps","slug":"ids-and-timestamps","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"apipod","siteName":"APIPod Docs","title":"Endpoint conventions - APIPod Docs","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{"en":{"href":"/endpoint-conventions","matchLevel":0},"zh-CN":{"href":"/zh-CN/endpoint-conventions","matchLevel":1}}},"lastModified":"2026-11-18T00:19:28.268Z","originalFileLocation":"endpoint-conventions.mdx","locale":"en"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Understand APIPod URLs, headers, envelopes, request IDs, and idempotency.\">\u003cmeta data-mint-head name=\"application-name\" content=\"APIPod Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/apipod/vxS4fP5ezbC3ZtwJ/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/apipod/vxS4fP5ezbC3ZtwJ/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/apipod/vxS4fP5ezbC3ZtwJ/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/apipod/vxS4fP5ezbC3ZtwJ/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/apipod/vxS4fP5ezbC3ZtwJ/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/apipod/vxS4fP5ezbC3ZtwJ/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/apipod/vxS4fP5ezbC3ZtwJ/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/apipod/vxS4fP5ezbC3ZtwJ/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/apipod/vxS4fP5ezbC3ZtwJ/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Endpoint conventions - APIPod Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Understand APIPod URLs, headers, envelopes, request IDs, and idempotency.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"APIPod Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.apipod.ai/endpoint-conventions\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://apipod.mintlify.site/_mintlify/api/og/v2?division=Overview\u0026amp;title=Endpoint+conventions\u0026amp;description=Understand+APIPod+URLs%2C+headers%2C+envelopes%2C+request+IDs%2C+and+idempotency.\u0026amp;theme=5aea6f2132a648cb0995271a\u0026amp;signature=55f830d3a120c2d3d2cbac575257b46bb6a11aa715b82012ab13e346c56ddb95\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Endpoint conventions - APIPod Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Understand APIPod URLs, headers, envelopes, request IDs, and idempotency.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://apipod.mintlify.site/_mintlify/api/og/v2?division=Overview\u0026amp;title=Endpoint+conventions\u0026amp;description=Understand+APIPod+URLs%2C+headers%2C+envelopes%2C+request+IDs%2C+and+idempotency.\u0026amp;theme=5aea6f2132a648cb0995271a\u0026amp;signature=55f830d3a120c2d3d2cbac575257b46bb6a11aa715b82012ab13e346c56ddb95\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/apipod/vxS4fP5ezbC3ZtwJ/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"APIPod Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#7F22FE\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.apipod.ai/endpoint-conventions\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/endpoint-conventions.md\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"en\" href=\"https://docs.apipod.ai/endpoint-conventions\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"zh-CN\" href=\"https://docs.apipod.ai/zh-CN/endpoint-conventions\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"x-default\" href=\"https://docs.apipod.ai/endpoint-conventions\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.apipod.ai/#organization\",\"name\":\"APIPod Docs\",\"url\":\"https://docs.apipod.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/apipod/eQooMSJ0T7lbhJsR/logo.svg?fit=max\u0026auto=format\u0026n=eQooMSJ0T7lbhJsR\u0026q=85\u0026s=8c3136fb3cec60f625ec4693d5313b42\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.apipod.ai#website\",\"name\":\"APIPod Docs\",\"url\":\"https://docs.apipod.ai\",\"publisher\":{\"@id\":\"https://docs.apipod.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.apipod.ai/endpoint-conventions#webpage\",\"url\":\"https://docs.apipod.ai/endpoint-conventions\",\"name\":\"Endpoint conventions\",\"description\":\"Understand APIPod URLs, headers, envelopes, request IDs, and idempotency.\",\"dateModified\":\"2026-11-18T00:19:28.268Z\",\"isPartOf\":{\"@id\":\"https://docs.apipod.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.apipod.ai/endpoint-conventions#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.apipod.ai/endpoint-conventions#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Overview\",\"item\":\"https://docs.apipod.ai/introduction\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Endpoint conventions\",\"item\":\"https://docs.apipod.ai/endpoint-conventions\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.apipod.ai/endpoint-conventions#article\",\"headline\":\"Endpoint conventions\",\"name\":\"Endpoint conventions\",\"description\":\"Understand APIPod URLs, headers, envelopes, request IDs, and idempotency.\",\"url\":\"https://docs.apipod.ai/endpoint-conventions\",\"mainEntityOfPage\":{\"@id\":\"https://docs.apipod.ai/endpoint-conventions#webpage\"},\"dateModified\":\"2026-11-18T00:19:28.268Z\",\"publisher\":{\"@id\":\"https://docs.apipod.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.apipod.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"APIPod Docs\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"APIPod Docs\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/endpoint-conventions.md","siteName":"APIPod Docs","nav":{"global":null,"languages":[{"language":"en","default":true,"tabs":[{"tab":"Get Started","groups":[{"group":"Overview","icon":"compass","pages":[{"title":"Welcome to APIPod","icon":"house","href":"/introduction"},{"title":"Quickstart","icon":"rocket","href":"/quickstart"},{"title":"Authentication","description":"Authenticate APIPod API requests and protect your credentials.","icon":"key-round","href":"/authentication"},{"title":"Endpoint conventions","icon":"route","href":"/endpoint-conventions"}]},{"group":"Core concepts","icon":"blocks","pages":[{"title":"Asynchronous tasks","description":"Create, poll, and complete APIPod image and video tasks.","icon":"clock-3","href":"/asynchronous-tasks"},{"title":"Webhooks","icon":"webhook","href":"/webhooks"},{"title":"Error codes","icon":"circle-alert","href":"/error-codes"}]}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/gpt-image-2/gpt-image-2"}]}]},{"language":"zh-CN","pages":[{"title":"zh-CN","href":"/zh-CN/endpoint-conventions"}]}]},"basePath":"","title":"Endpoint conventions - APIPod Docs","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":[],"chunks":[]}