Models and API keys

Choose an agent engine

Settings → AI model lets you choose Claude Code or Codex. The selected engine builds and edits Studio projects. Changing engines starts a fresh agent session, while keeping the same project files and chat.

• Claude Code → Anthropic API key, Claude subscription, or an Anthropic Messages-compatible gateway.
• Codex → OpenAI API key, ChatGPT subscription, or an OpenAI Responses-compatible gateway.
• Choose the engine first: it determines which provider connection Poko can use.

Option 1: use Poko Engine

Choose Poko credits when you want Poko to manage routing and billing without adding a provider key.

• Poko Pulse is tuned for quality-first video builds.
• Poko Flow is for faster edits and iteration.

Your Poko balance is charged at the published Poko Engine rate. This is the simplest setup: select Poko credits, choose the model that fits the job, and start a new generation.

Poko Engine: when to choose each route

• Use Poko Pulse when the agent needs to plan a complete video, inspect a larger source pack, establish visual direction, or make a substantial revision. It prioritizes the stronger first pass.
• Use Poko Flow when you already have a project and want a shorter edit cycle: rewrite a line, change a scene treatment, adjust a CTA, test a visual direction, or make several focused follow-up edits. Select a Priority variant only when the faster processing path is important for your delivery deadline.

Option 2: add your own provider key

Choose Bring your own key, then add the key for the active engine: an Anthropic API key for Claude Code or an OpenAI API key for Codex. Save the setting before you begin the next agent run.

Your provider bills model usage directly when its key is active, and Poko credits are not used for that agent request. Background music and sound effects are the exception: they continue to use Poko credits. BYOK requires an eligible plan.

Direct provider key: step by step

The engine and key must match. An Anthropic key cannot power Codex, and an OpenAI key cannot power Claude Code. If both a provider key and a personal subscription are connected, the API key wins until you remove it.

1. Stop any active agent run.
2. Open Settings → AI model.
3. Choose Claude Code for an Anthropic key or Codex for an OpenAI key.
4. Select Bring your own key.
5. Paste the provider key for the selected engine.
6. Wait for Poko to save the setting, then start a new Studio request.

Connect a personal subscription

On eligible Pro and Agency plans, you can connect a Claude or ChatGPT subscription instead of pasting an API key. In Settings → AI model, select the relevant engine, choose Bring your own key, then select Connect and complete the browser sign-in.

A pasted provider key takes priority over a connected subscription. Remove the API key if you want the connected subscription to be used instead. Subscription usage remains subject to the provider’s own terms and limits.

Use a gateway for more models

A gateway lets you route an agent through a provider or proxy that exposes the API required by the selected engine. This is how you can use compatible current models outside the built-in catalog, including Qwen coder models or GLM Flash models when your gateway exposes them.

OpenRouter and OpenCode Zen are examples of hosted gateways. OpenCode, Ollama, LM Studio, or a private proxy can also work only when they expose the required API surface. Set Bring your own key, then enter the gateway Base URL, API key, and exact provider model ID in Settings → AI model. Gateway routing requires an eligible Pro or Agency plan.

Gateway setup: step by step

Poko sends the configured model ID exactly as entered. This makes model aliases and provider-specific names usable, but it also means a typo is rejected or fails at the provider. Keep a known-good model ID in your notes before switching to a newly released model.

1. Confirm your plan includes gateway routing.
2. Choose the agent engine that matches your gateway API.
3. Select Bring your own key.
4. In AI gateway, paste the API version root—not a chat page or provider dashboard URL.
5. Add the gateway API key and exact model ID shown by that gateway.
6. Start a small test request before using the configuration on a large project.

Gateway compatibility matters

• Codex requires an endpoint that implements OpenAI’s native Responses API, including POST /responses, streamed Responses events, and the native tools Poko sends.
• Claude Code requires an endpoint that implements Anthropic’s native Messages API, including POST /v1/messages and tool streaming.

A Chat Completions-only endpoint is not sufficient. Standard Ollama and LM Studio servers are not compatible with the Claude Code gateway unless you place a compatible proxy in front of them. Check the gateway documentation before adding a model.

OpenRouter: use its Responses API with Codex

OpenRouter supports the OpenAI-compatible Responses API at https://openrouter.ai/api/v1/responses. In Poko, select Codex and enter the API version root, https://openrouter.ai/api/v1, as the Base URL. Poko then sends the required /responses request.

Enter your OpenRouter API key and use the exact provider-prefixed model ID from the OpenRouter catalog. For example, a Qwen or GLM model ID normally includes the provider namespace. Model availability and tool support are model-specific, so check the catalog before selecting a new release.

Agent engine: Codex
Billing mode: Bring your own key
Base URL: https://openrouter.ai/api/v1
API key: your-openrouter-api-key
Model: <exact provider/model ID from OpenRouter>

Poko sends: POST /responses

OpenCode Zen: choose the endpoint for your engine

OpenCode Zen publishes separate endpoints for the two agent protocols.

• Codex: Use its OpenAI Responses endpoint at https://opencode.ai/zen/v1/responses. In Poko, enter https://opencode.ai/zen/v1 as the Base URL so Poko can send POST /responses.
• Claude Code: Use OpenCode Zen’s Anthropic Messages endpoint at https://opencode.ai/zen/v1/messages. Enter https://opencode.ai/zen as the Base URL so the client reaches POST /v1/messages.

OpenCode Zen lists Qwen models on its Messages surface and GPT-family models on its Responses surface; select the engine that matches the endpoint rather than mixing the two.

Codex
Base URL: https://opencode.ai/zen/v1
Request endpoint: POST /responses

Claude Code
Base URL: https://opencode.ai/zen
Request endpoint: POST /v1/messages

Examples: Qwen and GLM Flash

These examples show the values to enter after you have selected the matching agent engine and confirmed that your gateway supports its required API. Model IDs are supplied by your gateway, so use its exact spelling rather than assuming every provider exposes the same name.

Billing mode: Bring your own key
Base URL: https://your-gateway.example/v1
API key: your-gateway-api-key
Model: qwen3-coder

# Another compatible gateway model example
Model: z-ai/glm-4.5-flash

Example workflows

Match the model and request size to the job. Start new configurations with a narrow task, then use the same model for a larger build only after it produces a reliable result.

• Product launch: Use Poko Pulse for the first build, then Poko Flow for captions, visual swaps, and CTA variations.
• Coding-heavy brief: Use a compatible Qwen coder model through your gateway. Ask it to summarize story beats before it builds.
• Rapid draft: Configure compatible GLM Flash only after you confirm the exact model ID and required API support. Start with a focused prompt and review the plan first.

Choosing a model for a new release

New model releases can be useful, but model availability, model IDs, supported tools, context limits, and gateway compatibility vary by provider. Add a new model to your gateway first, then use its exact ID in Poko and test it against a small project.

Do not change the model halfway through an active agent session. Stop the session, update the setting, and begin a fresh run. The project and its chat remain available, so tell the new run what you want to continue or revise.

Credentials and priority

• For Claude Code, an Anthropic API key takes priority over a connected Claude subscription.
• For Codex, an OpenAI API key takes priority over a connected ChatGPT subscription.
• A configured gateway is used when its Base URL, API key, and model fields are all present.

Troubleshooting provider connections

• Configuration unavailable: Select Bring your own key, then check that your plan includes the connection type.
• Direct key fails: Confirm the key belongs to the selected provider and has not been revoked.
• Gateway fails: Verify the API version root, key, and exact model ID against the gateway catalog.
• API compatibility: Codex needs Responses API; Claude Code needs Messages API. A working Chat Completions request does not prove either requirement.
• Works in one engine only: Switch to the engine matching the provider’s compatible API.

Audio exception

Background music and sound effects continue to consume Poko credits even when an AI model uses your own key. Check your selected billing mode before generation.