# SDK oficial Biziva — JavaScript / TypeScript v0.1.0

Node20+; sem dependências de execução. Instalação pelo pacote oficial (não está no registro npm):

```sh
npm install https://api.biziva.com.br/sdk/v0.1.0/biziva-sdk-0.1.0.tgz
```

```js
import {Biziva,SANDBOX_URL} from '@biziva/sdk';
const client=new Biziva({apiKey:process.env.BIZIVA_API_KEY,baseUrl:SANDBOX_URL});
const result=await client.text({model:'biziva-validated',messages:[{role:'user',content:'Olá'}]},
 {idempotencyKey:'pedido-interno-0001'});
console.log(result.choices[0].message.content);
```

Crie chave de homologação em https://api.biziva.com.br/developers. SANDBOX usa somente fixtures e moeda virtual; não mede a qualidade do modelo real. Para produção, use outra chave e omita baseUrl. Não exponha chave em frontend/browser/repositório.

Métodos: models(), balance() (usage:read), text(), images(), editImage(), createVideo(), video(), videoContent(), speech(), transcribe(FormData), embeddings(), job() e request(method,'/v1/...',options). textStream() somente para endpoints/modelos que ofereçam SSE; não converte resposta JSON em streaming. Métodos genéricos permitem outras rotas documentadas. Arquivos são Uint8Array; grave no servidor com fs.writeFile. Métodos de áudio dependem dos formatos suportados pelo endpoint.

Todas as mutações exigem idempotencyKey estável. Guarde a chave por operação em seu banco, inclusive após timeout. O SDK nunca repete automaticamente POST/PATCH/DELETE, não troca provedor e não gera fallback pago. BizivaError tem status/code/requestId/idempotencyKey/uncertain. Após uncertain=true, consulte a requisição original antes de iniciar outra. Chaves diferentes podem gerar nova cobrança. Não execute exemplos de mídia em produção sem intenção de consumo e saldo próprio.

Exemplo de imagem:
```js
const image=await client.images({model:'biziva-image',prompt:'Fixture de integração'},
 {idempotencyKey:'imagem-pedido-0001'});
```

Vídeo em homologação entrega apenas metadados de fixture, não arquivo MP4. Pagamentos /v1/test/payments são virtuais e não geram Pix; nunca os use como comprovação comercial. Texto/imagem/áudio de homologação não são geração real. Não envie pacientes/clientes reais.