API key and custom MCP clients
Use a Bearer API key with Streamable HTTP and verify the MCP handshake.
Choose authentication
For a custom client with OAuth support, add https://i2v.ai/api/mcp as a Streamable HTTP server and follow . For a script, backend, or token-based client, create an API key in and supply it from your secret store or I2V_API_KEY. Send the key only to the intended i2v.ai API host. The key's account limits and IP allowlist still apply.
Verify the remote handshake
curl -fsS https://i2v.ai/api/mcp \
-H "Authorization: Bearer $I2V_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
--data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"i2v-check","version":"1.0.0"}}}'Check the returned serverInfo and negotiated protocolVersion. An MCP SDK handles initialization and JSON or server-sent event responses. After initialization, call tools/list, then tools/call with name: list_models and arguments: {"mediaType":"image"}. Continue with the response's offset, limit, and total when listing all results.
Configure a client
Configure Codex to read the key from the environment that launches it.
codex mcp add i2v --url https://i2v.ai/api/mcp --bearer-token-env-var I2V_API_KEYFor other clients, set Authorization: Bearer YOUR_API_KEY through their credential settings. Check that the client's actual source IP matches an allowlist if you use one. Hosted clients may connect from their own network.
Query balances and usage over REST
curl -fsS 'https://api.i2v.ai/api/v1/account' \
-H "Authorization: Bearer $I2V_API_KEY"
curl -fsS 'https://api.i2v.ai/api/v1/account/usage?range=30d' \
-H "Authorization: Bearer $I2V_API_KEY"See for the reported amounts and authentication errors.

