> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Listar imagens geradas > Liste as imagens geradas pela conta conectada, das mais recentes para as mais antigas. Inclui status, dimensões e expiração; use nextCursor para a próxima página. Liste as imagens geradas pela conta conectada, das mais recentes para as mais antigas. Inclui status, dimensões e expiração; use nextCursor para a próxima página. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/images_list ``` ## Autenticação e permissões Envie uma chave de API VoiceCheap neste cabeçalho. Authorization: Bearer com a mesma chave de API também é aceito. Tokens de acesso OAuth são aceitos apenas pelo MCP, não por este endpoint REST. Permissões necessárias: `images:read`. É necessária uma assinatura paga ativa. As permissões não alteram funções na equipe, propriedade dos recursos, créditos de mídia ou limites do plano. ## Parâmetros Valor inteiro. Mínimo: 1. Máximo: 100. Valor padrão: 20. O nextCursor da página anterior. Comprimento mínimo: 1. Comprimento máximo: 512. O JSON Schema abaixo preserva os nomes exatos dos campos, tipos aninhados, valores padrão, limites e valores aceitos expostos pela descoberta. Regras adicionais entre campos são listadas nas notas da operação. ```json theme={null} { "type": "object", "properties": { "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "description": "The nextCursor from the previous page.", "type": "string", "minLength": 1, "maxLength": 512 } }, "additionalProperties": false } ``` ## Exemplos de requisição Substitua os identificadores de recursos e as chaves de mídia dos exemplos pelos valores retornados para sua conta. Mantenha o identificador da requisição ao tentar novamente a mesma alteração. ```bash cURL theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/images_list' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"limit":20}' ``` ```javascript JavaScript theme={null} const input = { limit: 20, }; const response = await fetch('https://api.voicecheap.ai/v1/actions/images_list', { method: 'POST', headers: { 'x-api-key': process.env.VOICECHEAP_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify(input), }); const body = await response.json(); if (!response.ok) throw new Error(body.code + ': ' + body.message); console.log(body); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.voicecheap.ai/v1/actions/images_list", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"limit": 20}, timeout=120, ) body = response.json() if not response.ok: raise RuntimeError(f"{body.get('code')}: {body.get('message')}") print(body) ``` ## Resposta Uma primeira execução bem-sucedida retorna HTTP 200 com o resultado da operação em data. Uma repetição pode retornar o estado salvo da requisição. O exemplo mostra uma resposta aceita, não todos os campos opcionais. Uma página de metadados de imagens geradas no aplicativo do usuário conectado, dos mais recentes aos mais antigos. Um histórico vazio retorna items: \[] e nextCursor: null. ```json HTTP 200 theme={null} { "data": { "items": [ { "generationId": "6224018c7635dcb933ce5c8f7804aea73738dd1c", "status": "completed", "aspectRatio": "square", "width": 1024, "height": 1024, "referenceImageCount": 1, "createdAt": 1792144800000, "updatedAt": 1792144820000, "expiresAt": 1792749600000 } ], "nextCursor": null } } ``` ## Campos do resultado | Campo | Descrição | | - | - | | `data.items` | Array de objetos de metadados de imagens. | | `data.items[].generationId` | Identificador a ser passado sem alterações para images\_get ou images\_download. | | `data.items[].status` | pending, completed, failed ou expired. A expiração tem precedência sobre o status armazenado. | | `data.items[].aspectRatio` | square, landscape ou portrait. | | `data.items[].width` | Largura da saída em pixels, ou null antes que as dimensões estejam disponíveis. | | `data.items[].height` | Altura da saída em pixels, ou null antes de as dimensões estarem disponíveis. | | `data.items[].referenceImageCount` | Número de imagens de referência usadas: 0 ou 1. | | `data.items[].createdAt` | Horário de criação em milissegundos Unix. | | `data.items[].updatedAt` | Horário da última atualização em milissegundos Unix. | | `data.items[].expiresAt` | Momento em milissegundos Unix após o qual a imagem gerada não pode ser baixada. | | `data.nextCursor` | Cursor opaco da próxima página, ou null quando não há outra página disponível. | ## Notas da operação * Exige images:read. limit usa 20 por padrão e deve ser um número inteiro de 1 a 100. cursor é opcional e limitado a 512 caracteres. * Passe nextCursor sem alterações como cursor para a próxima página. nextCursor é null no final; a ordenação usa o horário de criação e o identificador da geração em ordem decrescente. * Esta ação usa as criações e os envios do próprio usuário conectado, inclusive quando a credencial está conectada em um contexto de equipe. * Os registros expõem os status pending, completed, failed ou expired. As dimensões podem ser null para gerações não concluídas ou com falha. Os metadados podem informar expired antes que a limpeza remova um registro; isso não torna a imagem disponível para download. * Somente imagens geradas pelo aplicativo pertencem a este histórico. Use images\_download para obter os dados da imagem; os históricos não incorporam bytes de imagens nem URLs de prévia. ## Uso Cada chamada bem-sucedida consome uma chamada mensal da API/MCP. Os créditos de mídia e as cotas de geração da própria operação também se aplicam. ## Erros | Status HTTP | Código | Significado ou recuperação | | - | - | - | | 400 | `CREDENTIAL_IN_QUERY` | Foram fornecidas credenciais em um parâmetro de consulta access\_token ou api\_key. Envie as credenciais nos cabeçalhos. | | 400 | `INVALID_CURSOR` | cursor não é um cursor de histórico válido; use o nextCursor retornado pela página anterior. | | 400 | `VALIDATION_ERROR` | Um argumento está ausente, tem um valor não compatível, excede seu limite ou não faz parte do esquema estrito de entrada. | | 401 | `API_KEY_EXPIRED` | A chave de API expirou. | | 401 | `INVALID_API_KEY` | Forneça uma chave de API válida e dentro do prazo de validade. | | 401 | `INVALID_CREDENTIAL` | O cabeçalho Authorization está malformado ou entra em conflito com x-api-key. | | 401 | `MISSING_CREDENTIAL` | Nenhuma credencial utilizável foi fornecida no cabeçalho, ou ela excedeu 4096 caracteres. | | 401 | `USER_NOT_FOUND` | A conta da credencial não existe mais. | | 403 | `AMBIGUOUS_TEAM_API_KEY` | O usuário da credencial pertence a mais de uma equipe, portanto o contexto de cobrança é ambíguo. | | 403 | `INSUFFICIENT_SCOPE` | Conceda todas as permissões necessárias ou escolha outra credencial. | | 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Não foi possível verificar os limites de integração da conta. | | 403 | `SUBSCRIPTION_REQUIRED` | Use uma assinatura paga ativa. | | 403 | `TEAM_OWNER_NOT_FOUND` | Não foi possível encontrar a conta efetiva do proprietário da equipe. | | 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Aguarde a renovação do limite mensal ou mude de plano. | | 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Aguarde o prazo de Retry-After, quando presente, e aumente progressivamente o intervalo entre as tentativas. | | 500 | `INTERNAL_ERROR` | Verifique o estado da requisição salva e o histórico do recurso antes de decidir repetir uma alteração. | | 503 | `SERVER_RESTARTING` | O servidor está reiniciando. Tente novamente em breve e mantenha o mesmo identificador de requisição para uma alteração. | ```json theme={null} { "code": "INSUFFICIENT_SCOPE", "message": "This credential does not permit the requested action.", "status": 403, "details": { "requiredScopes": ["images:read"] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.