> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hy-Image-3.5 Preview Geração de imagens

> Texto para imagem, até 5 imagens de referência, saída 1K / 2K / 4K ou dimensões exatas. Uma imagem por requisição.

<Info>
  Este endpoint é assíncrono. Após o envio, obtenha o ID em `data[0].task_id` e use [Consulta de tarefas](/pt/api-reference/tasks/status) para obter status e imagem. Consulte a cada 3–5 segundos; o tempo limite total recomendado no cliente é de 5 minutos. Pare em `completed` ou `failed`.
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "hy-image-v3.5-preview",
      "prompt": "A golden retriever running on a beach in warm evening light",
      "size": "16:9",
      "resolution": "2K"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.apimart.ai/v1/images/generations",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "hy-image-v3.5-preview",
          "prompt": "A golden retriever running on a beach in warm evening light",
          "size": "16:9",
          "resolution": "2K"
      }
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.apimart.ai/v1/images/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "hy-image-v3.5-preview",
      prompt: "A golden retriever running on a beach in warm evening light",
      size: "16:9",
      resolution: "2K"
    })
  });
  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01K..."
      }
    ]
  }
  ```
</ResponseExample>

## Cabeçalhos da requisição

<ParamField header="Authorization" type="string" required>
  Autenticação Bearer: `Bearer <token>`, em que `<token>` é sua APIMart API Key.
</ParamField>

## Parâmetros da requisição

<ParamField body="model" type="string" required>
  Valor fixo: `hy-image-v3.5-preview`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Descrição para geração ou edição. Aceita chinês e inglês; não pode estar vazia.
</ParamField>

<ParamField body="size" type="string" default="auto">
  Proporção de saída ou dimensões exatas em pixels.

  * Proporção: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
  * Pixels exatos: por exemplo `2000x1104`, respeitando os limites abaixo.
  * `auto` ou omitido: o modelo escolhe a proporção conforme o prompt.

  Com pixels exatos, `resolution` não determina as dimensões.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  Nível de resolução: `1K`, `2K` ou `4K`; padrão `1K`.

  Com pixels exatos, este campo não determina o tamanho. Use sempre um valor aceito; valores não aceitos retornam HTTP 400.
</ParamField>

<ParamField body="width" type="integer">
  Largura exata em pixels. Deve ser enviada com `height` e tem prioridade sobre `size` e `resolution`.

  Largura entre 256 e 8192; largura × altura não pode exceder 8.294.400. Recomendam-se múltiplos de 16.
</ParamField>

<ParamField body="height" type="integer">
  Altura exata em pixels. Deve ser enviada com `width`.

  Altura entre 256 e 8192; largura × altura não pode exceder 8.294.400. Recomendam-se múltiplos de 16.
</ParamField>

<ParamField body="image_urls" type="string[]">
  URLs públicas de referência, até 5 imagens. Omita para texto para imagem; inclua para geração com referências no mesmo endpoint.

  Aceita JPEG, PNG e WEBP. Recomenda-se menos de 7MB por imagem. As URLs devem ser públicas.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Conteúdo que não deve aparecer na imagem.
</ParamField>

<ParamField body="seed" type="integer">
  Semente aleatória; inteiro não negativo. `0` ou omissão usa um valor aleatório.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Uma imagem por requisição. Apenas `1` é aceito; outros valores retornam HTTP 400.
</ParamField>

## Seleção de dimensões

Prioridade: par `width` / `height` → pixels exatos em `size` → proporção ou `auto` em `size` junto com `resolution`.

Para pixels exatos, largura e altura devem ficar entre 256 e 8192, com no máximo 8.294.400 pixels no total. Recomendam-se múltiplos de 16 para ambas.

### Exemplo de pixels exatos

```json theme={null}
{
  "model": "hy-image-v3.5-preview",
  "prompt": "A minimalist seaside travel poster with a warm sunset",
  "width": 2000,
  "height": 1104
}
```

Você também pode omitir `width` e `height` e enviar `"size": "2000x1104"`.

### Exemplo com imagem de referência

```json theme={null}
{
  "model": "hy-image-v3.5-preview",
  "prompt": "Make the car in the reference image red, preserving the original background and lighting",
  "image_urls": ["https://example.com/car.png"],
  "size": "16:9",
  "resolution": "2K",
  "negative_prompt": "blur, text watermarks",
  "seed": 42,
  "n": 1
}
```

Substitua as URLs de exemplo por endereços públicos reais. Para várias referências, adicione URLs em `image_urls`, até 5 imagens no total.

## Resposta de envio

<ResponseField name="code" type="integer">
  Código de resposta; `200` indica sucesso.
</ResponseField>

<ResponseField name="data" type="array">
  Resultado do envio da tarefa.

  <Expandable title="Mostrar campos da tarefa">
    <ResponseField name="status" type="string">
      `submitted` indica envio bem-sucedido, não conclusão da geração.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      ID da tarefa para consultar status e resultados.
    </ResponseField>
  </Expandable>
</ResponseField>

## Consultar resultados

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'
```

Exemplo de resposta bem-sucedida (URL de imagem ilustrativa):

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.png"]
        }
      ]
    }
  }
}
```

* `pending` / `processing`: continuar consultando.
* `completed`: obter a URL em `data.result.images[0].url[0]`; `url` é um array de strings.
* `failed`: parar as consultas e ler o motivo em `data.error.message`. Reembolso integral. Violações no prompt e reprovações na moderação também são tratadas como falhas.

As imagens são armazenadas no CDN da plataforma. Baixe e salve antes do prazo `expires_at` informado no resultado.

## Cobrança

Cobrança por imagem. Consulte os [preços dos modelos](https://apimart.ai/pricing).

* Com proporção, a cobrança segue o nível `resolution`.
* Com pixels exatos, o lado mais curto determina o nível:

| Nível | Lado mais curto |
| - | - |
| 1K | Até 1024 pixels |
| 2K | 1025–2048 pixels |
| 4K | Acima de 2048 pixels |

Tarefas que falham recebem reembolso integral.

## Erros de parâmetros comuns

Os seguintes casos retornam HTTP 400 de forma síncrona, sem criar tarefa nem cobrar:

| Problema | Ação |
| - | - |
| `prompt` vazio | Fornecer um prompt não vazio |
| `n` diferente de `1` | Solicitar apenas uma imagem por vez |
| `seed` negativo | Usar inteiro não negativo; `0` significa aleatório |
| `resolution` não aceita | Usar `1K`, `2K` ou `4K` |
| Proporção de `size` não aceita | Usar uma das 10 proporções acima ou `auto` |
| Dimensões fora dos limites | Largura e altura entre 256 e 8192, total máximo de 8.294.400 pixels |
| Mais de 5 imagens de referência | Reduzir `image_urls` para no máximo 5 imagens |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.