lowpoly será descontinuado a 30/10/2026. meshy-7 como modelo de geração 3D será descontinuado a 31/12/2026; como modelo de textura continua disponível. Mude de modelo antes destas datas para evitar erros nos pedidos. Ver todas as descontinuações

API de utilização

Liste as tarefas de API concluídas da sua equipa e os créditos que cada uma consumiu, para exportações de faturação e relatórios de custos.

Para chamar este endpoint, utilize uma chave de API de um membro ativo de uma equipa Studio ou Enterprise. Qualquer membro pode chamá-lo, não apenas proprietários e administradores. Com qualquer outra chave de API, o pedido devolve 403.


GET/openapi/v1/usage/tasks

Listar registos de utilização

Devolve uma página dos registos de utilização da sua equipa, por predefinição dos mais recentes para os mais antigos. Sem start_time e end_time, os registos abrangem os últimos 30 dias. Chamar este endpoint é gratuito.

Os registos incluem estas tarefas:

  • Tarefas de API que terminaram como SUCCEEDED ou FAILED
  • Tarefas de todos os membros atuais da equipa, a partir de qualquer uma das suas chaves de API
  • Tarefas que eliminou, e tarefas cujos ficheiros expiraram

Os registos excluem estas tarefas:

  • Tarefas ainda PENDING ou IN_PROGRESS, e tarefas CANCELED
  • Tarefas de pessoas que saíram da equipa
  • Tarefas do Creative Lab
  • Tarefas executadas pelos agentes de IA da Meshy
  • Trabalho realizado na aplicação web da Meshy

Uma tarefa só aparece nos registos depois de terminar, na janela do seu created_at. A Meshy cobra créditos quando cria uma tarefa, pelo que uma tarefa ainda em execução não consta dos registos. Antes de reconciliar os registos com o seu saldo de créditos, obtenha novamente as janelas recentes, ou exporte após um breve atraso.

Se a sua equipa 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
    predefinição 1
    Description

    A página a devolver, de 1 a 255. Um valor acima de 255 devolve 400. Uma janela comporta no máximo 255 páginas, pelo que deve dividir uma exportação grande em janelas mais curtas.

  • Name
    page_size
    Type
    integer
    predefinição 10
    Description

    Número de registos por página, de 1 a 100. Um valor de 101 a 255 devolve 100 registos, e um valor acima de 255 devolve 400.

  • Name
    sort_by
    Type
    string
    predefinição -created_at
    Description

    A ordem de ordenação.

    Valores disponíveis:

    • +created_at: do mais antigo para o mais recente
    • -created_at: do mais recente para o mais antigo

    Num URL, escreva + como %2B. Caso contrário, o + é interpretado como um espaço, e o pedido devolve 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 registos incluem tarefas criadas nesse momento ou depois. Omita para iniciar a janela 30 dias antes de end_time.

    A janela pode abranger no máximo 366 dias. Uma janela mais longa devolve 400, pelo que deve dividir 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 registos incluem tarefas criadas antes deste momento. Omita para terminar a janela no momento do seu pedido.

  • Name
    endpoints
    Type
    string
    Description

    Uma lista separada por vírgulas dos endpoints a incluir, com os mesmos nomes do campo endpoint. Omita para incluir todos os endpoints. Um nome desconhecido devolve 400.

    Valores disponíveis:

    • text-to-3d: todas as tarefas 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
    • relief
  • Name
    status
    Type
    string
    Description

    O estado a incluir, SUCCEEDED ou FAILED. Omita para incluir ambos. Qualquer outro valor devolve 400.

Devolve

Devolve uma matriz de registos de utilização. A matriz fica vazia quando nenhum registo corresponde.

Modos de falha

  • Name
    400 - Bad Request
    Description

    Um parâmetro é inválido, e a mensagem de erro indica qual. Corrija o parâmetro e envie o pedido novamente.

  • Name
    401 - Unauthorized
    Description

    A chave de API está em falta ou é inválida. Verifique o cabeçalho Authorization.

  • Name
    403 - Forbidden
    Description

    A conta da chave de API não é membro ativo de uma equipa Studio ou Enterprise. A mensagem é This endpoint is available on Studio and Enterprise plans. Utilize uma chave de API de um membro de uma equipa Studio ou Enterprise.

  • Name
    429 - Too Many Requests
    Description

    Enviou demasiados pedidos. Aguarde o número de segundos indicado em Retry-After e tente novamente.


Objeto de registo de utilização

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 criador devolveu. Para obter a própria tarefa, com os seus 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 registo 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 a sua fase, text-to-3d-preview ou text-to-3d-refine.

    Registos mais antigos podem ter nomes de endpoints descontinuados, que o filtro endpoints não aceita.

  • Name
    status
    Type
    string
    Description

    O estado final da tarefa, SUCCEEDED ou FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

    Momento em que a tarefa foi criada, em milissegundos Unix.

  • Name
    finished_at
    Type
    timestamp
    Description

    Momento em que a tarefa terminou, em milissegundos Unix. null se a tarefa não tiver momento de conclusão.

  • Name
    consumed_credits
    Type
    integer
    Description

    Número de créditos que a tarefa consumiu, após reembolsos. 0 para uma tarefa falhada, porque a Meshy reembolsa-a, 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 início de sessão de aplicação, é o nome da aplicação, por exemplo Meshy CLI.

    É uma cadeia de caracteres vazia em alguns casos, por exemplo:

    • A tarefa nunca foi cobrada, como uma tarefa de Analisar imprimibilidade, que é gratuita.
    • A chave de API foi eliminada.
    • 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 distinguir chaves com o mesmo nome. Uma cadeia de caracteres vazia sempre que api_key_name está vazio, e para inícios de sessão de aplicação como o Meshy CLI.

  • Name
    metadata
    Type
    object
    Description

    As etiquetas enviadas no cabeçalho X-Meshy-Metadata quando a tarefa foi criada. {} se não houver nenhuma. Consulte Metadados.