Nesta página
Seedream API para Seedream 5.0 Pro
Use o Seedream 5.0 Pro pela Seedream API para gerar uma imagem por texto ou até dez referências HTTPS públicas. A Imya gerencia autenticação, tarefas, créditos em tempo real, erros seguros e resultados armazenados.
REST API · v1 · Tarefas assíncronas
O que você pode criar
Use um único fluxo REST para criação por texto, variações por referência e automação de imagens.
Imagens de produto e campanha
Gere cenas de produto, conceitos de publicidade e visuais de marca por texto.
Variações por referência
Use de 1 a 10 imagens para orientar assunto, composição ou direção visual.
Fluxos automatizados
Envie de forma assíncrona, consulte o task ID e receba a imagem armazenada.
Primeira solicitação à Seedream API
Crie uma tarefa, salve o task ID público e consulte até concluir ou falhar.
- 1
Criar uma API Key
Gere uma chave na conta Imya.
- 2
Escolher a entrada
Use apenas prompt ou adicione de 1 a 10 referências.
- 3
Obter o resultado
Consulte o task ID a cada 5 segundos ou mais.
Autenticação e idempotência
Envie a API Key como Bearer token. Todo POST exige Idempotency-Key única para repetir sem duplicar tarefa ou cobrança.
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEYCriar uma geração de imagem
Omita image_urls para texto em imagem. Adicione de 1 a 10 URLs HTTPS públicas para referências. O servidor retorna credits_reserved em tempo real.
/v1/images/generationscurl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedream-product-shot-001" \
-d '{
"model": "seedream-5-pro",
"prompt": "A premium skincare bottle on pale stone, soft morning light",
"aspect_ratio": "4:3",
"quality": "basic",
"output_format": "png",
"n": 1
}'curl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedream-edit-001" \
-d '{
"model": "seedream-5-pro",
"prompt": "Keep the product shape and place it in a warm studio",
"image_urls": ["https://cdn.example.com/input/product.png"],
"aspect_ratio": "4:3",
"quality": "high",
"output_format": "jpeg",
"n": 1
}'Consultar uma tarefa
Retorna status, custo final, imagem armazenada ou erro seguro. Consulte em intervalos de pelo menos 5 segundos.
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| model | string | Sim | Use seedream-5-pro. |
| prompt | string | Sim | Instruções de 3 a 3.000 caracteres. |
| image_urls | string[] | Não | De 1 a 10 referências HTTPS públicas. Omita para texto em imagem. |
| aspect_ratio | string | Não | 1:1, 4:3, 3:4, 16:9, 9:16, 2:3 ou 3:2. Padrão: 1:1. |
| quality | string | Não | basic ou high. 16:9 e 9:16 aceitam apenas basic. |
| output_format | string | Não | png ou jpeg. Padrão: png. |
| n | number | Não | Deve ser 1. Uma imagem é gerada. |
Respostas
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "seedream-5-pro",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 44
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "seedream-5-pro",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:38.000Z",
"credits_reserved": 44,
"credits_used": 44,
"data": [
{
"url": "https://cdn.imya.ai/generated/example.png"
}
]
}Uma tarefa nova retorna HTTP 202. Uma repetição idêntica retorna HTTP 200 e Idempotent-Replayed: true. A imagem é copiada para o armazenamento Imya antes de succeeded.
Créditos em tempo real
basic e high têm custo base de 35 créditos. O servidor aplica o coeficiente do plano e retorna credits_reserved. Se não concluir em 30 minutos, a tarefa falha e os créditos elegíveis são devolvidos uma vez sem mudar a validade.
Ver planos de créditosStatus da tarefa
pendingA tarefa foi aceita e aguarda início.
processingO modelo está gerando a imagem.
succeededA geração terminou e data contém a imagem.
failedA geração falhou. Leia o objeto error seguro.
Erros
400Idempotency-Key ausente ou JSON inválido.
401API Key ausente ou inválida.
402Créditos insuficientes.
403Conta desativada ou solicitação não permitida.
404Tarefa inexistente ou de outra conta.
409Chave reutilizada com outro corpo.
413O corpo excede 64 KiB.
415Content-Type deve ser application/json.
422Parâmetro, prompt ou referência inválida.
429Limite de velocidade ou concorrência atingido.
5xxNão foi possível concluir. Verifique a tarefa antes de criar outra.
Contrato comum da API pública da Imya
Estas regras valem para todos os endpoints públicos de geração. Campos e preços específicos ficam na tabela do modelo.
Cobrança e repetição segura
Ao aceitar uma nova tarefa, os créditos exatos de credits_reserved são descontados atomicamente. Repetir a mesma Idempotency-Key e corpo retorna a tarefa original sem nova cobrança.
Prazo e reembolsos
Uma tarefa que não conclui em 30 minutos falha. Créditos elegíveis são devolvidos uma vez e mantêm a validade original.
Limites de velocidade e concorrência
Cada API Key aceita 120 solicitações por 60 segundos; uma conta executa até cinco tarefas de imagem ou três de vídeo. Respeite Retry-After no 429.
Consulta e propriedade
Consulte GET /v1/tasks/{id} com o id retornado e intervalo mínimo de 5 segundos. Só a conta criadora pode ler a tarefa; webhooks, SDK e envio batch não estão disponíveis.
Erros e segurança
Erros públicos removem credenciais, URLs internas e detalhes de infraestrutura. Um prompt inseguro pode ser rejeitado com prompt_blocked.
Retenção de imagens
Contas grátis mantêm imagens por 7 dias e contas pagas ativas ou Lifetime por até 30. Depois, status é failed e error.code é media_deleted.
Guia de integração em produção da Seedream API
Projete a integração do Seedream 5.0 Pro como um sistema de tarefas assíncronas recuperável, não como uma solicitação HTTP longa. Salve sempre o id da Imya e torne as repetições determinísticas.
Escolher parâmetros do contrato
Valide cada solicitação com a tabela desta página. Comece com a configuração mínima e aumente qualidade, tamanho, duração ou referências somente quando necessário.
Preserve a ordem das referências e confirme os direitos de uso.
Projetar um fluxo assíncrono recuperável
Envie a tarefa de imagem, salve id e consulte GET /v1/tasks/{id} com intervalo mínimo de 5 segundos. Os status públicos são pending, processing, succeeded e failed e o limite é 30 minutos. Não há webhooks, SDK ou batch.
- 01Salve id, status, credits_reserved e identidade da solicitação antes de atualizar a UI.
- 02Use backoff, respeite Retry-After no 429 e não transforme erro de transporte em outra tarefa paga.
- 03Limite a cinco tarefas de imagem por conta e 120 solicitações por 60 segundos e API Key.
Cobrança e repetição determinísticas
Na aceitação, credits_reserved é descontado. Salve uma Idempotency-Key por criação; repeti-la com o mesmo corpo retorna a tarefa original.
Falhas elegíveis são reembolsadas uma vez com a validade original. refund_pending indica liquidação e credits_refunded confirma.
Proteger credenciais, propriedade e mídia
Mantenha API Keys no servidor e associe id ao usuário autenticado. Registre identificadores de suporte sem expor prompts, URLs privadas ou credenciais.
Imagens duram 7 dias no grátis e até 30 no pago ativo ou Lifetime. Depois status é failed e error.code media_deleted.
Checklist de produção
- Valide campos do modelo.
- Salve Idempotency-Key e corpo.
- Persista status e consulte a cada 5 segundos ou mais.
- Aplique concorrência e velocidade.
- Trate os quatro status e códigos de liquidação.
- Mantenha credenciais no servidor e defina retenção.
Perguntas frequentes
Com que frequência consultar?
Espere pelo menos 5 segundos e use backoff.
Quando os créditos são cobrados?
Na aceitação, credits_reserved é descontado.
Uma repetição cobra duas vezes?
Não com a mesma Idempotency-Key e corpo.
Como tratar falha final?
Mostre erro seguro, preserve id e verifique credits_refunded.
Pronto para desenvolver?
Crie uma API Key ou teste prompts, referências e qualidade no gerador antes de integrar.