Exemplos de API

Versão

API

Rota

POST PUT POST

/api/v2/api/translate/uploads
R2 target
/api/v2/api/translate

Parâmetros

Parâmetro	Obrigatório	Tipo	Descrição
`image`	Sim	file[]	Um ou mais arquivos de imagem, ou um arquivo ZIP
`source_language`	Não	string	Opcional; obrigatório quando o modelo é manga (ex.: ja)
`target_language`	Sim	string	Código do idioma de destino (ex.: en)
`model`	Não	string	Modelo de reconhecimento; omita para usar o padrão da API
`font`	Não	string	Estilo da fonte; omita para usar o padrão da API

Parâmetro	Obrigatório	Tipo	Descrição
`Idempotency-Key`	Sim	HTTP header	Cabeçalho da preparação: chave estável para repetir com segurança a mesma lista de arquivos por 8 horas
`platform`	Não	string \| null	Solicitações de preparação e final: rótulo opcional de plataforma informado pelo cliente, usado apenas para auditoria de chamadas da API
`files[]`	Sim	array<object>	Solicitação de preparação: metadados do arquivo com filename, content_type, size e content_sha256
`upload_id`	Sim	string	Solicitação final: identificador opaco do lote de upload retornado pela preparação
`files[].index files[].upload_intent`	Sim	integer string	Solicitação final: index e upload_intent opaco de cada arquivo retornados pela preparação; envie somente após concluir cada upload para o R2
`source_language`	Não	string	Opcional; obrigatório quando o modelo é manga (ex.: ja)
`target_language`	Sim	string	Código do idioma de destino (ex.: en)
`model`	Não	string	Modelo de reconhecimento; omita para usar o padrão da API
`font`	Não	string	Estilo da fonte; omita para usar o padrão da API

Parâmetro	Obrigatório	Tipo	Descrição
`batch_id`	Sim	string	Identificador do lote usado para consultar o status da tarefa

Parâmetro	Obrigatório	Tipo	Descrição
Sem parâmetros

Parâmetros da resposta

Campo	Tipo	Descrição
`task_id`	string	Identificador da tarefa
`batch_id`	string	Identificador do lote usado para consultar o status da tarefa

Campo	Tipo	Descrição
`status`	integer	Código de status da aplicação; 200 em caso de sucesso
`cost_ms`	integer	Tempo de processamento desta requisição de API em milissegundos
`request_id`	string	Identificador da requisição para rastrear esta chamada de API
`data`	object	Identificadores da tarefa de tradução retornados após a aceitação da requisição
`message`	string	Sempre success em uma resposta bem-sucedida da API; não significa que a tarefa de tradução foi concluída
`data.task_id`	string	Identificador da tarefa
`data.batch_id`	string	Identificador do lote usado para consultar o status da tarefa

Campo	Tipo	Descrição
`status_code`	integer	Sempre 200 em uma resposta Task Status bem-sucedida
`request_id`	string	Identificador da requisição para rastrear esta chamada de API
`auth_type`	string	Sempre account em uma requisição Task Status autenticada por PAT
`task_reference`	string	O batch_id do caminho da requisição, retornado sem alterações
`data`	object	Contêiner dos resultados por imagem e do status geral da tarefa
`data.items`	array<object>	Lista de resultados da tarefa por imagem
`data.items[].image_id`	string	Identificador estável do resultado da imagem
`data.items[].index`	integer	Posição da imagem no lote, iniciando em zero
`data.items[].filename`	string	Nome do arquivo da imagem original
`data.items[].status`	string	Status do resultado da imagem (pending \| processing \| completed \| failed \| canceled)
`data.items[].original_url`	string	URL da imagem de origem; está disponível para tarefas atuais criadas pela API.
`data.items[].translated_url`	string	URL da imagem traduzida; fica vazia até haver um resultado disponível, inclusive para imagens pendentes, em processamento ou com falha.
`data.items[].is_translated`	boolean	true somente quando a URL de uma imagem traduzida concluída está disponível
`data.items[].output_file_path`	string	Alias de compatibilidade de translated_url; fica vazio quando não há imagem traduzida disponível.
`data.items[].message`	string \| null	Mensagem informativa opcional
`data.items[].error`	string \| null	Detalhe do erro quando a tarefa da imagem falha; caso contrário, null
`data.items[].inpaint_image_url`	string \| null	URL da imagem com o texto removido, ou null quando o modelo ou caminho de execução escolhido não a gera.
`data.items[].block_json`	array<object>	Blocos de texto estruturados preservados pela V1; pode ser uma matriz vazia quando o modelo ou caminho não retorna metadados de blocos.
`data.task_status`	string	Status geral da tarefa (pending \| processing \| completed \| failed \| canceled)

Campo	Tipo	Descrição
`status`	integer	Código de status da aplicação; 200 em caso de sucesso
`cost_ms`	integer	Tempo decorrido da tarefa em milissegundos; 0 quando faltam horários válidos da tarefa
`request_id`	string	Identificador da requisição para rastrear esta chamada de API
`data`	array<object>	Lista compacta de resultados por imagem
`message`	string	Sempre success em uma resposta bem-sucedida da API; não significa que a tarefa de tradução foi concluída
`data[].image_id`	string	Identificador estável do resultado da imagem
`data[].filename`	string	Nome do arquivo da imagem original
`data[].status`	string	Status do resultado da imagem (pending \| processing \| completed \| failed \| canceled)
`data[].original_url`	string	URL da imagem de origem; está disponível para tarefas atuais criadas pela API.
`data[].translated_url`	string	URL da imagem traduzida; fica vazia até haver um resultado disponível, inclusive para imagens pendentes, em processamento ou com falha.
`data[].erased_url`	string	URL da imagem com o texto removido; pode ser vazia. Modelos ou caminhos que retornam apenas a imagem final, como Manga com o caminho de imagem final Auto, não a geram.
`data[].blocks`	array<object>	Blocos de texto traduzidos estruturados; pode ser uma matriz vazia quando o modelo ou caminho não retorna metadados de blocos, como Manga com o caminho de imagem final Auto.
`data[].blocks[].angle`	number	Ângulo de rotação do bloco de texto
`data[].blocks[].color`	string	Cor hexadecimal usada no texto traduzido
`data[].blocks[].handwritten`	boolean	Indica se o texto original foi detectado como manuscrito
`data[].blocks[].location`	object	Limites dos quatro cantos do bloco de texto
`data[].blocks[].location.left_bottom`	array<number>	Par de coordenadas do canto indicado
`data[].blocks[].location.right_bottom`	array<number>	Par de coordenadas do canto indicado
`data[].blocks[].location.left_top`	array<number>	Par de coordenadas do canto indicado
`data[].blocks[].location.right_top`	array<number>	Par de coordenadas do canto indicado
`data[].blocks[].text`	string	Texto traduzido renderizado no bloco
`data[].blocks[].direction`	string	Direção de escrita do texto traduzido

Campo	Tipo	Descrição
`subscription_credits`	integer	Saldo de créditos da categoria indicada
`subscription_credits_expires_at`	string \| null	Data de expiração dos créditos de assinatura no formato ISO 8601, ou null
`one_time_credits`	integer	Saldo de créditos da categoria indicada
`one_time_credits_expires_at`	string \| null	Data de expiração dos créditos avulsos no formato ISO 8601, ou null
`free_credits`	integer	Saldo de créditos da categoria indicada
`total_credits`	integer	Soma de todos os saldos de créditos disponíveis
`is_temporary`	boolean	Indica se o saldo pertence a uma conta temporária

Campo	Tipo	Descrição
`status`	integer	Código de status da aplicação; 200 em caso de sucesso
`cost_ms`	integer	Tempo de processamento desta requisição de API em milissegundos
`request_id`	string	Identificador da requisição para rastrear esta chamada de API
`data`	object	Contêiner dos saldos de créditos atuais
`message`	string	Sempre success em uma resposta bem-sucedida da API; não significa que a tarefa de tradução foi concluída
`data.total_credits`	integer	Soma de todos os saldos de créditos disponíveis
`data.is_temporary`	boolean	Indica se o saldo pertence a uma conta temporária
`data.detail`	object	Detalhamento dos créditos disponíveis por categoria
`data.detail.subscription`	object	Saldo e vencimento da categoria indicada
`data.detail.subscription.credits`	integer	Saldo de créditos da categoria indicada
`data.detail.subscription.expires_at`	string \| null	Data de expiração do crédito no formato ISO 8601, ou null
`data.detail.one_time`	object	Saldo e vencimento da categoria indicada
`data.detail.one_time.credits`	integer	Saldo de créditos da categoria indicada
`data.detail.one_time.expires_at`	string \| null	Data de expiração do crédito no formato ISO 8601, ou null
`data.detail.free`	object	Saldo e vencimento da categoria indicada
`data.detail.free.credits`	integer	Saldo de créditos da categoria indicada
`data.detail.free.expires_at`	null	Sempre null porque este endpoint agregado não fornece uma única data de expiração para os créditos gratuitos

Resposta de exemplo (JSON)

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "batch_id": "00000000-0000-4000-8000-000000000001"
}

Resposta de exemplo (JSON)

{
  "status": 200,
  "cost_ms": 125,
  "request_id": "4b7370383cacccc7",
  "data": {
    "task_id": "00000000-0000-4000-8000-000000000001",
    "batch_id": "00000000-0000-4000-8000-000000000001"
  },
  "message": "success"
}

Resposta de exemplo (JSON)

{
  "status_code": 200,
  "request_id": "4b7370383cacccc7",
  "auth_type": "account",
  "task_reference": "00000000-0000-4000-8000-000000000001",
  "data": {
    "items": [
      {
        "image_id": "00000000-0000-4000-8000-000000000001_0",
        "index": 0,
        "filename": "007.jpg",
        "status": "completed",
        "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
        "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "is_translated": true,
        "output_file_path": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "message": "ok",
        "error": null,
        "inpaint_image_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
        "block_json": []
      }
    ],
    "task_status": "completed"
  }
}

Resposta de exemplo (JSON)

{
  "status": 200,
  "cost_ms": 5300,
  "request_id": "4b7370383cacccc7",
  "data": [
    {
      "image_id": "00000000-0000-4000-8000-000000000001_0",
      "filename": "007.jpg",
      "status": "completed",
      "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
      "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
      "erased_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
      "blocks": [
        {
          "angle": 0,
          "color": "#484848",
          "handwritten": false,
          "location": {
            "left_bottom": [1685, 293],
            "right_bottom": [1786, 293],
            "left_top": [1685, 264],
            "right_top": [1786, 264]
          },
          "text": "OOOUGH!",
          "direction": "horizontal"
        }
      ]
    }
  ],
  "message": "success"
}

Resposta de exemplo (JSON)

{
  "subscription_credits": 0,
  "subscription_credits_expires_at": null,
  "one_time_credits": 0,
  "one_time_credits_expires_at": null,
  "free_credits": 10,
  "total_credits": 10,
  "is_temporary": true
}

Resposta de exemplo (JSON)

{
  "status": 200,
  "cost_ms": 4,
  "request_id": "4b7370383cacccc7",
  "data": {
    "total_credits": 10,
    "is_temporary": true,
    "detail": {
      "subscription": {
        "credits": 0,
        "expires_at": null
      },
      "one_time": {
        "credits": 0,
        "expires_at": null
      },
      "free": {
        "credits": 10,
        "expires_at": null
      }
    }
  },
  "message": "success"
}

Parâmetros da resposta de erro

Em caso de falha na V2, o status HTTP é preservado e o mesmo envelope de cinco campos é retornado.

Campo	Tipo	Descrição
`status`	integer	Código de status de erro HTTP real
`cost_ms`	integer	Tempo de processamento desta requisição de API em milissegundos
`request_id`	string	Identificador da requisição para rastrear esta chamada de API
`data`	object	Contêiner de dados de erro contendo apenas o código estável legível por máquina
`message`	string	Mensagem de erro pública; detalhes internos de diagnóstico não são expostos
`data.code`	string	Código de erro estável legível por máquina

Exemplo de resposta de erro (JSON)

{
  "status": 400,
  "cost_ms": 1,
  "request_id": "4b7370383cacccc7",
  "data": {
    "code": "PZ_API_ACCESS_BAD_REQUEST"
  },
  "message": "Invalid target language"
}

Entradas de exemplo

Chave API

Idioma de origem

Idioma de destino

Modelo

Fonte

Exemplos de API

Rota

Parâmetros

Parâmetros da resposta

Resposta de exemplo (JSON)

Resposta de exemplo (JSON)

Resposta de exemplo (JSON)

Resposta de exemplo (JSON)

Resposta de exemplo (JSON)

Resposta de exemplo (JSON)

Parâmetros da resposta de erro

Exemplo de resposta de erro (JSON)

Entradas de exemplo

Exemplo em Python3

Exemplos cURL

Exemplo em Python3

cURL

Exemplo em Python3

cURL

Rota

Parâmetros

Parâmetros da resposta

Resposta de exemplo (JSON)

Resposta de exemplo (JSON)

Resposta de exemplo (JSON)

Resposta de exemplo (JSON)

Resposta de exemplo (JSON)

Resposta de exemplo (JSON)

Parâmetros da resposta de erro

Exemplo de resposta de erro (JSON)

Entradas de exemplo

Exemplo em Python3

Exemplos cURL

Exemplo em Python3

cURL

Exemplo em Python3

cURL

Preferências de Cookies