Node.js
Instale o SDK Node.js da ChartQuery e faça sua primeira chamada à API.
O SDK Node.js oficial da ChartQuery, com um método tipado por endpoint e um request() genérico para o resto.
Requisitos
- Node.js 20+
Instalação
npm install @chartquery/sdkObtenha sua chave de API
Copie sua chave de API no painel da ChartQuery e coloque-a na variável de ambiente CHARTQUERY_API_KEY, que o SDK lê por padrão. Não a inclua no controle de versão.
Início rápido
import { ChartQueryClient } from "@chartquery/sdk";
const client = new ChartQueryClient({ apiKey: process.env.CHARTQUERY_API_KEY });
const response = await client.chartAi({
prompt: "Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18",
});
console.log(response.data);Jobs assíncronos
Qualquer chamada aceita is_async, útil além do limite de 60 segundos do servidor. A resposta é então um job_id, e o SDK pode aguardar o fim do job.
const submitted = await client.chartAi({
prompt: "Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18",
is_async: true,
});
const job = await client.waitForJob(submitted.data.job_id, {
onProgress: (j) => console.log(`${j.status} ${j.progress ?? 0}%`),
});
console.log(JSON.stringify(job.data, null, 2));Erros
Uma resposta fora de 2xx gera um erro de API com status e mensagem. Veja os códigos de status para a lista completa.
import { ChartQueryApiError } from "@chartquery/sdk";
try {
await client.chartAi({
prompt: "Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18",
});
} catch (error) {
if (error instanceof ChartQueryApiError) {
console.error(error.status, error.message, error.responseBody);
}
throw error;
}Novas tentativas
As requisições são repetidas até 3 vezes após um erro de rede, um 408, 500, 502, 503 ou 504, ou um limite de taxa do plano. Erros de cota por chave e timeouts do cliente não são repetidos. A espera começa em 1 segundo e cresce 1,5× a cada tentativa, e um cabeçalho Retry-After tem prioridade.
const client = new ChartQueryClient({ maxRetries: 5, retryDelay: 500 });
// or for one request
await client.chartAi(
{ prompt: "Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18" },
{ maxRetries: 0 },
);Requisições em lote
Execute muitas chamadas de uma vez, 10 por padrão. Uma falha não interrompe as outras.
const inputs = [
"Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18",
"Market share as a pie chart: A 40, B 35, C 25",
];
const results = await client.batch(
inputs,
(prompt) => client.chartAi({ prompt }),
{ concurrency: 5 },
);
for (const result of results) {
if (result.status === "fulfilled") console.log(result.value.data);
else console.error(inputs[result.index], result.reason);
}Qualquer endpoint
request() alcança qualquer caminho, inclusive endpoints lançados depois da sua versão do SDK.
const response = await client.request("GET", "/v1/usage");Erros comuns
- Colocar a chave de API no código front-end. Qualquer pessoa poderia lê-la. Chame a API a partir do seu servidor.
- Tratar todo
401como chave incorreta. Um401também pode ser um limite de taxa: leia a mensagem. O SDK repete automaticamente os limites do plano. - Repetir um
402. Não há mais créditos nem cota, então uma nova tentativa não pode funcionar. Veja Créditos. - Esperar requisições longas. Acima de 60 segundos, use o modo assíncrono como mostrado acima em vez de aumentar o timeout. Veja Timeout.
Links
- Pacote:
@chartquery/sdk - Código-fonte: github.com/chartquery/chartquery-node
- Referência da API