API de Uso

Liste as tarefas de API concluídas da sua equipe e os créditos que cada uma consumiu, para exportações de cobrança e relatórios de custo.

Para chamar este endpoint, use uma chave de API de um membro ativo de uma equipe Studio ou Enterprise. Qualquer membro pode chamá-lo, não apenas proprietários e administradores. Com qualquer outra chave de API, a solicitação retorna 403.

GET/openapi/v1/usage/tasks

Listar registros de uso

Retorna uma página dos registros de uso da sua equipe, por padrão do mais novo para o mais antigo. Sem start_time e end_time, os registros cobrem os últimos 30 dias. Chamar este endpoint é gratuito.

Os registros incluem estas tarefas:

Tarefas de API que terminaram como SUCCEEDED ou FAILED
Tarefas de todos os membros atuais da equipe, de qualquer uma de suas chaves de API
Tarefas que você excluiu, e tarefas cujos arquivos expiraram

Os registros deixam de fora estas tarefas:

Tarefas que ainda estão PENDING ou IN_PROGRESS, e tarefas CANCELED
Tarefas de pessoas que saíram da equipe
Tarefas do Creative Lab
Tarefas executadas pelos agentes de IA da Meshy
Trabalho feito no aplicativo web da Meshy

Uma tarefa aparece nos registros somente depois de terminar, na janela de seu created_at. A Meshy cobra créditos quando cria uma tarefa, então uma tarefa que ainda está em execução fica ausente dos registros. Antes de reconciliar os registros com seu saldo de créditos, busque as janelas recentes novamente, ou exporte após um pequeno atraso.

Se sua equipe tiver um período de retenção de dados, a janela não começa antes do que esse período permite.

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",
    "metadata": {
      "user": "alex@example.com",
      "team": "fab"
    }
  },
  {
    "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",
    "metadata": {}
  }
]

Parâmetros

Name
page_num
Type
integer
padrão 1
Description
A página a retornar, de 1 a 255. Um valor acima de 255 retorna 400. Uma janela comporta no máximo 255 páginas, então divida uma exportação grande em janelas mais curtas.
Name
page_size
Type
integer
padrão 10
Description
Número de registros por página, de 1 a 100. Um valor de 101 a 255 retorna 100 registros, e um valor acima de 255 retorna 400.
Name
sort_by
Type
string
padrão -created_at
Description
A ordem de classificação.
Valores disponíveis:
- +created_at: mais antigo primeiro
- -created_at: mais novo primeiro
Em uma URL, escreva + como %2B. Caso contrário, o + é interpretado como um espaço, e a solicitação retorna 400.
Name
start_time
Type
string
Description
O início da janela, como um carimbo de data/hora RFC 3339, por exemplo 2026-08-01T00:00:00Z. Os registros incluem tarefas criadas nesse momento ou depois. Deixe-o de fora para iniciar a janela 30 dias antes de end_time.
A janela pode abranger no máximo 366 dias. Uma janela mais longa retorna 400, então divida uma exportação mais longa em várias janelas.
Name
end_time
Type
string
Description
O fim da janela, como um carimbo de data/hora RFC 3339. Os registros incluem tarefas criadas antes desse momento. Deixe-o de fora para encerrar a janela no momento da sua solicitação.
Name
endpoints
Type
string
Description
Uma lista separada por vírgulas dos endpoints a incluir, com os mesmos nomes do campo endpoint. Deixe-a de fora para incluir todos os endpoints. Um nome desconhecido retorna 400.
Valores disponíveis:
- text-to-3d: toda tarefa de Texto para 3D, preview e refine
- text-to-3d-preview: apenas tarefas de preview
- text-to-3d-refine: apenas tarefas de 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
Name
status
Type
string
Description
O status a incluir, SUCCEEDED ou FAILED. Deixe-o de fora para incluir ambos. Qualquer outro valor retorna 400.

Retornos

Retorna um array de registros de uso. O array fica vazio quando nenhum registro corresponde.

Modos de falha

Name
400 - Bad Request
Description
Um parâmetro é inválido, e a mensagem de erro informa qual. Corrija o parâmetro e envie a solicitação novamente.
Name
401 - Unauthorized
Description
A chave de API está ausente ou é inválida. Verifique o cabeçalho Authorization.
Name
403 - Forbidden
Description
A conta da chave de API não é um membro ativo de uma equipe Studio ou Enterprise. A mensagem é This endpoint is available on Studio and Enterprise plans. Use uma chave de API de um membro de uma equipe Studio ou Enterprise.
Name
429 - Too Many Requests
Description
Você enviou solicitações demais. Aguarde o número de segundos em Retry-After e tente novamente.

Objeto de registro de uso

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",
  "metadata": {
    "user": "alex@example.com",
    "team": "fab"
  }
}

Name
task_id
Type
string
Description
O ID da tarefa, o mesmo ID que o endpoint de criação retornou. Para obter a própria tarefa, com suas URLs de saída, envie o ID para a rota de obtenção desse endpoint, por exemplo GET /openapi/v1/image-to-3d/{task_id} para um registro image-to-3d.
Name
endpoint
Type
string
Description
O endpoint em que a tarefa foi executada, por exemplo image-to-3d ou rig. Uma tarefa de Texto para 3D mostra seu estágio, text-to-3d-preview ou text-to-3d-refine.
Registros mais antigos podem ter nomes de endpoints descontinuados, que o filtro endpoints não aceita.
Name
status
Type
string
Description
O status final da tarefa, SUCCEEDED ou FAILED.
Name
created_at
Type
timestamp
Description
Horário em que a tarefa foi criada, em milissegundos Unix.
Name
finished_at
Type
timestamp
Description
Horário em que a tarefa terminou, em milissegundos Unix. null se a tarefa não tiver horário de término.
Name
consumed_credits
Type
integer
Description
Número de créditos que a tarefa usou, após reembolsos. 0 para uma tarefa com falha, porque a Meshy a reembolsa, e para uma tarefa gratuita como Analisar imprimibilidade.
Name
api_key_name
Type
string
Description
O nome da chave de API que executou a tarefa. Para uma tarefa executada com um login de aplicativo, é o nome do aplicativo, por exemplo Meshy CLI.
É uma string vazia em alguns casos, por exemplo:
- A tarefa nunca foi cobrada, como uma tarefa de Analisar imprimibilidade, que é gratuita.
- A chave de API foi excluída.
- A chave de API foi criada nos últimos minutos.
Name
api_key_suffix
Type
string
Description
Os últimos quatro caracteres dessa chave de API, para diferenciar chaves com o mesmo nome. Uma string vazia sempre que api_key_name estiver vazio, e para logins de aplicativo como o Meshy CLI.
Name
metadata
Type
object
Description
As tags enviadas no cabeçalho X-Meshy-Metadata quando a tarefa foi criada. {} se nenhuma. Veja Metadata.