> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Instruções para Integração da API SeeDream Images Generation > ByteDance Seedream Image Generation 集成指南 - XHuoAPI Este documento apresenta as instruções para integração da API SeeDream Images Generation, que permite gerar imagens oficiais do SeeDream a partir de parâmetros personalizados. ## Processo de Solicitação Para usar a API, é necessário primeiro solicitar o serviço na página correspondente do [SeeDream Images Generation API](https://api.xhuoapi.ai/documents/seedream-images). Ao acessar a página, clique no botão "Acquire", conforme mostrado na imagem: ![](https://cdn.xhuoapi.ai/q6ytrc.png) Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login para se registrar e entrar. Após o login, você será redirecionado de volta para a página atual. Na primeira solicitação, há uma cota gratuita disponível para uso da API. ## Uso Básico Primeiro, entenda o modo básico de uso: basta inserir o prompt, a ação de geração (`action`) e o tamanho da imagem (`size`) para obter o resultado processado. Inicialmente, é necessário enviar um campo `action` com o valor `generate`, além do prompt. O conteúdo específico é o seguinte:

Aqui configuramos os Request Headers, incluindo: * `accept`: formato desejado para a resposta, aqui definido como `application/json` (formato JSON). * `authorization`: chave de acesso à API, que pode ser selecionada após a solicitação. Também configuramos o Request Body, incluindo: * `prompt`: o prompt de texto. * `model`: modelo de geração, padrão `doubao-seedream-5.0-lite`. Suporta `doubao-seedream-5.0-lite` (mais recente), `doubao-seedream-4.5`, `doubao-seedream-4.0`, `doubao-seedream-3.0-t2i`, `doubao-seededit-3.0-i2i`. * `image`: informações da imagem de entrada, suportando URL ou codificação Base64. Os modelos `doubao-seedream-5.0-lite`, `doubao-seedream-4.5`, `doubao-seedream-4.0` suportam entrada de uma ou múltiplas imagens; `doubao-seededit-3.0-i2i` suporta apenas uma imagem; `doubao-seedream-3.0-t2i` não suporta este parâmetro. * `size`: especifica o tamanho da imagem gerada, suportando duas formas, que não podem ser usadas simultaneamente.\ Forma 1 | Define a resolução da imagem gerada e descreve a proporção da imagem em linguagem natural no prompt. **Cada modelo suporta presets diferentes**: `doubao-seedream-5.0-lite` suporta `2K`/`3K`/`4K`; `doubao-seedream-4.5` suporta apenas `2K`/`4K`; `doubao-seedream-4.0` suporta `1K`/`2K`/`4K`; `doubao-seedream-3.0-t2i` e `doubao-seededit-3.0-i2i` **não suportam presets**, aceitando apenas a Forma 2.\ Forma 2 | Define a largura e altura em pixels da imagem gerada: padrão `2048x2048`. O intervalo de pixels totais e proporção varia conforme o modelo (por exemplo, limite inferior de pixels totais para 5.0 / 4.5 é 3.686.400, para 4.0 é 921.600, para 3.0-t2i / seededit-3.0-i2i é \[512x512, 2048x2048]). * `seed`: semente aleatória para controlar a aleatoriedade da geração. Intervalo \[-1, 2147483647]. **Apenas `doubao-seedream-3.0-t2i` suporta este parâmetro**. * `sequential_image_generation`: geração de conjunto de imagens relacionadas com base no conteúdo inserido. Suportado por `doubao-seedream-5.0-lite`, `doubao-seedream-4.5`, `doubao-seedream-4.0`. Padrão `disabled`. * `stream`: controla se o modo de saída em streaming está ativado. Suportado por `doubao-seedream-5.0-lite`, `doubao-seedream-4.5`, `doubao-seedream-4.0`. Padrão `false`. * `guidance_scale`: grau de correspondência do resultado do modelo com o prompt, quanto maior, maior a correlação. Intervalo \[1, 10]. Valor padrão 2.5 para `doubao-seedream-3.0-t2i`, 5.5 para `doubao-seededit-3.0-i2i`. Não suportado por outros modelos. * `response_format`: formato de retorno da imagem gerada. Padrão `url`, também suporta `b64_json`. * `watermark`: se deve adicionar marca d’água na imagem gerada. Padrão `true`. * `output_format`: formato do arquivo da imagem gerada, suporta `jpeg` (padrão) e `png`. Apenas `doubao-seedream-5.0-lite` suporta. * `tools`: configura ferramentas que o modelo pode chamar, atualmente suporta `web_search` (pesquisa online). Apenas `doubao-seedream-5.0-lite` suporta. * `callback_url`: URL para callback do resultado. Após a seleção, o código correspondente é gerado à direita, conforme a imagem:

Clique no botão "Try" para testar. Conforme a imagem acima, obtemos o seguinte resultado: ```json theme={null} { "success": true, "task_id": "25027ba3-0430-4a1b-91c8-d2297f19ba73", "trace_id": "8043a9e9-692f-43b0-82f7-5890f798be38", "data": [ { "prompt": "a white siamese cat", "size": "2048x2048", "image_url": "https://platform.cdn.xhuoapi.ai/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg" } ] } ``` O resultado retornado contém vários campos, descritos a seguir: * `success`: status da tarefa de geração de imagem. * `task_id`: ID da tarefa de geração. * `trace_id`: ID de rastreamento da tarefa. * `data`: lista de resultados da tarefa de geração de imagem. * `image_url`: link da imagem gerada. * `prompt`: prompt utilizado. * `size`: resolução da imagem gerada. Assim, obtemos as informações da imagem desejada, bastando acessar o link em `data` para obter a imagem SeeDream gerada. Se desejar gerar o código de integração correspondente, pode copiar diretamente, por exemplo, o código CURL abaixo: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/seedream/images' \ -H 'accept: application/json' \ -H 'authorization: Bearer ${token}' \ -H 'content-type: application/json' \ -d '{ "action": "generate", "model": "doubao-seedream-4-0-250828", "prompt": "a white siamese cat" }' ``` ## Tarefa de Edição de Imagem Para editar uma imagem, o parâmetro `image` deve conter o link da imagem a ser editada. * `model`: modelo usado para a tarefa de edição, `doubao-seedream-5.0-lite`, `doubao-seedream-4.5`, `doubao-seedream-4.0` suportam entrada de uma ou múltiplas imagens; `doubao-seededit-3.0-i2i` suporta apenas uma imagem. * `image`: imagem(s) a ser(em) editada(s), uma ou múltiplas. Exemplo de preenchimento:

Código correspondente: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/flux/images" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "doubao-seedream-4-0-250828", "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.", "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 executar, obteremos imediatamente o resultado: ```json theme={null} { "success": true, "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde", "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286", "data": [ { "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.", "size": "2048x2048", "image_url": "https://platform.cdn.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg" } ] } ``` O resultado mostra o efeito da edição da imagem original, similar ao exemplo anterior. ## Callback Assíncrono Como a geração de imagens pela SeeDream Images Generation API pode levar de 1 a 2 minutos, se a API não responder por muito tempo, a requisição HTTP permanecerá aberta, consumindo recursos do sistema. Por isso, a API oferece suporte a callbacks assíncronos. O fluxo geral é: o cliente envia a requisição incluindo o campo `callback_url`. Após o envio, a API retorna imediatamente um resultado contendo o campo `task_id`, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado da geração da imagem será enviado via POST em JSON para o `callback_url` especificado, incluindo também o campo `task_id`, permitindo associar o resultado à tarefa. Vamos ver um exemplo prático. Ao executar, obteremos imediatamente o resultado: ``` { "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde" } ``` Conteúdo do callback: ```json theme={null} { "success": true, "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde", "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286", "data": [ { "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.", "size": "2048x2048", "image_url": "https://platform.cdn.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg" } ] } ``` O campo `task_id` permite associar o resultado à tarefa correspondente. ## Tratamento de Erros Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de erro correspondentes. Exemplos: * `400 token_mismatched`: Requisição inválida, possivelmente por parâmetros ausentes ou inválidos. * `400 api_not_implemented`: Requisição inválida, possivelmente por 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 requisições, limite de taxa excedido. * `500 api_error`: Erro interno do 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 Com este documento, você aprendeu como usar a SeeDream Images Generation API para gerar imagens a partir de prompts. Esperamos que este guia ajude você a integrar e utilizar a API de forma eficiente. Em caso de dúvidas, entre em contato com nossa equipe de suporte técnico.