> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Instruções de Integração da API de Geração de Imagens SeeDream
> ByteDance Seedream Image Generation API guide - Ace Data Cloud
Este documento apresentará uma instrução de integração da API de Geração de Imagens SeeDream, que pode gerar imagens oficiais da SeeDream através da entrada de parâmetros personalizados.
## Processo de Solicitação
Para usar a API de Geração de Imagens SeeDream, primeiro acesse o [Console da Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu Token de API, que deve ser guardado para uso futuro.
Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e fazer login. Após a conclusão, você será redirecionado de volta para a página atual.
**Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar individualmente para cada serviço.** A primeira solicitação oferece um crédito gratuito para que você possa experimentar; quando o crédito estiver baixo, você pode recarregar o saldo geral no [console](https://platform.acedata.cloud/console/coin).
> 📘 Documentação Completa: [API de Geração de Imagens SeeDream →](https://platform.acedata.cloud/documents/seedream-images)
## Uso Básico
Primeiro, entenda a forma básica de uso, que consiste em inserir a palavra-chave `prompt`, a ação `action` e o tamanho da imagem `size`, para obter o resultado processado. Primeiro, é necessário passar um campo `action`, cujo valor deve ser `generate`, e em seguida, precisamos inserir a palavra-chave, conforme detalhado abaixo:
Podemos ver que aqui configuramos os Cabeçalhos da Solicitação, incluindo:
* `accept`: o formato de resposta desejado, que deve ser preenchido como `application/json`, ou seja, formato JSON.
* `authorization`: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.
Além disso, configuramos o Corpo da Solicitação, incluindo:
* `prompt`: palavra-chave.
* `model`: modelo de geração, padrão `doubao-seedream-5-0-260128` (SeeDream 5.0 Lite, o mais recente). Suporta `doubao-seedream-5-0-pro-260628`, `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828`, `doubao-seedream-3-0-t2i-250415`, `doubao-seededit-3-0-i2i-250628`. O `doubao-seedream-5-0-pro-260628` (SeeDream 5.0 Pro) é o modelo de imagem única, gerando apenas uma única imagem, **não suporta geração de múltiplas imagens (`sequential_image_generation`), streaming (`stream`) e busca na web (`tools`)**. **O `model` deve ser passado como uma string completa do modelo (como `doubao-seedream-5-0-260128`), passar abreviações como `doubao-seedream-5.0-lite` resultará em erro 400.**
* `image`: informações da imagem de entrada, suportando URL ou codificação Base64. Dentre eles, `doubao-seedream-5-0-pro-260628` suporta entrada de uma ou várias imagens (2-10 imagens, a partir da segunda imagem será cobrado por imagem), `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` suportam entrada de uma ou várias imagens, `doubao-seededit-3-0-i2i-250628` suporta apenas entrada de uma imagem, `doubao-seedream-3-0-t2i-250415` não suporta esse parâmetro.
* `size`: especifica as informações de tamanho da imagem gerada, suportando as seguintes duas formas, que não podem ser misturadas. Forma 1 | Especifica a resolução da imagem gerada e descreve a proporção largura-altura da imagem em linguagem natural no prompt. **As predefinições suportadas variam entre os modelos**: `doubao-seedream-5-0-pro-260628` suporta `1K`/`2K`; `doubao-seedream-5-0-260128` suporta `2K`/`3K`/`4K`; `doubao-seedream-4-5-251128` suporta apenas `2K`/`4K`; `doubao-seedream-4-0-250828` suporta `1K`/`2K`/`4K`; `doubao-seedream-3-0-t2i-250415` e `doubao-seededit-3-0-i2i-250628` **não suportam predefinições**, aceitam apenas a forma 2. Forma 2 | Especifica os valores de pixel da largura e altura da imagem gerada: padrão `2048x2048`, o total de pixels e a proporção largura-altura variam conforme o modelo (por exemplo, o intervalo total de pixels do 5.0 Pro é \[921600, 4194304], o limite inferior do 5.0 Lite / 4.5 é 3.686.400, o limite inferior do 4.0 é 921.600, e o intervalo do 3.0-t2i / seededit-3.0-i2i é \[512x512, 2048x2048]).
* `seed`: semente de número aleatório, usada para controlar a aleatoriedade do conteúdo gerado pelo modelo. O intervalo de valores é \[-1, 2147483647]. **Apenas `doubao-seedream-3-0-t2i-250415` suporta esse parâmetro**.
* `sequential_image_generation`: múltiplas imagens: um conjunto de imagens relacionadas geradas com base no conteúdo que você inseriu. `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` suportam esse parâmetro, padrão `disabled`.
* `stream`: controla se o modo de saída em streaming está ativado. `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` suportam esse parâmetro, padrão é `false`.
* `guidance_scale`: grau de consistência entre o resultado da saída do modelo e o prompt, quanto maior o valor, mais forte a correlação. O intervalo de valores é \[1, 10]. `doubao-seedream-3-0-t2i-250415` tem valor padrão 2.5, `doubao-seededit-3-0-i2i-250628` tem valor padrão 5.5, outros modelos não suportam.
* `response_format`: especifica o formato de retorno da imagem gerada. O padrão é `url`, também suporta `b64_json`.
* `watermark`: se deve adicionar uma marca d'água à imagem gerada. O padrão é `true`.
* `output_format`: especifica o formato do arquivo da imagem gerada, suportando `jpeg` (padrão) e `png`. Apenas `doubao-seedream-5-0-pro-260628` e `doubao-seedream-5-0-260128` suportam.
* `tools`: configura os ferramentas que o modelo deve chamar, atualmente suporta `web_search` (busca na web). Apenas `doubao-seedream-5-0-260128` suporta.
* `callback_url`: URL que precisa receber o resultado de retorno.
* `async`: se deve processar em modo assíncrono. Se definido como `true`, a interface retorna imediatamente `task_id`, não sendo necessário fornecer `callback_url`, e em seguida, você pode obter os resultados através de `/seedream/tasks`.
Após a seleção, você pode notar que o código correspondente também foi gerado à direita, como mostrado na imagem:
Clique no botão "Try" para realizar o teste, como mostrado na imagem acima, e aqui obtivemos o seguinte resultado:
```json theme={null}
{
"success": true,
"task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
"trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
"data": [
{
"prompt": "Uma foto realista de um frasco de perfume de vidro fosco sobre ardósia preta molhada, luz chave de softbox única, gotas de água, fundo escuro e sombrio, 85mm macro.",
"size": "2048x2048",
"image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
}
]
}
```
Os resultados retornados têm vários campos, conforme descrito abaixo:
* `success`, o estado atual da tarefa de geração de vídeo.
* `task_id`, o ID da tarefa de geração de vídeo atual.
* `trace_id`, o ID de rastreamento da geração de vídeo atual.
* `data`, a lista de resultados da tarefa de geração de imagem atual.
* `image_url`, o link da tarefa de geração de imagem atual.
* `prompt`, a palavra-chave.
* `size`: a resolução da imagem gerada.
Podemos ver que recebemos informações de imagem satisfatórias, e só precisamos obter a imagem gerada do SeeDream com base no link da imagem no resultado `data`.
Além disso, se você quiser gerar o código correspondente, pode copiá-lo diretamente, como o código CURL abaixo:
```shell theme={null}
curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
"action": "generate",
"model": "doubao-seedream-5-0-260128",
"prompt": "Uma foto realista de um frasco de perfume de vidro fosco sobre ardósia preta molhada, luz chave de softbox única, gotas de água, fundo escuro e sombrio, 85mm macro."
}'
```
## Editar Tarefa de Imagem
Se você quiser editar uma imagem específica, primeiro o parâmetro `image` deve conter o link da imagem que precisa ser editada.
* model: o modelo utilizado para a tarefa de edição de imagem, `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` suportam entrada de uma ou mais imagens, `doubao-seededit-3-0-i2i-250628` suporta apenas entrada de uma imagem.
* image: faça o upload da imagem que precisa ser editada, uma ou mais.
Um exemplo de preenchimento é o seguinte:
Código correspondente:
```python theme={null}
import requests
url = "https://api.acedata.cloud/flux/images"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "doubao-seedream-4-0-250828",
"prompt": "Mantenha a pose do modelo e a forma do vestido líquido inalteradas. Mude o material da roupa de metal prateado para água completamente transparente (ou vidro). Através do fluxo do líquido, os detalhes da pele do modelo são visíveis. O efeito de luz e sombra muda de reflexão para refração.",
"image": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"],
"size": "2K",
"watermark": False
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
Ao clicar em executar, você pode ver que receberá imediatamente um resultado, como abaixo:
```json theme={null}
{
"success": true,
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
"trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
"data": [
{
"prompt": "Mantenha a pose do modelo e a forma do vestido líquido inalteradas. Mude o material da roupa de metal prateado para água completamente transparente (ou vidro). Através do fluxo do líquido, os detalhes da pele do modelo são visíveis. O efeito de luz e sombra muda de reflexão para refração.",
"size": "2048x2048",
"image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
Podemos ver que o efeito gerado é uma edição da imagem original, e o resultado é semelhante ao mencionado acima.
## Callback Assíncrono
Como a API de Geração de Imagens SeeDream leva um tempo relativamente longo para gerar, cerca de 1-2 minutos, se a API não responder por um longo tempo, a solicitação HTTP manterá a conexão, resultando em consumo adicional de recursos do sistema. Portanto, esta API também oferece suporte a callbacks assíncronos.
O fluxo geral é: quando o cliente inicia a solicitação, deve especificar um campo `callback_url` adicional. Após o cliente fazer a solicitação da API, a API retornará imediatamente um resultado, contendo um campo `task_id`, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado da imagem gerada será enviado para o `callback_url` especificado pelo cliente no formato JSON POST, que também incluirá o campo `task_id`, permitindo que o resultado da tarefa seja associado pelo ID.
Se você não tiver um endereço público disponível para callback, também pode não especificar `callback_url`, mas definir o campo `async` como `true` na solicitação. Nesse caso, a interface também retornará imediatamente o `task_id`, mas não enviará o resultado. Você precisará usar esse `task_id` para chamar a interface `/seedream/tasks` e consultar o status da tarefa para obter o resultado final.
Vamos entender como operar isso através de um exemplo.
Ao clicar em executar, você pode ver que receberá imediatamente um resultado, como abaixo:
```
{
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}
```
O conteúdo é o seguinte:
```json theme={null}
{
"success": true,
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
"trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
"data": [
{
"prompt": "Mantenha a pose do modelo e a forma do vestido líquido inalteradas. Mude o material da roupa de metal prateado para água completamente transparente (ou vidro). Através do fluxo do líquido, os detalhes da pele do modelo são visíveis. O efeito de luz e sombra muda de reflexão para refração.",
"size": "2048x2048",
"image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
Podemos ver que o resultado contém um campo `task_id`, e os outros campos são semelhantes ao mencionado acima, permitindo a associação da tarefa através desse campo.
## Tratamento de Erros
Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de erro correspondentes. Por exemplo:
* `400 token_mismatched`: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
* `400 api_not_implemented`: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
* `401 invalid_token`: Não autorizado, token de autorização inválido ou ausente.
* `429 too_many_requests`: Muitas solicitações, você excedeu o limite de taxa.
* `500 api_error`: Erro interno do servidor, algo deu errado no servidor.
### Exemplo de Resposta de Erro
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Conclusão
Através deste documento, você já entendeu como usar a API de Geração de Imagens SeeDream para gerar imagens através da entrada de palavras-chave. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, sinta-se à vontade para entrar em contato com nossa equipe de suporte técnico.