API de Uso

A API de Uso retorna as tarefas históricas da API da sua equipe com os créditos que cada uma consumiu. Filtre por janela de tempo, endpoint ou status, e navegue pelos resultados para exportar em massa.

Disponibilidade. A chave de API deve pertencer a uma equipe Studio ou Enterprise; chaves de qualquer outro plano, ou sem equipe, recebem um 403.

GET/openapi/v1/usage/tasks

Listar Registros de Uso

Retorna uma página das tarefas de API da equipe, das mais recentes para as mais antigas. Sem um intervalo de tempo explícito, a resposta cobre os últimos 30 dias.

Parâmetros

Name
page_num
Type
integer
padrão 1
Description
Número da página para paginação.
Name
page_size
Type
integer
padrão 10
Description
Limite do tamanho da página. O máximo permitido é 100 itens.
Name
sort_by
Type
string
padrão -created_at
Description
Campo para ordenação.
Valores disponíveis:
- +created_at: Ordena por horário de criação em ordem crescente.
- -created_at: Ordena por horário de criação em ordem decrescente.
Name
start_time
Type
string
Description
Início da janela de created_at, como um carimbo de data/hora RFC 3339 (ex.: 2026-08-01T00:00:00Z). O padrão é 30 dias antes de end_time. A janela pode abranger no máximo 1 ano — para exportações maiores, navegue por janelas consecutivas.
Name
end_time
Type
string
Description
Fim da janela de created_at, como um carimbo de data/hora RFC 3339. O padrão é o horário atual.
Name
endpoints
Type
string
Description
Lista de nomes de endpoints separados por vírgula a incluir. Aceita os mesmos valores que o campo de resposta endpoint carrega — text-to-3d, text-to-3d-preview, text-to-3d-refine, image-to-3d, multi-image-to-3d, retexture, remesh, convert, resize, uv-unwrap, rig, animate, text-to-motion, text-to-image, image-to-image, print-multi-color, print-repair, print-analyze, print-split — sendo que text-to-3d é um termo abrangente que cobre tanto a fase de preview quanto a de refine. Omita para incluir todos os endpoints.
Name
status
Type
string
Description
Filtra pelo status terminal da tarefa: SUCCEEDED ou FAILED. Omita para incluir ambos.

Retornos

Retorna uma lista paginada de Objetos de Registro de Uso.

Os registros cobrem tarefas que atingiram um status terminal. Os créditos são cobrados quando uma tarefa é criada, então uma tarefa ainda em execução no momento da sua exportação ainda não está nos resultados daquela janela — busque novamente as janelas recentes (ou exporte com um pequeno atraso) se seus totais precisarem corresponder exatamente ao seu saldo de créditos.

Equipes com uma política de retenção de dados personalizada recebem registros dentro da janela de retenção configurada.

Request

GET

/openapi/v1/usage/tasks

curl "https://api.meshy.ai/openapi/v1/usage/tasks?page_size=50&start_time=2026-08-01T00:00:00Z&end_time=2026-09-01T00:00:00Z" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "endpoint": "image-to-3d",
    "status": "SUCCEEDED",
    "created_at": 1755787000000,
    "finished_at": 1755787045000,
    "consumed_credits": 20,
    "api_key_name": "production",
    "api_key_suffix": "a1b2"
  },
  {
    "task_id": "018a210d-1c22-7e0f-9d3a-4a5b6c7d8e9f",
    "endpoint": "text-to-3d-refine",
    "status": "FAILED",
    "created_at": 1755786000000,
    "finished_at": 1755786030000,
    "consumed_credits": 0,
    "api_key_name": "production",
    "api_key_suffix": "a1b2"
  }
]

O Objeto de Registro de Uso

Name
task_id
Type
string
Description
ID da tarefa que este registro cobra — o mesmo ID retornado pelo endpoint que a criou. Para buscar a própria tarefa (incluindo seu modelo de saída ou URLs de imagem, re-assinadas a cada leitura), passe-o para o endpoint de recuperação correspondente, ex.: GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
O endpoint em que a tarefa foi executada, ex.: image-to-3d ou text-to-3d-refine. Tarefas de Texto para 3D relatam sua fase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Status terminal da tarefa: SUCCEEDED ou FAILED.
Name
created_at
Type
timestamp
Description
Carimbo de data/hora da criação da tarefa, em milissegundos.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora da conclusão, em milissegundos. null se a tarefa não tiver um horário de conclusão.
Name
consumed_credits
Type
integer
Description
Créditos consumidos por esta tarefa. Retorna 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).
Name
api_key_name
Type
string
Description
Nome de exibição da chave de API que executou a tarefa. Permanece preenchido mesmo para chaves revogadas, para que os gastos históricos continuem atribuíveis após a rotação de chaves.
Name
api_key_suffix
Type
string
Description
Os últimos quatro caracteres dessa chave de API, para distinguir chaves com o mesmo nome.

Example Usage Record Object

{
  "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "endpoint": "image-to-3d",
  "status": "SUCCEEDED",
  "created_at": 1755787000000,
  "finished_at": 1755787045000,
  "consumed_credits": 20,
  "api_key_name": "production",
  "api_key_suffix": "a1b2"
}