SiCore TokenWorks

Documentazione API

Guide di integrazione dettagliate e riferimento API per integrare rapidamente i servizi API AI di SiCore TokenWorks

1Avvio rapido

Utilizzare l'API SiCore TokenWorks richiede solo tre semplici passaggi:

  1. Registrare un account SiCore TokenWorks e accedere alla console
  2. Creare una chiave API nella console
  3. Utilizzare la propria chiave API per chiamare le nostre interfacce

Tip: I nuovi utenti riceveranno una quota di prova gratuita dopo la registrazione, senza bisogno di associare una carta di credito per iniziare.

2Indirizzo dell'interfaccia

L'indirizzo di base dell'API è il seguente; tutte le richieste utilizzano il protocollo HTTPS:

text
https://www.token8341.com/v1

Interfaccia di completamento chat:

text
POST https://www.token8341.com/v1/chat/completions

Note: Questa interfaccia è completamente compatibile con il formato dell'interfaccia Chat Completions di OpenAI; è possibile utilizzare direttamente l'SDK di OpenAI per effettuare chiamate.

3Metodo di autenticazione

SiCore TokenWorks utilizza Bearer Token per l'autenticazione API. Includere la propria chiave API nell'intestazione della richiesta:

text
Authorization: Bearer sk-your-api-key-here

È possibile creare e gestire le proprie chiavi nella pagina «API Keys» della console. Conservare con cura la propria chiave API e non esporla in repository di codice pubblici o nel codice client.

4Elenco dei modelli supportati

ID modelloNome modelloFornitore
gpt-4oGPT-4oOpenAI
gpt-4o-miniGPT-4o MiniOpenAI
claude-3-5-sonnetClaude 3.5 SonnetAnthropic
claude-4-sonnetClaude 4 SonnetAnthropic
gemini-2-0-proGemini 2.0 ProGoogle
deepseek-v4-proDeepSeek-V4-ProDeepSeek
qwen-maxQwen-MaxAlibaba Cloud

Ulteriori modelli sono in fase di integrazione continua; si prega di seguire i nostri aggiornamenti.

5Codice di esempio

curl

bash
curl https://www.token8341.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Python (openai SDK)

python
from openai import OpenAI

client = OpenAI(
    base_url="https://www.token8341.com/v1",
    api_key="sk-your-api-key-here"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)

Node.js (openai SDK)

javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://www.token8341.com/v1",
  apiKey: "sk-your-api-key-here",
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "Hello!" },
  ],
});

console.log(response.choices[0].message.content);

6Spiegazione dei codici di errore

Quando una richiesta API fallisce, vengono restituiti il codice di stato HTTP e il messaggio di errore corrispondenti, nel formato seguente:

json
{
  "error": {
    "message": "Insufficient balance",
    "type": "insufficient_balance",
    "code": 402
  }
}
Codice di statoNomeDescrizione
400Bad Request请求参数错误，请检查请求体格式
401UnauthorizedAPI Key 无效或缺失，请检查 Authorization 请求头
402Insufficient Balance账户余额不足，请充值后重试
404Not Found请求的模型或接口不存在
429Rate Limit请求频率过高，请稍后重试
500Internal Server Error服务内部错误，请联系技术支持
503Service Unavailable模型服务暂时不可用，请稍后重试

Domande frequenti sull'integrazione

Domande frequenti su API Key, cambio di modello e linguaggi di integrazione

Una sola API Key può chiamare tutti i modelli?

Sì. Questa è la caratteristica principale di SiCore TokenWorks: gli sviluppatori devono integrarsi una sola volta per chiamare tutti i modelli della piattaforma, senza dover richiedere account separati e gestire Key per ogni fornitore.

Per cambiare modello è necessario modificare il codice?

Non è necessario modificare il codice logico: basta cambiare il solo parametro model ID per passare tra modelli nazionali ed esteri.

Quali linguaggi di programmazione sono supportati?

Sono forniti esempi di integrazione per cURL, Python, Node.js e altri linguaggi principali, compatibili con qualsiasi linguaggio che supporti richieste HTTP e con l'SDK ufficiale OpenAI.

Come avviene l'autenticazione delle API?

L'autenticazione avviene tramite Bearer Token: è sufficiente includere l'API Key nell'header della richiesta. L'interfaccia è completamente compatibile con il formato Chat Completions di OpenAI e può essere chiamata direttamente utilizzando l'SDK ufficiale di OpenAI, senza necessità di adattamenti aggiuntivi.

Esistono SDK o esempi di codice già pronti?

Sì. La piattaforma fornisce esempi di integrazione per i principali linguaggi come cURL, Python e Node.js; gli sviluppatori possono scegliere in base al proprio linguaggio per un'integrazione rapida.

I modelli continueranno ad aumentare? Per i nuovi modelli sarà necessario modificare il codice?

Sì. La piattaforma integra costantemente nuovi modelli nazionali e internazionali di riferimento, mantenendo invariati modalità di accesso e sistema di fatturazione; una volta online, i nuovi modelli possono essere selezionati direttamente senza modificare il codice.

Come si usa il meccanismo di cache delle API dei modelli di grandi dimensioni? In quali scenari si ottiene un cache hit?

La piattaforma utilizza una cache condivisa tra utenti per lo stesso prompt; in caso di cache hit il prezzo si riduce di oltre il 90%, con un prezzo minimo per cache hit di ¥0.010 / milione di Token, e la parte che ha ottenuto il cache hit viene fatturata al prezzo di cache. È adatta a scenari in cui più utenti riutilizzano lo stesso prompt di prefisso, ad esempio system prompt fissi, prefissi di conoscenza comune e così via: mettendo la parte invariata all'inizio, il tasso di cache hit è più alto.

Se una chiamata API fallisce o va in timeout, come si implementano retry automatico e fallback?

L'approccio tipico è: per i timeout e gli errori ritentabili, usare retry con backoff esponenziale e impostare un numero massimo di tentativi; se fallisce ancora, eseguire il fallback su un modello di riserva. Sulla piattaforma, per cambiare modello basta modificare l'ID del modello, senza alcuna modifica al codice: è sufficiente scrivere il modello di fallback come un altro ID di modello. Lato piattaforma sono inoltre presenti ridondanza multi-nodo e routing intelligente cross-region, con commutazione automatica in caso di anomalia di un singolo nodo.

Come si confrontano le prestazioni e i costi di modelli diversi?

Con una sola API Key è possibile chiamare tutti i modelli; per cambiare modello basta modificare l'ID del modello, senza alcuna modifica al codice, quindi per un confronto orizzontale non è necessario integrare separatamente ogni modello. Si consiglia di chiamare ciascun modello con lo stesso insieme di campioni di business, registrare la qualità dell'output e il consumo, e poi confrontare voce per voce il prezzo ufficiale e il prezzo di questo sito utilizzando la «tabella di comparazione prezzi di tutti i modelli» sul sito ufficiale.

Come si conserva in modo sicuro l'API Key lato server?

Si consiglia di salvare l'API Key solo lato server, trasmettendola tramite header di richiesta come Bearer Token, senza inserirla nel codice frontend o client. I dati di richiesta e risposta della piattaforma sono trasmessi con crittografia HTTPS end-to-end, e sono disponibili gestione dei permessi di livello enterprise e log di audit, con record delle chiamate tracciabili.

Come si garantiscono stabilità delle chiamate e bassa latenza in scenari ad alta concorrenza?

La piattaforma si basa su data center di calcolo situati a Helingeer in Mongolia Interna, Hami nello Xinjiang, Zhongwei nel Ningxia e altre località, e utilizza algoritmi di scheduling proprietari per il routing intelligente cross-region e il bilanciamento dinamico del carico, con commutazione automatica in caso di anomalia di un singolo nodo; gli utenti nelle città principali possono ottenere latenza in millisecondi, con un impegno di disponibilità del servizio del 99.9%. Si consiglia di abbinare lato client retry con backoff e fallback su più modelli.

Come si monitorano volume di chiamate, costi e anomalie?

La piattaforma offre un account unificato e un unico sistema di fatturazione, con consumo trasparente, saldo accreditato in tempo reale e dettaglio dei consumi consultabile in qualsiasi momento; fornisce inoltre la funzionalità di log di audit delle chiamate API, con record delle chiamate tracciabili. Gli utenti enterprise che necessitano di requisiti di conformità più rigorosi (gestione dei permessi, log di audit, ecc.) possono contattare il servizio clienti per il supporto commerciale.