Kimi K3 API Migration Acceptance Checklist 2026

As of July 28, 2026, the official Kimi K3 API documents three reasoning settings: low, high, and max. It also requires the complete assistant message to be preserved across multi-turn tool calls, not just the visible text. See the official Kimi K3 quickstart.

Do not move production traffic after one successful text request. Finish contract tests first, replay real Agent tasks with shadow traffic, then use a reversible canary. Keep the official API or another confirmed endpoint as your baseline. Leave any not-yet-confirmed provider in the pending queue.

This Kimi K3 API migration acceptance checklist is for:

• Teams already using the official Kimi K3 API and adding a backup provider.
• Platform engineers moving another model or endpoint to Kimi K3.
• Technical leads responsible for tool execution, cost controls, reliability, privacy, and rollback.

Freeze the baseline before you compare providers

A provider migration becomes difficult when the team changes three things at once:

1. The model endpoint.
2. The prompt or agent policy.
3. The application code.

Freeze the first two before changing the third. Export the current production configuration into a versioned test fixture. Record:

• Current base URL and model identifier.
• Authentication method and key scope.
• Request timeout and connection timeout.
• Retry count, retry delay, and backoff policy.
• Streaming enabled or disabled.
• Maximum output token setting.
• Reasoning setting.
• Tool definitions and tool_choice behavior.
• Structured output schema.
• Image or video input format.
• Fields used by billing, tracing, and audit logs.
• The exact assistant message stored between turns.

Kimi K3 is not a plain text-only migration. Moonshot AI describes it as a multimodal model with a 1-million-token context window. Its published model card lists 2.8 trillion total parameters and 16 activated experts out of 896 per token. Those figures describe the model, not the behavior of a hosted endpoint. They do not tell you whether a provider preserves stream events, tool-call IDs, or usage accounting in the same way. (huggingface.co)

Create a provider status sheet before writing adapter code:

The official Kimi page uses kimi-k3 and the Moonshot endpoint https://api.moonshot.ai/v1. The Fireworks model page lists its own Kimi K3 model path. Together AI may publish a model page before your account, region, plan, or API path can serve the model reliably. Do not turn a public listing into a production approval without an authenticated request and a documented response.

Use the SpinMac help resources when you need a repeatable Mac-based development or CI environment for the test harness. The machine is not the acceptance result. It is the controlled place where you reproduce it.

Run the first contract test against every endpoint

The first test should use the same minimal request against the baseline and every candidate. A successful answer is only one assertion.

Build a small request matrix. Start with authentication, model selection, and basic message handling. Then add the fields your Agent actually uses.

curl -sS "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "$MODEL_ID",
    "messages": [
      {"role": "user", "content": "Return the word ACCEPTANCE only."}
    ],
    "reasoning_effort": "low",
    "stream": false
  }' | jq .

Capture the raw response. Do not normalize it before saving the evidence. You need to see whether the provider returns:

• The expected model identifier.
• A stable response ID.
• A usable assistant message.
• A finish reason that your application understands.
• Input and output usage fields.
• Reasoning content in the expected location.
• A valid error object when the request is rejected.

The official Kimi documentation separates reasoning content from final-answer content during streaming. It also says structured output should constrain message.content, not reasoning_content. That distinction matters if your parser, token counter, or safety filter assumes every generated field is ordinary text. (platform.moonshot.ai)

Test streaming separately:

from openai import OpenAI

client = OpenAI(
    api_key="test-key",
    base_url="https://candidate.example/v1",
)

stream = client.chat.completions.create(
    model="candidate-model-id",
    messages=[{"role": "user", "content": "Give one short sentence."}],
    stream=True,
)

for chunk in stream:
    choice = chunk.choices[0]
    delta = choice.delta

    if getattr(delta, "reasoning_content", None):
        print(delta.reasoning_content, end="", flush=True)

    if getattr(delta, "content", None):
        print(delta.content, end="", flush=True)

A provider passes this stage only when your client can distinguish reasoning events, final content, terminal events, and interrupted streams. Do not assume that an OpenAI-compatible SDK creates OpenAI-compatible semantics.

Your negative tests should include:

• Invalid API key.
• Unknown model ID.
• Malformed JSON.
• Missing messages.
• Invalid tool schema.
• Unsupported response format.
• Oversized input.
• Forced timeout.
• Cancelled stream.
• Provider-side rate limit.

Store the HTTP status, provider error code, message, retry headers, and request ID for each failure. A generic 500 response may be acceptable during an isolated provider fault. A permanent schema mismatch is not.

Prove Agent behavior with preserved state and tools

This is where a migration that looked successful often fails.

Kimi K3 uses preserved thinking history for multi-turn conversations and tool calls. The official documentation instructs developers to pass the complete assistant message back into the next request. A wrapper that stores only content can silently break the second turn. (huggingface.co)

Test one complete tool loop before testing a full Agent:

import json

tools = [{
    "type": "function",
    "function": {
        "name": "lookup_ticket",
        "description": "Find a support ticket by ID.",
        "parameters": {
            "type": "object",
            "properties": {
                "ticket_id": {"type": "string"}
            },
            "required": ["ticket_id"],
            "additionalProperties": False
        }
    }
}]

first = client.chat.completions.create(
    model="candidate-model-id",
    messages=[
        {"role": "user", "content": "Check ticket T-1042."}
    ],
    tools=tools,
    tool_choice="required",
)

assistant_message = first.choices[0].message
messages = [
    {"role": "user", "content": "Check ticket T-1042."},
    assistant_message,
]

for call in assistant_message.tool_calls or []:
    arguments = json.loads(call.function.arguments)

    result = {
        "ticket_id": arguments["ticket_id"],
        "status": "open"
    }

    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": json.dumps(result)
    })

second = client.chat.completions.create(
    model="candidate-model-id",
    messages=messages,
    tools=tools,
)

Your acceptance record should show:

• The tool name selected.
• The exact JSON arguments.
• Whether required fields are present.
• The tool-call ID.
• The order of parallel calls.
• The assistant message returned to the next turn.
• The final termination reason.
• The behavior when the tool returns an error.
• The behavior when the same request is retried.

Use at least five fixture classes:

1. A normal single tool call.
2. Two independent calls that may run in parallel.
3. A malformed argument response.
4. A tool timeout.
5. A repeated request after a network interruption.

External side effects need an idempotency key or an equivalent deduplication guard. If a retry can send the same email, create the same ticket, submit the same payment, or deploy the same artifact twice, the endpoint is not ready for production even if the response quality is high.

Vision and structured output need separate tests. The Kimi documentation specifies array-based multimodal content for vision requests and strict JSON schema handling for structured output. Do not test only text prompts and then infer that image inputs or JSON contracts will behave identically. (platform.moonshot.ai)

Use shadow traffic before a canary

Shadow testing answers a different question from contract testing.

Contract testing asks whether the endpoint follows the shape your code expects. Shadow traffic asks whether it completes your real work.

Copy a controlled set of redacted production tasks to the baseline and candidate at the same time. Do not let the candidate response reach users, trigger tools, write to databases, or send notifications. Compare:

• Task completion.
• Required fields.
• JSON parsing success.
• Tool selection.
• Number of turns.
• Long-context state retention.
• Vision interpretation.
• Human review score.
• Timeout and interruption behavior.
• Cost per completed task.

Use your own workload. Include code changes, document extraction, image review, research workflows, and tool chains if those are part of your product. Public benchmark results can help you understand the model, but they cannot replace an Agent replay set built from your failure modes.

A useful shadow record contains:

case_id
input_hash
provider
model_id
prompt_version
tool_schema_version
response_status
finish_reason
tool_call_count
parse_status
latency_bucket
retry_count
estimated_cost
review_label
reproduction_notes

Redact secrets before sending any copied task. Remove customer identifiers, access tokens, private repository content, and unneeded attachments. Check the provider terms and privacy documentation rather than relying on a sales page. Your data handling and privacy reference can help structure the environment-side review, but it does not replace the model provider's own data terms.

Acceptance warning: A lower output price can be offset by longer reasoning traces, more retries, failed tool calls, or extra routing logic. Measure cost per completed business task, not cost per successful HTTP response.

Do not advance a candidate because it wins a generic benchmark. Advance it because your representative workload has an explainable result and every critical failure has a reproduction record.

Move only low-risk traffic into a reversible canary

After contract and shadow tests pass, choose a traffic slice that can be reversed without data repair.

Good first candidates include:

• Read-only research jobs.
• Asynchronous document classification.
• Internal developer assistants.
• Non-customer-facing report drafts.
• Replay jobs with no external side effects.

Avoid starting with payment actions, account changes, destructive maintenance, or user-visible long-running workflows.

Define the routing rule outside the Agent prompt. The router should record the selected provider, model ID, request hash, and fallback decision.

def choose_provider(task):
    if task.is_destructive:
        return "official"

    if task.requires_vision and not task.candidate_supports_vision:
        return "official"

    if task.risk_level == "low" and task.canary_enabled:
        return "candidate"

    return "official"

Then test failure switching deliberately. Simulate:

• Connection timeout.
• HTTP rate limit.
• Empty response.
• Stream ending before the final message.
• Tool-call parse failure.
• Candidate model unavailable.
• Candidate authentication failure.

The fallback must preserve the original task state. It must not replay a completed external action. For asynchronous jobs, use a durable job ID and provider attempt number. For interactive sessions, record whether the candidate produced an assistant message that is safe to pass to the official endpoint. If the provider's reasoning format differs, you may need to restart from the last application-level checkpoint rather than forwarding the raw message.

Set a rollback condition before the canary begins. Examples include:

• Any critical tool call executes twice.
• Any required structured output fails parsing.
• A candidate-specific outage exceeds the approved window.
• Sensitive data handling cannot be verified.
• Cost per completed task becomes unexplainable.
• The fallback path cannot be demonstrated in a controlled test.

A provider page may state infrastructure availability, but that does not prove your account has the same access, limits, or behavior. Fireworks currently presents a Kimi K3 endpoint on its official model page and related documentation. Treat that as a candidate to verify, not as evidence that every feature matches the official API. (fireworks.ai)

For Together AI, keep the candidate in a pending state until your review confirms the official model page, authenticated endpoint, documentation, feature support, rate limits, and commercial terms at the same time. Do not fill missing price or limit fields with forecasts.

Reconcile real cost and governance during the first week

The first week is an operations review, not another benchmark.

Record the following for each task class:

• Input tokens.
• Output tokens.
• Cached input, if reported.
• Reasoning-related usage, if reported.
• Retry count.
• Failed request count.
• Partial stream count.
• Tool-call count.
• Human review time.
• Router and observability overhead.
• Storage and log retention cost.
• Engineering time spent maintaining the adapter.

The official Kimi API documentation states that access requires a successful top-up of at least $1 and that account tier affects concurrency, requests per minute, tokens per minute, and tokens per day. Those controls are operational constraints, not just billing details. Record the tier and limit state used during testing. (platform.moonshot.ai)

Do not create a comparison row for a price that has not been formally published. Mark it as pending, attach the source URL, and add an owner and review date. A blank cell is more trustworthy than a predicted number presented as a quote.

Governance checks should include:

• Data retention period.
• Training-use policy.
• Processing region.
• Subprocessor disclosure.
• Log access controls.
• Key rotation.
• Audit log availability.
• Account deletion process.
• Incident notification terms.
• Dedicated capacity terms, if required.

If any critical governance answer is missing, the candidate can remain useful for non-sensitive testing but should not receive production traffic.

Sign off with a branch-based decision

Use these conditions instead of a single overall score:

• If authentication, model ID, streaming, error handling, usage fields, tools, structured output, and multi-turn state all pass, then continue to shadow traffic. Otherwise, keep the current endpoint and open a compatibility defect.
• If shadow traffic passes on your own critical task set and every failed sample is reproducible, then begin a low-risk canary. Otherwise, return to adapter or prompt isolation.
• If rollback completes without duplicate side effects and preserves task state, then permit a controlled traffic increase. Otherwise, use the candidate only as a non-production fallback.
• If cost per completed task is explainable and governance evidence is complete, then consider primary or active-passive operation. Otherwise, keep the provider in dual-track mode.
• If a provider's availability, pricing, limits, or data terms remain unclear, then leave it pending. Do not make uncertainty a production dependency.

The final sign-off should name one of three outcomes:

1. Switch: the candidate can receive approved production traffic.
2. Dual track: the official endpoint remains primary while the candidate handles bounded workloads.
3. Pause: the current endpoint stays in place until a blocking issue or missing provider fact is resolved.

Keep the test suite after launch. Kimi K3 model versions, hosted implementations, limits, and response behavior can change independently. Run contract tests after provider changes and replay a smaller regression set on a fixed schedule.

The better production environment is the one you can reproduce

An API migration also exposes weaknesses in the development environment. The current setup may rely on a single laptop, inconsistent local dependencies, fragile SSH access, or a CI runner that cannot reproduce the same Agent replay and rollback tests. Those are real drawbacks when you need daily shadow traffic, scheduled regressions, and controlled provider failover.

A cloud Mac environment does not replace provider acceptance, and it is not the right fit for every workload. Long-term, steady, high-volume inference may justify dedicated infrastructure. Workflows that require physical devices or local peripherals may also need on-site hardware. But for temporary migration work, macOS-based Agent development, automated regression, and parallel endpoint testing, renting a reproducible Mac environment can be easier to audit than sharing one developer machine.

After you complete the Kimi K3 API migration acceptance process, check whether your Mac development and CI setup can reproduce the same fixtures, logs, secrets handling, and rollback drills. If local capacity is the bottleneck, review the available SpinMac environments before committing to a longer test cycle.