ChartQuery

Python

Instale o SDK Python da ChartQuery e faça sua primeira chamada à API.

O SDK Python oficial da ChartQuery, com um método tipado por endpoint e um request() genérico para o resto.

Requisitos

  • Python 3.11+

Instalação

pip install chartquery

Obtenha 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 os

from chartquery import ChartQueryClient

with ChartQueryClient(os.environ["CHARTQUERY_API_KEY"]) as client:
    response = client.chart_ai(prompt="Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18")
    print(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.

submitted = client.chart_ai(prompt="Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18", is_async=True)
job = client.wait_for_job(
    submitted.data["job_id"],
    on_progress=lambda j: print(j["status"], j.get("progress")),
)
print(job.data)

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.

from chartquery import ChartQueryAPIError

try:
    client.chart_ai(prompt="Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18")
except ChartQueryAPIError as error:
    print(error.status, error, error.response_body)

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.

client = ChartQueryClient(max_retries=5, retry_delay=0.5)

# or for one request
client.chart_ai(prompt="Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18", request_options=RequestOptions(max_retries=0))

Requisições em lote

Execute muitas chamadas de uma vez, 10 por padrão. Uma falha não interrompe as outras.

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"]
results = client.batch(inputs, lambda prompt: client.chart_ai(prompt=prompt), concurrency=5)

for result in results:
    if result.ok:
        print(result.value.data)
    else:
        print(inputs[result.index], result.error)

Qualquer endpoint

request() alcança qualquer caminho, inclusive endpoints lançados depois da sua versão do SDK.

response = 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 401 como chave incorreta. Um 401 també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.

Nesta página