iCreat API Setup Guide

Claude Code

Claude Code is an AI coding agent designed specifically for software development. You can communicate with it using natural language, just like talking to a human developer, with virtually no learning curve.

Simply describe your idea, and Claude Code can help implement it while you enjoy a cup of coffee.

Supported IDEs

• Visual Studio Code (including popular forks such as Cursor and Windsurf)

• JetBrains IDEs (PyCharm, WebStorm, IntelliJ IDEA, GoLand)

api.icreat.ai Safe Invocation Guide for AI Agents

This document is intended for AI platforms, agents, and workflow systems that can automatically invoke APIs, including but not limited to WorkBuddy, OpenClaw, custom agent frameworks, tool-calling LLM platforms, and desktop automation systems.

The goal of this document is simple:

• Help agents call api.icreat.ai correctly

• Prevent duplicate generation and duplicate billing caused by repeated submissions, incorrect retries, or misclassified missing responses

• Define best practices for synchronous endpoints, asynchronous endpoints, task polling, and retry boundaries

Core Principles

Single-Submission Principle

For the same logical job, an agent must issue at most one create-type request at a time.

This principle does not forbid intentional repeated calls, batch calls, or concurrent calls requested by the user. It only forbids an agent from resubmitting the same create-type request for the same logical job because of misclassification, timeout, uncertainty, or missing UI feedback before the current request has a response or a terminal state.

The same logical job must not be submitted again in any of the following states:

• The request has been sent and the first HTTP response has not yet arrived

• A “task created” response has already been received, but the task is not finished

• A task_id, job_id, request_id, or equivalent task identifier has already been received and the agent is now checking status

• The final outcome is unknown and the agent cannot confirm whether the upstream has accepted the request

If the user explicitly requests multiple generations, batch processing, or concurrent execution, the agent must assign a separate logical_job_id to each independent call and track its state, response, task ID, and billing risk separately.

Allowed Repeated and Concurrent Calls

The following behaviors are allowed:

• The user explicitly asks to “generate 5 different versions”

• The user explicitly asks to “run 10 calls concurrently”

• The user asks to process multiple files, inputs, or prompts separately

• A previous task returned a clear failure response and the user asks to “try again”

• Each call has its own logical_job_id and idempotency identity

Accidental Duplicate Calls to Avoid

The following behaviors should be avoided:

• Resubmitting while the same logical_job_id has not received a response

• Calling submit again after an async task has already returned a task_id

• Recreating a task after a status query fails

• Automatically resubmitting because the network is slow or the UI has not changed

• Making implicit duplicate calls without clear user intent or a new task identity

Wait-for-Response Principle

Once a request is sent, the agent must wait for its result.

For the purpose of this guide, all of the following count as a response:

• A success response

• A failure response

• An error response

Important notes:

• An error response does not mean the agent should immediately retry

• “Still waiting” does not mean “the call failed”

• A long wait does not mean the agent may submit again

Conservative Unknown-State Principle

If a timeout, disconnection, or gateway interruption prevents the agent from determining whether the upstream has accepted the request, the agent must enter unknown or timeout_unknown.

In that state, the agent must not automatically submit the same create-type request again.

It may only do one of the following:

• Query the status of an existing task

• Check logs or request records

• Ask the user whether to retry

• Retry safely with idempotency guarantees

Endpoint Categories

Before invoking any endpoint, the agent must determine what kind of endpoint it is calling.

Synchronous Endpoints

Characteristics:

• One HTTP request maps directly to one HTTP response

• The response body directly contains a result or an error

• No follow-up task polling is required

Typical synchronous endpoint examples:

• POST /v1/chat/completions

• POST /v1/completions

• POST /v1/embeddings

• POST /v1/moderations

• POST /v1/images/generations

• POST /v1/images/edits

• POST /v1/audio/speech

• POST /v1/audio/transcriptions

• POST /v1/audio/translations

• POST /v1/responses

• POST /v1/responses/compact

Correct behavior for these endpoints:

• Send exactly one request

• Continue waiting for the response

• Make the next decision only after the HTTP response arrives

• Never submit the same job again before the response arrives

Asynchronous Submission Endpoints

Characteristics:

• The first request only creates a task

• The response typically contains a task_id, job_id, request_id, or equivalent identifier

• The final result must be queried using a status endpoint or result endpoint

Typical asynchronous endpoint examples:

• POST /cs2/v1/video/submit

• Other async submit endpoints for video, image, or audio generation

Correct behavior for these endpoints:

• Submit exactly once

• If a task_id, job_id, or request_id is returned, save it

• Poll for status afterward instead of resubmitting

• Continue until the task reaches a terminal state

Status Query Endpoints

Characteristics:

• Used only to read the state of an existing task

• Must not create a new task

• May be called repeatedly while the task is unfinished

Typical status endpoint examples:

• GET or POST variants of /status

• GET or POST variants of /result

• Other /fetch, /query, /status, or /result paths

Correct behavior for these endpoints:

• Polling is allowed

• They should not incur new creation cost

• They do not replace submit endpoints

• A failed status query must not be interpreted as “submit again”

Required Agent State Machine

Each logical job must have a local state machine.

Recommended states:

• idle: not submitted yet

• submitting: request sent, waiting for the first HTTP response

• accepted: upstream accepted the task and returned a task identifier

• polling: polling task status

• success: task completed successfully

• failure: task completed with failure

• error: request returned an error response

• timeout_unknown: timed out and it is unclear whether the upstream accepted the request

• cancelled: cancelled by the user

Mandatory rules:

• No resubmission in submitting

• No resubmission in accepted

• No resubmission in polling

• No automatic resubmission in timeout_unknown

Correct Call Flows

Correct Flow for Synchronous Endpoints

1. Build the request

1. Generate a local logical_job_id

1. Set the job state to submitting

1. Send one HTTP request

1. Wait for the HTTP response

1. Transition based on the outcome:

• success

• failure

• error

1. Do not create the same request again before the current one finishes

Correct Flow for Asynchronous Endpoints

1. Build the request

1. Generate a local logical_job_id

1. Set the job state to submitting

1. Send one submit request

1. Wait for the submit response

1. If the response contains a task_id, job_id, or request_id

• Store that identifier

• Change the state to accepted

1. Poll the status endpoint while the task is:

• queued

• processing

• in_progress

1. Stop when a terminal state is reached:

• success

• failure

• error

What Counts as “A Response”

For an agent, all of the following must be treated as “a response has already arrived”:

• HTTP 2xx with a parseable body

• HTTP 4xx

• HTTP 5xx

• A normalized error object

• An upstream task failure status

• A clear message such as task not found, invalid parameters, or authentication failure

The following may be treated as “no confirmed response yet”:

• TCP connection interruption

• TLS handshake failure

• Local timeout with no response headers or body at all

• A network failure where the service may or may not have received the request

Even in those cases, the agent must not directly resubmit.

Retry Rules

Cases Where Limited Automatic Retry Is Allowed

Automatic retry is only acceptable for:

• Read-only requests

• Status query requests

• Clearly idempotent GET requests

• Early network failures where the agent can confirm the upstream never received the request

Cases Where Automatic Retry Is Forbidden by Default

Automatic retry is forbidden by default for:

• Text-to-image generation

• Image-to-image generation

• Video generation

• Audio generation

• Any submit, create, or generate endpoint

• Potentially billable model invocations

• Any create-type request already sent but not yet conclusively resolved

Preconditions for Retrying Create-Type Requests

A create-type request may only be attempted again if at least one of the following is true:

• The user explicitly asked to “try again”

• The previous request returned a clear failure response and the business workflow allows retry

• A strong idempotency mechanism guarantees no duplicate creation

• It has been confirmed that the upstream never accepted the previous request

Idempotency Requirements

All agents are strongly encouraged to attach at least one of the following identifiers to create-type requests:

• Idempotency-Key

• X-Request-Id

• client_request_id

• logical_job_id

Requirements:

• The same logical job must use the same idempotency identifier for its entire lifecycle

• If a retry is absolutely required after a timeout, it must reuse the same identifier

• A new business request identifier must not be generated on every retry

Purpose:

• Prevent duplicate creation

• Prevent duplicate billing

• Make log analysis easier for the platform side

• Help the agent recover task state safely

Minimum Agent Implementation Requirements

Every agent integrating with api.icreat.ai should implement at least the following:

• A local logical_job_id

• An in-flight lock

• Endpoint classification for submit vs. status

• No resubmission before a response arrives

• Terminal state recognition

• Unknown-timeout handling

• Idempotency key reuse

• Structured logging

Recommended minimum log fields:

• logical_job_id

• request_id

• task_id

• endpoint

• method

• submit_time

• first_response_time

• final_status

• http_status

• retry_count

• idempotency_key

Recommended Pseudocode

Create or Synchronous Call

function execute_job(job):
    if job.state in [submitting, accepted, polling]:
        return "job already in progress, do not resubmit"

    job.logical_job_id = get_or_create_job_id(job)
    job.idempotency_key = get_or_create_idempotency_key(job)
    job.state = submitting

    response = send_once(job)

    if response.network_unknown:
        job.state = timeout_unknown
        return "unknown result, do not auto-resubmit"

    if response.http_error_or_business_error:
        job.state = error
        return response

    if response.contains_task_id:
        job.task_id = response.task_id
        job.state = accepted
        return poll_until_terminal(job)

    job.state = success_or_failure_based_on_response
    return response

Asynchronous Polling

function poll_until_terminal(job):
    job.state = polling

    while true:
        status = fetch_status(job.task_id)

        if status in [queued, processing, in_progress]:
            wait()
            continue

        if status == success:
            job.state = success
            return status

        if status in [failure, error]:
            job.state = failure
            return status

        if status is unknown:
            return "keep polling or escalate, do not resubmit submit request"

Explicitly Forbidden Incorrect Patterns

The following behaviors are explicitly forbidden:

• Calling the same prompt or job repeatedly before any response arrives

• Submitting again just because the first submit seems slow

• Misclassifying “still processing” as “failed” for async tasks

• Using a status endpoint as if it were a submit endpoint

• Treating submit failure and status query failure as the same thing

• Creating a brand-new task immediately after a timeout

• Generating a new idempotency key for each retry

• Continuing without saving task_id, job_id, or request_id

• Automatically repeating high-cost calls without user confirmation

• Launching multiple concurrent submissions for the same generation job

Note: If the user explicitly requests batch generation or concurrent execution, and the agent creates a separate logical_job_id for each call, it is not considered an incorrect pattern under this section.

Strong Prompt for Agents

If this guide needs to be embedded directly into an agent instruction set, the following short prompt is recommended:

You are calling a cost-sensitive API platform.

Rules:
1. Never submit the same logical job more than once while the previous request is still in flight.
2. Wait for the first HTTP response before deciding the next action.
3. If the API is async and returns a task_id, store it and poll status endpoints instead of resubmitting.
4. Timeout without confirmation is an unknown state, not a failure. Do not auto-resubmit.
5. Only retry create/submit requests when the user explicitly asks, or when idempotency guarantees safety.
6. Any success, failure, or error HTTP response counts as a response.
7. Status polling may repeat; task creation may not.

Integration Recommendations

Integrators should implement two layers of protection.

Layer 1: Agent-Side Duplicate Prevention

• One submit per logical job

• In-flight locking

• Local state machine

• Idempotency key reuse

Layer 2: Server-Side Safeguards

• Support Idempotency-Key

• Return the original result or existing task on duplicate create requests

• Reject duplicate in-progress requests with the same idempotency identity

• Provide request and task status lookup capabilities

One-Sentence Summary

For every high-cost create-type request on api.icreat.ai, the best practice is always:

• Submit once

• Wait for the response

• If asynchronous, store the task ID and poll

• Never create the same task again before a clear terminal state is known

Claude Code Setup Guide

The King of Stability, Cost Efficiency, and Reputation

Official Website

Visit the official iCreat platform to create and manage your API Keys.

Key Advantages

• No VPN Required — Direct access from both domestic and international networks with fast response times.

• Transparent Cache Billing (Exclusive) — Every request is clearly recorded and verifiable through third-party monitoring tools.

• High Cache Hit Rate Technology (Exclusive) — Significantly reduces token consumption and improves efficiency.

• Enhanced Error Compatibility (Exclusive) — Better handling of common official API errors.

• Third-Party Client Support — Compatible with Roo Code, Kilo Code, Cherry Studio, and ChatBox.

• Official Package Installation Support — Works through environment variable configuration.

Installation

Install the official Claude Code package:

npm install -g @anthropic-ai/claude-code
claude --version

Windows Configuration

Recommended Method: Configure settings.json

Create or edit:
C:\Users\<username>.claude\settings.json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.icreat.ai/",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

Temporary Environment Variables

# PowerShell
$env:ANTHROPIC_BASE_URL="https://api.icreat.ai/"
$env:ANTHROPIC_AUTH_TOKEN="your api key"

# CMD
set ANTHROPIC_BASE_URL=https://api.icreat.ai/
set ANTHROPIC_AUTH_TOKEN=your api key

Permanent Environment Variables

Create:

[System.Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://api.icreat.ai/', 'User')
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', 'Your API Key', 'User')

Restart the terminal for changes to take effect.

macOS Configuration

Recommended Method: Configure settings.json

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "Your API Key",
    "ANTHROPIC_BASE_URL": "https://api.icreat.ai/",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

Temporary Configuration

export ANTHROPIC_BASE_URL="https://api.icreat.ai/"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"

Permanent Configuration

# For Bash:
echo 'export ANTHROPIC_BASE_URL="https://api.icreat.ai/"' >> ~/.bash_profile
echo 'export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"' >> ~/.bash_profile

# For Zsh:
echo 'export ANTHROPIC_BASE_URL="https://api.icreat.ai/"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"' >> ~/.zshrc

Apply changes:

source ~/.bash_profile  # or source ~/.zshrc

Linux Configuration

Temporary Configuration

export ANTHROPIC_BASE_URL="https://api.icreat.ai/"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"

Permanent Configuration

# Bash:
echo 'export ANTHROPIC_BASE_URL="https://api.icreat.ai/"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"' >> ~/.bashrc

# Zsh:
echo 'export ANTHROPIC_BASE_URL="https://api.icreat.ai/"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"' >> ~/.zshrc

Apply changes:

source ~/.bashrc or source ~/.zshrc

Alternative Recommended Method

Create:

\~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.icreat.ai/",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

Verify Configuration

# macOS/Linux:
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

# Windows PowerShell:
echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_AUTH_TOKEN

# Windows CMD:
echo %ANTHROPIC_BASE_URL%
echo %ANTHROPIC_AUTH_TOKEN%

Using Claude Code with Third-Party Clients

Roo Code / Kilo Code

Configuration:

• Provider: Anthropic

• API Key: Your API Key

• Custom Base URL:

https://api.icreat.ai/

Cherry Studio

• Add New Provider

• Provider Type: Anthropic

• Enter API Key

• API Endpoint:

https://api.icreat.ai/

• Sync and import available models.

ChatBox

• Model Provider: Claude

• Enter API Key

• API Endpoint:

https://api.icreat.ai/v1

VSCode

Install the official Claude Code extension.
For newer Claude Code extensions that require login:
Create:
~/.claude/config.json

{
  "primaryApiKey": "fox"
}

Codex Installation Guide

Install Codex

npm install -g @openai/codex

Configuration

Create:

\~/.codex/config.toml

model_provider = "icreat"

model = "gpt-5"

model_reasoning_effort = "high"

disable_response_storage = true

[model_providers.icreat]

name = "icreat"

base_url = "https://api.icreat.ai/v1"

wire_api = "responses"

requires_openai_auth = true

Create:

\~/.codex/auth.json

{

"OPENAI_API_KEY": "YOUR_API_KEY"

}

Switch models:

codex -m gpt-5-codex

Install the official VSCode extension after configuration is complete.

Gemini CLI Installation Guide

Install Gemini CLI

npm install -g @google/gemini-cli

Configure Environment

Edit:
~/.gemini/.env

GOOGLE_GEMINI_BASE_URL="https://api.icreat.ai/"
GEMINI_API_KEY=YOUR_API_KEY
GEMINI_MODEL=gemini-3-pro-preview

Edit or create:
~/.gemini/settings.json

{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

If a 401 error occurs:
Run:
/auth

Enter your API Key when prompted.

Official Claude Code Documentation

Claude Code Official Documentation:

https://docs.anthropic.com/en/docs/claude-code/quickstart