# Generation and recovery

## Plan a first task

1. Use `recommend_models` for a task and its constraints, or look up a named model with `get_model_params`. `list_models` has `mediaType`, `category`, `search`, `limit`, and `offset` filters.
2. Build inputs against the selected model's contract. Supply a reachable HTTPS reference or upload an approved file as described below.
3. Send `modelId` and `inputs` to `prepare_generation`. Read `maximumReservation`, `normalized`, and `expectedRevision`. Resolve `review_adjustments` or `over_budget` before submitting. Preflight checks the request and price without uploading or reserving funds.
4. Once the user approves, submit `create_task` with the same `modelId` and `inputs`, approved `maxCostUsd`, `expectedRevision`, and a stable `idempotencyKey`. For OAuth submissions that should be recoverable, also set `recoveryScope: "connection"`. Keep the task ID and submission key.
5. Check the same ID with `get_task`, using a backoff between polls. When successful, use the returned output URLs. The local stdio wrapper can save them into your configured workspace.

An approved budget is a decimal USD string, such as `"0.25000000"`. A model revision change requires a fresh plan. The service reads the current account quote again at submission and rejects a quote above the cap. Eligible free-model entitlements can yield an explicit zero USD quote. See [USD billing](/docs/billing) for reservations and settlement.

## Upload a reference

Call `create_upload_url` with `fileName`, `contentType`, and `fileSize`. PUT exactly those bytes using the supplied `Content-Type`, then call `complete_upload` with `assetId`. Use the verified asset URL in your model inputs. Send the API key only to i2v.ai. The signed storage upload uses its own credentials. With local stdio, `upload_file` handles these steps for an allowed workspace path.

## Find the original task after a lost response

If you have a task ID, call `get_task`. If you only have the original idempotency key, call `recover_submission` using the same API key or original OAuth client. For OAuth, the original submission must have opted into connection recovery.

| Receipt status | Next action |
| --- | --- |
| `accepted` | Continue with the returned task ID. |
| `pending` or `not_found` | Continue checking the original submission. Preserve the key while acceptance is unknown. |
| `retryable` | Wait as instructed, then replay the same payload with the same key. |
| `rejected` | Review the original error before deciding on a corrected request. |

Keep every submission field the same on an exact replay, including revision, budget, and recovery scope. `waiting` and `generating` indicate that the task is still pending or running. A local wait can end while the task continues. See [errors and retries](/docs/errors) for shared error semantics.

## Receive completion callbacks

For server-side notifications, configure a signing secret in [developer settings](/settings/developer), then send `callBackUrl` alongside `modelId` and `inputs` to `create_task`. Verify the signature and deduplicate event IDs before processing a callback. Delivery retries and settlement are independent. See [Webhooks](/docs/webhooks) and the [REST media workflow](/docs/media-workflow).