API reference
Request and response contracts for generation tasks, account USD balance, and usage.

i2v.aiRequest and response contracts for generation tasks, account USD balance, and usage.
Public catalog prices are indicative. Use quoteGeneration for a maximum on a specific account and request.
/api/v1/generation-modelscurl -X GET "https://api.i2v.ai/api/v1/generation-models"/api/v1/uploadsIn: header
1 <= length <= 180"image/jpeg" | "image/png" | "image/webp" | "image/gif" | "image/avif" | "video/mp4" | "video/quicktime" | "video/webm" | "video/x-msvideo" | "video/x-matroska" | "audio/mpeg" | "audio/wav" | "audio/mp4" | "audio/aac" | "audio/ogg" | "audio/flac" | "audio/mp3" | "audio/m4a" | "audio/x-m4a" | "audio/x-flac"1 <= value <= 52428800/api/v1/uploadsIn: header
/api/v1/assets/{assetId}/completeIn: header
/api/v1/jobs/createTaskIn: header
/api/v1/jobs/submissionIn: header
/api/v1/jobs/cancelIn: header
/api/v1/account/usageIn: header
Storage path returned by the upload ticket.
length <= 801 <= length <= 180Bytes. Limits are 10 MiB for images, 50 MiB for video, and 15 MiB for audio.
1 <= value <= 52428800"image/jpeg" | "image/png" | "image/webp" | "image/gif" | "audio/mpeg" | "audio/wav" | "audio/mp3" | "audio/m4a" | "audio/x-m4a" | "audio/mp4" | "audio/aac" | "audio/flac" | "audio/x-flac" | "audio/ogg" | "video/mp4" | "video/webm" | "video/quicktime" | "video/x-msvideo" | "video/x-matroska"uuid1 <= length <= 200Empty Object
Stable identifier for one logical submission. A conflicting payload returns HTTP 409.
1 <= length <= 200"gpt-image-2" | "gpt-image-2.5" | "grok-imagine" | "nanobanana-2" | "nano-banana-2-lite" | "official-kling-v3-turbo" | "official-kling-v3-0" | "gemini-2.5-flash" | "seedream-5.0-pro" | "gemini-3-pro" | "wan-3-0" | "official-kling-v3-0-pro" | "official-kling-v3-motion-control" | "google-veo3.1" | "official-kling-v3-omni" | "seedream-5.0" | "seedance-2-mini" | "google-veo3.1-pro" | "seedream-5.0-flash" | "seedance2-5" | "seedance-2-0" | "seedance-2-0-fast" | "midjourney" | "wan-3-0-pro" | "minimax-h3" | "gpt-image-2.6" | "gemini-omni-1.2-flash" | "seedance-2-5-flash"Model-specific inputs. See the model documentation for required fields, defaults and mode constraints.
Empty Object
Public callback URL for signed image and video completion events. Use HTTPS on port 443 and create a signing secret in developer settings.
uriuri^(0|[1-9][0-9]*)(\.[0-9]{1,8})?$0 <= value1 <= length <= 2001 <= length <= 200"30d""today" | "yesterday" | "7d" | "30d" | "90d"curl -X POST "https://api.i2v.ai/api/v1/uploads" \
-H "Content-Type: application/json" \
-d '{
"fileName": "string"
}'{
"data": [
{
"id": "string",
"name": "string",
"mediaType": "image",
"inputSchema": {},
"prices": [
{}
]
}
]
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}Request a signed PUT URL using only a file name. PUT the raw bytes directly to storage, then pass the public URL in inputs.uploadedUrls. Content-Type and size may also be supplied.
Bytes. Limits are 10 MiB for images, 50 MiB for video, and 15 MiB for audio.
PUT the raw bytes to uploadUrl using the returned Content-Type. Do not send the i2v.ai Bearer credential to the storage URL. Call completeUrl after upload.
Verifies account ownership, file size and Content-Type. Use the returned URL in the model input after confirmation.
Uses the same model inputs, account entitlements and API pricing channel as createTask. No task or reservation is created. Send maximum.amount as maxCostUsd and expectedRevision with the same model and inputs when submitting.
Reserves a quoted USD maximum and returns a task ID. The selected model determines accepted inputs. Reuse the same idempotency key and payload when retrying a logical submission.
Send the API key and Idempotency-Key used at submission. This lookup never creates a task or reserves money. Pending means continue checking the same receipt. Retryable means you may replay the original body and key. For an accepted receipt, continue with recordInfo.
Read an owned task. Poll with backoff until success or fail. API image and video tasks can include lifecycle.phase and a suggested polling delay. Queries return the original USD reservation, charge, release, refunds and funding allocation.
Cancels an owned API task that has never been claimed for generation and releases its USD reservation. Repeating a successful cancellation is safe. A 409 means dispatch may have started or the task is otherwise ineligible. Query recordInfo to read its current state.
Returns account-wide settled usage and usage refunds by UTC booking date. Verified historical net usage is included separately. Pending reserves remain in the account balance endpoint. A refund booked in a later window can make net negative.
curl -X GET "https://api.i2v.ai/api/v1/uploads?path=string"curl -X POST "https://api.i2v.ai/api/v1/assets" \
-H "Content-Type: application/json" \
-d '{
"fileName": "string",
"fileSize": 1,
"contentType": "image/jpeg"
}'curl -X POST "https://api.i2v.ai/api/v1/assets/497f6eca-6276-4993-bfeb-53cbbbba6f08/complete"curl -X POST "https://api.i2v.ai/api/v1/jobs/quote" \
-H "Content-Type: application/json" \
-d '{
"model": "string"
}'curl -X POST "https://api.i2v.ai/api/v1/jobs/createTask" \
-H "Idempotency-Key: string" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"inputs": {
"prompt": "A calm lake at sunrise",
"resolution": "1K"
}
}'curl -X GET "https://api.i2v.ai/api/v1/jobs/submission" \
-H "Idempotency-Key: string"curl -X GET "https://api.i2v.ai/api/v1/jobs/recordInfo?taskId=string"curl -X POST "https://api.i2v.ai/api/v1/jobs/cancel" \
-H "Content-Type: application/json" \
-d '{
"taskId": "string"
}'curl -X GET "https://api.i2v.ai/api/v1/account"curl -X GET "https://api.i2v.ai/api/v1/account/usage?range=today"{
"path": "string",
"url": "http://example.com",
"size": 1,
"contentType": "string",
"uploadedAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"assetTtlSeconds": 86400,
"media": {
"kind": "image",
{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"assetId": "9179b887-04ef-4ce5-ab3a-b5bbd39ea3c8",
"uploadUrl": "http://example.com",
"method": "PUT",
"contentType": "string",
"expiresIn": 0,
"completeUrl": "string"
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"url": "http://example.com",
"status": "ready",
"bytes": 1
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"model": "string",
"maximum": {
"currency": "USD",
"amount": "string"
},
"expectedRevision": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"taskId": "YOUR_TASK_ID"
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"status": "accepted",
"createdAt": "2019-08-24T14:15:22Z",
"taskId": "string"
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"taskId": "string",
"model": "string",
"status": "waiting",
"lifecycle": {
"phase": "pending",
"pollAfterSeconds": 0
},
"billing": {
"currency": "USD",
"origin": "usd",
"reservationId":
{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"taskId": "string",
"phase": "cancelled"
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"userId": "string",
"email": "string",
"name": "string",
"balance": {
"currency": "USD",
"amount": "string"
},
"reserved": {
"currency": "USD",
"amount": "string"
},
"funding": [
{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"scope": "account",
"period": {
"range": "today",
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"timezone": "UTC"
},
"charged": {
"currency": "USD",
"amount": "string"
},
"refunded"
{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}Alias for callBackUrl. If both fields are sent, they must match.
Optional USD ceiling as an exact decimal string. A quote above this amount returns HTTP 409 before generation. Legacy maxCredits does not set a USD ceiling.
Optional published model revision for optimistic concurrency checks.
{
"path": "string",
"url": "http://example.com",
"uploadUrl": "http://example.com",
"method": "PUT",
"contentType": "string",
"expiresIn": 900,
"confirmUrl": "string",
"assetTtlSeconds": 86400
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}{
"code": "string",
"message": "string",
"reason": "string",
"limit": 1,
"current": 0
}