Vai al contenuto
Riferimento API
Riferimento API

Seedream Modifica immagine

Usa l'endpoint edit image per creare un Task asincrono.

Visualizza Markdown
01

Panoramica

Usa l'endpoint edit image con un modello supportato. Usa il Task ID restituito per recuperarne lo stato, oppure fornisci callback_url per le consegne documentate di seguito.

Avvio rapido

  1. Crea una Chiave API e impostala come RUNAPI_API_KEY.
  2. Scegli un modello supportato e invia una richiesta POST il cui corpo corrisponda allo schema di quel modello.
  3. Conserva l'ID attività restituito, quindi esegui il polling fino a uno stato terminale o gestisci i callback documentati di seguito.

Endpoint

POST /api/v1/seedream/edit_image
URL di base
https://runapi.ai
Versione API
v1
Autenticazione
Authorization: Bearer YOUR_API_TOKEN
02

Modelli supportati

Apri la pagina di un modello per i prezzi correnti, i limiti di frequenza e i dettagli sull'uso commerciale.

03

Schema della richiesta

Corpo JSON

I campi e i valori consentiti dipendono dal modello selezionato. Se fornito, callback_url riceve le notifiche Task documentate di seguito.

seedream-4.5-edit10 campi
aspect_ratiostring
Obbligatorio Valori consentiti: 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9
callback_urlstring
Opzionale
enable_safety_checkerboolean
Opzionale
modelstring
Opzionale
output_countinteger
Opzionale
output_qualitystring
Obbligatorio Valori consentiti: basic, high
output_resolutionstring
Opzionale
promptstring
Opzionale
seedinteger
Opzionale
source_image_urlsarray
Obbligatorio Intervallo elementi: 1 - 14
seedream-5-lite-edit11 campi
aspect_ratiostring
Obbligatorio Valori consentiti: 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9
callback_urlstring
Opzionale
enable_safety_checkerboolean
Opzionale
modelstring
Opzionale
output_countinteger
Opzionale
output_formatstring
Opzionale Valori consentiti: png, jpeg Predefinito: png
output_qualitystring
Obbligatorio Valori consentiti: basic, high, ultra
output_resolutionstring
Opzionale
promptstring
Opzionale
seedinteger
Opzionale
source_image_urlsarray
Obbligatorio Intervallo elementi: 1 - 14
seedream-5-pro-edit8 campi
aspect_ratiostring
Obbligatorio Valori consentiti: 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9
callback_urlstring
Opzionale
enable_safety_checkerboolean
Opzionale
modelstring
Opzionale
output_formatstring
Opzionale Valori consentiti: png, jpeg Predefinito: png
output_qualitystring
Obbligatorio Valori consentiti: basic, high
promptstring
Obbligatorio Intervallo: 3 - 5000
source_image_urlsarray
Obbligatorio Intervallo elementi: 1 - 10
seedream-v4-edit10 campi
aspect_ratiostring
Opzionale Valori consentiti: 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9
callback_urlstring
Opzionale
enable_safety_checkerboolean
Opzionale
modelstring
Opzionale
output_countinteger
Opzionale Valori consentiti: 1, 2, 3, 4, 5, 6
output_qualitystring
Opzionale
output_resolutionstring
Opzionale Valori consentiti: 1k, 2k, 4k
promptstring
Opzionale
seedinteger
Opzionale
source_image_urlsarray
Obbligatorio Intervallo elementi: 1 - 10

Regole condizionali

Questi requisiti si applicano quando tutte le condizioni elencate corrispondono.

  1. Quando model = seedream-4.5-edit
    Obbligatorio
    Non accettato
    output_format
  2. Quando model = seedream-5-pro-edit
    Obbligatorio
    Non accettato
    output_resolution, output_count, seed
  3. Quando model = seedream-v4-edit
    Obbligatorio
    Non accettato
    output_format
04

Crea accettazione

HTTP 202

POST /api/v1/seedream/edit_image

Schema della risposta
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "task_replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}
05

Polling in elaborazione

HTTP 200

GET /api/v1/seedream/edit_image/:id

Schema della risposta
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}
06

Polling completato

HTTP 200

GET /api/v1/seedream/edit_image/:id

Schema della risposta
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "images": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "images",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "images": [
    {
      "url": "https://cdn.runapi.ai/public/samples/image.jpg"
    }
  ],
  "status": "completed"
}
07

Polling non riuscito

HTTP 200

GET /api/v1/seedream/edit_image/:id

Schema della risposta
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "error": "Task processing failed.",
  "id": "tsk_reference_demo",
  "status": "failed"
}
08

Callback cliente: completato

HTTP 200

POST callback_url

Schema della risposta
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "images": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "images"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "id": "tsk_reference_demo",
  "images": [
    {
      "url": "https://cdn.runapi.ai/public/samples/image.jpg"
    }
  ],
  "status": "completed"
}
09

Callback cliente: fallito

HTTP 200

POST callback_url

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "properties": {
            "code": {
              "type": "string"
            },
            "limit_cents": {
              "type": "integer"
            },
            "message": {
              "type": "string"
            },
            "reset_at": {
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "used_cents": {
              "type": "integer"
            },
            "window": {
              "enum": [
                "1h",
                "1d",
                "7d",
                "daily",
                "weekly",
                "monthly",
                "lifetime"
              ],
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object",
          "unevaluatedProperties": false
        }
      ]
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": {
    "code": "generation_failed",
    "message": "Task processing failed."
  },
  "id": "tsk_reference_demo",
  "status": "failed"
}
10

Errori

HTTP 401

POST /api/v1/seedream/edit_image

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Authentication required"
}
11

Errori

HTTP 401

GET /api/v1/seedream/edit_image/:id

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Authentication required"
}
12

Errori

HTTP 400

POST /api/v1/seedream/edit_image

Schema della risposta
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "Messaggio di errore leggibile.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "Riepilogo di convalida leggibile dall'utente.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "Messaggi di convalida con chiave per campo della richiesta pubblica, con un array di stringhe leggibili dall'utente per ogni campo.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

Esempio di risposta

JSON 
{
  "error": "model must be one of: seedream-4.5-edit, seedream-5-lite-edit, seedream-5-pro-edit, seedream-v4-edit"
}
13

Errori

HTTP 402

POST /api/v1/seedream/edit_image

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Insufficient balance"
}
14

Errori

HTTP 429

POST /api/v1/seedream/edit_image

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "API key credit limit exceeded"
}
15

Errori

HTTP 409

POST /api/v1/seedream/edit_image

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "The request uses features that are not supported for the selected model"
}
16

Errori

HTTP 429

POST /api/v1/seedream/edit_image

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Rate limit reached. Please retry later."
}
17

Errori

HTTP 503

POST /api/v1/seedream/edit_image

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Service under maintenance, please try again later"
}
18

Errori

HTTP 504

POST /api/v1/seedream/edit_image

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "The request timed out"
}
19

Errori

HTTP 404

GET /api/v1/seedream/edit_image/:id

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Task with id 'tsk_reference_demo' not found"
}
20

Esempi di Codice Generati

Usa cURL direttamente, oppure installa un SDK per il tuo linguaggio. Ogni esempio invia la richiesta validata mostrata in questo riferimento.

Installa

Shell 
pip install runapi-seedream
PYTHON 
import os
from runapi.seedream import SeedreamClient

client = SeedreamClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.edit_image.create(
  model="seedream-5-pro-edit",
  prompt="Change the vase to cobalt blue.",
  aspect_ratio="1:1",
  output_quality="high",
  source_image_urls=["https://cdn.runapi.ai/public/samples/image.jpg"]
)