Seedream 4.0 API Documentation
Seedream Text to Image - Request Code
POST https://gateway.pixazo.ai/byteplus/v1/getTextToImage Content-Type: application/json Cache-Control: no-cache Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY { "prompt": "A fisheye lens close-up of a cat’s head, where the unique distortion of the lens exaggerates and warps the cat’s facial features for a playful, dramatic effect.", "model": "seedream-3-0-t2i-250415", "size": "1024x1024", "guidance_scale": 2.5, "watermark": true } import requests url = "https://gateway.pixazo.ai/byteplus/v1/getTextToImage" headers = { "Content-Type": "application/json", "Cache-Control": "no-cache", "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY" } data = { "prompt": "A fisheye lens close-up of a cat’s head, where the unique distortion of the lens exaggerates and warps the cat’s facial features for a playful, dramatic effect.", "model": "seedream-3-0-t2i-250415", "size": "1024x1024", "guidance_scale": 2.5, "watermark": True } response = requests.post(url, json=data, headers=headers) print(response.json()) const url = 'https://gateway.pixazo.ai/byteplus/v1/getTextToImage'; const headers = { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY' }; const data = { prompt: 'A fisheye lens close-up of a cat’s head, where the unique distortion of the lens exaggerates and warps the cat’s facial features for a playful, dramatic effect.', model: 'seedream-3-0-t2i-250415', size: '1024x1024', guidance_scale: 2.5, watermark: true }; fetch(url, { method: 'POST', headers: headers, body: JSON.stringify(data) }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error('Error:', error)); curl -v -X POST "https://gateway.pixazo.ai/byteplus/v1/getTextToImage" \ -H "Content-Type: application/json" \ -H "Cache-Control: no-cache" \ -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \ --data-raw '{ "prompt": "A fisheye lens close-up of a cat’s head, where the unique distortion of the lens exaggerates and warps the cat’s facial features for a playful, dramatic effect.", "model": "seedream-3-0-t2i-250415", "size": "1024x1024", "guidance_scale": 2.5, "watermark": true }' import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; public class Main { public static void main(String[] args) throws Exception { String json = """ { "prompt": "A fisheye lens close-up of a cat’s head, where the unique distortion of the lens exaggerates and warps the cat’s facial features for a playful, dramatic effect.", "model": "seedream-3-0-t2i-250415", "size": "1024x1024", "guidance_scale": 2.5, "watermark": true } """; HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://gateway.pixazo.ai/byteplus/v1/getTextToImage")) .headers("Content-Type", "application/json", "Cache-Control", "no-cache", "Ocp-Apim-Subscription-Key", "YOUR_SUBSCRIPTION_KEY") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } } <?php $url = 'https://gateway.pixazo.ai/byteplus/v1/getTextToImage'; $headers = [ 'Content-Type: application/json', 'Cache-Control: no-cache', 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' ]; $data = json_encode([ 'prompt' => 'A fisheye lens close-up of a cat’s head, where the unique distortion of the lens exaggerates and warps the cat’s facial features for a playful, dramatic effect.', 'model' => 'seedream-3-0-t2i-250415', 'size' => '1024x1024', 'guidance_scale' => 2.5, 'watermark' => true ]); $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $response = curl_exec($ch); curl_close($ch); echo $response; ?> Output
Successful API response:
{ "created": 1757499942, "data": [{ "url": "https://..../byteplus/XXXXXXXXXXXXXXX-hntkjsg9kj.jpg" }], "usage": { "generated_images": 1 } } Request Body - Seedream Text to Image
Parameters for /getTextToImage:
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | No | string | The ID of the model to call. You can activate a model service and query the model ID. An endpoint ID can also be used to call a |
| prompt | Yes | string | The text prompt used to generate the image. Describes the style and content for the generated image. |
| response_format | No | string | Specifies the format of the generated image returned in the response. Supported values: "url" (downloadable JPEG image link), "b64_json" (Base64-encoded JSON string). |
| size | No | string | Specifies the dimensions (width x height in pixels) of the generated image. Must be between 512x512 and 2048x2048. Recommended: 1024x1024 (1:1), 864x1152 (3:4), 1152x864 (4:3), 1280x720 (16:9), 720x1280 (9:16), 832x1248 (2:3), 1248x832 (3:2), 1512x648 (21:9). |
| seed | No | integer | Random seed to control stochasticity. Range: [-1, 2147483647]. -1 or unset means auto-generated. Use the same seed to reproduce results. |
| guidance_scale | No | float | Controls how closely the output matches the prompt. Higher values = stronger prompt adherence, less freedom. Range: [1, 10]. |
| watermark | No | boolean | Whether to add a watermark. false: No watermark. true: Adds "AI generated" in bottom-right corner. |
Example Request - Seedream Text to Image
JSON
{ "prompt": "A fisheye lens close-up of a cat’s head, where the unique distortion of the lens exaggerates and warps the cat’s facial features for a playful, dramatic effect.", "model": "seedream-3-0-t2i-250415", "size": "1024x1024", "guidance_scale": 2.5, "watermark": true } Response - Seedream Text to Image
JSON
{ "created": 1757499942, "data": [ { "url": "https://..../byteplus/XXXXXXXXXXXXXXX-hntkjsg9kj.jpg" } ], "usage": { "generated_images": 1, "output_tokens": 4096, "total_tokens": 4096 } } Request Headers
| Header | Description |
|---|---|
| Content-Type | application/json |
| Cache-Control | no-cache |
| Ocp-Apim-Subscription-Key | Authentication key required for API access |
Response Handling
The Bytedance Text to Image returns specific HTTP status codes and response bodies to indicate the success or failure of a request. Developers should implement error handling in their applications to manage these responses effectively.
Common Status Codes and Responses
| Status Code | Description | Response Body |
|---|---|---|
| 200 | Success - The request was successfully processed. | { "success": true, ... } |
| 400 | Bad Request - The request contains invalid parameters or missing fields. | { "error": "Invalid request parameters" } |
| 401 | Unauthorized - The provided subscription key is missing or invalid. | { "error": "Invalid or missing authentication" } |
| 403 | Forbidden - The subscription does not have access to this API or action. | { "error": "Access denied for this operation" } |
| 404 | Not Found - The requested resource or endpoint could not be found. | { "error": "Endpoint not found" } |
| 429 | Too Many Requests - The request rate limit has been exceeded. | { "error": "Rate limit exceeded, please retry later" } |
| 500 | Internal Server Error - An unexpected error occurred on the server. | { "error": "An unexpected error occurred, please try again later" } |
Example Error Response
{ "error": "Invalid parameters" } Retrieving Image Result and URL
After submitting your request, use this endpoint to check status and retrieve results.
Endpoint
POST https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults
Request Body
{ "job_set_id": "your-job-set-id-here" } Headers
Content-Type: application/jsonCache-Control: no-cacheOcp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Example Request Using cURL
curl -v -X POST "https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults" \ -H "Content-Type: application/json" \ -H "Cache-Control: no-cache" \ -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \ --data-raw '{ "job_set_id": "your-job-set-id-here" }' Example Success Response
{ "job_set_id": "your-job-set-id-here", "status": "succeeded", "images": [ { "url": "https://..../byteplus/XXXXXXXXXXXXXXX-hntkjsg9kj.jpg" } ], "created_at": 1757499942, "updated_at": 1757499950 } Bytedance API Pricing
| Resolution | Price (USD) |
|---|---|
| All Resolution | Free |