# Quickstart

## Create an API key

Create a key in [your account](/me?section=api-keys). Web, REST and MCP use the same account USD balance. Keep the key on your server.

```bash
export I2V_API_KEY="YOUR_API_KEY"
export I2V_BASE_URL="https://api.i2v.ai"
export IDEMPOTENCY_KEY="$(uuidgen)"
```

Use `https://api.i2v.ai` as the REST origin, and send task requests under `/api/v1`. Read the [public media catalog](/api/v1/generation-models) for image and video models. `/api/v1/models` lists Chat Completions models.

To generate media in an AI client, start with the [MCP client guides](/docs/mcp). For terminal scripts and local files, use the [CLI and Agent Skills](/cli). To integrate media generation into your backend, follow the REST workflow below and see the [runnable API examples](https://github.com/i2v-ai/i2v-api-examples).

For persistent jobs and signed callbacks, see [SaaS and workflow integration](/docs/integration).

## Choose a model

Open the [model documentation](/docs/models) and select an image or video model. Each model page provides its public ID, accepted inputs, published USD prices, and cURL, Node.js and Python submission examples. Check any reference-image requirements before submitting.

## Quote the request

Send the model and inputs you intend to submit. A quote creates no task and reserves no funds. Review `maximum.amount` in the response before setting your spending ceiling. These commands use `jq`.

```bash
export I2V_MEDIA_REQUEST='{"model":"gpt-image-2","inputs":{"prompt":"A calm lake at sunrise"}}'
export I2V_QUOTE="$(curl --fail-with-body "$I2V_BASE_URL/api/v1/jobs/quote" \
  -H "Authorization: Bearer $I2V_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$I2V_MEDIA_REQUEST")"
printf '%s\n' "$I2V_QUOTE" | jq '{maximum, expectedRevision}'
```

## Submit a task

Set `I2V_MAX_COST_USD` to the USD decimal string you approve for this task. Carry the quoted `expectedRevision` and unchanged model inputs into the submission. If the revision or price changes, quote the request again and review the new amount.

```bash
export I2V_MAX_COST_USD="YOUR_APPROVED_USD_LIMIT"
export I2V_SUBMISSION="$(jq -ce \
  --arg cap "$I2V_MAX_COST_USD" \
  --argjson quote "$I2V_QUOTE" \
  'select($quote.expectedRevision | type == "number") |
   . + {maxCostUsd: $cap, expectedRevision: $quote.expectedRevision}' \
  <<< "$I2V_MEDIA_REQUEST")"
test -n "$I2V_SUBMISSION" && curl --fail-with-body "$I2V_BASE_URL/api/v1/jobs/createTask" \
  -H "Authorization: Bearer $I2V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data "$I2V_SUBMISSION"
```

A successful response contains `{"taskId":"YOUR_TASK_ID"}`. Keep the task ID, original idempotency key, and original request body. If the response is lost, [look up the submission receipt](/docs/media-workflow#recover-or-poll-with-python) using the original key and credentials. Replay the same request with the same body and key.

## Retrieve the result

```bash
curl "$I2V_BASE_URL/api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer $I2V_API_KEY"
```

| `status` | Meaning | What to do |
| --- | --- | --- |
| `waiting` | Accepted and queued; not yet sent upstream. | Keep polling. |
| `generating` | Upstream call is in flight. | Keep polling; video is slower than image. |
| `success` | Finished. | Read `output[].url`. |
| `fail` | Terminal failure. | Read `error.code` and `error.message`. |

**Polling guidance**

- Start at 2–5 seconds and increase the interval (for example ×1.5) up to about 30 seconds.
- A typical image returns in under a minute; a video usually takes 1–5 minutes, and long clips or busy upstreams can take longer.
- Treat `waiting` and `generating` as still-running; stop only on `success` or `fail`.
- Always call the same `taskId`; do not resubmit while polling, or you will create a second paid task.
- Add a client-side deadline (for example 30 minutes) and surface the task ID to your user instead of retrying blindly.

Successful response:

```json
{
  "taskId": "YOUR_TASK_ID",
  "model": "gpt-image-2",
  "status": "success",
  "output": [{ "url": "https://file.example.com/generated/YOUR_TASK_ID/display.png" }],
  "billing": {
    "currency": "USD",
    "status": "captured",
    "charged": { "currency": "USD", "amount": "0.07200000" }
  },
  "createTime": 1763520000000,
  "completeTime": 1763520060000
}
```

Failed response (reservation is released, nothing is charged):

```json
{
  "taskId": "YOUR_TASK_ID",
  "model": "gpt-image-2",
  "status": "fail",
  "error": { "code": "generation_failed", "message": "Generation failed" },
  "billing": {
    "currency": "USD",
    "status": "released",
    "charged": { "currency": "USD", "amount": "0.00000000" }
  }
}
```

For successful media tasks, read `output[].url`. The `output` field can be null while the task is pending or if it fails.

The [API reference](/docs/api) describes every field. Configure [webhooks](/docs/webhooks) to receive signed completion events instead of polling. See [errors and retries](/docs/errors) when a submission response is lost.

See the [media workflow and recovery guide](/docs/media-workflow) for signed uploads, request-specific USD quotes, and recovering lost submissions.